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://apisms.olysphere.com
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": "sendit", "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": "sendit" } }

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": "sendit", "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://apisms.olysphere.com/v1/sms/send" \ -H "Content-Type: application/json" \ -H "x-api-key: SUA_API_KEY" \ -d '{ "provider": "sendit", "to": ["258841234567", "258861234567"], "message": "Promoção válida hoje" }'

Exemplo em JavaScript

fetch("https://apisms.olysphere.com/v1/sms/send", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "SUA_API_KEY" }, body: JSON.stringify({ "provider": "sendit", 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://apisms.olysphere.com/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://apisms.olysphere.com/v1/sms/balance" \ -H "x-api-key: SUA_API_KEY"

Exemplo em JavaScript

fetch("https://apisms.olysphere.com/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

{ }

Notas

  • Os números devem ir no formato normalizado, por exemplo: 258841234567.
  • A API suporta dois providers: tsemba e sendit.
  • tsemba é o provider económico: custa 1,75 MZN / SMS.
  • tsemba não suporta acentos, emojis ou caracteres especiais. Use apenas texto simples sem unicode.
  • sendit é o provider premium: custa 3,25 MZN / SMS.
  • sendit suporta acentos e caracteres 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.