# AtendroZAP

> API HTTP de integração WhatsApp para o Atendro. Instâncias, mensagens, grupos, consultas e webhooks. Documentação central em https://wpp.atendro.cloud/docs. As requisições REST usam a URL do servidor selecionado; a API do servidor 1 é https://1.atendro.cloud.

Notas de integração:
- Administração usa `admintoken`; operações de instância usam `token`. A query `?token=` é aceita somente na ponte de áudio WebSocket; o console usa o header no backend. Bearer não substitui essas credenciais.
- Credenciais são privadas e específicas de cada servidor/instância; esta documentação não contém segredos reais.
- Webhook global por servidor em `/v1/webhook`, herdado pelas instâncias sem exceção. O receptor AtendroZAP valida HMAC SHA-256 sobre timestamp + ponto + corpo bruto.
- `504 send_ambiguous/action_ambiguous` exige reconciliação pelo ID antes de reenviar. Idempotência depende da rota e dos mesmos bytes da requisição.
- Ligações exigem `capabilities.calls=true` e instância `kind=calls` conectada. `/call/make` mantém 501 nas instâncias de mensagens; áudio usa WebSocket e o evento `call` é entregue quando inscrito.
- Contrato em fase `laboratory`. Os exemplos têm valores sintéticos; testes não equivalem a homologação de números reais.

## Guias

- [Primeiros passos](https://wpp.atendro.cloud/docs/guias/primeiros-passos.md): Cadastro, teste de acesso e primeira instância.
- [Servidores e autenticação](https://wpp.atendro.cloud/docs/guias/autenticacao.md): URL base, admintoken, token da instância e proteção de credenciais.
- [Ciclo de vida da instância](https://wpp.atendro.cloud/docs/guias/instancias.md): Criação, pareamento, estados, reinício e desvinculação.
- [Configurar webhooks](https://wpp.atendro.cloud/docs/guias/webhooks.md): Destino global por servidor, herança, exceções e eventos disponíveis.
- [Implementar o receptor](https://wpp.atendro.cloud/docs/guias/receber-eventos.md): Corpo bruto, assinatura HMAC, deduplicação e vínculo com a empresa.
- [Payloads e entrega de eventos](https://wpp.atendro.cloud/docs/guias/eventos.md): Envelope, tipos de evento, recibos, retries e reprocessamento.
- [Erros e idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md): Status HTTP, resultados ambíguos e repetição segura de requisições.
- [Chamadas de voz](https://wpp.atendro.cloud/docs/guias/chamadas-de-voz.md): Instâncias calls, discagem, eventos e áudio pelo painel.
- [Compatibilidade](https://wpp.atendro.cloud/docs/guias/compatibilidade.md): Diferenças de contrato e comportamento em relação ao consumidor legado.
- [Validação e limites](https://wpp.atendro.cloud/docs/guias/validacao.md): Testes executados, publicação e pendências de homologação.

## Diagnóstico

Disponibilidade do serviço e capacidades do servidor.

- [GET /health/live](https://wpp.atendro.cloud/docs/api/health-live.md): Verificar processo HTTP. Sem autenticação; não atesta banco nem WhatsApp.
- [GET /health/ready](https://wpp.atendro.cloud/docs/api/health-ready.md): Verificar banco acessível. 200 não significa instância conectada nem integração homologada.
- [GET /v1/capabilities](https://wpp.atendro.cloud/docs/api/get-capabilities.md): Consultar capacidades. Fonte para habilitar funcionalidades. Para voz, exigir capabilities.calls=true e instance_kinds contendo calls. status=laboratory.

## Instâncias

Crie, conecte e acompanhe sessões de WhatsApp.

- [POST /instance/init](https://wpp.atendro.cloud/docs/api/create-instance.md): Criar instância e emitir token. Não pareia nem conecta. Guardar instance.id e instance.token no backend; listar não recupera o token. kind=whatsapp por padrão; kind=calls cria um dispositivo vinculado próprio para voz.
- [GET /instance/all](https://wpp.atendro.cloud/docs/api/list-instances.md): Listar instâncias do servidor. Array direto. Nunca inclui token; qrcode é vazio. companyId é filtro administrativo, não isolamento de autenticação.
- [POST /instance/connect](https://wpp.atendro.cloud/docs/api/connect-instance.md): Conectar ou iniciar pareamento. Abre conexão real; exige autorização para laboratório. Aguarda até 5 s por QR/login; acompanhar /instance/status. Sem phone: QR; com phone: paircode.
- [GET /instance/status](https://wpp.atendro.cloud/docs/api/get-instance-status.md): Consultar sessão e webhook. Sem iniciar conexão. Usar connected e loggedIn; QR/código podem estar presentes durante pareamento.
- [POST /instance/disconnect](https://wpp.atendro.cloud/docs/api/disconnect-instance.md): Desvincular e limpar credencial. Logout, distinto de restart. unlinked informa confirmação remota.
- [POST /instance/restart](https://wpp.atendro.cloud/docs/api/restart-instance.md): Reiniciar preservando credencial. Reabre sessão; não usar como rotina de validação de cadastro.
- [DELETE /instance](https://wpp.atendro.cloud/docs/api/delete-instance.md): Excluir instância. Logout em melhor esforço e exclusão definitiva; somente após autorização do responsável.

## Administração

Gerencie instâncias por ID usando o token administrativo.

- [GET /v1/instances/{id}](https://wpp.atendro.cloud/docs/api/admin-get-instance.md): Consultar instância por ID. Ação administrativa com admintoken, sem precisar do token da instância. Mesmos efeitos da rota de instância.
- [DELETE /v1/instances/{id}](https://wpp.atendro.cloud/docs/api/admin-delete-instance.md): Excluir instância por ID. Ação administrativa com admintoken, sem precisar do token da instância. Mesmos efeitos da rota de instância.
- [POST /v1/instances/{id}/connect](https://wpp.atendro.cloud/docs/api/admin-connect-instance.md): Conectar instância por ID. Ação administrativa com admintoken, sem precisar do token da instância. Mesmos efeitos da rota de instância.
- [POST /v1/instances/{id}/disconnect](https://wpp.atendro.cloud/docs/api/admin-disconnect-instance.md): Desvincular instância por ID. Ação administrativa com admintoken, sem precisar do token da instância. Mesmos efeitos da rota de instância.
- [POST /v1/instances/{id}/restart](https://wpp.atendro.cloud/docs/api/admin-restart-instance.md): Reiniciar instância por ID. Ação administrativa com admintoken, sem precisar do token da instância. Mesmos efeitos da rota de instância.
- [POST /v1/instances/{id}/token](https://wpp.atendro.cloud/docs/api/admin-reissue-token.md): Reemitir token da instância. O novo segredo aparece nesta resposta. graceSeconds=0 revoga o anterior imediatamente; máximo 3600. Não possui idempotência.
- [POST /admin/restart](https://wpp.atendro.cloud/docs/api/admin-restart-worker.md): Reiniciar sessões deste worker. Soft restart das sessões do worker que atende a requisição. Não reinicia processo nem todos os workers do cluster.

## Enviar mensagens

Envie texto, mídia, contato, localização e menus.

- [POST /send/text](https://wpp.atendro.cloud/docs/api/send-text.md): Enviar texto. Retorna ID real do WhatsApp, não ID de fila. linkPreview é ignorado.
- [POST /send/media](https://wpp.atendro.cloud/docs/api/send-media.md): Enviar mídia. URL depende da allowlist de mídia. PTT requer OGG/Opus; sem transcodificação outros formatos saem como áudio comum.
- [POST /send/contact](https://wpp.atendro.cloud/docs/api/send-contact.md): Enviar contato. Contato vCard; number é o destinatário e phoneNumber é o telefone do contato.
- [POST /send/location](https://wpp.atendro.cloud/docs/api/send-location.md): Enviar localização. Coordenadas obrigatórias; suporta citação e marca de encaminhada.
- [POST /send/menu](https://wpp.atendro.cloud/docs/api/send-menu.md): Enviar botões, lista ou enquete. renderMode=auto tenta nativo e pode cair para enquete/texto. rendered informa o formato entregue. 3 botões; 4–10 respostas podem virar lista; até 10 linhas; enquetes 2–12 opções. call: e carousel recusados.

## Ações em mensagens

Encaminhe, reaja, edite e apague mensagens armazenadas.

- [POST /message/forward](https://wpp.atendro.cloud/docs/api/forward-message.md): Encaminhar mensagem guardada. Rota própria do AtendroZAP. Faz novo envio; mídias são baixadas e reenviadas, com marca de encaminhada.
- [POST /message/react](https://wpp.atendro.cloud/docs/api/react-message.md): Reagir ou remover reação. Chat vem do ID guardado; number é ignorado. text vazio remove a reação.
- [POST /message/delete](https://wpp.atendro.cloud/docs/api/delete-message.md): Apagar mensagem própria para todos. Mensagem recebida retorna cannot_delete. recorded=false indica WhatsApp aceitou mas o banco não gravou. Repetida pode retornar alreadyDeleted.
- [POST /message/edit](https://wpp.atendro.cloud/docs/api/edit-message.md): Editar texto ou legenda própria. Janela de 20 min. id/messageid do resultado identificam o original; editId identifica a ação. recorded=false exige reconciliação.
- [PUT /message/edit](https://wpp.atendro.cloud/docs/api/edit-message-put.md): Editar mensagem (alias PUT). Mesmo contrato de POST /message/edit. Trocar POST por PUT com a mesma Idempotency-Key muda o hash da requisição.

## Conversas e consultas

Consulte conversas, mensagens, números e perfis.

- [POST /message/find](https://wpp.atendro.cloud/docs/api/find-messages.md): Buscar mensagens no formato legado. Ordem mais recente primeiro. includeHistory=true por padrão; histórico nunca dispara automações novas. id ausente no store retorna messages=[].
- [GET /message/status/{id}](https://wpp.atendro.cloud/docs/api/get-message-status.md): Consultar resultado da mensagem. Estados internos em minúsculas; usar para reconciliar resultado ambíguo. Preferir ID bruto messageid devolvido no envio.
- [GET /v1/messages](https://wpp.atendro.cloud/docs/api/list-stored-messages.md): Listar mensagens no formato interno. Até 200, sem offset. Para paginação e formato legado use /message/find.
- [POST /chat/check](https://wpp.atendro.cloud/docs/api/check-numbers.md): Verificar números no WhatsApp. 1–50 telefones; number é alias singular de numbers. Exige sessão conectada.
- [POST /chat/details](https://wpp.atendro.cloud/docs/api/get-chat-details.md): Obter identidade e foto. Foto em cache por 24 h; campos vazios dependem de privacidade do WhatsApp. Não devolver dados de terceiros em logs.
- [POST /chat/find](https://wpp.atendro.cloud/docs/api/find-chats.md): Listar conversas conhecidas. Não consulta histórico remoto sob demanda. wa_lastMsgTimestamp e wa_lastMessageTime estão em segundos. Sem filtros de lead/etiqueta.

## Mídia

Baixe arquivos e use URLs assinadas com prazo de validade.

- [POST /message/download](https://wpp.atendro.cloud/docs/api/download-message-media.md): Obter link assinado de mídia. Pode buscar mídia no WhatsApp e pedir reenvio ao celular; não é uma consulta sem efeitos. Link vence com retenção de 48 h, use expiresAt.
- [GET /v1/media/{token}](https://wpp.atendro.cloud/docs/api/get-signed-media.md): Ler bytes pelo link assinado. Sem header token: a credencial é o token na URL assinada devolvida pela API. Não registrar/compartilhar o link. Expirado ou inválido retorna 404. Não aceita upload.

## Leitura

Marque mensagens ou conversas como lidas.

- [POST /message/markread](https://wpp.atendro.cloud/docs/api/mark-messages-read.md): Enviar recibos de leitura por ID. Até 1000 IDs; mensagens próprias e desconhecidas são ignoradas. Afeta leitura no WhatsApp.
- [POST /chat/read](https://wpp.atendro.cloud/docs/api/mark-chat-read.md): Marcar recebidas do chat como lidas. Envia recibo para até 100 mensagens ainda não lidas. read=false retorna marked=0 e note; não há suporte a marcar como não lido.

## Grupos

Consulte e gerencie grupos com as permissões da conta.

- [GET /group/list](https://wpp.atendro.cloud/docs/api/list-groups.md): Listar grupos sincronizados. Contrato implementado; homologação real de grupos pendente. force=true consulta WhatsApp; noparticipants=true omite Participants.
- [POST /group/info](https://wpp.atendro.cloud/docs/api/get-group-info.md): Consultar grupo. Cache de 10 min; force=true atualiza. getInviteLink só retorna link para administrador. getRequestsParticipants ignorado.
- [POST /group/create](https://wpp.atendro.cloud/docs/api/create-group.md): Criar grupo. Nome até 100 caracteres e até 50 participantes na criação. Conferir Error por participante. Exige autorização para grupo de teste.
- [POST /group/updateParticipants](https://wpp.atendro.cloud/docs/api/update-group-participants.md): Alterar participantes. add/remove/promote/demote. approve/reject retornam 400 invalid_action. Conferir Error por participante e atualizar o grupo.
- [POST /group/updateName](https://wpp.atendro.cloud/docs/api/update-group-name.md): Alterar nome do grupo. Nome até 100 caracteres. Efeito real em grupo; homologação de laboratório pendente.
- [POST /group/updateImage](https://wpp.atendro.cloud/docs/api/update-group-image.md): Alterar imagem do grupo. JPEG/PNG/GIF até 8 MiB; corpo JSON até 12 MiB; convertido em JPEG até 640×640. remove/delete removem a foto.

## Proxy da instância

Consulte e configure a conexão de rede da instância.

- [GET /instance/proxy](https://wpp.atendro.cloud/docs/api/get-instance-proxy.md): Consultar proxy da instância. Credenciais da URL são redigidas; não há pool gerenciado nem fallback automático.
- [POST /instance/proxy](https://wpp.atendro.cloud/docs/api/set-instance-proxy.md): Configurar proxy ou conexão direta. custom sonda conectividade antes de gravar. internal significa conexão direta; none exige confirm_no_proxy=true. Mudança pode reiniciar sessão; não usar para testar cadastro.

## Webhooks e eventos

Configure destinos, acompanhe a entrega e reprocesse eventos.

- [POST /webhook](https://wpp.atendro.cloud/docs/api/configure-webhook.md): Configurar, desativar ou herdar webhook. Um destino efetivo por instância. Cadastro cria exceção ao global. URL nova começa após o backlog; mesma URL preserva cursor e segredo omitido. action=delete desativa inclusive em mudanças globais; action=inherit volta ao global. groups e call são entregues; qrcode continua ignorado. call é emitido pelas instâncias calls.
- [GET /webhook](https://wpp.atendro.cloud/docs/api/get-webhook.md): Consultar webhook e entrega. Sem cadastro: registered=false, webhooks=[]. Com cadastro inclui webhooks=[registro] e deliveryStatus. Nunca revela o secret.
- [GET /webhook/errors](https://wpp.atendro.cloud/docs/api/get-webhook-errors.md): Consultar falhas recentes de entrega. Falhas deste worker, sem payload; também inclui estado persistido quando houver webhook.
- [GET /v1/events](https://wpp.atendro.cloud/docs/api/list-events.md): Inspecionar eventos internos e fila. Formato persistido difere do envelope legado entregue. Consultar EVENTS.md. Não expor payloads em logs.
- [POST /v1/events/{id}/replay](https://wpp.atendro.cloud/docs/api/replay-event.md): Reenfileirar evento. Reinicia orçamento de tentativas; pode repetir automações no consumidor. Deduplicar pelo ID do evento. Exige avaliação antes do replay real.
- [POST /v1/webhook](https://wpp.atendro.cloud/docs/api/configure-global-webhook.md): Salvar ou remover webhook global. Configuração persistida por servidor. Instâncias sem exceção herdam automaticamente. Atualização transacional preserva configurações próprias. action=delete limpa o global; a configuração salva prevalece sobre bootstrap por ambiente. Segredo nunca é devolvido.
- [GET /v1/webhook](https://wpp.atendro.cloud/docs/api/get-global-webhook.md): Consultar webhook global. Configuração persistida por servidor. Instâncias sem exceção herdam automaticamente. Atualização transacional preserva configurações próprias. action=delete limpa o global; a configuração salva prevalece sobre bootstrap por ambiente. Segredo nunca é devolvido.
- [POST /v1/instances/{id}/webhook](https://wpp.atendro.cloud/docs/api/admin-configure-webhook.md): Configurar, desativar ou herdar webhook por ID. Um destino efetivo por instância. Cadastro cria exceção ao global. URL nova começa após o backlog; mesma URL preserva cursor e segredo omitido. action=delete desativa inclusive em mudanças globais; action=inherit volta ao global. groups e call são entregues; qrcode continua ignorado. call é emitido pelas instâncias calls.
- [GET /v1/instances/{id}/webhook](https://wpp.atendro.cloud/docs/api/admin-get-webhook.md): Consultar webhook e entrega por ID. Sem cadastro: registered=false, webhooks=[]. Com cadastro inclui webhooks=[registro] e deliveryStatus. Nunca revela o secret.
- [GET /v1/instances/{id}/webhook/errors](https://wpp.atendro.cloud/docs/api/admin-get-webhook-errors.md): Consultar falhas recentes de entrega por ID. Falhas deste worker, sem payload; também inclui estado persistido quando houver webhook.

## Chamadas de voz

Chamadas 1:1 por instância calls, com módulo habilitado e ponte de áudio.

- [POST /call/make](https://wpp.atendro.cloud/docs/api/make-call.md): Iniciar ligação por instância calls. Exige kind=calls conectado e módulo ligado. Retorna 201 ao iniciar; acompanhar o estado. Em instância whatsapp mantém 501 calls_not_supported. Não equivale à chamada sem áudio do provedor legado.
- [POST /call/answer](https://wpp.atendro.cloud/docs/api/answer-call.md): Atender ligação recebida. Token da instância calls que possui a chamada. Corpo com callId; a operação renova o lease antes do efeito externo.
- [POST /call/reject](https://wpp.atendro.cloud/docs/api/reject-call.md): Recusar ligação recebida. Token da instância calls que possui a chamada. Corpo com callId; a operação renova o lease antes do efeito externo.
- [POST /call/hangup](https://wpp.atendro.cloud/docs/api/hangup-call.md): Encerrar ligação. Token da instância calls que possui a chamada. Corpo com callId; a operação renova o lease antes do efeito externo.
- [GET /call/active](https://wpp.atendro.cloud/docs/api/list-active-calls.md): Listar ligações ativas. Lista as chamadas vivas da instância calls neste worker.
- [GET /call/{id}](https://wpp.atendro.cloud/docs/api/get-call.md): Consultar estado de ligação. Consulta chamada viva ou recém-encerrada mantida na memória deste worker.
- [GET /call/{id}/audio](https://wpp.atendro.cloud/docs/api/stream-call-audio.md): Abrir ponte WebSocket de áudio. Upgrade WebSocket. PCM s16le mono 16 kHz binário nos dois sentidos; origem validada por ATENDROZAP_CALLS_AUDIO_ORIGINS. Aceita token no header ou na query somente nesta rota. O console faz proxy com o header e guarda o token fora do navegador. Fechar o socket encerra a chamada; um segundo socket substitui o primeiro. Códigos 4000 encerrada, 4001 PCM ímpar, 4002 falha de escrita, 4003 substituído.

## Contratos e modelos

- [OpenAPI 3.1](https://wpp.atendro.cloud/openapi.json): Métodos, autenticação, schemas e respostas das 62 operações.
- [Documentação completa](https://wpp.atendro.cloud/llms-full.txt): Guias, endpoints e modelos reunidos em texto.
- [Modelos de dados](https://wpp.atendro.cloud/docs/modelos.md): Índice dos 75 modelos, com links individuais.
- [Validador de assinatura](https://wpp.atendro.cloud/docs/examples/verify-webhook.mjs): Exemplo de HMAC sobre o corpo bruto com Web Crypto.

## Optional

- [Runbooks](https://wpp.atendro.cloud/docs/RUNBOOKS.md): Operação e recuperação.
- [Gates de piloto](https://wpp.atendro.cloud/docs/PILOT_GATES.md): Pendências para ativação de clientes.