POST /api/v1/analytics/customer-events

Versão servidor-a-servidor do /track. Mesmo schema e semântica, mas autenticada por API Key + HMAC. Use quando os eventos forem disparados pelo seu backend (ex.: confirmação de pagamento, webhook de gateway de pagamentos).

Autenticação

API Key + HMAC. Permissão ADMIN no app CRM.

Headers

Header	Valor
Authorization	Bearer <api-key-uuid>
x-signature	HMAC-SHA256(JSON.stringify(body), <api-key-secret>) em hex
Content-Type	application/json

Body

Campo	Tipo	Obrigatório	Descrição
key	string (Event Key)	Sim	Tipo do evento
data	object	Sim	Payload específico do evento
anonymousId	string	Sim	Identificador anônimo do visitante
userId	string | null	Não	ID do usuário autenticado
sessionId	UUID	Não	Sessão atual
dispatchId	string	Não	ID único do disparo
context	SegmentContext	Não	Contexto de ambiente

Exemplo de requisição

curl -X POST https://api-crm.ecommerceapp.com.br/api/v1/analytics/customer-events \
  -H "Authorization: Bearer 1a2b3c4d-5e6f-7890-abcd-ef1234567890" \
  -H "x-signature: 9c1f...hex..." \
  -H "Content-Type: application/json" \
  -d '{
    "key": "Order Refunded",
    "anonymousId": "anon-7c1f3a",
    "userId": "user-9182",
    "data": {
      "order_id": "ORD-9182",
      "total": 199.90,
      "currency": "BRL",
      "reason": "customer_request"
    }
  }'

Resposta

200 OK

{
  "session": { "sessionId": "01J9XK8E7G5R3M2N4P6Q8S0T1V" }
}

Quando usar customer-events em vez de track

Cenário	Endpoint
Tracking do browser do cliente	/track
Backend disparando evento de e-commerce (webhook do gateway de pagamento, ERP, OMS)	/customer-events
Evento crítico onde você precisa garantir integridade do payload (assinatura HMAC)	/customer-events

Erros

Status	Causa
400 Bad Request	Body inválido
401 Unauthorized	API Key inválida, ausente, ou assinatura HMAC incorreta
403 Forbidden	Chave sem acesso ao app CRM ou sem permissão ADMIN
404 Not Found	key não está na lista de eventos suportados