ConectZap · Documentação

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

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.