Avila SMS

API

REST, JSON, autenticação por chave no header. Toda chamada é da conta dona da chave — não existe parâmetro de conta, e por isso não existe como pedir mensagem de outro cliente.

Autenticação

Mande a chave em Authorization: Bearer sk_live_.... Chaves sk_test_ percorrem o fluxo inteiro — id, status, webhook — sem sair para a operadora e sem custo. Número de teste terminado em 0000 falha de propósito, para você exercitar o tratamento de erro.

  • Sinal30 requisições por minuto
  • Alcance120 requisições por minuto
  • Operação600 requisições por minuto

Enviar

POST /api/v1/mensagens — para aceita um número ou uma lista de até 500. O número pode vir como o cliente cadastrou: normalizamos para E.164, completamos o nono dígito e recusamos DDD que não existe.

curl -X POST https://sms.avilaops.com/api/v1/mensagens \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821-confirmacao" \
  -d '{
    "para": "(17) 99999-8888",
    "texto": "Pedido #4821 confirmado. Sai para entrega hoje ate as 18h.",
    "remetenteId": "rem_...",
    "simplificar": true
  }'
{
  "id": "cmf2k...",
  "para": "+5517999998888",
  "status": "ENVIADA",
  "segmentos": 1,
  "alfabeto": "GSM-7",
  "custo": 0.11,
  "operadora": "twilio",
  "criadoEm": "2026-08-27T12:03:11.204Z"
}

Idempotency-Key protege reenvio por timeout: a mesma chave devolve a mesma mensagem em vez de cobrar de novo. Com lista, cada destino ganha um sufixo próprio.

Consultar

GET /api/v1/mensagens/:id devolve o status atual e a linha do tempo de eventos da operadora. GET /api/v1/mensagens?limite=50&status=FALHOU lista o histórico.

Código de acesso (OTP)

A plataforma gera, envia e guarda só o hash. O código nunca volta pela API — nem em ambiente de teste. Expira em 5 minutos e queima em 5 tentativas erradas.

# 1. envia o código
curl -X POST https://sms.avilaops.com/api/v1/otp/enviar \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"para": "17999998888", "marca": "Sua Loja"}'

# 2. confere o que a pessoa digitou
curl -X POST https://sms.avilaops.com/api/v1/otp/verificar \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"para": "17999998888", "codigo": "418302"}'
# -> {"valido": true, "para": "+5517999998888", ...}

Consumo

GET /api/v1/uso devolve franquia, consumo do mês e quanto já entrou como excedente. Serve para o seu sistema avisar o financeiro antes da fatura, não depois.

Remetentes

GET /api/v1/remetentes lista os perfis e o estágio de verificação. POST /api/v1/remetentes pede um novo. Todo perfil nasce em análise — quem aprova é gente, depois que a operadora homologa o identificador.

Webhook de status

Cadastre a URL no painel. Cada mudança de status chega assinada; confira a assinatura antes de confiar no corpo, senão qualquer um na internet declara "entregue" para você.

POST https://seu-sistema.com.br/sms
x-avila-assinatura: 9f2c...   # HMAC-SHA256 do corpo, com o segredo do webhook

{
  "evento": "sms.entregue",
  "mensagemId": "cmf2k...",
  "para": "+5517999998888",
  "status": "ENTREGUE",
  "em": "2026-08-27T12:03:19.881Z"
}

Descadastro

Quem responde SAIR (ou PARE, CANCELAR, STOP) entra na lista de opt-out da sua conta na hora e para de receber. VOLTAR reativa. Código de acesso continua saindo: quem pediu para sair da lista de avisos ainda precisa entrar na própria conta.

Erros

Sempre JSON com erro e, quando dá para tratar em código, um codigo estável:

  • 401chave ausente, inválida ou revogada
  • 402conta suspensa ou teto de excedente do mês atingido
  • 403recurso fora do seu plano (OTP, remetente verificado)
  • 409remetente ainda não verificado
  • 429limite de requisições por minuto — respeite tenteEmSegundos