# Catálogo de endpoints do AtendroZAP

**64 operações em 58 caminhos**, geradas de [openapi.json](openapi.json).
Autenticação, parâmetros, corpos e respostas completos estão no OpenAPI.
Leia primeiro o [guia de integração](ATENDRO_INTEGRATION.md).

A coluna de testes aponta para fixtures locais; não atesta execução contra WhatsApp real.
Os testes `TestOpenAPICoversRouter` e `TestOpenAPIAuthenticationMatchesRouter` também verificam todas as operações.
Resultados executados: [API_VALIDATION.md](API_VALIDATION.md).

## Diagnóstico

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `GET /health/live` | `público` | Verificar processo HTTP | — | `TestLivenessAndReadiness` |
| `GET /health/ready` | `público` | Verificar banco acessível | — | `TestLivenessAndReadiness` |
| `GET /v1/capabilities` | `admintoken` | Consultar capacidades | — | `TestCapabilitiesReportLaboratoryScope`, `TestInitCreatesCallsInstances` |

## Instâncias

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /instance/init` | `admintoken` | Criar instância e emitir token | 15 min | `TestInitCreatesInstanceAndReturnsTokenOnce`, `TestInitValidatesNames`, `TestIdempotentSendAndInit`, `TestInitCreatesCallsInstances` |
| `GET /instance/all` | `admintoken` | Listar instâncias do servidor | — | `TestInitCreatesInstanceAndReturnsTokenOnce` |
| `POST /instance/connect` | `token` | Conectar ou iniciar pareamento | — | `TestConnectReturnsRenderedQRCode`, `TestConnectValidatesPairingPhone` |
| `GET /instance/status` | `token` | Consultar sessão e webhook | — | `TestStatusReportsConnectedSession`, `TestStatusExposesDisconnectCodeAndLimits` |
| `POST /instance/disconnect` | `token` | Desvincular e limpar credencial | — | `TestDisconnectRestartAndDelete` |
| `POST /instance/restart` | `token` | Reiniciar preservando credencial | — | `TestDisconnectRestartAndDelete` |
| `DELETE /instance` | `token` | Excluir instância | — | `TestDisconnectRestartAndDelete` |

## Administração

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `GET /v1/instances/{id}` | `admintoken` | Consultar instância por ID | — | `TestAdminRoutesByInstanceID` |
| `DELETE /v1/instances/{id}` | `admintoken` | Excluir instância por ID | — | `TestAdminRoutesByInstanceID` |
| `POST /v1/instances/{id}/connect` | `admintoken` | Conectar instância por ID | — | `TestAdminRoutesByInstanceID` |
| `POST /v1/instances/{id}/disconnect` | `admintoken` | Desvincular instância por ID | — | `TestAdminRoutesByInstanceID` |
| `POST /v1/instances/{id}/restart` | `admintoken` | Reiniciar instância por ID | — | `TestAdminRoutesByInstanceID` |
| `POST /v1/instances/{id}/token` | `admintoken` | Reemitir token da instância | — | `TestTokenReissueByInstanceID` |
| `POST /admin/restart` | `admintoken` | Reiniciar sessões deste worker | — | `TestChatFindAndAdminRoutes` |

## Mensagens

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /send/text` | `token` | Enviar texto | 24 h | `TestSendTextReturnsRealMessageID`, `TestSendTextMapsSessionErrors`, `TestIdempotentSendAndInit` |
| `POST /send/media` | `token` | Enviar mídia | 24 h | `TestSendMediaValidatesAndForwards`, `TestSendMediaFromAllowlistedURL` |
| `POST /send/contact` | `token` | Enviar contato | 24 h | `TestSendContactAndLocation` |
| `POST /send/location` | `token` | Enviar localização | 24 h | `TestSendContactAndLocation` |
| `POST /send/menu` | `token` | Enviar botões, lista ou enquete | 24 h | `TestSendMenuParsesLegacyChoices` |
| `POST /message/forward` | `token` | Encaminhar mensagem guardada | 24 h | `TestMessageActionRoutes` |
| `POST /message/react` | `token` | Reagir ou remover reação | 24 h | `TestMessageActionRoutes` |
| `POST /message/delete` | `token` | Apagar mensagem própria para todos | 24 h | `TestMessageActionRoutes` |
| `POST /message/edit` | `token` | Editar texto ou legenda própria | 24 h | `TestMessageActionRoutes` |
| `PUT /message/edit` | `token` | Editar mensagem (alias PUT) | 24 h | `TestMessageActionRoutes` |

## Consultas

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /message/find` | `token` | Buscar mensagens no formato legado | — | `TestFindMessagesLegacyShape`, `TestPhoneChatFiltersResolveThroughTheSession` |
| `GET /message/status/{id}` | `token` | Consultar resultado da mensagem | — | `TestMessageListingStatusAndEvents` |
| `GET /v1/messages` | `token` | Listar mensagens no formato interno | — | `TestMessageListingStatusAndEvents` |
| `POST /chat/check` | `token` | Verificar números no WhatsApp | — | `TestReadCheckAndDetails` |
| `POST /chat/details` | `token` | Obter identidade e foto | — | `TestReadCheckAndDetails` |
| `POST /chat/find` | `token` | Listar conversas conhecidas | — | `TestChatFindAndAdminRoutes` |

## Mídia

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /message/download` | `token` | Obter link assinado de mídia | — | `TestDownloadAndServeMedia` |
| `GET /v1/media/{token}` | `link assinado` | Ler bytes pelo link assinado | — | `TestDownloadAndServeMedia` |

## Leitura

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /message/markread` | `token` | Enviar recibos de leitura por ID | — | `TestReadCheckAndDetails` |
| `POST /chat/read` | `token` | Marcar recebidas do chat como lidas | — | `TestReadCheckAndDetails` |

## Grupos

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `GET /group/list` | `token` | Listar grupos sincronizados | — | `TestGroupRoutesFollowTheLegacyContract` |
| `POST /group/info` | `token` | Consultar grupo | — | `TestGroupRoutesFollowTheLegacyContract` |
| `POST /group/create` | `token` | Criar grupo | 24 h | `TestGroupRoutesFollowTheLegacyContract` |
| `POST /group/updateParticipants` | `token` | Alterar participantes | 24 h | `TestGroupRoutesFollowTheLegacyContract` |
| `POST /group/updateName` | `token` | Alterar nome do grupo | 24 h | `TestGroupRoutesFollowTheLegacyContract` |
| `POST /group/updateImage` | `token` | Alterar imagem do grupo | 24 h | `TestGroupRoutesFollowTheLegacyContract` |

## Proxy

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `GET /instance/proxy` | `token` | Consultar proxy da instância | — | `TestInstanceProxyRoutes` |
| `POST /instance/proxy` | `token` | Configurar proxy ou conexão direta | — | `TestInstanceProxyRoutes`, `TestProxyRequiredWorkerRefusesDirectMode` |

## Webhooks

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /webhook` | `token` | Configurar, desativar ou herdar webhook | — | `TestWebhookRegistrationAndEvents`, `TestCallWebhookSubscription` |
| `GET /webhook` | `token` | Consultar webhook e entrega | — | `TestWebhookRegistrationAndEvents` |
| `GET /webhook/errors` | `token` | Consultar falhas recentes de entrega | — | `TestWebhookRegistrationAndEvents` |
| `GET /v1/events` | `token` | Inspecionar eventos internos e fila | — | `TestMessageListingStatusAndEvents`, `TestWebhookRegistrationAndEvents` |
| `POST /v1/events/{id}/replay` | `token` | Reenfileirar evento | — | `TestWebhookRegistrationAndEvents` |
| `POST /v1/webhook` | `admintoken` | Salvar ou remover webhook global | — | `TestGlobalAndAdminWebhooks` |
| `GET /v1/webhook` | `admintoken` | Consultar webhook global | — | `TestGlobalAndAdminWebhooks` |
| `POST /v1/instances/{id}/webhook` | `admintoken` | Configurar, desativar ou herdar webhook por ID | — | `TestGlobalAndAdminWebhooks` |
| `GET /v1/instances/{id}/webhook` | `admintoken` | Consultar webhook e entrega por ID | — | `TestGlobalAndAdminWebhooks` |
| `GET /v1/instances/{id}/webhook/errors` | `admintoken` | Consultar falhas recentes de entrega por ID | — | `TestGlobalAndAdminWebhooks` |

## Ligações

| Método e caminho | Header | Operação | Idempotência | Testes locais |
|---|---|---|---|---|
| `POST /call/make` | `token` | Iniciar ligação por instância calls | 24 h | `TestCallRoutesOnACallsInstance`, `TestCallRoutesAreGatedByKind`, `TestCallRoutesMapSessionErrors` |
| `POST /call/answer` | `token` | Atender ligação recebida | — | `TestCallRoutesOnACallsInstance`, `TestCallRoutesAreGatedByKind`, `TestCallRoutesMapSessionErrors` |
| `POST /call/reject` | `token` | Recusar ligação recebida | — | `TestCallRoutesOnACallsInstance`, `TestCallRoutesAreGatedByKind`, `TestCallRoutesMapSessionErrors` |
| `POST /call/hangup` | `token` | Encerrar ligação | — | `TestCallRoutesOnACallsInstance`, `TestCallRoutesAreGatedByKind`, `TestCallRoutesMapSessionErrors` |
| `GET /call/active` | `token` | Listar ligações ativas | — | `TestCallRoutesOnACallsInstance`, `TestCallRoutesAreGatedByKind` |
| `GET /call/{id}` | `token` | Consultar estado de ligação | — | `TestCallRoutesOnACallsInstance` |
| `GET /call/{id}/audio` | `token` | Abrir ponte WebSocket de áudio | — | `TestCallAudioAcceptsTheTokenInTheQuery`, `TestCallRoutesAreGatedByKind` |
| `GET /call/history` | `token` | Consultar histórico de chamadas | — | `TestCallHistoryRoutesArePrivateAndWorkOffline`, `TestCallHistoryFilters` |
| `GET /call/{id}/recording` | `token` | Ouvir ou baixar gravação | — | `TestCallRecordingFilesArePrivate`, `TestCallHistoryRoutesArePrivateAndWorkOffline` |

## Fora da URL base da API

`GET /metrics` pertence ao listener opcional `ATENDROZAP_METRICS_ADDR`, para operação interna.
O console centraliza a documentação em `https://wpp.atendro.cloud`: `GET/HEAD /docs`, `/openapi.json`, `/llms.txt` e os documentos públicos vinculados são servidos sem autenticação, fora do catálogo operacional. Os antigos caminhos na API redirecionam para a central; as operações da API usam a URL do servidor selecionado.

## Manutenção

Atualizar o OpenAPI junto com qualquer rota e executar:

```sh
python3 scripts/sync_api_docs.py
python3 scripts/sync_api_docs.py --check
go test ./internal/httpapi -run TestOpenAPI -v
```

O script confere referências locais, parâmetros de caminho, headers de autenticação e sincronização do catálogo.
Ele não é um validador completo da especificação OpenAPI nem de todos os payloads possíveis.