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).
- 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) comcodeestável. - Paginação por cursor (
limit,cursor) — nunca por offset. POSTque cria efeitos aceitaIdempotency-Key(24 h de retenção).- Envio de mensagens é assíncrono:
202 Accepted+ statusqueued; o resultado final chega por webhook / realtime (message.sent,message.updated,message.failed). - Idioma:
Accept-Languageescolhept-BR(padrão),enouespara 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: optionalnã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)/v1fica 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
/v1nesta versão. - Painel (ADR-045): o painel do cliente (
app.conectzap.app) usa as operações de conta, instância, webhook ecreateRealtimeTicketpor 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 seminstanceId, mídia de upload):403 forbidden.
Respostas incluem RateLimit-Policy, RateLimit e, em 429, Retry-After. Os limites dependem do plano do tenant.