API de administração: administre clientes e números pelo seu sistema

Em resumo: uma chave de administração faz pela API o que o dono da conta faz no painel do ZapClaw. O seu sistema cria o cliente, gera a chave de API dele, envia o link de conexão, configura o webhook (inclusive no modo Chatwoot) e lê o número assim que ele conecta. Os seus clientes nunca abrem o ZapClaw.

O que uma chave de administração faz

• Clientes (contas de agência): criar, renomear, arquivar e reativar, cada um com o seu próprio externalId.
• Links de conexão: a página onde o seu cliente entra com o Facebook e lê o QR code, com um botão opcional de volta para o seu sistema.
• Números: saúde, limites, Phone Number ID e WABA ID; renomear, desconectar e mover entre clientes.
• Chaves de API dos clientes: criar e revogar as chaves zc_live_ que as integrações usam para enviar.
• Webhooks: o seu endpoint ou o Chatwoot, o segredo de assinatura, testes e reenvios.
• Tudo o que a chave de um cliente já faz, em qualquer cliente: templates, envio, mídia, perfil, QR codes, uso e registros.
• Eventos da conta num webhook seu: número conectado, desconectado ou restrito, link que expirou.

Algumas coisas ficam de propósito com uma pessoa no painel: senha e verificação em duas etapas, excluir a conta, cobrança e pagamentos, aceitar termos e aprovar o que um agente de IA quer enviar.

Autenticação

Envie a chave no cabeçalho X-API-Key. As rotas de administração ficam em https://api.zapclaw.app/api/v1/admin e indicam o cliente no caminho. Nas rotas que a chave de um cliente já chama, mande X-Client-Id para dizer em qual cliente você age.

curl https://api.zapclaw.app/api/v1/admin/clients \
  -H "X-API-Key: $ZAPCLAW_ADMIN_KEY"

Uma chave de administração enviada na URL é recusada e marcada como exposta. Uma chave com lista de IPs só atende chamadas desses endereços.

Permissões

Cada chave tem só as permissões marcadas ao criá-la. Administração completa marca todas; Conectar e configurar clientes marca o que um fluxo de cadastro precisa.

• clients:read, clients:write: ver e alterar clientes.
• numbers:read, numbers:write: números, saúde e limites; renomear, desconectar, mover, perfil, QR codes, automações e bloqueios.
• links:read, links:write: links de conexão e o histórico.
• keys:read, keys:write: chaves de API dos clientes.
• webhooks:read, webhooks:write, webhooks:secret: webhooks, entregas e o segredo de assinatura.
• templates:read, templates:write, messages:read, messages:send: templates e mensagens de qualquer cliente.
• usage:read, billing:read, audit:read: uso, limites por cliente, registros, plano, faturas e a atividade da conta (a cobrança é só de leitura).

Principais endpoints

GET    /api/v1/admin/key                                        the calling key
GET    /api/v1/admin/clients                                    clients:read
POST   /api/v1/admin/clients                                    clients:write
PATCH  /api/v1/admin/clients/{clientId}                         clients:write
POST   /api/v1/admin/clients/{clientId}/keys                    keys:write
POST   /api/v1/admin/clients/{clientId}/links                   links:write
GET    /api/v1/admin/clients/{clientId}/links/{linkId}          links:read
GET    /api/v1/admin/clients/{clientId}/numbers                 numbers:read
PUT    /api/v1/admin/clients/{clientId}/webhooks/{mode}         webhooks:write
GET    /api/v1/admin/clients/{clientId}/webhooks/{mode}/secret  webhooks:secret
GET    /api/v1/admin/clients/{clientId}/numbers/{numberId}/chatwoot-inbox numbers:read + webhooks:secret
PUT    /api/v1/admin/event-endpoint                             webhooks:write
GET    /api/v1/admin/activity                                   audit:read

Corpos, respostas e erros de cada rota estão na referência da API e no openapi.yaml.

Segredos aparecem uma vez

Uma chave de administração, uma chave de cliente ou um link de conexão novos voltam uma vez, na resposta que os cria, e o ZapClaw guarda só o hash. O segredo de assinatura do webhook é o único que pode ser lido de novo, com webhooks:secret, e cada leitura aparece na atividade da conta.

Saiba quando o número conectou

Cadastre um webhook de eventos da conta e o ZapClaw envia para ele, assinado no cabeçalho X-ZapClaw-Signature com um segredo próprio: client_link.used, number.connected, number.disconnected, number.restricted e client_link.expired. Também dá para consultar o link: o status vira connected e ele mostra o número.

Segurança

• Só o dono ou um administrador cria uma chave, confirmando com a senha e, quando ativo, o código da verificação em duas etapas. O dono recebe um e-mail.
• Até 10 chaves de administração ativas por conta. Uma chave revogada para na hora.
• Toda mudança feita com uma chave aparece em Configurações, Atividade, com o nome da chave.
• Uma chave nunca alcança outra conta, e todo cliente que ela indica é conferido com a sua.
• Quando quem criou a chave deixa de ser dono ou administrador, a chave para.