# Visão geral da API

Fonte: https://apiwpp.com/docs/api
Seção: Referência
Atualizado em: 2026-09-29

O endereço base da API é `https://api.apiwpp.com`. As requisições e as respostas são JSON: envie `Content-Type: application/json` nas requisições com corpo.

**Autenticação.** Toda operação recebe uma chave de API (`wag_live_…`), como `Authorization: Bearer <chave>` ou `X-Api-Key: <chave>`. A chave pertence a um projeto e só alcança os recursos dele. Cada operação indica o escopo de que a chave precisa (veja [Escopos](https://apiwpp.com/docs/referencia/escopos)); só o download de mídia dispensa a chave, porque a URL assinada é a credencial. Detalhes em [Autenticação](https://apiwpp.com/docs/autenticacao).

**Erros** respondem `{ "error": "…" }` com o status HTTP; alguns acrescentam `code` (como `number_limit_reached`) e `message`, e a validação do corpo responde `400` com `code: "FST_ERR_VALIDATION"`. Decida pelo status e pelo `code`, nunca pelo texto. `401` é chave ausente, desconhecida, revogada ou expirada; `403` é permissão que falta (um escopo, citado na mensagem, ou um recurso do plano); um recurso de outra pessoa responde `404`, exatamente como um que não existe. Veja [Erros](https://apiwpp.com/docs/guias/erros) e [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro).

**Limites.** Por padrão, cada IP de origem faz até 600 requisições por minuto, e, depois de 20 chaves erradas em 5 minutos, as próximas chaves erradas desse IP também recebem `429` (a chave certa continua aceita); os dois limites respondem com `Retry-After`. Os envios entram numa fila com ritmo controlado por número: `POST /connections/{id}/send` responde `202` com o job. Todos os números estão em [Limites](https://apiwpp.com/docs/referencia/limites).

**Listas.** Os registros (`GET /messages` e `GET /webhooks/deliveries`) devolvem os itens mais recentes primeiro, sem paginação por cursor: `limit` vale 60 por padrão e no máximo 200.

## Conexões

| Método | Caminho | Operação |
| --- | --- | --- |
| `POST` | `/connections` | [Criar conexão](https://apiwpp.com/docs/api/conexoes/criar-conexao): Criar uma conexão de WhatsApp |
| `GET` | `/connections/{id}/qr` | [QR code e status](https://apiwpp.com/docs/api/conexoes/qr-code-e-status): Obter o QR code e o status da conexão |
| `POST` | `/connections/{id}/pairing-code` | [Código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento): Obter um código de pareamento para conectar um número sem o QR code |
| `POST` | `/connections/{id}/disconnect` | [Desconectar](https://apiwpp.com/docs/api/conexoes/desconectar): Desconectar uma conexão do WhatsApp |
| `GET` | `/connections` | [Listar conexões](https://apiwpp.com/docs/api/conexoes/listar-conexoes): Listar conexões |
| `POST` | `/connections/{id}/logout` | [Sair do WhatsApp](https://apiwpp.com/docs/api/conexoes/sair-do-whatsapp): Sair do WhatsApp (logout) |
| `GET` | `/connections/{id}/groups` | [Listar grupos](https://apiwpp.com/docs/api/conexoes/listar-grupos): Listar grupos |
| `GET` | `/connections/{id}/proxy` | [Consultar proxy](https://apiwpp.com/docs/api/conexoes/consultar-proxy): Obter o proxy de uma conexão |
| `PUT` | `/connections/{id}/proxy` | [Definir proxy](https://apiwpp.com/docs/api/conexoes/definir-proxy): Definir o proxy de uma conexão |
| `DELETE` | `/connections/{id}/proxy` | [Remover proxy](https://apiwpp.com/docs/api/conexoes/remover-proxy): Remover o proxy de uma conexão |
| `GET` | `/connections/{id}/dedicated-ip` | [IP dedicado](https://apiwpp.com/docs/api/conexoes/ip-dedicado): Obter o IP dedicado de uma conexão |

## Mensagens

| Método | Caminho | Operação |
| --- | --- | --- |
| `POST` | `/connections/{id}/send` | [Enviar mensagem](https://apiwpp.com/docs/api/mensagens/enviar-mensagem): Enfileirar uma mensagem para envio |
| `GET` | `/connections/{id}/queue` | [Fila do número](https://apiwpp.com/docs/api/mensagens/fila-do-numero): Consultar a fila de uma conexão |
| `POST` | `/connections/{id}/react` | [Reagir](https://apiwpp.com/docs/api/mensagens/reagir): Reagir a uma mensagem |
| `POST` | `/connections/{id}/messages/{messageId}/edit` | [Editar mensagem](https://apiwpp.com/docs/api/mensagens/editar-mensagem): Editar uma mensagem enviada |
| `DELETE` | `/connections/{id}/queue/{jobId}` | [Cancelar da fila](https://apiwpp.com/docs/api/mensagens/cancelar-mensagem-na-fila): Cancelar uma mensagem na fila |
| `DELETE` | `/connections/{id}/messages/{messageId}` | [Apagar mensagem](https://apiwpp.com/docs/api/mensagens/apagar-mensagem): Apagar uma mensagem enviada para todos |
| `POST` | `/connections/{id}/read` | [Marcar como lidas](https://apiwpp.com/docs/api/mensagens/marcar-como-lidas): Marcar mensagens recebidas como lidas |
| `POST` | `/connections/{id}/presence` | [Mostrar presença](https://apiwpp.com/docs/api/mensagens/mostrar-presenca): Mostrar uma presença em uma conversa |

## Projetos

| Método | Caminho | Operação |
| --- | --- | --- |
| `PATCH` | `/tenants/{id}` | [Atualizar projeto](https://apiwpp.com/docs/api/projetos/atualizar-projeto): Atualizar um projeto |
| `GET` | `/tenants` | [Listar projetos](https://apiwpp.com/docs/api/projetos/listar-projetos): Listar projetos |
| `GET` | `/tenants/{id}` | [Consultar projeto](https://apiwpp.com/docs/api/projetos/consultar-projeto): Consultar um projeto |
| `DELETE` | `/tenants/{id}` | [Desativar projeto](https://apiwpp.com/docs/api/projetos/desativar-projeto): Desativar um projeto |
| `POST` | `/tenants/webhook-test` | [Testar webhook](https://apiwpp.com/docs/api/projetos/testar-webhook): Testar um endpoint de webhook |
| `GET` | `/tenants/{id}/connections` | [Conexões do projeto](https://apiwpp.com/docs/api/projetos/listar-conexoes-do-projeto): Listar as conexões de um projeto |
| `POST` | `/tenants/{id}/connections` | [Criar conexão no projeto](https://apiwpp.com/docs/api/projetos/criar-conexao-no-projeto): Criar uma conexão no projeto |
| `GET` | `/tenants/{id}/connections/{connId}` | [Consultar conexão](https://apiwpp.com/docs/api/projetos/consultar-conexao): Consultar uma conexão |
| `DELETE` | `/tenants/{id}/connections/{connId}` | [Excluir conexão](https://apiwpp.com/docs/api/projetos/excluir-conexao): Excluir uma conexão |
| `GET` | `/tenants/{id}/connections/{connId}/heartbeats` | [Histórico de heartbeats](https://apiwpp.com/docs/api/projetos/historico-de-heartbeats): Histórico de heartbeats da conexão |
| `GET` | `/tenants/{id}/connections/{connId}/qr` | [QR code como imagem](https://apiwpp.com/docs/api/projetos/qr-code-como-imagem): Obter o QR code como imagem |
| `POST` | `/tenants/{id}/connections/{connId}/disconnect` | [Desconectar conexão](https://apiwpp.com/docs/api/projetos/desconectar-conexao-do-projeto): Desconectar uma conexão |
| `POST` | `/tenants/{id}/connections/{connId}/connect` | [Reconectar conexão](https://apiwpp.com/docs/api/projetos/reconectar-conexao): Conectar de novo uma conexão |

## Contatos

| Método | Caminho | Operação |
| --- | --- | --- |
| `POST` | `/connections/{id}/contacts/check` | [Verificar números](https://apiwpp.com/docs/api/contatos/verificar-numeros): Verificar se números estão no WhatsApp |
| `GET` | `/connections/{id}/profile/{phone}` | [Perfil do contato](https://apiwpp.com/docs/api/contatos/perfil-do-contato): Consultar o perfil de um contato |

## Templates

| Método | Caminho | Operação |
| --- | --- | --- |
| `POST` | `/connections/{id}/templates` | [Criar template](https://apiwpp.com/docs/api/templates/criar-template): Criar um template de mensagem |
| `GET` | `/connections/{id}/templates` | [Listar templates](https://apiwpp.com/docs/api/templates/listar-templates): Listar os templates |
| `GET` | `/connections/{id}/templates/{name}` | [Consultar template](https://apiwpp.com/docs/api/templates/consultar-template): Consultar um template pelo nome |
| `PUT` | `/connections/{id}/templates/{name}` | [Atualizar template](https://apiwpp.com/docs/api/templates/atualizar-template): Atualizar um template |
| `DELETE` | `/connections/{id}/templates/{name}` | [Excluir template](https://apiwpp.com/docs/api/templates/excluir-template): Excluir um template |

## Chaves de API

| Método | Caminho | Operação |
| --- | --- | --- |
| `GET` | `/tenants/{id}/api-keys` | [Listar chaves](https://apiwpp.com/docs/api/chaves-de-api/listar-chaves): Listar as chaves de API de um projeto |
| `POST` | `/tenants/{id}/api-keys` | [Criar chave](https://apiwpp.com/docs/api/chaves-de-api/criar-chave): Criar uma chave de API |
| `POST` | `/tenants/{id}/api-keys/{keyId}/rotate` | [Rotacionar chave](https://apiwpp.com/docs/api/chaves-de-api/rotacionar-chave): Rotacionar uma chave de API |
| `DELETE` | `/tenants/{id}/api-keys/{keyId}` | [Revogar chave](https://apiwpp.com/docs/api/chaves-de-api/revogar-chave): Revogar uma chave de API |

## Conta

| Método | Caminho | Operação |
| --- | --- | --- |
| `GET` | `/me` | [Quem está chamando](https://apiwpp.com/docs/api/conta/quem-esta-chamando): Quem está chamando |

## Uso

| Método | Caminho | Operação |
| --- | --- | --- |
| `GET` | `/tenants/{id}/usage` | [Uso do projeto](https://apiwpp.com/docs/api/uso/uso-do-projeto): Consultar o uso de um projeto |
| `GET` | `/usage/daily` | [Uso diário](https://apiwpp.com/docs/api/uso/uso-diario): Totais diários de mensagens dos projetos de quem chama (de todos, para a plataforma) |

## Registros

| Método | Caminho | Operação |
| --- | --- | --- |
| `GET` | `/messages` | [Listar mensagens](https://apiwpp.com/docs/api/registros/listar-mensagens): Listar as mensagens registradas |
| `GET` | `/webhooks/deliveries` | [Entregas de webhook](https://apiwpp.com/docs/api/registros/listar-entregas-de-webhook): Listar as entregas de webhook |
| `POST` | `/webhooks/deliveries/resend-dead` | [Reenviar entregas mortas](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas): Reenviar todas as entregas de webhook mortas |
| `POST` | `/webhooks/deliveries/{id}/resend` | [Reenviar entrega](https://apiwpp.com/docs/api/registros/reenviar-entrega): Reenviar uma entrega de webhook |

## Mídia

| Método | Caminho | Operação |
| --- | --- | --- |
| `GET` | `/media/{connectionId}/{fileName}` | [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia): Baixar um arquivo de mídia |

## Webhooks

Os eventos chegam por `POST` ao `webhookBaseUrl` do projeto.

- [`connection.status`](https://apiwpp.com/docs/webhooks/connection-status): A conexão abriu, fechou ou foi restringida
- [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming): Alguém escreveu para o número
- [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing): O número enviou uma mensagem (opcional: emitOutgoing)
- [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery): Uma mensagem enviada pelo número mudou de status
- [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed): Um envio na fila com clientRef não vai acontecer
- [`message.reaction`](https://apiwpp.com/docs/webhooks/message-reaction): Alguém reagiu a uma mensagem
- [`contact.resolved`](https://apiwpp.com/docs/webhooks/contact-resolved): Um remetente conhecido só pelo LID agora tem telefone
- [`group.joined`](https://apiwpp.com/docs/webhooks/group-joined): O número entrou num grupo
- [`group.left`](https://apiwpp.com/docs/webhooks/group-left): O número foi removido de um grupo
- [`group.updated`](https://apiwpp.com/docs/webhooks/group-updated): Um grupo do número mudou
- [`ping`](https://apiwpp.com/docs/webhooks/ping): O teste de um endpoint de webhook
