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

# Ingestione Eventi

> Invia eventi di utilizzo dalla tua applicazione per monitorare il consumo dei clienti e alimentare la fatturazione.

Gli eventi sono la base della fatturazione basata sull'uso. Invia eventi quando si verificano azioni fatturabili e i contatori li aggregano in addebiti.

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  Documentazione API completa con esempi e codici di risposta.
</Card>

## Struttura dell'Evento

<Accordion title="Required Fields">
  <ParamField body="event_id" type="string" required>
    Identificatore univoco. Usa UUID o combina ID cliente + timestamp + azione.
  </ParamField>

  <ParamField body="customer_id" type="string" required>
    ID cliente Dodo Payments. Deve essere un cliente esistente valido.
  </ParamField>

  <ParamField body="event_name" type="string" required>
    Tipo di evento che corrisponde esattamente al nome dell’evento del tuo meter (sensibile alle maiuscole). Esempi: `api.call`, `image.generated`
  </ParamField>
</Accordion>

<Accordion title="Optional Fields">
  <ParamField body="timestamp" type="string">
    Timestamp ISO 8601. Se omesso, predefinito all’ora del server. Includilo per una fatturazione precisa con eventi ritardati o in batch.
  </ParamField>

  <ParamField body="metadata" type="object">
    Proprietà aggiuntive per l’aggregazione e il filtraggio:

    * Valori numerici: `bytes`, `tokens`, `duration_ms`
    * Filtri: `endpoint`, `method`, `quality`

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

## Invio di Eventi

<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>
  Raggruppa fino a 1.000 eventi per richiesta per ottenere prestazioni migliori. L'API impone un limite massimo di 1.000 eventi per chiamata.
</Tip>

## Modelli di Ingestione

Modelli di eventi pronti all'uso per casi d'uso comuni. Inizia con un modello collaudato invece di costruire da zero.

<CardGroup cols={2}>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Monitora l’utilizzo dei token AI su OpenAI, Anthropic, Groq, Gemini e altro.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Misura le richieste API con filtraggio degli endpoint e supporto per il rate limiting.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Monitora i caricamenti di file e il consumo di storage per i servizi di cloud storage.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Misura la larghezza di banda streaming per video, audio e dati in tempo reale.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Fattura in base al tempo trascorso per funzioni serverless e istanze di calcolo.
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Vedi tutti i blueprint disponibili con guide di implementazione dettagliate.
  </Card>
</CardGroup>

## Migliori Pratiche

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    Usa ID deterministici per prevenire duplicati: `${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    Riprova con backoff esponenziale sugli errori 5xx. Non riprovare errori 4xx.
  </Accordion>

  <Accordion title="Include Timestamps">
    Omettilo per eventi in tempo reale. Includilo per eventi ritardati o in batch per garantire precisione.
  </Accordion>

  <Accordion title="Monitor Delivery">
    Monitora i tassi di successo e accoda gli eventi falliti per il retry.
  </Accordion>
</AccordionGroup>

## Risoluzione dei Problemi

<AccordionGroup>
  <Accordion title="Events not appearing">
    * Il nome dell’evento deve corrispondere esattamente al meter (sensibile alle maiuscole)
    * L’ID cliente deve esistere
    * Verifica che i filtri del meter non stiano escludendo gli eventi
    * Assicurati che i timestamp siano recenti
  </Accordion>

  <Accordion title="Authentication errors (401)">
    Verifica che la chiave API sia corretta e usa il formato: `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    Assicurati che tutti i campi obbligatori siano presenti: `event_id`, `customer_id`, `event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * Le chiavi dei metadata devono corrispondere esattamente a "Over Property" del meter
    * Usa numeri, non stringhe: `tokens: 150` non `tokens: "150"`
  </Accordion>
</AccordionGroup>

## Prossimi Passi

<CardGroup cols={2}>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    Definisci come i tuoi eventi vengono aggregati in quantità fatturabili con filtri e funzioni di aggregazione.
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Usa blueprint pronti per casi d’uso comuni come monitoraggio LLM, gateway API e storage.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Costruisci da zero un generatore di immagini AI con fatturazione basata sull’utilizzo.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    Documentazione API completa con tutti i parametri, codici di risposta e test interattivi.
  </Card>
</CardGroup>