POST /api/v1/analytics/track

Envia um evento de cliente (e-commerce, page view, login etc.) para a plataforma. Endpoint público, autenticado por Write Key — pode ser chamado diretamente do browser.

Autenticação

API Key.

Headers

Header	Valor
Authorization	Bearer <api-key>
Content-Type	application/json

Body

Campo	Tipo	Obrigatório	Descrição
key	string (Event Key)	Sim	Tipo do evento (Product Viewed, Order Completed, ...)
data	object	Sim	Payload específico do evento
anonymousId	string	Sim	Identificador anônimo persistente do visitante
userId	string | null	Não	ID do usuário autenticado, se houver
sessionId	UUID	Não	Sessão atual; se omitido, será resolvida automaticamente
dispatchId	string	Não	ID único do disparo (correlaciona eventos a um envio)
context	SegmentContext	Não	Contexto de ambiente (UTM, página, IP)

Exemplo de requisição

curl -X POST https://api-crm.ecommerceapp.com.br/api/v1/analytics/track \
  -H "Authorization: Bearer 8f9e0c11-5b2d-4a7e-9f08-1b6c2d3e4f5a" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "Order Completed",
    "anonymousId": "anon-7c1f3a",
    "userId": "user-9182",
    "data": {
      "order_id": "ORD-9182",
      "total": 199.90,
      "currency": "BRL",
      "products": [
        { "product_id": "SKU-123", "name": "Camiseta", "price": 89.90, "quantity": 1 },
        { "product_id": "SKU-456", "name": "Calça", "price": 110.00, "quantity": 1 }
      ]
    },
    "context": {
      "campaign": { "source": "google", "medium": "cpc", "name": "black-friday" },
      "page": { "url": "https://loja.exemplo.com/checkout/success" }
    }
  }'

Resposta

200 OK

{
  "success": true,
  "session": {
    "sessionId": "01J9XK8E7G5R3M2N4P6Q8S0T1V",
    "isNew": false
  }
}

Comportamentos especiais

• Resolução automática de userId: se você não enviar userId, o sistema busca um mapeamento anonymousId → userId previamente registrado via /identify e o aplica automaticamente.
• Atribuição em Order Completed: este evento dispara o fluxo assíncrono de atribuição, usando UTMs/touchpoints anteriores dentro da janela de 7 dias.

Erros

Status	Causa
400 Bad Request	Body inválido (campo obrigatório ausente, tipo incorreto)
401 Unauthorized	Write Key inválida ou ausente
404 Not Found	key não pertence à lista de eventos suportados