# KambaSMS — Plataforma de Comunicação Transacional para Angola

> KambaSMS (https://www.kambasms.ao) é a plataforma e API REST de comunicações transacionais para empresas e programadores em Angola. Permite enviar SMS e OTP para as operadoras angolanas (Unitel, Movicel e Africell), autenticar acessos de segundo fator (Kamba Authenticator), enviar emails transacionais (Kamba Email), validar números +244 (Kamba Lookup), criar links curtos rastreáveis (Kamba Links), orquestrar canais com fallback (Kamba Transactions) e ativar o WhatsApp Business API oficial com configuração assistida (Kamba for WhatsApp).

## Informações Essenciais

- **Website:** https://www.kambasms.ao
- **URL Base da API:** `https://api.kambasms.ao`
- **Documentação Pública da API:** https://www.kambasms.ao/docs
- **Guia Kamba Authenticator (2FA):** https://www.kambasms.ao/docs/authenticator
- **Suporte e Configuração Assistida:** support@kambasms.ao
- **Conformidade Legal (Angola):** Lei n.º 22/11 de 17 de Junho (Lei da Proteção de Dados Pessoais — APD Angola). Acordo de Subcontratação (DPA) disponível em https://www.kambasms.ao/dpa

---

## Modelo de Preços e Saldos (Kwanzas — AOA)

A KambaSMS separa o saldo de créditos SMS/OTP do volume mensal de Kamba Email dentro da mesma conta:

1. **SMS & OTP Transacional (Compra pré-paga, sem expiração):**
   - **Pacote base:** 50 créditos por **6.000 Kz** (acumuláveis, sem mensalidade obrigatória).
   - **Consumo:** 1 crédito por segmento SMS aceite (codificação GSM-7 até 160 caracteres; mensagens com caracteres Unicode/UCS-2 têm 70 caracteres por segmento).
   - **Custo 0 créditos:** Validação de código (`/otp/verify`, `/verify/check`), Kamba Lookup (`/lookup/check`), TOTP (Authenticator) e chamadas em Sandbox (`kamba_test_`).

2. **Kamba Email (Saldo separado · Ciclo mensal):**
   - **Piloto:** 1.000 emails — **5.000 Kz**
   - **Essencial (Recomendado):** 5.000 emails — **15.000 Kz**
   - **Negócio:** 20.000 emails — **45.000 Kz**
   - **Escala:** 50.000 emails — **85.000 Kz**
   - Inclui Sandbox gratuita e exige domínio próprio autenticado com SPF e DKIM para produção.

3. **Kamba for WhatsApp (Configuração Assistida + API):**
   - Onboarding acompanhado em 5 etapas (Qualificação e número `+244`, Verificação Meta Business com NIF/Certidão Comercial, Aprovação de Templates `AUTHENTICATION`/`UTILITY`, Ligação da API à KambaSMS e Produção com Fallback SMS).
   - Mais informações: https://www.kambasms.ao/channels/whatsapp

---

## Autenticação, Ambientes e Cabeçalhos HTTP

Todas as chamadas à API REST devem usar HTTPS e JSON (`Content-Type: application/json`):

- **Cabeçalho de autenticação:**
  - `X-API-Key: kamba_live_...` (Produção) ou `X-API-Key: kamba_test_...` (Sandbox)
  - Alternativa suportada: `Authorization: Bearer kamba_live_...`
- **Cabeçalho de idempotência (altamente recomendado em operações de envio):**
  - `Idempotency-Key: <identificador-unico-por-evento>` (ex.: `order-1042-confirmation`)
- **Formato de números de telefone (Angola E.164):**
  - Sempre `+2449XXXXXXXX` (ex.: `+244923000000`).
- **Regras de conteúdo SMS:**
  - Uso estritamente transacional. Não são permitidos links/URLs em mensagens SMS diretas nem envios promocionais não solicitados. Sender ID alfanumérico (3 a 11 caracteres) requer aprovação prévia na conta.

---

## Principais Endpoints da API (`https://api.kambasms.ao`)

### 1. SMS Transacional
- **`POST /messages/send`** — Envia um SMS transacional individual.
  ```json
  {
    "to": "+244923000000",
    "text": "O seu pedido #1042 foi confirmado.",
    "sanitize_gsm7": true
  }
  ```
- **`POST /messages/bulk`** — Envio em massa (até 1.000 números `+244`, processado em fila com controlo de pausa/retoma).
- **`POST /messages/schedule`** — Agenda um SMS para data/hora futura (`ISO 8601`).
- **`GET /messages/history`** — Lista o histórico de mensagens enviadas.
- **`GET /credits/balance`** — Consulta o saldo atual de créditos SMS.

### 2. OTP & Kamba Verify (Verificação Telefónica Atómica)
- **`POST /otp/send`** — Gera e envia um código OTP de 6 dígitos por SMS (protegido com `HMAC-SHA256` por domínio e mascarado como `[OTP ocultado]` nos logs). Devolve `otp_id`.
  ```json
  {
    "phone": "+244923000000"
  }
  ```
- **`POST /otp/verify`** — Valida o código OTP de uso único (0 créditos).
  ```json
  {
    "phone": "+244923000000",
    "code": "482916",
    "otp_id": "UUID_OPCIONAL_RECOMENDADO"
  }
  ```
- **`POST /sandbox/v2/otp/send` e `POST /sandbox/v2/otp/verify`** — Ciclo completo de OTP em Sandbox v2 com chave `kamba_test_`, validade de 5 minutos, máximo de 5 tentativas e consumo único real sem gastar créditos.
- **`POST /verify/start`**, **`POST /verify/resend`** e **`POST /verify/check`** — Fluxo completo Kamba Verify com invalidação atómica do código anterior no reenvio.

### 3. Kamba Authenticator (2FA por SMS + TOTP + Códigos de Recuperação)
- Documentação dedicada: https://www.kambasms.ao/docs/authenticator
- Segredos TOTP cifrados em repouso com `AES-256-GCM`, provas de sessão assinadas (`HMAC-SHA256`) de consumo único no servidor da aplicação cliente e isolamento estrito entre `sandbox` e `live`.

### 4. Kamba Email
- **`POST /email/send`** — Envia email transacional em produção com idempotência por fingerprint `SHA-256` do payload e guarda partilhada de supressão de bounces/complaints.
  ```json
  {
    "domain_id": "UUID_DO_DOMINIO_VERIFICADO",
    "from_local": "notificacoes",
    "from_name": "Minha Empresa",
    "to": "cliente@empresa.ao",
    "subject": "Recibo #2048",
    "text": "O seu pagamento foi confirmado."
  }
  ```
- **`POST /email/sandbox/send`** — Simula estados previsíveis de email sem entrega externa e sem consumir volume.

### 5. Kamba Notify, Lookup, Links, Transactions e Webhooks
- **`POST /notify/templates` e `POST /notify/send`** — Criação e disparo de templates SMS com variáveis `{{nome}}`.
- **`POST /lookup/check` e `POST /lookup/bulk`** — Normalização para `+244` (E.164) e identificação de operadora (0 créditos).
- **`POST /links`** — Criação de links curtos com estatísticas de cliques.
- **`POST /transactions/send`** — Orquestração transacional multi-canal (SMS + Email) com idempotência comum.
- **`POST /webhooks`** — Registo de endpoints HTTPS para eventos de entrega assinados com `HMAC-SHA256` (`whsec_...`) e proteção anti-SSRF.

---

## Receitas Rápidas de Integração

- **Keycloak / Authelia (SSO & 2FA):** Webhook HTTP chamando `POST /messages/send` para envio de código OTP ou alerta de login em números `+244`.
- **Laravel (PHP):** Integração com `Http::withHeaders(['X-API-Key' => ...])->post('https://api.kambasms.ao/messages/send', [...])`.
- **WordPress / WooCommerce:** Hook `woocommerce_order_status_processing` via `wp_remote_post`.
- **Node.js / TypeScript:** Snippet assíncrono nativo com `fetch` e suporte a `auto_gsm7: true`.

---

## Mapa de Páginas Principais

- Home: https://www.kambasms.ao/
- SMS & OTP: https://www.kambasms.ao/sms-otp
- Kamba Verify: https://www.kambasms.ao/verify
- Kamba Authenticator: https://www.kambasms.ao/authenticator
- Kamba Email: https://www.kambasms.ao/email
- Kamba Notify: https://www.kambasms.ao/notify
- Kamba Lookup: https://www.kambasms.ao/lookup
- Kamba Links: https://www.kambasms.ao/links
- KambaChat: https://www.kambasms.ao/chat
- Kamba Transactions: https://www.kambasms.ao/transactions
- Kamba for WhatsApp: https://www.kambasms.ao/channels/whatsapp
- KambaSMS Desktop: https://www.kambasms.ao/workspace
- KambaSMS Connect (Extensão Chrome/Edge): https://www.kambasms.ao/connect
- Soluções por Setor: https://www.kambasms.ao/solutions
- Cobertura em Angola: https://www.kambasms.ao/coverage
- Sandbox: https://www.kambasms.ao/sandbox
- SDKs & HTTP Nativo: https://www.kambasms.ao/sdks
- Estado dos Serviços: https://www.kambasms.ao/status
- Centro Legal & DPA (Lei n.º 22/11): https://www.kambasms.ao/legal e https://www.kambasms.ao/dpa