Messageria

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.

WhatsApp

É a mesma rota, com canal: "whatsapp". O que muda é uma regra da Meta que a plataforma não deixa você esquecer: fora da janela de 24 horas, só entra modelo aprovado. Dentro dela, cabe texto livre.

A janela abre quando o cliente final responde, e só então. Mensagem que a empresa manda não abre nada, por mais que ela queira.

curl -X POST https://sms.avilaops.com/api/v1/mensagens   -H "authorization: Bearer sk_live_..."   -H "content-type: application/json"   -d '{
    "canal": "whatsapp",
    "para": "(17) 99999-8888",
    "modelo": "pedido_confirmado",
    "variaveis": ["Maria", "4821"]
  }'
curl -X POST https://sms.avilaops.com/api/v1/mensagens   -H "authorization: Bearer sk_live_..."   -H "content-type: application/json"   -d '{
    "canal": "whatsapp",
    "para": "(17) 99999-8888",
    "texto": "Seu pedido saiu para entrega."
  }'

O número é seu: cada conta conecta o próprio WhatsApp Business em Painel → WhatsApp. A plataforma não empresta número compartilhado, porque no WhatsApp quem a Meta bloqueia é o número, e a campanha ruim de um cliente derrubaria a entrega de todos.

GET /api/v1/whatsapp/modelos lista os modelos e o status de cada um na Meta. POST com {"acao":"sincronizar"} traz de lá; sem isso, submete um modelo novo para aprovação.

Catálogo

Produto com foto e preço dentro da conversa. O catálogo é criado no Commerce Manager da Meta e ligado ao seu número em POST /api/v1/whatsapp/catalogo; os produtos entram por aqui.

curl -X POST https://sms.avilaops.com/api/v1/whatsapp/catalogo/produtos   -H "authorization: Bearer sk_live_..."   -H "content-type: application/json"   -d '{
    "sincronizar": true,
    "produtos": [{
      "sku": "CAM-AZUL-M",
      "nome": "Camiseta azul M",
      "precoCentavos": 7990,
      "imagemUrl": "https://sualoja.com.br/f/cam.jpg",
      "link": "https://sualoja.com.br/p/cam"
    }]
  }'

O sku é o mesmo código do seu sistema: mandar de novo atualiza, não duplica. Preço vai em centavos, sempre inteiro, porque ponto flutuante é como R$ 19,90 vira R$ 19,89 no aparelho de alguém.

Sem sincronizar: true, o produto fica pendente e vai para a Meta na próxima sincronização. É de propósito: uma loja que atualiza cem produtos em cinco chamadas não deve gastar cinco idas à Meta.

curl -X POST https://sms.avilaops.com/api/v1/mensagens   -H "authorization: Bearer sk_live_..."   -H "content-type: application/json"   -d '{
    "canal": "whatsapp",
    "para": "(17) 99999-8888",
    "produto": "CAM-AZUL-M",
    "texto": "Separei este para você:"
  }'

Até 30 produtos por mensagem, usando produtos no lugar de produto. Mensagem de produto é conteúdo livre, então também exige a janela de 24 horas aberta. DELETE na mesma rota de produtos desativa: sai da Meta e continua aqui, para o histórico de quem citou aquele SKU seguir fazendo sentido.

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