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

# Ingestão de Eventos

> Envie eventos de uso do seu aplicativo para rastrear o consumo do cliente e alimentar a cobrança.

Eventos são a base da cobrança baseada em uso. Envie eventos quando ações cobradas ocorrerem, e medidores os agregam em cobranças.

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  Documentação completa da API com exemplos e códigos de resposta.
</Card>

## Estrutura do Evento

<Accordion title="Required Fields">
  <ParamField body="event_id" type="string" required>
    Identificador único. Use UUIDs ou combine ID do cliente + carimbo de data/hora + ação.
  </ParamField>

  <ParamField body="customer_id" type="string" required>
    ID do cliente Dodo Payments. Deve ser um cliente existente válido.
  </ParamField>

  <ParamField body="event_name" type="string" required>
    Tipo de evento que corresponde ao nome do evento do seu medidor (case-sensitive). Exemplos: `api.call`, `image.generated`
  </ParamField>
</Accordion>

<Accordion title="Campos Opcionais">
  <ParamField body="timestamp" type="string">
    Carimbo de data/hora ISO 8601. Padrão para a hora do servidor se omitido. Inclua para faturamento preciso com eventos em lote/atrasados.
  </ParamField>

  <ParamField body="metadata" type="object">
    Propriedades adicionais para agregação e filtragem:

    * Valores numéricos: `bytes`, `tokens`, `duration_ms`
    * Filtros: `endpoint`, `method`, `quality`

    ```javascript theme={null}
    metadata: {
      endpoint: "/v1/orders",
      method: "POST",
      tokens: 1024
    }
    ```
  </ParamField>
</Accordion>

## Enviando Eventos

<CodeGroup>
  ```javascript Single Event theme={null}
  await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [{
        event_id: "api_call_1234",
        customer_id: "cus_abc123",
        event_name: "api.call",
        metadata: { endpoint: "/v1/orders" }
      }]
    })
  });
  ```

  ```javascript Batch Events theme={null}
  await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [
        { event_id: "call_1", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_2", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_3", customer_id: "cus_abc", event_name: "api.call" }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://test.dodopayments.com/events/ingest',
      headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
      json={'events': [{'event_id': 'call_1', 'customer_id': 'cus_abc', 'event_name': 'api.call'}]}
  )
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://test.dodopayments.com/events/ingest' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"events": [{"event_id": "call_1", "customer_id": "cus_abc", "event_name": "api.call"}]}'
  ```
</CodeGroup>

<Tip>
  Agrupe até 1.000 eventos por solicitação para melhor desempenho. A API impõe um limite rígido de 1.000 eventos por chamada.
</Tip>

## Modelos de Ingestão

Padrões de eventos prontos para casos de uso comuns. Comece com um modelo comprovado em vez de construir do zero.

<CardGroup cols={2}>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Acompanhe o uso de tokens de IA em OpenAI, Anthropic, Groq, Gemini e mais.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Controle requisições da API com filtragem de endpoints e suporte a limitação de taxa.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Acompanhe envios de arquivos e consumo de armazenamento para serviços de nuvem.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Meça largura de banda de streaming para vídeo, áudio e dados em tempo real.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Cobrança por tempo decorrido para funções serverless e instâncias de computação.
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Veja todos os blueprints disponíveis com guias detalhados de implementação.
  </Card>
</CardGroup>

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    Use IDs determinísticos para evitar duplicatas: `${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    Reenvie em erros 5xx com backoff exponencial. Não reenvie erros 4xx.
  </Accordion>

  <Accordion title="Include Timestamps">
    Omitir para eventos em tempo real. Incluir para eventos em lote/atrasados para precisão.
  </Accordion>

  <Accordion title="Monitor Delivery">
    Acompanhe taxas de sucesso e enfileire eventos com falha para reenvio.
  </Accordion>
</AccordionGroup>

## Resolução de Problemas

<AccordionGroup>
  <Accordion title="Events not appearing">
    * O nome do evento deve corresponder exatamente ao medidor (case-sensitive)
    * O ID do cliente deve existir
    * Verifique se os filtros do medidor não estão excluindo eventos
    * Verifique se os carimbos de data/hora são recentes
  </Accordion>

  <Accordion title="Authentication errors (401)">
    Verifique se a chave da API está correta e use o formato: `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    Garanta que todos os campos obrigatórios estejam presentes: `event_id`, `customer_id`, `event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * As chaves de metadados devem corresponder exatamente à "Over Property" do medidor
    * Use números, não strings: `tokens: 150` não `tokens: "150"`
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    Defina como seus eventos são agregados em quantidades faturáveis com filtros e funções de agregação.
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Use blueprints prontos para casos comuns como rastreamento de LLM, gateways de API e armazenamento.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Construa um gerador completo de imagens de IA com faturamento baseado em uso do zero.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    Documentação completa da API com todos os parâmetros, códigos de resposta e testes interativos.
  </Card>
</CardGroup>