> ## Documentation Index
> Fetch the complete documentation index at: https://disparo.ingrave.com.br/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API v1

> Referência dos endpoints públicos.

Base: `https://disparo.ingrave.com.br/api/v1`

Autenticação: cabeçalho `Authorization: Bearer <chave>`. A chave é da **organização** e é criada em **API e webhooks**.

Limite: **120 chamadas por minuto** por chave. Ao exceder, a API responde `429` com o cabeçalho de limite.

## GET /me

Dados da organização e do plano.

```json theme={"system"}
{ "organization": { "id": "...", "name": "...", "slug": "..." } }
```

## GET /connections

Conexões da organização (nome, provedor, status).

## GET /contacts

Lista contatos. Aceita `?phone=` para filtrar por número.

## POST /contacts

Cria ou atualiza o contato pelo telefone (idempotente).

| Campo | Tipo | Observação |
| - | - | - |
| `nome` | string | obrigatório |
| `telefone` | string | obrigatório; com DDD, o `55` é acrescentado |
| `email` | string | opcional |
| `observacoes` | string | opcional |
| `categoria` | string | pelo nome; criada se não existir |
| `consent` | boolean | `true` registra consentimento LGPD |
| `consentText` | string | texto do consentimento |
| `dataNascimento` / `birthday` | string | `AAAA-MM-DD`, `DD/MM/AAAA` ou `DD/MM` |

Resposta: `201` (criado) ou `200` (atualizado), com `created: true|false`.

## GET /campaigns

Lista campanhas (`?limit=`). Retorna id, nome, status, totais e datas.

## GET /campaigns/:id

Resultado de uma campanha (status, contadores e rastreio de links), sem a lista de contatos.

## POST /messages

Envia uma mensagem avulsa.

| Campo | Tipo | Observação |
| - | - | - |
| `telefone` | string | destino |
| `texto` | string | corpo da mensagem |
| `connectionName` | string | conexão; opcional se houver uma só |

A API respeita carência, descadastro e bloqueio do WhatsApp.

## Erros

| Código | Significado |
| - | - |
| `401` | chave ausente ou inválida |
| `429` | limite de chamadas excedido |
| `400` | dados inválidos (por exemplo, telefone ou data de nascimento) |