> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jornada do Lead

> Retorna o lead e todos os eventos dele em ordem cronológica: páginas visitadas, cliques, mensagens de WhatsApp, checkouts e compras, cada um com URL, UTMs e a origem (`website`, `api`, `whatsapp`, checkout).


## Exemplo

```bash
curl "https://api.metrito.com/v3/tracking/leads/lead_20261113_jp77jfdh6t/journey" \
  -H "Authorization: Bearer mtk_live_..."
```

> [!TIP]
>
> Para a origem do lead, olhe o primeiro evento (`events[0].utm` e `events[0].referrer`) e o `last_utms` do lead.


## OpenAPI

````yaml /openapi/tracking.yaml get /v3/tracking/leads/{lead_id}/journey
openapi: 3.1.0
info:
  title: API de Rastreamento — Metrito
  version: '3.0'
  description: >
    API para envio de eventos de rastreamento, consulta de leads e jornadas,
    gerenciamento de gatilhos (triggers) e webhooks de transação.


    ## Conceitos


    - **Container** — O contêiner de rastreamento vinculado a um domínio.

    - **Gatilho (Trigger)** — Uma *configuração* que define quando e como uma
    conversão deve ser disparada (tipo de disparo, mapeamento Meta, condições).
    Recurso CRUD.

    - **Lead** — Uma pessoa rastreada no container (identificada por nome,
    e-mail, telefone ou documento).

    - **Jornada** — O lead com todos os eventos dele em ordem cronológica.

    - **Evento** — Um *dado de rastreamento* enviado em tempo real: "usuário
    visualizou página X", "usuário comprou Y". Transitório, processado via fila.


    ## Infraestrutura


    - Rate limiting via `X-RateLimit-*` headers

    - Request ID via `X-Request-Id` em todas as respostas

    - `Idempotency-Key` suportado em POSTs de criação e ingestão
servers:
  - url: https://api.metrito.com
    description: Produção
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v3/tracking/leads/{lead_id}/journey:
    get:
      summary: Jornada do lead
      description: >
        Retorna o lead e todos os eventos dele em ordem cronológica: páginas
        visitadas, cliques, mensagens de WhatsApp, checkouts e compras, cada um
        com URL, UTMs e a origem (`website`, `api`, `whatsapp`, checkout).
      operationId: getLeadJourney
      parameters:
        - $ref: '#/components/parameters/LeadId'
        - $ref: '#/components/parameters/ContainerIdQuery'
        - name: events_limit
          in: query
          description: Máximo de eventos devolvidos, a partir do primeiro (1 a 1000).
          schema:
            type: integer
            default: 500
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Jornada do lead
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  parameters:
    LeadId:
      name: lead_id
      in: path
      required: true
      description: '`id` do lead, como devolvido em Listar leads.'
      schema:
        type: string
        example: lead_20261113_jp77jfdh6t
    ContainerIdQuery:
      name: container_id
      in: query
      required: false
      description: >
        Container a consultar (ObjectId, domínio ou `MTC-XXXX`). Dispensável com
        chave de API do container; obrigatório com chave do workspace.
      schema:
        type: string
        example: MTC-AB12
  schemas:
    Journey:
      type: object
      properties:
        object:
          type: string
          const: journey
        lead:
          $ref: '#/components/schemas/Lead'
        events_count:
          type: integer
        first_event_at:
          type:
            - string
            - 'null'
          format: date-time
        last_event_at:
          type:
            - string
            - 'null'
          format: date-time
        events:
          type: array
          items:
            $ref: '#/components/schemas/JourneyEvent'
    Lead:
      type: object
      properties:
        object:
          type: string
          const: lead
        id:
          type: string
          description: Identificador do lead (o mesmo `mlid` usado no rastreamento).
          example: lead_20261113_jp77jfdh6t
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
          example: '+5511999998888'
        document:
          type:
            - string
            - 'null'
        gender:
          type:
            - string
            - 'null'
        birth_date:
          type:
            - string
            - 'null'
          format: date
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
        last_utms:
          type: object
          description: Últimas UTMs vistas para o lead.
          additionalProperties: true
          example:
            utm_source: facebook
            utm_medium: cpc
            utm_campaign: black-friday
        first_referrer:
          type:
            - string
            - 'null'
        first_referrer_at:
          type:
            - string
            - 'null'
          format: date-time
        is_bot:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
    JourneyEvent:
      type: object
      properties:
        object:
          type: string
          const: event
        id:
          type: string
        event_id:
          type:
            - string
            - 'null'
          description: ID usado na deduplicação com a Meta.
        name:
          type: string
          example: PageView
        time:
          type: string
          format: date-time
        source:
          type: string
          description: De onde o evento veio.
          example: website
        url:
          type:
            - string
            - 'null'
        referrer:
          type:
            - string
            - 'null'
        utm:
          type: object
          additionalProperties: true
        data:
          type: object
          description: Dados enviados com o evento (valor, moeda, produto etc.).
          additionalProperties: true
        whatsapp_connection:
          type:
            - object
            - 'null'
          description: Número de WhatsApp que atendeu, em eventos de WhatsApp.
          properties:
            id:
              type:
                - string
                - 'null'
            name:
              type:
                - string
                - 'null'
            phone:
              type:
                - string
                - 'null'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - authorization_error
                - validation_error
                - rate_limit_error
                - not_found_error
                - api_error
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
              nullable: true
  responses:
    Unauthorized:
      description: API key ausente, inválida, revogada ou expirada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: The API key provided is invalid or has been revoked.
              request_id: req_abc123
    Forbidden:
      description: A chave não tem acesso a este container
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authorization_error
              code: forbidden
              message: Container out of API key scope
              request_id: req_abc123
    NotFound:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: not_found_error
              code: resource_not_found
              message: Trigger not found
              request_id: req_abc123
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or API Key
      description: JWT da plataforma ou API key `mtk_live_...`
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key `mtk_live_...` via header `x-api-key`

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.