SMS Angola
REST · JSON · v1

Documentação da API

Integra o envio de SMS no teu site, aplicação ou ERP. Todos os pedidos usam HTTPS e JSON, e os valores monetários estão em Kwanzas (Kz).

Introdução

URL base:

https://sms-ao-a4yn.vercel.app/api/v1

Os números de telefone usam o formato internacional E.164 (por exemplo, +244923000000). Números angolanos sem indicativo (923000000) são aceites e convertidos automaticamente. As datas são devolvidas em ISO 8601 (UTC).

Autenticação

Cria uma chave em Painel → API. A chave só é mostrada uma vez: guarda-a num local seguro, como uma variável de ambiente, e nunca a uses no código do browser ou de aplicações móveis. Envia-a no cabeçalho Authorization:

Authorization: Bearer smsao_live_xxxxxxxxxxxxxxxx

Podes revogar uma chave a qualquer momento. Os pedidos com uma chave revogada recebem 401.

Enviar SMS

POST/api/v1/sms/send
CampoTipoObrig.Descrição
tostringsimNúmero do destinatário (E.164 ou nacional angolano).
fromstringnãoRemetente aprovado na tua conta. Por defeito usa o remetente da plataforma.
messagestringsimTexto da mensagem (máximo 10 segmentos). Os segmentos são calculados automaticamente (GSM-7/Unicode).
referencestringnãoA tua referência interna, devolvida nas consultas e nos webhooks.

Envia o cabeçalho opcional Idempotency-Key para garantir que um pedido repetido (por exemplo, depois de um timeout) não gera uma segunda SMS nem uma segunda cobrança.

curl -X POST https://sms-ao-a4yn.vercel.app/api/v1/sms/send \
  -H "Authorization: Bearer smsao_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821" \
  -d '{
    "to": "+244923000000",
    "from": "MINHAEMPRESA",
    "message": "A sua encomenda #4821 saiu para entrega.",
    "reference": "encomenda-4821"
  }'

Resposta:

HTTP/1.1 202 Accepted
{
  "data": {
    "id": "8d3f0a52-6c1e-4b8e-9b0e-0f6a3f8c2d11",
    "to": "+244923000000",
    "from": "MINHAEMPRESA",
    "status": "queued",
    "segments": 1,
    "encoding": "GSM7",
    "price_kz": 20,
    "demo": false,
    "client_reference": "encomenda-4821",
    "created_at": "2026-11-13T14:05:12.000Z"
  }
}

Consultar mensagem

GET/api/v1/sms/{id}

Devolve o estado atual de uma mensagem enviada pela tua conta.

curl https://sms-ao-a4yn.vercel.app/api/v1/sms/8d3f0a52-... \
  -H "Authorization: Bearer $SMSAO_API_KEY"

Histórico

GET/api/v1/sms/history?status=delivered&from=2026-11-01&limit=50&page=1
CampoTipoObrig.Descrição
statusstringnãoFiltra por estado (queued, sending, sent, delivered, failed, undelivered, rejected).
from / todatanãoIntervalo de datas (AAAA-MM-DD).
limitnúmeronão1 a 100 (por defeito 50).
pagenúmeronãoPágina (começa em 1).
{
  "data": [ { "id": "…", "to": "+244923000000", "status": "delivered", … } ],
  "pagination": { "page": 1, "limit": 50, "total": 1284 }
}

Consultar saldo

GET/api/v1/balance
{
  "data": {
    "credits": 9225,
    "reserved_credits": 60,
    "available_credits": 9165,
    "currency": "AOA",
    "balance_kz": 184500,
    "reserved_kz": 1200,
    "available_kz": 183300,
    "price_per_segment_kz": { "+244": 20 },
    "estimated_sms_available": 9165
  }
}

Remetentes

GET/api/v1/senders

Lista os remetentes aprovados que podes usar no campo from.

Estados de entrega

queuedEm fila para envio (ou agendada).
sendingA ser submetida ao fornecedor.
sentAceite pelo fornecedor/operador. Saldo debitado.
deliveredConfirmada como entregue no telemóvel (DLR).
undeliveredO operador não conseguiu entregar (telemóvel desligado, número inativo…).
failedFalhou depois de esgotar as retentativas. Saldo devolvido.
rejectedRejeitada pelo fornecedor (número inválido, remetente…). Saldo devolvido.

Webhooks

Configura um URL HTTPS em Painel → API → Webhooks para receberes eventos message.sent, message.delivered, message.undelivered, message.failed e message.rejected. Cada pedido inclui o cabeçalho X-SMSAO-Signature: sha256=…, que é o HMAC-SHA256 do corpo com o segredo do webhook.

$body = file_get_contents("php://input");
$expected = "sha256=" . hash_hmac("sha256", $body, getenv("SMSAO_WEBHOOK_SECRET"));
if (!hash_equals($expected, $_SERVER["HTTP_X_SMSAO_SIGNATURE"] ?? "")) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
// $event["event"] === "message.delivered"
http_response_code(200);

Erros

Os erros devolvem um código HTTP adequado e um corpo com error.code e error.message em português.

400VALIDATION_ERRORCampos em falta ou inválidos (número, mensagem demasiado longa…).
401UNAUTHORIZEDChave em falta, inválida ou revogada.
402SALDO_INSUFICIENTESaldo disponível insuficiente para o envio.
403REMETENTE_NAO_APROVADO / CONTA_SUSPENSA / DESTINATARIO_EXCLUIDOOperação não permitida para esta conta ou destinatário.
404NOT_FOUNDRecurso inexistente ou de outra conta.
422DESTINO_NAO_SUPORTADO / CONTEUDO_BLOQUEADOSem rota para o destino, ou conteúdo bloqueado pelas regras antifraude.
429RATE_LIMITED / LIMITE_DIARIO_EXCEDIDOLimite de pedidos por minuto ou limite diário atingido.

Limites

Cada chave tem um limite de pedidos por minuto (60 por defeito, ajustável). As respostas incluem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. A conta tem ainda um limite diário de SMS, definido pela equipa SMS Angola.

Pronto para integrar?

Cria a conta e gera a primeira chave API em menos de 2 minutos.

Criar conta
Documentação da API · SMS Angola