> ## 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.

# Enviar Evento

> Envia um evento de rastreamento ao Metrito.

## Dois modos de uso

| Modo | Como usar | Resolução do container |
|------|-----------|------------------------|
| **Autenticado** (API key) | `Authorization: Bearer mtk_live_...` ou `x-api-key` | Container resolvido automaticamente pela chave |
| **Público** (sem auth) | Sem header de autenticação | Campo `domain` obrigatório no body |

O modo público é equivalente ao endpoint legado `POST /v2/public/tracking/events` — use este endpoint como ponto de entrada único.

## Idempotência

Envie `Idempotency-Key` com um valor único por evento. Dentro de 24h, chamadas repetidas com o mesmo key retornam a resposta original com `X-Idempotent-Replayed: true`.


## Modo Autenticado vs Público

**Com API key** — o container é resolvido automaticamente pela chave. O campo `domain` no body é ignorado (mas pode ser enviado).

**Público (sem auth)** — o campo `domain` é obrigatório e identifica o container de destino.

## config.name vs config.facebook.name

| Campo                  | Onde é usado                  | Descrição                                                                 |
| ---------------------- | ----------------------------- | ------------------------------------------------------------------------- |
| `config.name`          | **Metrito**                   | Nome interno para relatórios e dashboards                                 |
| `config.facebook.name` | **Meta (Facebook/Instagram)** | Nome enviado à Meta Conversion API (`PageView`, `Purchase`, `Lead`, etc.) |

Se `config.facebook` for omitido, o evento é registrado no Metrito mas **não** é enviado para a Meta.


## OpenAPI

````yaml /openapi/tracking.yaml post /v3/tracking/events
openapi: 3.1.0
info:
  title: API de Rastreamento — Metrito
  version: '3.0'
  description: >
    API para envio de eventos de rastreamento, 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.

    - **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/events:
    post:
      summary: Enviar evento
      description: >
        Envia um evento de rastreamento ao Metrito.


        ## Dois modos de uso


        | Modo | Como usar | Resolução do container |

        |------|-----------|------------------------|

        | **Autenticado** (API key) | `Authorization: Bearer mtk_live_...` ou
        `x-api-key` | Container resolvido automaticamente pela chave |

        | **Público** (sem auth) | Sem header de autenticação | Campo `domain`
        obrigatório no body |


        O modo público é equivalente ao endpoint legado `POST
        /v2/public/tracking/events` — use este endpoint como ponto de entrada
        único.


        ## Idempotência


        Envie `Idempotency-Key` com um valor único por evento. Dentro de 24h,
        chamadas repetidas com o mesmo key retornam a resposta original com
        `X-Idempotent-Replayed: true`.
      operationId: sendEvent
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackingEventPayload'
            examples:
              authenticated_pageview:
                summary: PageView com API key
                value:
                  config:
                    name: PageView
              authenticated_purchase:
                summary: Compra com API key
                value:
                  config:
                    name: Compra
                    facebook:
                      name: Purchase
                  data:
                    value: 299.9
                    currency: BRL
                  lead:
                    email: joao@exemplo.com
                    phone: '+5511999999999'
              public_pageview:
                summary: PageView público (sem auth)
                value:
                  domain: minhaloja.com.br
                  config:
                    name: PageView
              public_purchase:
                summary: Compra pública (sem auth)
                value:
                  domain: minhaloja.com.br
                  config:
                    name: Compra
                    facebook:
                      name: Purchase
                  data:
                    value: 299.9
                    currency: BRL
                  lead:
                    name: João Silva
                    email: joao@exemplo.com
                    phone: '+5511999999999'
                  utm:
                    utm_source: facebook
                    utm_medium: cpc
                    utm_campaign: Campanha Verão|123456789
      responses:
        '200':
          description: Evento aceito e enfileirado para processamento
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingEventResponse'
              example:
                success: true
                event_id: 1758388123_kk78h7u5sf
                lead_id: lead_20260324_xyz789
                timestamp: 1758388123
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
        - {}
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Chave de idempotência. Dentro de 24h, chamadas repetidas com o mesmo key
        retornam a resposta original.
      schema:
        type: string
  schemas:
    TrackingEventPayload:
      type: object
      properties:
        domain:
          type: string
          description: >-
            Domínio do container. **Obrigatório no modo público** (sem API key).
            Ignorado no modo autenticado.
          example: minhaloja.com.br
        config:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Nome do evento no Metrito
              example: Purchase
            facebook:
              type: object
              description: Omita para não enviar à Meta
              properties:
                name:
                  type: string
                  description: >-
                    Nome do evento no padrão Meta: `PageView`, `Lead`,
                    `Purchase`, etc.
                  example: Purchase
        version:
          type: number
          default: 2
        event_id:
          type: string
          description: ID único do evento. Gerado automaticamente se omitido.
        event_time:
          type: number
          description: Timestamp Unix em segundos. Usa horário atual se omitido.
        data:
          type: object
          properties:
            value:
              type: number
            currency:
              type: string
        lead:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            email:
              type: string
              format: email
            phone:
              type: string
        utm:
          type: object
          properties:
            utm_source:
              type: string
            utm_medium:
              type: string
            utm_campaign:
              type: string
            utm_content:
              type: string
            utm_term:
              type: string
        cookies:
          type: object
          additionalProperties:
            type: string
          example:
            _fbp: fb.1.1234567890.987654321
            _ga: GA1.2.1234567890.1234567890
    TrackingEventResponse:
      type: object
      properties:
        success:
          type: boolean
        event_id:
          type: string
        lead_id:
          type: string
          nullable: true
        timestamp:
          type: number
    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:
    ValidationError:
      description: Parâmetro ausente ou inválido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: validation_error
              code: invalid_parameter
              message: trigger.type must be 'api' for Partner API triggers
              request_id: req_abc123
    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
    RateLimited:
      description: Rate limit excedido
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: rate_limit_error
              code: rate_limit_exceeded
              message: Rate limit exceeded. Maximum 120 requests per 60s.
              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`

````