Visão geral

Acesso direto à API HTTP: base URL, autenticação Bearer, versionamento e o formato de erro.

O @wabroker/sdk (TypeScript) e o Wabroker.Sdk (.NET) são os caminhos recomendados — eles cuidam de autenticação, idempotência, tipos e verificação de webhook por você. Mas o broker é, por baixo, uma API HTTP/JSON, e você pode falar com ela direto de qualquer linguagem. Esta trilha documenta os endpoints tenant-scoped (/v1/*) tal como o broker os implementa.

Base URL

Todos os endpoints de tenant vivem sob /v1 na rota pública do broker:

text

https://api.grwthy.com/v1

Ajuste para o seu deployment

https://api.grwthy.com é a rota pública de referência. Se você opera um broker próprio, troque pela sua origem — o caminho /v1 e o contrato são os mesmos.

Autenticação

Toda requisição a /v1/* exige uma API key de tenant no header Authorization, no esquema Bearer. A key identifica o tenant e o broker escopa tudo a ele — você nunca envia um tenantId no corpo ou na query (se enviar, é descartado).

bash

curl https://api.grwthy.com/v1/channels \
  -H "Authorization: Bearer $WABROKER_API_KEY"

A key viaja só no header — nunca na URL, nunca no corpo, nunca em log.
Sem key, ou com uma key inválida/revogada: 401 unauthorized.
Um recurso de outro tenant responde 404 (indistinguível de inexistente), nunca 403.

A key é secreta — mantenha-a no servidor

A API key concede acesso total ao tenant. Guarde-a no backend (variável de ambiente); nunca a embarque num app cliente/browser. Veja Autenticação (na trilha Começar) para criar, rotacionar e revogar keys.

Requisições e respostas

Corpo de entrada e saída são application/json. Envie Content-Type: application/json em toda escrita (POST/PATCH/PUT).
Números de telefone são sempre E.164 sem o + (ex.: 5511999999999).
Envio de mensagem responde 202 Accepted (aceite, não confirmação de entrega); criação de recurso responde 201; leituras, 200.
Campos desconhecidos no corpo são ignorados (não é 400) — compatibilidade progressiva entre versões.

Versionamento

A versão do contrato está no caminho (/v1). Não há header de versão. Mudanças compatíveis (campos novos, códigos de erro novos) entram em /v1 sem quebrar clientes; uma quebra incompatível seria um /v2. Trate seus parsers de forma tolerante — ignore campos que não conhece.

Formato de erro

Toda falha é um JSON com forma estável. O code pertence à taxonomia fechada do broker (veja Erros) — trate-o exaustivamente. O httpStatus vem do próprio código.

json

{
  "code": "channel_disconnected",
  "message": "Canal desconectado",
  "retryable": true
}

campo	sempre?	descrição
`code`	sim	código da taxonomia fechada (veja Erros)
`message`	sim	texto legível — estável, nunca vaza dado de outro tenant
`retryable`	sim	true quando repetir a mesma requisição pode ter sucesso
`retryAfter`	só em 429	segundos a esperar — presente em rate_limited e queue_saturated
`traceId`	quando disponível	correlacionador para diagnóstico/suporte

Respeite retryAfter e retryable

Em 429, espere os segundos de retryAfter antes de repetir — não faça busy-retry. Para os demais, use retryable: false significa que repetir a mesma requisição falha do mesmo jeito. Um timeout de rede é incerteza, não falha — reconcilie (consulte o recurso) em vez de reenviar cegamente.