Ingestione Eventi

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

API Reference — Events Ingestion

Documentazione completa dell’API con esempi e codici di risposta.

Struttura dell’Evento

Required Fields

string

obbligatorio

Un identificatore univoco per l’evento, utilizzato per rilevare eventi duplicati durante un nuovo tentativo. Derivalo dall’azione, ad esempio ID cliente + azione + timestamp, in modo che un evento ritentato mantenga lo stesso ID. Un UUID casuale nuovo a ogni tentativo consente di conteggiare due volte lo stesso evento.

string

obbligatorio

L’ID cliente di Dodo Payments. Deve corrispondere a un cliente esistente valido.

string

obbligatorio

Il tipo di evento che corrisponde al nome dell’evento del tuo meter (con distinzione tra maiuscole e minuscole). Esempi: api.call, image.generated.

Optional Fields

string

Timestamp in formato ISO 8601 (UTC). Se omesso, viene impostato sull’ora corrente del server. Includilo per una fatturazione accurata con eventi ritardati o elaborati in batch. I timestamp più vecchi di 1 ora o più avanti di 5 minuti nel futuro vengono rifiutati.

object

Proprietà aggiuntive per l’aggregazione e il filtraggio. Fino a 50 chiavi; ogni chiave può contenere fino a 100 caratteri e ogni valore fino a 500 caratteri.

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

metadata: {
  endpoint: "/v1/orders",
  method: "POST",
  tokens: 1024
}

Invio di Eventi

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" }
    }]
  })
});

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" }
    ]
  })
});

import os
import requests

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

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"}]}'

Raggruppa fino a 1.000 eventi per richiesta per ottenere prestazioni migliori. L’API applica un limite massimo di 1.000 eventi per richiesta.

Modelli di Ingestione

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

LLM Blueprint

Monitora l’utilizzo dei token AI su OpenAI, Anthropic, Groq, Gemini e altro.

API Gateway Blueprint

Misura le richieste API con filtraggio degli endpoint e supporto per il rate limiting.

Object Storage Blueprint

Monitora i caricamenti di file e il consumo di storage per i servizi di cloud storage.

Stream Blueprint

Misura la larghezza di banda streaming per video, audio e dati in tempo reale.

Time Range Blueprint

Fattura in base al tempo trascorso per funzioni serverless e istanze di calcolo.

View All Blueprints

Vedi tutti i blueprint disponibili con guide di implementazione dettagliate.

Migliori Pratiche

Use Unique Event IDs

Usa ID deterministici per prevenire i duplicati: ${customerId}_${action}_${timestamp}.

Implement Retries

Esegui un nuovo tentativo in caso di errori 5xx e 429, utilizzando un backoff esponenziale. Non ripetere il tentativo per altri errori 4xx.

Include Timestamps

Ometti i timestamp per gli eventi in tempo reale. Includili per gli eventi ritardati o elaborati in batch, per garantire la precisione.

Monitor Delivery

Monitora i tassi di successo e accoda gli eventi falliti per il retry.

Risoluzione dei Problemi

Events not appearing

Il nome dell’evento deve corrispondere esattamente al meter (con distinzione tra maiuscole e minuscole)
L’ID cliente deve esistere nel tuo account
Verifica che i filtri del meter non escludano gli eventi
Verifica che i timestamp siano recenti

Authentication errors (401)

Verifica che la API key sia corretta e utilizza il formato: Bearer YOUR_API_KEY.

Validation errors (400)

Assicurati che siano presenti tutti i campi obbligatori: event_id, customer_id, event_name.

Metadata not aggregating

Le chiavi dei metadati devono corrispondere esattamente a “Over Property” del meter
Usa numeri, non stringhe: tokens: 150 non tokens: "150"

Prossimi Passi

Create Meters

Definisci come i tuoi eventi vengono aggregati in quantità fatturabili con filtri e funzioni di aggregazione.

Ingestion Blueprints

Usa blueprint pronti per casi d’uso comuni come monitoraggio LLM, gateway API e storage.

Complete Tutorial

Costruisci da zero un generatore di immagini AI con fatturazione basata sull’utilizzo.

API Reference

Documentazione API completa con tutti i parametri, codici di risposta e test interattivi.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

API Reference — Events Ingestion

Struttura dell’Evento

Invio di Eventi

Modelli di Ingestione

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

Migliori Pratiche

Risoluzione dei Problemi

Prossimi Passi

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

API Reference — Events Ingestion

​Struttura dell’Evento

​Invio di Eventi

​Modelli di Ingestione

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

​Migliori Pratiche

​Risoluzione dei Problemi

​Prossimi Passi

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

Struttura dell’Evento

Invio di Eventi

Modelli di Ingestione

Migliori Pratiche

Risoluzione dei Problemi

Prossimi Passi