API da VENUM

Recursos para máquinas

• OpenAPI 3.1 — descrição completa das rotas, esquemas e webhooks (/openapi.json).
• Catálogo de APIs — RFC 9727 (/.well-known/api-catalog).
• llms.txt e llms-full.txt — resumo do site para agentes de IA, com "quando usar".
• Qualquer página deste site responde em Markdown com Accept: text/markdown — ou em /<página>/index.md (esta aqui).
• Documentação no painel — exige login; mostra exatamente o que a sua conta consegue fazer.

Como obter uma chave

No painel (dash.venum.app.br), em Integrações, gere uma chave vnm_…. Chave somente leitura responde apenas aos GET; para enviar mensagem ou mover lead, gere uma de acesso total. A chave vale para uma conta e pode ser revogada a qualquer momento.

Autenticação

Mande a chave no cabeçalho Authorization. Toda rota exige.

curl https://dash.venum.app.br/api/v1/conta \
  -H "Authorization: Bearer vnm_SUACHAVE"

Rotas

Listas são paginadas (paginacao.pagina, limite, total) e vêm ordenadas da mais recente para a mais antiga. Cada contato traz janela_aberta: se o cliente escreveu nas últimas 24h, texto livre é entregue; passou disso, o WhatsApp exige um template aprovado. Valores monetários nas listas (valor) chegam como texto decimal (ex.: "249.90"); o filtro estagio ainda não aceita sem_resposta.

Enviar uma mensagem

curl -X POST https://dash.venum.app.br/api/v1/mensagens \
  -H "Authorization: Bearer vnm_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "telefone": "5547999990000", "texto": "Seu pedido saiu para entrega!" }'

Fora da janela de 24h, envie um template aprovado (se vierem texto e template juntos, vale o template):

{ "telefone": "5547999990000",
  "template": { "nome": "aviso_envio", "idioma": "pt_BR", "variaveis": ["Maria", "BR123456789"] } }

Resposta: { "enviada": true, "mensagem_id": "wamid…", "contato_id": 1234 }. Se o contato ainda não existir, ele é criado (e o evento contato.criado é emitido).

Mover um lead

Estágios: novo, atendimento, qualificado, adiado, sem_resposta, ganho, perdido.

curl -X PATCH https://dash.venum.app.br/api/v1/leads/1234 \
  -H "Authorization: Bearer vnm_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "estagio": "ganho", "valor": 249.90, "produto": "Plano anual" }'

Marcar ganho com valor maior que zero cria o pedido e envia a conversão para a Meta — exatamente como se alguém tivesse clicado no painel. A resposta traz pedido_id e capi.enviada. Valor negativo é recusado (valor_invalido). Para adiado, informe retomar_em (AAAA-MM-DD) e, se quiser, retomar_motivo.

Webhooks

Cadastre um endereço em Integrações, escolha os eventos e responda com qualquer 2xx em até 10 segundos. Outra resposta, ou tempo esgotado, faz a VENUM tentar de novo em 5, 30, 120 e 360 minutos (5 tentativas no total; depois a entrega fica marcada como falha no painel). Cada entrega vem com User-Agent: Venum-Webhook/1 e os cabeçalhos X-Venum-Event, X-Venum-Delivery e X-Venum-Signature (t=<timestamp>,v1=<hmac>).

{
  "evento": "lead.mudou_estagio",
  "criado_em": "2026-08-24T18:00:00.000Z",
  "conta_id": 12,
  "dados": { "contato_id": 1234, "estagio": "ganho", "rotulo": "Ganho", "valor": 249.9, "pedido_id": 88, "capi_enviada": true }
}

Confira a assinatura. Calcule HMAC-SHA256 de t + "." + corpo cru com o segredo do endpoint e compare com v1; recuse se t tiver mais de 5 minutos.

Quando dá errado

Erro sempre vem com um código estável em erro (trate por ele) e um texto em mensagem (mostre para a pessoa).

Precisa de mais?

Um evento ou campo que não está aqui? A lista cresce conforme o uso. Fale com a gente pelo WhatsApp.