Integração com a API DevZap
Guias para quem vai conectar um sistema à API. A referência campo a campo de cada endpoint fica
em /docs (OpenAPI interativo, exige login no painel); aqui está o que a referência não
cabe: por que as coisas são assim, o que costuma dar errado e como decidir entre as opções.
Trilha de leitura
Se você tem pressa, leia 01, depois 03 e 05. Isso cobre enviar mensagens e tratar erros direito, que é 90% de uma integração.
| Guia | Sobre |
|---|---|
| 01; Primeiros passos | Da chave de API à primeira mensagem enviada |
| 02; Conceitos | Tenant, instância, chave; ciclo de vida da conexão |
| 03; Envio de mensagens | Texto, mídia, envio direto × fila |
| 04; Webhooks | Receber mensagens, validar assinatura, lidar com repetição |
| 05; Erros e retry | Os três envelopes, o que retentar e como |
| 06; Limites e planos | Rate limit, cotas, recursos por plano |
| 07; Tempo real | WebSocket, e quando não usá-lo |
| 08; OAuth 2.1 | Fluxo para aplicações parceiras |
| 09; Receitas | Soluções prontas para tarefas comuns |
| 10; Agendamentos | Envio recorrente com conteúdo dinâmico via callback |
| 11; Erro 463 | Primeiro contato bloqueado, número restrito e a rota de limites |
| 12; Etiquetas | Etiquetas do WhatsApp Business: listar, quem tem cada uma, pôr e tirar |
| 13; Assistentes de IA | Claude, Cursor e outros clientes MCP consultando e enviando pela conta |
Onde cada coisa está documentada
Para não duplicar (e não divergir), a divisão é:
/docs: todo endpoint, todo campo, todo código de status, com exemplos executáveis.- Estes guias: narrativa, decisões, armadilhas e receitas.
Os guias linkam para operações específicas da referência, no formato
/docs#operation/sendMessage.
Uma nota sobre confiança
Esta documentação é verificada por testes automatizados. Os blocos de exemplo marcados com
<!-- fixture: ... --> são comparados com arquivos que, por sua vez, são testados contra o
servidor real a cada build. Os endpoints citados aqui são conferidos contra as rotas registradas.
Isso não torna a documentação infalível, mas significa que as partes verificáveis não podem divergir em silêncio. Se você encontrar uma diferença entre o que está escrito aqui e o que a API faz, é um bug, e vale reportar.
Estabilidade
A v1 é estável: campos não são removidos nem renomeados, e códigos de erro existentes não mudam
de significado. Podemos acrescentar campos nas respostas e novos valores em enums, trate
campos desconhecidos com tolerância e não assuma que um enum está fechado.
Mudanças incompatíveis, se acontecerem, virão em /api/v2.