API Reference — Visão Geral

Base URL

https://apicrm.galdix.com.br

Em desenvolvimento local: http://localhost:3001

Autenticação

A maioria dos endpoints requer autenticação via Bearer token do Clerk.

Authorization: Bearer <clerk_jwt_token>

O token é obtido automaticamente pelo SDK do Clerk no frontend. Em testes manuais (curl/Postman), gere um token na dashboard do Clerk.

Endpoints públicos (sem auth)

Endpoints marcados com @Public() no código não precisam de token:

• GET /webhooks/whatsapp — verificação de hub Meta
• POST /webhooks/whatsapp — webhooks Meta (HMAC em vez de JWT)
• POST /webhooks/clerk — webhooks Clerk (Svix signature)
• GET /go/:token — redirect de campanha
• GET /go/unsubscribe/:token — opt-out WhatsApp
• GET/POST /public/survey/* — pesquisas de satisfação
• GET/POST /email-tracking/* — rastreamento de email

Endpoints internos (Internal API Key)

Alguns endpoints são protegidos por INTERNAL_API_KEY em vez de JWT:

Authorization: Bearer <INTERNAL_API_KEY>

Padrões de resposta

Sucesso

// Lista paginada
{
  "data": [...],
  "total": 150,
  "page": 1,
  "limit": 20
}

// Objeto único
{
  "id": "...",
  "field": "value"
}

Erro

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Códigos de status

Código	Significado
200	OK
201	Created
204	No Content
400	Bad Request (validação)
401	Unauthorized (token ausente ou inválido)
403	Forbidden (sem permissão ou role insuficiente)
404	Not Found
409	Conflict (recurso já existe)
429	Too Many Requests (rate limit)
500	Internal Server Error

Headers importantes

Header	Descrição
x-correlation-id	UUID de rastreamento da request (gerado automaticamente se ausente)
x-org-id	Override de organização (apenas Super Admin)
Authorization	Bearer token do Clerk ou Internal API Key
x-hub-signature-256	HMAC-SHA256 para webhooks Meta
svix-id, svix-timestamp, svix-signature	Headers de autenticação de webhooks Clerk

Rate limiting

Endpoints específicos têm limites próprios:

Endpoint	Limite
POST /users/invite	30 requests / 60s
PATCH /users/:id/role	20 requests / 60s
POST /webhooks/whatsapp	100 requests / 60s

Multi-tenancy

Todos os dados são isolados por organização. O organizationId é extraído automaticamente do JWT do Clerk — nunca passe o organizationId como parâmetro em endpoints normais.

Exceção: Super Admin pode passar o header x-org-id para impersonar uma organização.

Correlação de logs

Cada request recebe um x-correlation-id único. Inclua esse ID ao reportar bugs para facilitar a busca nos logs.

curl -H "Authorization: Bearer ..." \
     -v https://apicrm.galdix.com.br/health
# Header de resposta: x-correlation-id: <uuid>