API da RomaSMS

Toda requisição precisa do seu token de API. Você gera (e revoga) ele no painel, em Configurações → API. Ele começa com rsk_.

Envie no cabeçalho Authorization:

Authorization: Bearer rsk_seu_token_aqui

⚠️ O token é secreto e dá acesso ao seu saldo — use só no servidor da sua aplicação, nunca no navegador/app do usuário final.

Envia para um número ou uma lista. Debita o saldo na hora e enfileira o disparo.

Corpo (JSON)

• numero — um celular. Ou numeros — lista (até 1000). Aceita com ou sem o 55.
• mensagem — o texto (obrigatório).
• remetente — opcional.

Exemplo

curl -X POST https://roma-sms.com/api/v1/sms \
  -H "Authorization: Bearer rsk_seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "numero": "11987654321",
    "mensagem": "Sua consulta é amanhã às 14h. Responda SIM para confirmar."
  }'

Resposta (200)

{
  "ok": true,
  "id": "e2b1...-uuid-do-disparo",
  "ids": ["e2b1...-uuid-do-disparo"],
  "quantidade": 1,
  "creditos_debitados": 1,
  "saldo_restante": 999,
  "status": "enfileirado"
}

Guarde o id pra consultar a entrega depois (ou receba pelo webhook). Se algum número for inválido, a requisição inteira é recusada (HTTP 400) e nada é cobrado.

curl https://roma-sms.com/api/v1/saldo \
  -H "Authorization: Bearer rsk_seu_token_aqui"

{ "saldo_br": 999, "saldo_pt": 0 }

Consulta o status de um SMS pelo id devolvido no envio.

curl https://roma-sms.com/api/v1/sms/e2b1...-uuid \
  -H "Authorization: Bearer rsk_seu_token_aqui"

{
  "id": "e2b1...-uuid",
  "numero": "5511987654321",
  "status": "entregue",
  "creditos": 1,
  "motivo_falha": null,
  "criado_em": "2026-07-05T08:00:00.000Z",
  "enviado_em": "2026-07-05T08:00:03.000Z",
  "entregue_em": "2026-07-05T08:00:07.000Z"
}

Status possíveis: pendente, enviado, entregue, falha, expirado.

Em vez de ficar consultando o status, cadastre uma URL de webhook em Configurações → API. Quando a operadora confirmar cada SMS, a gente faz um POST pra você:

POST (a sua URL)
Content-Type: application/json
X-RomaSMS-Webhook-Event: sms.status
X-RomaSMS-Webhook-Timestamp: 1783238407
X-RomaSMS-Webhook-Signature: t=1783238407,v1=<hmac_sha256>

{
  "evento": "sms.status",
  "id": "e2b1...-uuid",
  "numero": "5511987654321",
  "status": "entregue",   // ou "falha"
  "motivo": null,          // motivo quando falha
  "data": "2026-07-05T08:00:07.000Z"
}

Valide X-RomaSMS-Webhook-Signature com HMAC SHA-256 sobre timestamp.payload, usando seu token da API como segredo.

Perfeito pra fluxos tipo confirmação de consulta: o paciente responde e o seu sistema é avisado na hora. Use uma URL https:// pública.

• Hoje o envio é só para Brasil (Portugal em breve).
• Até 1000 números por requisição; mensagem até 1600 caracteres.
• Cada SMS custa 1 crédito por 160 caracteres (mensagens longas contam mais).
• Limite de 120 requisições/minuto por token.
• A conta precisa estar verificada (celular confirmado) pra usar a API.
• Erros vêm como { "erro": "..." } com o HTTP correspondente (401 token, 402 saldo, 400 dados, 429 limite).