ConectZap API (1.0.0-draft.1)

API REST multi-tenant para instâncias WhatsApp.

Contrato preliminar da API pública do ConectZap (/v1).

Contrato próprio do ConectZap (ADR-026). Modelo de produto — API de passagem (ADR-025): o ConectZap mantém sessões de WhatsApp Web ativas e conecta chatbots, ERPs e CRMs. Não armazena conversas: mensagens recebidas, status de entrega e eventos de conexão chegam somente por webhook (e realtime). Não há endpoints de histórico, contatos ou conversas guardados. Consultas como grupos e verificação de número são feitas ao vivo na sessão. Mídia recebida fica disponível por URL temporária (padrão 24 h). Este arquivo é a fonte de verdade do contrato: o código do gateway é gerado/validado a partir dele (ver conectzap-code-standards).

Convenções

  • Autenticação: Authorization: Bearer <api_key> (chave por tenant, com escopos).
  • IDs públicos são opacos e prefixados (inst_, msg_, whk_, med_, key_, evt_, dlv_, iev_).
  • Erros seguem RFC 9457 (application/problem+json) com code estável.
  • Paginação por cursor (limit, cursor) — nunca por offset.
  • POST que cria efeitos aceita Idempotency-Key (24 h de retenção).
  • Envio de mensagens é assíncrono: 202 Accepted + status queued; o resultado final chega por webhook / realtime (message.sent, message.updated, message.failed).
  • Idioma: Accept-Language escolhe pt-BR (padrão), en ou es para os textos de erro; o contrato (caminhos, campos, code, enums) não depende do idioma (ADR-034).
  • Datas em RFC 3339 UTC.
  • Recursos marcados com x-conectzap-tier: optional não fazem parte do MVP.
  • Estabilidade: enquanto a versão for 1.0.0-draft.* o contrato pode mudar. A partir do GA (Fase 08) /v1 fica congelado: apenas adições compatíveis.
  • Telefones: E.164 somente dígitos, sem +.
  • Usuários, convites e papéis do painel são geridos pelo AuthGateway (interno, não público), fora de /v1 nesta versão.
  • Painel (ADR-045): o painel do cliente (app.conectzap.app) usa as operações de conta, instância, webhook e createRealtimeTicket por uma ponte de sessão do AuthGateway (/api/v1/*, interna, não pública), com os escopos do papel da pessoa. Não há contrato novo: as respostas são as mesmas deste documento. O painel não monta as rotas de mensagem, mídia, contatos, grupos nem chaves de API de /v1.
  • Chaves restritas a instâncias não acessam recursos de tenant inteiro (/account, /api-keys, webhooks sem instanceId, mídia de upload): 403 forbidden.

Limites de taxa

Respostas incluem RateLimit-Policy, RateLimit e, em 429, Retry-After. Os limites dependem do plano do tenant.

Aviso

O runtime atual usa um cliente não oficial do WhatsApp Web (Baileys). Recursos podem mudar sem aviso por decisão da Meta. O contrato é independente de provedor (campo provider da instância) para permitir a API oficial Cloud API no futuro.

Servers
Produção (ambiente único, ADR-023)
https://api.conectzap.app/v1