Tema
API para desenvolvedores
A API pública do Konversia permite que outro sistema, como o seu ERP ou uma plataforma de automação, envie mensagens de WhatsApp em nome da sua empresa e acompanhe o status de cada envio, sem passar pela tela. Ela também consulta horários livres e cria e gerencia os agendamentos da Agenda.
Este livro é para quem integra: aqui os nomes de campo, os métodos HTTP e os códigos de erro são o assunto. Se você procura o que a integração faz na prática, sem jargão técnico, veja Chaves de API no guia do produto.
Três formas de integrar
Todas usam a mesma chave de API e os mesmos escopos. A diferença é quem começa a conversa e quanto código você precisa escrever.
| Forma | Use quando | Precisa de código |
|---|---|---|
| API REST | O seu sistema é quem manda: um ERP disparando o boleto do mês, um e-commerce avisando que o pedido saiu | Sim, no seu servidor |
| Konversia Connect (webhooks) | Você quer reagir do lado de fora ao que acontece no Konversia, com Zapier, Make ou um endpoint seu | Pouco ou nenhum, se usar Zapier ou Make |
| MCP | Você quer operar o Konversia conversando com uma IA, como o Claude, pedindo as coisas em português | Não |
Elas se somam sem conflito: é comum um cliente ter o ERP integrado pela API REST, um Zap reagindo a conversas resolvidas e o MCP conectado para consultas do dia a dia.
O que já existe
- Canais: listar as linhas de WhatsApp da empresa e o que cada uma suporta.
- Templates: listar os modelos de mensagem aprovados, prontos para envio.
- Envio de mensagens: texto, mídia (em duas etapas) e template.
- Status de um envio: consultar o que aconteceu depois do aceite.
- Arquivos: subir um arquivo e reaproveitar um já enviado antes.
- Agenda: listar serviços, consultar horários livres, criar, remarcar, cancelar e confirmar agendamentos, e registrar pagamento.
- Webhooks: o Konversia avisando o seu sistema, em tempo real, quando algo muda no atendimento ou na agenda.
- Servidor MCP: as mesmas operações publicadas como ferramentas para uma IA, sem escrever código.
Por onde começar
- Autenticação: como identificar sua chave e o que cada permissão libera.
- Enviar mensagens: o guia completo de envio, a janela de 24 horas, mídia em duas etapas e idempotência.
- Agenda: serviços, horários livres e agendamentos, com o passo a passo de consultar e agendar.
- Erros: a tabela completa de códigos, o status HTTP de cada um e o que fazer.
- Webhooks: o envelope de evento, os dezenove tipos com exemplo de payload, como conferir a assinatura e os contratos de entrega.
- MCP: como conectar a empresa a uma IA, as dezessete ferramentas e os limites que valem.
Convenções
- Toda chamada vai para
https://konversia.com.br, com o caminho/api/v1. O endereço é o mesmo para todas as empresas: quem identifica a sua empresa é a chave de API, não o endereço. Por exemplo:https://konversia.com.br/api/v1/.... - Use o endereço exatamente assim, sem
www. Owwwredireciona para ele, e muitos clientes HTTP perdem o corpo de umPOSTquando seguem um redirecionamento. - O corpo das requisições e das respostas é sempre JSON, exceto o upload de arquivo, que é
multipart/form-data. - Toda resposta de erro segue o mesmo formato, descrito em Erros.
Aceite não é entrega
Um 202 Accepted num envio significa que a mensagem foi aceita e está na fila, não que ela já chegou ao cliente final. O status real vem em GET /v1/messages/{id}. Nenhuma resposta desta API usa a palavra "enviada" para descrever esse aceite.
Limites
- 120 requisições por minuto por chave de API. Passar do limite devolve
429com o códigorate_limited. O servidor MCP tem um limite próprio, de 60 por minuto, num balde separado deste. - Cota mensal de envios da empresa: a mesma que já vale para a tela, campanhas e automações (veja Limites de envio). Estourar a cota devolve
429com o códigoquota_exceeded. - Intervalo entre envios na linha não oficial: 8 a 25 segundos entre as mensagens da mesma linha, aplicado automaticamente para evitar bloqueio. Veja Intervalo entre envios.