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

# Ingesta de Eventos

> Envía eventos de uso desde tu aplicación para rastrear el consumo del cliente y gestionar la facturación.

Los eventos son la base de la facturación basada en el uso. Envía eventos cuando ocurren acciones facturables, y los medidores los agregan en cargos.

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  Documentación completa de la API con ejemplos y códigos de respuesta.
</Card>

## Estructura del Evento

<Accordion title="Required Fields">
  <ParamField body="event_id" type="string" required>
    Identificador único. Use UUIDs o combine ID de cliente + marca temporal + acción.
  </ParamField>

  <ParamField body="customer_id" type="string" required>
    ID de cliente de Dodo Payments. Debe ser un cliente válido existente.
  </ParamField>

  <ParamField body="event_name" type="string" required>
    Tipo de evento que coincide con el nombre del evento de su medidor (sensible a mayúsculas). Ejemplos: `api.call`, `image.generated`
  </ParamField>
</Accordion>

<Accordion title="Optional Fields">
  <ParamField body="timestamp" type="string">
    Marca temporal ISO 8601. Por defecto se usa la hora del servidor si se omite. Inclúyala para facturación precisa con eventos retrasados o por lotes.
  </ParamField>

  <ParamField body="metadata" type="object">
    Propiedades adicionales para agregación y filtrado:

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

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

## Envío de 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 hasta 1,000 eventos por solicitud para un mejor rendimiento. La API impone un límite máximo de 1,000 eventos por llamada.
</Tip>

## Plantillas de Ingesta

Patrones de eventos listos para casos de uso comunes. Comienza con una plantilla probada en lugar de construir desde cero.

<CardGroup cols={2}>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Realice un seguimiento del uso de tokens de IA en OpenAI, Anthropic, Groq, Gemini y más.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Mida las solicitudes a la API con filtrado por punto final y compatibilidad con limitación de velocidad.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Controle las cargas de archivos y el consumo de almacenamiento para servicios en la nube.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Mida el ancho de banda de streaming para video, audio y datos en tiempo real.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Facture por tiempo transcurrido para funciones serverless e instancias de cómputo.
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Vea todos los planos disponibles con guías detalladas de implementación.
  </Card>
</CardGroup>

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    Use IDs deterministas para evitar duplicados: `${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    Reintente ante errores 5xx con retroceso exponencial. No reintente errores 4xx.
  </Accordion>

  <Accordion title="Include Timestamps">
    Omita en eventos en tiempo real. Inclúyalo en eventos retrasados o por lotes para mayor precisión.
  </Accordion>

  <Accordion title="Monitor Delivery">
    Monitoree las tasas de éxito y encole eventos fallidos para reintentos.
  </Accordion>
</AccordionGroup>

## Solución de Problemas

<AccordionGroup>
  <Accordion title="Events not appearing">
    * El nombre del evento debe coincidir exactamente con el medidor (sensible a mayúsculas)
    * El ID del cliente debe existir
    * Verifique que los filtros del medidor no estén excluyendo eventos
    * Verifique que las marcas temporales sean recientes
  </Accordion>

  <Accordion title="Authentication errors (401)">
    Verifique que la clave de la API sea correcta y use el formato: `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    Asegúrese de que todos los campos obligatorios estén presentes: `event_id`, `customer_id`, `event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * Las claves de metadatos deben coincidir exactamente con la "Over Property" del medidor
    * Use números, no cadenas: `tokens: 150` no `tokens: "150"`
  </Accordion>
</AccordionGroup>

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    Defina cómo se agregan sus eventos en cantidades facturables con filtros y funciones de agregación.
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Utilice planos preconfeccionados para casos comunes como seguimiento de LLM, puertas de enlace de API y almacenamiento.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Construya un generador completo de imágenes de IA con facturación basada en el uso desde cero.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    Documentación completa de la API con todos los parámetros, códigos de respuesta y pruebas interactivas.
  </Card>
</CardGroup>