API

Integração simples para envio de SMS por API
  1. Dashboard
  2. API
Saldo disponível Activo

0.00 MZN

SMS estimados: 0

Preço estimado por SMS: 3.25 MZN

API Key

Chave actual
A carregar...
Criada em: —

Informação base

Base URL
https://api-sms-service-815241442321.us-central1.run.app
Autenticação
Header x-api-key
Formato
JSON

Endpoint principal

POST /v1/sms/send

Envia uma mensagem SMS para um ou vários destinatários usando a tua API key.

Para envio imediato, não envie isScheduled. Para agendamento, envie isScheduled: true e scheduleAt.

Headers
x-api-key: SUA_API_KEY Content-Type: application/json
Body
{ "provider": "tsemba", "to": ["258841234567", "258861234567"], "message": "O seu código é 1234" }
Resposta de sucesso
{ "ok": true, "message": "SMS sent successfully", "data": { "totalRecipients": 2, "successCount": 2, "failedCount": 0, "segments": 2, "totalCost": 3.5, "status": "sent", "provider": "tsemba" } }

Agendar SMS via API

POST /v1/sms/send

Para agendar uma mensagem, use o mesmo endpoint de envio e adicione isScheduled: true e scheduleAt.

Body
{ "provider": "tsemba", "to": ["258841234567"], "message": "Lembrete de pagamento pendente", "campaignName": "Lembrete Pagamento", "isScheduled": true, "scheduleAt": "2026-05-01T14:20:00+02:00" }
Resposta de sucesso
{ "ok": true, "message": "SMS scheduled successfully", "data": { "id": "schedule_id", "campaignName": "Lembrete Pagamento", "totalRecipients": 1, "segments": 1, "estimatedTotalCost": 3.25, "scheduleAt": "2026-05-01T14:20:00.000Z", "status": "scheduled" } }
  • scheduleAt deve ser uma data futura.
  • Recomenda-se enviar o horário com timezone, por exemplo +02:00.
  • Exemplo Maputo: 2026-05-01T14:20:00+02:00.
  • O saldo é validado no momento do agendamento.
  • O envio será processado automaticamente quando chegar a hora.

Exemplo em cURL

curl -X POST "https://api-sms-service-815241442321.us-central1.run.app/v1/sms/send" \ -H "Content-Type: application/json" \ -H "x-api-key: SUA_API_KEY" \ -d '{ "provider": "tsemba", "to": ["258841234567", "258861234567"], "message": "Promoção válida hoje" }'

Exemplo em JavaScript

fetch("https://api-sms-service-815241442321.us-central1.run.app/v1/sms/send", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "SUA_API_KEY" }, body: JSON.stringify({ "provider": "tsemba", to: ["258841234567"], message: "Olá! Este é um teste." }) }) .then(res => res.json()) .then(data => console.log(data)) .catch(err => console.error(err));

Listar SMS agendados

GET /v1/sms/schedules

Retorna a lista de mensagens SMS agendadas associadas à API key.

Headers
x-api-key: SUA_API_KEY
Resposta de sucesso
{ "ok": true, "data": { "items": [ { "id": "schedule_id", "campaignName": "Promoção", "message": "Mensagem agendada", "totalRecipients": 10, "segments": 1, "estimatedTotalCost": 17.5, "status": "scheduled", "scheduleAt": "2026-05-01T14:20:00.000Z" } ] } }

Cancelar SMS agendado

POST /v1/sms/schedules/{id}/cancel

Cancela um SMS previamente agendado.

Headers
x-api-key: SUA_API_KEY
Exemplo cURL
curl -X POST "https://api-sms-service-815241442321.us-central1.run.app/v1/sms/schedules/SCHEDULE_ID/cancel" \ -H "x-api-key: SUA_API_KEY"
Resposta de sucesso
{ "ok": true, "message": "Scheduled SMS cancelled successfully", "data": { "id": "schedule_id", "status": "cancelled" } }
  • Apenas mensagens com status scheduled podem ser canceladas.
  • Após cancelamento, o status passa para cancelled.
  • Mensagens já enviadas não podem ser canceladas.

Consultar saldo

GET /v1/sms/balance

Consulta o saldo disponível da conta associada à API key.

Headers
x-api-key: SUA_API_KEY
Resposta de sucesso
{ "ok": true, "data": { "balance": 1250, "currency": "MZN", "estimatedSmsUnitPrice": 2.5, "estimatedSmsAvailable": 500, "account": { "id": "user_id", "name": "Nome", "email": "email@email.com" } } }

Exemplo em cURL

curl -X GET "https://api-sms-service-815241442321.us-central1.run.app/v1/sms/balance" \ -H "x-api-key: SUA_API_KEY"

Exemplo em JavaScript

fetch("https://api-sms-service-815241442321.us-central1.run.app/v1/sms/balance", { method: "GET", headers: { "x-api-key": "SUA_API_KEY" } }) .then(res => res.json()) .then(data => console.log(data)) .catch(err => console.error(err));

Testar endpoint de saldo

{ }

Cadastrar contacto

POST /v1/contacts

Cadastra um contacto na conta associada à API key.

Headers
x-api-key: SUA_API_KEY Content-Type: application/json
Body
{ "externalId": "CLIENT-1938", "name": "Ana Manuel", "phone": "841234567", "group": "Clientes", "metadata": { "province": "Maputo" } }
Resposta de sucesso
{ "ok": true, "message": "Contact created successfully", "data": { "contact": { "id": "687b1bb903abcdef12345678", "externalId": "CLIENT-1938", "name": "Ana Manuel", "phone": "258841234567", "group": "Clientes", "source": "API", "status": "Ativo", "metadata": { "province": "Maputo" }, "createdAt": "2026-07-18T11:00:00.000Z" } } }
Exemplo cURL
curl -X POST "https://api-sms-service-815241442321.us-central1.run.app/v1/contacts" \ -H "Content-Type: application/json" \ -H "x-api-key: SUA_API_KEY" \ -d '{ "externalId": "CLIENT-1938", "name": "Ana Manuel", "phone": "841234567", "group": "Clientes" }'

Cadastrar contactos em lote

POST /v1/contacts/bulk

Cadastra até 500 contactos num único pedido. Contactos inválidos ou duplicados são ignorados e apresentados na resposta.

Headers
x-api-key: SUA_API_KEY Content-Type: application/json
Body
{ "contacts": [ { "externalId": "CLIENT-1001", "name": "João Manuel", "phone": "841234567", "group": "Clientes" }, { "externalId": "CLIENT-1002", "name": "Maria José", "phone": "861234567", "group": "Fornecedores" } ] }
Resposta
{ "ok": true, "message": "Contacts import processed successfully", "data": { "totalReceived": 2, "imported": 1, "skipped": 1, "insertedIds": [ "687b1bb903abcdef12345678" ], "errors": [ { "row": 2, "phone": "258861234567", "code": "PHONE_ALREADY_EXISTS", "message": "Phone already exists for this account" } ] } }

Listar contactos

GET /v1/contacts

Retorna os contactos da conta associada à API key.

Parâmetros opcionais
Parâmetro Descrição
page Página pretendida.
limit Máximo de 200 registos por página.
search Pesquisa por nome, telefone ou externalId.
group Filtra pelo grupo.
status Filtra por Ativo ou Inativo.
Exemplo cURL
curl -X GET "https://api-sms-service-815241442321.us-central1.run.app/v1/contacts?page=1&limit=50&group=Clientes" \ -H "x-api-key: SUA_API_KEY"
Resposta
{ "ok": true, "data": { "items": [ { "id": "687b1bb903abcdef12345678", "externalId": "CLIENT-1938", "name": "Ana Manuel", "phone": "258841234567", "group": "Clientes", "source": "API", "status": "Ativo" } ], "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 } } }

Erros da API de contactos

HTTP Código Descrição
400 VALIDATION_ERROR Campos obrigatórios em falta.
400 INVALID_PHONE Telefone inválido.
401 UNAUTHORIZED API key ausente ou inválida.
403 MODULE_NOT_ALLOWED Módulo SMS não atribuído à conta.
409 CONTACT_ALREADY_EXISTS Telefone ou externalId já cadastrado.
429 RATE_LIMIT Limite de pedidos excedido.

Notas

  • Os números devem ir no formato normalizado, por exemplo: 258841234567.
  • A API suporta dois providers: tsemba .
  • tsemba não suporta acentos, emojis ou caracteres especiais. Use apenas texto simples sem unicode.
  • O custo final depende do número de destinatários, provider escolhido e quantidade de partes SMS.
  • Uma mensagem normal tem até 160 caracteres. Mensagens maiores podem ser divididas em várias partes.
  • Se o saldo for insuficiente, a API devolve erro e a mensagem não será enviada.
  • A API key deve ser mantida em segredo e nunca exposta no frontend público.
  • Envie a API key no header x-api-key.
  • Máximo de 100 requests por minuto por API key.
  • Para envios em massa, recomenda-se agrupar destinatários no mesmo request em vez de fazer muitos requests individuais.
  • Para agendar SMS via API, use o mesmo endpoint /v1/sms/send.
  • Para agendamento, envie isScheduled: true e scheduleAt.
  • O campo scheduleAt deve estar em formato ISO, exemplo: 2026-05-01T14:20:00+02:00.
  • O horário recomendado é UTC+2 / Africa Maputo.
  • Mensagens agendadas ficam com status scheduled até serem processadas.