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.
É 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 revogada402conta suspensa ou teto de excedente do mês atingido403recurso fora do seu plano (OTP, remetente verificado)409remetente ainda não verificado429limite de requisições por minuto — respeite tenteEmSegundos