# API da VENUM

> Tudo em JSON, sobre HTTPS, na base `https://dash.venum.app.br/api/v1`. Uma chave de API dá acesso a uma conta — a mesma que aparece no painel de quem gerou a chave. Webhooks avisam o seu sistema em vez de ele ficar perguntando.

Página: https://venum.app.br/desenvolvedores/ · [OpenAPI 3.1](https://venum.app.br/openapi.json) · [Catálogo de APIs (RFC 9727)](https://venum.app.br/.well-known/api-catalog) · [llms.txt](https://venum.app.br/llms.txt) · [Documentação no painel (login)](https://dash.venum.app.br/integracoes/docs)

## Como obter uma chave

No painel (https://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.

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

## Rotas

| Método | Rota | O que faz |
| --- | --- | --- |
| GET | `/api/v1/conta` | Confirma a chave e mostra a conta (o "ping" da integração). |
| GET | `/api/v1/contatos` | Lista contatos — filtros: `estagio` (novo, atendimento, qualificado, adiado, ganho, perdido), `desde` (AAAA-MM-DD), `busca`, `limite` (até 200), `pagina`. |
| GET | `/api/v1/pedidos` | Vendas registradas, com resumo (quantidade, valor total, recebido, a receber) — filtros: `desde`, `ate`, `status` (`recebido` / `a_receber`). |
| POST | `/api/v1/mensagens` | Envia mensagem pelo WhatsApp da conta: texto (janela de 24h) ou template aprovado. |
| PATCH | `/api/v1/leads/{id}` | Move o lead no funil; `ganho` com valor cria o pedido e dispara a API de Conversões. |

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

```bash
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):

```json
{ "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`.

```bash
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>`).

```json
{
  "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.

| Evento | Quando |
| --- | --- |
| `mensagem.recebida` | O cliente mandou mensagem (é assim que um contato novo vindo do WhatsApp aparece) |
| `mensagem.enviada` | Alguém — ou a IA — respondeu |
| `contato.criado` | A própria API criou o contato num POST /api/v1/mensagens para um telefone novo |
| `lead.mudou_estagio` | O lead andou no funil (inclui ganho e perdido) |
| `pedido.criado` | Uma venda foi registrada, com valor |
| `agendamento.criado` | Reservado — ainda não é emitido pela plataforma |
| `agendamento.cancelado` | Reservado — ainda não é emitido pela plataforma |

## 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).

| HTTP | erro | Significado |
| --- | --- | --- |
| 400 | `estagio_invalido`, `data_invalida`, `telefone_invalido`… | Pedido malformado — a mensagem diz o que corrigir |
| 401 | `nao_autorizado` | Chave ausente, errada ou revogada |
| 403 | `sem_permissao` | Chave é somente leitura e a rota escreve |
| 404 | `nao_encontrado` | O id não existe nesta conta |
| 409 | `conta_desconectada` | O WhatsApp não está conectado no painel |
| 422 | `falha_no_envio` | A Meta recusou — o texto explica (ex.: fora da janela de 24h) |

## Precisa de mais?

Um evento ou campo que não está aqui? A lista cresce conforme o uso. Fale com a gente: https://wa.me/5547936183868