# Rotas da API e métodos da chave

Gerado da lista de métodos da própria API (`npm run skills:gerar`). Cada chave só chama os métodos marcados nela
(Minha Conta › Integrações › Chaves de API); sem o método, 403 `insufficient_scope`. Marque sempre `account.read`:
a skill confere por ele de qual CNPJ é a chave.

- **Tipo**: o limite por minuto em que a chamada entra (leitura, alteração ou envio — veja `GET /v1/account/limits`).
- **Sandbox** (chave `ocs_test_pk_`): *real* devolve o dado verdadeiro da conta; *simulado* confere tudo e responde
  sem enviar, gravar nem cobrar (`dryRun`); *recusado* responde 403 `test_key_not_allowed`.

## Conta, plano e limites

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `api.index` | `GET /v1` | Leitura | real | O que a API faz, o ambiente da chave e os métodos que ela pode chamar (toda chave chama) |
| `account.read` | `GET /v1/account` | Leitura | real | Conta e plano: em vigor ou vencendo, validade, dias restantes e cadastro da empresa |
| `account.limits` | `GET /v1/account/limits` | Leitura | real | Limites atuais: requisições da API, janela de envio, tetos por campanha e por disparo |
| `account.credits` | `GET /v1/account/credits` | Leitura | real | Saldo de créditos por canal |

## Erros, falhas e uso da API

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `account.health` | `GET /v1/account/health` | Leitura | real | Diagnóstico da conta: plano, saldo, números, provedores, webhook e campanhas pausadas |
| `account.apiUsage` | `GET /v1/account/api-usage` | Leitura | real | Uso da API por dia, método e chave, com erros e recusas por limite |
| `account.apiErrors` | `GET /v1/account/api-errors` | Leitura | real | Últimas chamadas da API que deram erro, com o código e o id da requisição |

## Envio para um contato

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `messages.whatsapp.send` | `POST /v1/whatsapp/messages` | Envio | simulado | Enviar WhatsApp para um contato |
| `messages.whatsappOfficial.send` | `POST /v1/whatsapp-official/messages` | Envio | simulado | Enviar WhatsApp Oficial (modelo aprovado) para um contato |
| `messages.sms.send` | `POST /v1/sms/messages` | Envio | simulado | Enviar SMS para um contato |
| `messages.email.send` | `POST /v1/email/messages` | Envio | simulado | Enviar e-mail para um contato |
| `calls.voice.create` | `POST /v1/voice/calls` | Envio | simulado | Fazer uma ligação de voz com IA |
| `messages.video.send` | `POST /v1/video/messages` | Envio | simulado | Enviar vídeo com avatar para um contato |
| `messages.list` | `GET /v1/messages` | Leitura | real | Listar os últimos envios avulsos da conta (de todos os contatos) |
| `messages.get` | `GET /v1/messages/{messageId}` | Leitura | real | Status de um envio (enviado, entregue, lido, respondido, falhou) |

## Disparo em massa

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `dispatches.create` | `POST /v1/dispatches/mass` | Envio | simulado | Disparo em massa: até 30 mil contatos em WhatsApp, SMS, e-mail e voz |
| `dispatches.list` | `GET /v1/dispatches` | Leitura | real | Listar os últimos disparos em massa |
| `dispatches.get` | `GET /v1/dispatches/{dispatchId}` | Leitura | real | Andamento de um disparo em massa |
| `dispatches.results` | `GET /v1/dispatches/{dispatchId}/results` | Leitura | real | Resultado de cada contato de um disparo, com o motivo das falhas |
| `dispatches.cancel` | `DELETE /v1/dispatches/{dispatchId}` | Alteração | simulado | Parar um disparo em massa |

## LGPD

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `lgpd.optIn` | `POST /v1/lgpd/opt-in-log` | Alteração | simulado | Registrar o consentimento (opt-in) de um contato |

## Números de WhatsApp

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `channels.list` | `GET /v1/channels` | Leitura | real | Números de WhatsApp da conta e se estão conectados |
| `channels.addNumber` | `POST /v1/channels/add-number` | Alteração | recusado | Conectar um número de WhatsApp (QR Code) |

## Cobrança

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `billing.renewPlan` | `POST /v1/billing/renew-plan` | Alteração | recusado | Gerar a cobrança Pix da renovação do plano (responde com o plano vencido) |
| `billing.rechargeCredits` | `POST /v1/billing/recharge-credits` | Alteração | recusado | Gerar a cobrança Pix de uma recarga de créditos |
| `billing.paymentStatus` | `GET /v1/billing/payments/{paymentId}` | Leitura | real | Status de uma cobrança Pix (responde com o plano vencido) |

## Webhooks de eventos

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `webhook.get` | `GET /v1/webhook` | Leitura | real | Ver o webhook de eventos da conta |
| `webhook.set` | `PUT /v1/webhook` | Alteração | recusado | Cadastrar ou alterar o webhook de eventos |
| `webhook.delete` | `DELETE /v1/webhook` | Alteração | recusado | Remover o webhook de eventos |
| `webhook.rotateSecret` | `POST /v1/webhook/rotate-secret` | Alteração | recusado | Trocar o segredo da assinatura do webhook |
| `webhook.test` | `POST /v1/webhook/test` | Alteração | recusado | Mandar um aviso de teste ao webhook |
| `webhook.deliveries` | `GET /v1/webhook/deliveries` | Leitura | real | Histórico de entregas do webhook (7 dias) |

## Contatos e lista de bloqueio

| Método | Chamada | Tipo | Sandbox | O que faz |
| --- | --- | --- | --- | --- |
| `blocklist.list` | `GET /v1/blocklist` | Leitura | real | Listar a lista de bloqueio da conta |
| `blocklist.add` | `POST /v1/blocklist` | Alteração | recusado | Bloquear contatos |
| `blocklist.remove` | `DELETE /v1/blocklist/{blockId}` | Alteração | recusado | Desfazer um bloqueio feito pela conta |
| `blocklist.check` | `POST /v1/blocklist/check` | Leitura | real | Conferir se contatos estão bloqueados |