Documentação API

Encontrar na documentação

Pesquisa por serviço ou navega diretamente para uma secção.

Sandbox

Simula resultados previsíveis, não envia mensagens reais e não consome créditos SMS nem volume de email.

kamba_test_ · sem cobrança

Produção

Contacta os providers reais. SMS, OTP, Verify e Notify usam créditos; Kamba Email usa volume mensal próprio.

kamba_live_ · consumo real

// quick start

1.Gera a tua API key em/dashboard/keys

2.Usa o headerX-API-Key: SUA_KEY

3.Envia SMS ou usa o serviço OTPPOST /messages/send

Rastreio de suporte: todas as respostas incluem X-Request-Id. Guarda este valor quando ocorrer um erro eGuarda este valor quando ocorrer um erro e envia-o ao suporte; ele permite localizar o pedido sem partilhar a API key, o token ou o conteúdo da mensagem. Também podes enviar o teu próprio identificador com 8-100 caracteres seguros.

Os exemplos usam valores ilustrativos. Para enviar, cria uma conta e uma chave API e aguarda a aprovação do Sender ID.

$ Gerar Chave

⏱️SMS:50/horaOTP:3/hora/númeroBulk:1000 dest.

Autenticação

Inclui o header X-API-Key: SUA_API_KEY em todos os pedidos autenticados. O endpoint /otp/verify é público e não requer chave.

Permissões

Limita cada chave aos produtos necessários. Uma tentativa fora do scope responde 403 API_KEY_SCOPE_DENIED.

Expiração

Pode ser indefinida ou definida para 30, 90, 180 ou 365 dias. Uma chave expirada responde 401 API_KEY_EXPIRED.

Rotação

A chave anterior continua válida durante 24 horas para permitir atualizar a integração sem interrupção.

Base URLhttps://api.kambasms.ao

HeaderX-API-Key: SUA_API_KEY

Formatoapplication/json

Números suportadosAngola (+244)

Sender IDSEU_SENDER_ID

Ecossistema

SDKs oficiais, coleção Postman e integrações futuras.

Node.js / TypeScript

npm install kambasms

PHP

PHP 8.0+

composer require kambasms/php-sdk

Python 3.8+

pip install kambasms

.NET 6.0+

dotnet add package KambaSMS

Postman Collection

Testes automáticos incluídos

WordPress Plugin

Em desenvolvimento

Sandbox e Webhook Inspector

Usa a página Sandbox para gerar chaves kamba_test_, simular OTP/SMS e inspecionar eventos assinados. O Inspector não envia dados para URLs externas: apresenta o corpo, X-Kamba-Event, X-Kamba-Delivery e X-Kamba-Signature para validação local.

signature = HMAC_SHA256(signing_secret, raw_request_body)
header: X-Kamba-Signature: sha256=<hex>

Abrir Sandbox →Abrir API Playground →

OTP Service

API Service

Serviço gerido de autenticação por SMS. Rate limiting, expiração e validação incluídos.

POST/otp/send

Envia um código OTP de 6 dígitos por SMS. Autenticado via API Key. Debita 1 crédito.

Parâmetros

phonestringobrigatório

Número angolano no formato +244XXXXXXXXX

Rate limit: máximo 3 OTPs por hora por número. Código válido por 5 minutos.

bash

curl -X POST https://api.kambasms.ao/otp/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "phone": "+244912345678"
  }'

Resposta 200

response.json200 OK

{
  "success": true,
  "message": "OTP enviado com sucesso.",
  "expires_in": 300
}

POST/otp/verify

Valida um código OTP. Endpoint PÚBLICO — não requer API Key.

Parâmetros

phonestringobrigatório

Mesmo número usado no envio

codestringobrigatório

Código de 6 dígitos recebido por SMS

Este endpoint é público. A segurança está no rate limiter global (20 tentativas/15min) e na expiração do código (5min).

bash

curl -X POST https://api.kambasms.ao/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+244912345678",
    "code": "123456"
  }'

Sucesso 200

response.json200 OK

{
  "success": true,
  "message": "Código verificado com sucesso."
}

Erro 400

response.json400 Bad Request

{
  "error": "Código inválido ou expirado."
}

Mensagens

POST/messages/send

Envia um SMS para um número angolano.

Evita duplicados: envia o cabeçalho Idempotency-Key com uma chave única por operação. A mesma chave e o mesmo JSON devolvem a resposta guardada durante pelo menos 24 horas. Se o conteúdo mudar, a API responde 409. A proteção também funciona em OTP Send, Verify Start/Resend, Notify, Bulk e Agendamentos.

Parâmetros

tostringobrigatório

Número de destino no formato +244XXXXXXXXX

textstringobrigatório

Conteúdo da mensagem. Máximo 160 caracteres. Sem links ou URLs.

O Sender ID é definido automaticamente a partir da tua chave API.

bash

curl -X POST https://api.kambasms.ao/messages/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "to": "+244912345678",
    "text": "Ola! Mensagem de teste."
  }'

Resposta 201

response.json201 Created

{
  "success": true,
  "message_id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued",
  "to": "+244912345678",
  "sender_id": "SEU_SENDER_ID",
  "remaining_balance": 99,
  "segments": 1,
  "timestamp": "2025-01-01T12:00:00.000Z"
}

GET/messages

Lista o histórico de mensagens enviadas.

Retorna as últimas 100 mensagens ordenadas por data.

bash

curl https://api.kambasms.ao/messages \
  -H "X-API-Key: SUA_API_KEY"

Verificação

Kamba Verify

Fluxo completo de verificação em duas chamadas. A API gera, envia, limita, expira e confirma o código.

POST/verify/start

Inicia a verificação e envia o código. Debita 1 crédito em produção.

phonestringobrigatório

Número no formato +244XXXXXXXXX

sender_idstringopcional

Usa o Sender ID associado à chave quando omitido

bash

curl -X POST https://api.kambasms.ao/verify/start \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"+244912345678"}'

POST/verify/check

Confirma o código introduzido pelo utilizador.

verification_iduuidobrigatório

Identificador devolvido por /verify/start

codestringobrigatório

Código de 6 dígitos

bash

curl -X POST https://api.kambasms.ao/verify/check \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"verification_id":"UUID","code":"123456"}'

Gestão: POST /verify/resend, GET /verify, GET /verify/stats?days=30, GET /verify/events e GET /verify/:id.

Dados

Kamba Lookup

Valida e normaliza números angolanos. A operadora indicada corresponde à atribuição provável do prefixo, sem consulta em tempo real nem identificação do titular.

POST/lookup

Consulta individual sem consumir créditos.

phonestringobrigatório

Número nacional ou internacional

bash

curl -X POST https://api.kambasms.ao/lookup \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"phone":"+244923000000"}'

POST/lookup/bulk

Analisa até 500 números e assinala inválidos e duplicados.

phonesarrayobrigatório

Lista com até 500 números

bash

curl -X POST https://api.kambasms.ao/lookup/bulk \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"phones":["+244923000000","+244953000000"]}'

Interação

Kamba Links

Cria links curtos para destinos públicos e acompanha cliques. Endereços locais e redes privadas são rejeitados.

POST/links

Cria um link com slug automático ou personalizado.

urlstringobrigatório

Destino público HTTP ou HTTPS

slugstringopcional

4-40 letras minúsculas, números ou hífen

expires_atstringopcional

Data ISO futura

bash

curl -X POST https://api.kambasms.ao/links \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://kambasms.ao","title":"KambaSMS"}'

Gestão: GET /links, GET /links/:id/stats e DELETE /links/:id. OO redirecionamento público usa GET /l/:slug.

Mensagens transacionais

Kamba Email

Envia emails transacionais pela API com domínio próprio, histórico, supressões automáticas e volume mensal separado dos créditos SMS.

POST/email/send

Envia um email em produção. Exige domínio verificado e volume mensal disponível.

domain_iduuidobrigatório

Domínio verificado na conta

from_localstringobrigatório

Parte antes de @, por exemplo notificacoes

from_namestringopcional

Nome apresentado ao destinatário

tostringobrigatório

Um destinatário por pedido

subjectstringobrigatório

Assunto até 200 caracteres

htmlstringopcional

Conteúdo HTML; usa html ou text

textstringopcional

Conteúdo em texto simples; usa html ou text

bash

curl -X POST https://api.kambasms.ao/email/send \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-email" \
  -d '{"domain_id":"UUID_DO_DOMINIO","from_local":"notificacoes","from_name":"Minha Loja","to":"cliente@exemplo.ao","subject":"Pedido confirmado","html":"<h1>Pedido confirmado</h1>"}'

POST/email/sandbox/send

Simula estados previsíveis sem contactar o fornecedor e sem consumir volume.

tostringobrigatório

Usa delivered, bounced, complained, opened, clicked ou failed antes de @kambasms.test

subjectstringobrigatório

Assunto do teste

bash

curl -X POST https://api.kambasms.ao/email/sandbox/send \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"to":"delivered@kambasms.test","subject":"Teste Kamba Email"}'

POST/email/templates

Cria um template reutilizável com variáveis no formato {{nome}}.

keystringobrigatório

Chave única, por exemplo pedido_confirmado

namestringobrigatório

Nome visível no dashboard

subjectstringobrigatório

Assunto, com variáveis opcionais

htmlstringopcional

HTML do email

textstringopcional

Alternativa em texto simples

bash

curl -X POST https://api.kambasms.ao/email/templates \
+  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
+  -d '{"key":"pedido_confirmado","name":"Pedido confirmado","subject":"Pedido {{pedido}} confirmado","text":"Olá {{nome}}, o pedido {{pedido}} foi confirmado."}'

POST/email/bulk

Coloca até 500 destinatários numa fila processada em segundo plano. Cada destinatário enviado consome uma unidade do volume mensal.

domain_iduuidobrigatório

Domínio verificado

template_iduuidobrigatório

Template ativo

recipientsarrayobrigatório

Objetos com email e variables

bash

curl -X POST https://api.kambasms.ao/email/bulk \
+  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
+  -H "Idempotency-Key: campanha-setembro-01" \
+  -d '{"name":"Confirmações","domain_id":"UUID_DO_DOMINIO","template_id":"UUID_DO_TEMPLATE","from_local":"notificacoes","recipients":[{"email":"ana@exemplo.ao","variables":{"nome":"Ana","pedido":"123"}}]}'

Gestão: domínios por GET /email/overview, POST /email/domains e POST /email/domains/:id/verify; templates por PATCH/DELETE /email/templates/:id e POST /email/templates/:id/render; bulk por GET /email/bulk/:id e POST /email/bulk/:id/cancel. Usa Usa Idempotency-Key nos envios para repetir pedidos em segurança. Bounces e complaints entram automaticamente nas supressões.

Mensagens

Kamba Notify

Modelos transacionais com variáveis. Nesta fase, o canal disponível é SMS.

POST/notify/templates

Cria um modelo reutilizável.

keystringobrigatório

Identificador único, por exemplo pedido_confirmado

namestringobrigatório

Nome visível no dashboard

bodystringobrigatório

Mensagem com variáveis como {{nome}}

bash

curl -X POST https://api.kambasms.ao/notify/templates \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"key":"pedido_confirmado","name":"Pedido confirmado","body":"Olá {{nome}}, o pedido {{pedido}} foi confirmado."}'

POST/notify/send

Renderiza o modelo e envia por SMS. Debita 1 crédito em produção.

template_keystringobrigatório

Chave do modelo ativo

tostringobrigatório

Destino +244XXXXXXXXX

variablesobjectobrigatório

Valores para todas as variáveis do modelo

bash

curl -X POST https://api.kambasms.ao/notify/send \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"template_key":"pedido_confirmado","to":"+244912345678","variables":{"nome":"Ana","pedido":"1234"}}'

Gestão: GET /notify/templates, DELETE /notify/templates/:id, POST /notify/render e GET /notify/deliveries.

Orquestração

Kamba Automations

Liga eventos de SMS, Verify, Links e Chat a um endpoint Webhook ou modelo Kamba Notify. Regras nascem pausadas e podem ser simuladas sem consumir créditos.

POST/automations

Cria uma regra pausada.

namestringobrigatório

Nome interno

trigger_eventstringobrigatório

Evento que inicia a regra

action_typestringobrigatório

webhook ou notify

action_configobjectobrigatório

endpoint_id ou template_key e to

bash

curl -X POST https://api.kambasms.ao/automations \
+  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
+  -d '{"name":"Verify concluído","trigger_event":"verify.completed","action_type":"webhook","action_config":{"endpoint_id":"UUID_DO_ENDPOINT"}}'

Ações Notify: cada execução real consome 1 crédito. A ativação exige confirm_paid_action: true. Cada regra aceita até 50 execuções por hora.

Gestão: GET /automations, PATCH/DELETE /automations/:id, POST /automations/:id/simulate e GET /automation-runs.

Developers / Eventos

Webhooks de produção

Entrega eventos para URLs HTTPS públicas. Cada pedido inclui identificador, tipo, data e dados sem conteúdo sensível. Falhas são repetidas até seis vezes.

POST/webhook-endpoints

Cria um endpoint. O segredo whsec_ é devolvido apenas nesta resposta.

namestringobrigatório

Nome interno do endpoint

urlstringobrigatório

URL HTTPS pública

eventsstring[]opcional

Tipos desejados; omite para receber todos

bash

curl -X POST https://api.kambasms.ao/webhook-endpoints \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Produção","url":"https://api.exemplo.ao/webhooks/kambasms","events":["verify.completed","message.status"]}'

Assinatura: HMAC SHA-256 de timestamp.raw_body. Lê x-kambasms-timestamp e compara x-kambasms-signature em tempo constante. Rejeita pedidos com mais de cinco minutos.
Eventos: message.status, verify.started, verify.completed, verify.failed, link.clicked, chat.conversation.created, chat.message.created, notify.sent e email.sent/delivered/bounced/complained/opened/clicked/failed.

Gestão: GET /webhook-endpoints, PATCH/DELETE /webhook-endpoints/:id, POST /webhook-endpoints/:id/test, GET /webhook-deliveries e POST /webhook-deliveries/:id/retry.

Atendimento

KambaChat

O dashboard gere o widget e a caixa de entrada. O browser do visitante usa um token temporário próprio e nunca recebe a chave API da conta.

POST/chat/widgets

Cria ou devolve o primeiro widget da conta.

namestringopcional

Nome apresentado no cabeçalho do widget

bash

curl -X POST https://api.kambasms.ao/chat/widgets \
  -H "X-API-Key: SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Atendimento"}'

Conta autenticada: GET/PATCH /chat/widgets, GET /chat/conversations, GET/POST /chat/conversations/:id/messages e PATCH /chat/conversations/:id.
Instalação pública: GET /chat/widget.js?key=.... Os endpoints /chat/public são utilizados internamente pelo widget.

Créditos

GET/credits/balance

Retorna o saldo atual de SMS disponíveis.

bash

curl https://api.kambasms.ao/credits/balance \
  -H "X-API-Key: SUA_API_KEY"

Resposta 200

response.json200 OK

{ "balance": 99 }

Agendamentos

POST/messages/schedule

Agenda um SMS para envio futuro. Requer primeira recarga SMS aprovada, saldo e Sender ID aprovado.

Parâmetros

tostringobrigatório

Número +244XXXXXXXXX

textstringobrigatório

Mensagem (máx 160 chars, sem URLs)

sender_idstringobrigatório

3–11 caracteres alfanuméricos

scheduled_atstringobrigatório

ISO 8601. Deve ser no futuro.

bash

curl -X POST https://api.kambasms.ao/messages/schedule \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "to": "+244912345678",
    "text": "Lembrete: consulta amanha as 10h.",
    "sender_id": "SEU_SENDER_ID",
    "scheduled_at": "2025-06-01T09:00:00.000Z"
  }'

Resposta 201

response.json201 Created

{
  "success": true,
  "scheduled": {
    "id": "uuid",
    "sms_to": "+244912345678",
    "scheduled_at": "2025-06-01T09:00:00.000Z",
    "status": "pending"
  }
}

Envio em Massa

POST/messages/bulk

Envio para múltiplos destinatários. Máx 1000. Processado em background.

Opt-out obrigatório para campanhas

Inclui forma de cancelamento: Responda PARAR para cancelar.

Parâmetros

namestringobrigatório

Nome da campanha

sender_idstringobrigatório

3–11 caracteres alfanuméricos

textstringobrigatório

Mensagem (máx 160 chars, sem URLs)

recipientsarrayobrigatório

Array de números +244. Máx 1000.

bash

curl -X POST https://api.kambasms.ao/messages/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "name": "Confirmacoes de consultas",
    "sender_id": "SEU_SENDER_ID",
    "text": "A sua consulta foi confirmada. Consulte os detalhes na sua conta.",
    "recipients": ["+244912345678", "+244923456789"]
  }'

Resposta 201

response.json201 Created

{
  "success": true,
  "job_id": "uuid",
  "total": 2
}

Boas Práticas e Limitações

📏

Limite de 160 caracteres

Cada SMS suporta no máximo 160 caracteres. As operadoras angolanas podem fragmentar ou rejeitar SMS concatenados.

🚫

Links e URLs não são permitidos

Mensagens com links (https://, www., domínios) são bloqueadas automaticamente pelas operadoras angolanas como spam.

⏱️

Limites de envio

SMS (/messages/send)50/hora por conta

OTP (/otp/send)3/hora por número

OTP verify (/otp/verify)20 tentativas/15min

Bulk (/messages/bulk)1000 destinatários/campanha

Pedidos globais por IP100/15 minutos

Códigos de erro

400

VALIDATION_ERROR

Pedido inválido

Parâmetros inválidos ou em falta. Revê corpo, formato e conteúdo.

Consumo

Não

Repetir

Depois de corrigir

401

UNAUTHORIZED

Não autenticado

API Key inválida, revogada ou em falta. Confirma a chave e o header.

Consumo

Não

Repetir

Sim

402

INSUFFICIENT_BALANCE

Saldo insuficiente

A conta não tem créditos SMS suficientes. Recarrega SMS e OTP.

Consumo

Não

Repetir

Depois da recarga

402

EMAIL_QUOTA_EXHAUSTED

Volume de email esgotado

O ciclo do Kamba Email não tem volume disponível. Ativa outro pacote de email.

Consumo

Não

Repetir

Depois da recarga

404

NOT_FOUND

Não encontrado

O recurso não existe ou não pertence à conta. Confirma o identificador.

Consumo

Não

Repetir

Não

409

EMAIL_SUPPRESSED

Destinatário suprimido

Bounce permanente ou reclamação bloqueou o endereço. Não forces um novo envio.

Consumo

Não

Repetir

Não

429

RATE_LIMITED

Limite atingido

A proteção de frequência recusou temporariamente o pedido. Respeita Retry-After quando existir.

Consumo

Não

Repetir

Após o intervalo

500

INTERNAL_ERROR

Erro interno

A plataforma não concluiu a operação. Guarda X-Request-Id e contacta o suporte.

Consumo

Confirmar histórico

Repetir

Com idempotência