Autenticação
Toda requisição à API (exceto GET /v1/health) leva uma chave de API da sua empresa no
cabeçalho Authorization:
curl https://api.conectzap.app/v1/account \
-H "Authorization: Bearer $CONECTZAP_API_KEY"
A chave
-
Formato
czk_{env}_{keyId}_{secret}. O prefixo (czk_live_{keyId}) identifica a chave sem revelar o segredo. - A chave completa aparece uma única vez, na criação. O ConectZap guarda só um hash e não tem como mostrá-la de novo: se perder, crie outra e revogue a antiga.
- Guarde-a num cofre de segredos ou variável de ambiente do servidor. Nunca em código, repositório, aplicativo móvel ou página web, nem em URL.
-
Chave ausente, malformada, inexistente, revogada, vencida ou com segredo errado recebem o mesmo
401 unauthenticated, comWWW-Authenticate: Bearer, sem dizer o motivo.
Escopos
Cada operação exige um ou mais escopos (campo x-required-scopes na
referência). Chave sem o escopo recebe
403 forbidden. Dê a cada integração só o que ela usa.
| Escopo | Permite |
|---|---|
account:read |
consultar a conta da empresa |
api_keys:read, api_keys:write |
listar, criar e revogar chaves de API |
instances:read |
listar e consultar instâncias, status, eventos e métricas |
instances:write |
criar e alterar instâncias |
instances:delete |
remover instâncias |
instances:connect |
conectar, parear (QR Code), desconectar e reiniciar |
messages:send |
enviar, editar e apagar mensagens e criar uploads de mídia |
messages:read |
consultar metadados de mídia |
contacts:read |
verificar se números têm WhatsApp |
groups:read |
consultar grupos ao vivo na sessão |
webhooks:read, webhooks:write |
consultar e gerenciar webhooks |
realtime:subscribe |
emitir tickets do tempo real |
Chaves restritas a instâncias
Uma chave pode ser restrita a uma lista de instâncias. Ela só enxerga essas instâncias (outras
respondem 403) e não acessa recursos da empresa inteira: /account,
/api-keys, webhooks sem instanceId e upload de mídia respondem
403 forbidden. Use chaves restritas quando cada cliente final ou unidade tem o
próprio número.
Criar chaves pela API
Uma chave com api_keys:write pode criar outras, mas a nova chave nunca tem mais poder
do que quem a cria: só escopos que a criadora tem, só instâncias dela (se ela for restrita) e
expiração igual ou anterior à dela (se ela expirar). A expiração (expiresAt) é
opcional e usa RFC 3339 com fuso.
Revogação e vazamento
Revogue pelo painel ou por DELETE /v1/api-keys/{apiKeyId}. A revogação também fecha
as conexões de tempo real abertas com tickets dessa chave. Se uma chave
vazou, revogue-a primeiro e só depois crie a substituta.