Skip to main content

API Reference — Events Ingestion

Accedi alla documentazione API completa per l’inserimento degli eventi di utilizzo e testa interattivamente le richieste e le risposte di acquisizione degli eventi.

API Reference — Meters Creation

Esplora la documentazione API completa per la creazione dei meter e testa interattivamente le richieste e le risposte di creazione dei meter.

Creazione di un contatore

I contatori definiscono come gli eventi di utilizzo vengono aggregati e misurati ai fini della fatturazione. Prima di creare un contatore, pianifica la tua strategia di tracciamento dell’uso:
  • Identifica quali eventi di utilizzo desideri monitorare
  • Determina come gli eventi devono essere aggregati (conteggio, somma, ecc.)
  • Definisci eventuali requisiti di filtraggio per casi d’uso specifici

Procedura passo-passo per la creazione di un contatore

Segui questa guida per configurare il tuo meter:
1

Configure Basic Information

Configura i dettagli fondamentali del tuo meter.
string
obbligatorio
Un nome chiaro e descrittivo che identifica cosa monitora questo meter.Esempi: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”
string
Una spiegazione dettagliata di ciò che misura questo meter.Esempio: “Counts each POST /v1/orders request made by the customer”
string
obbligatorio
L’identificatore dell’evento che attiverà questo meter.Esempi: “token”, “api.call”, “storage.usage”, “compute.session”
Il nome dell’evento deve corrispondere esattamente a quello che invii nei tuoi eventi di utilizzo. I nomi sono sensibili al maiuscolo/minuscolo.
2

Configure Aggregation Settings

Definisci come il meter calcola l’utilizzo dai tuoi eventi.
string
obbligatorio
Seleziona come devono essere aggregati gli eventi:
Conta il numero di eventi ricevuti.Caso d’uso: chiamate API, visualizzazioni di pagina, caricamenti di fileCalcolo: Numero totale di eventi
string
Nome della proprietà nei metadati dell’evento su cui effettuare l’aggregazione.
Questo campo è obbligatorio quando si utilizzano i tipi di aggregazione Somma, Massimo o Ultimo.
string
obbligatorio
L’etichetta dell’unità da visualizzare nei report e nella fatturazione.Esempi: “calls”, “GB”, “hours”, “tokens”
3

Configure Event Filtering (Optional)

Definisci i criteri per controllare quali eventi vengono inclusi nel meter.
Il filtraggio degli eventi ti permette di creare regole sofisticate che determinano quali eventi contribuiscono ai calcoli di utilizzo. Utile per escludere eventi di test, filtrare per tier utente o concentrarsi su azioni specifiche.
Abilita il filtraggio degli eventiAttiva Abilita il filtraggio degli eventi per attivare l’elaborazione condizionale degli eventi.Scegli la logica di filtroSeleziona come vengono valutate più condizioni:
Tutte le condizioni devono essere vere affinché un evento venga conteggiato. Usalo quando hai bisogno che gli eventi soddisfino più criteri rigorosi contemporaneamente.Esempio: Conta le chiamate API dove user_tier = "premium" AND endpoint = "/api/v2/users"
Impostazione delle condizioni di filtro
1

Add Condition

Clicca Aggiungi condizione per creare una nuova regola di filtro.
2

Configure Property Key

Specifica il nome della proprietà nei tuoi metadati dell’evento.
3

Select Comparator

Scegli tra gli operatori disponibili:
  • equals — Corrispondenza esatta
  • not_equals — Filtro di esclusione
  • greater_than — Confronto numerico
  • greater_than_or_equals — Confronto numerico (inclusivo)
  • less_than — Confronto numerico
  • less_than_or_equals — Confronto numerico (inclusivo)
  • contains — La stringa contiene la sottostringa
  • does_not_contain — Filtro di esclusione della stringa
4

Set Comparison Value

Imposta il valore di riferimento per il confronto.
5

Add Groups

Usa Aggiungi gruppo per creare gruppi di condizioni aggiuntivi per logica complessa.
Le proprietà filtrate devono essere incluse nei metadati dell’evento affinché le condizioni funzionino correttamente. Gli eventi privi delle proprietà richieste verranno esclusi dal conteggio.
4

Create Meter

Esamina la configurazione del meter e fai clic su Create Meter.
Il meter è ora pronto per ricevere e aggregare gli eventi di utilizzo.

Collegamento del meter a un prodotto

Dopo aver creato il meter, devi collegarlo a un prodotto per abilitare la fatturazione basata sull’utilizzo. Questo processo collega i dati di utilizzo del meter alle regole di prezzo per la fatturazione dei clienti. Il collegamento dei meter ai prodotti stabilisce la connessione tra il monitoraggio dell’utilizzo e la fatturazione:
  • I prodotti definiscono le regole di prezzo e il comportamento di fatturazione
  • I meter forniscono i dati di utilizzo per i calcoli di fatturazione
  • È possibile collegare più meter a un singolo prodotto per scenari di fatturazione complessi

Processo di configurazione del prodotto

Trasforma i dati di utilizzo in addebiti fatturabili configurando correttamente le impostazioni del prodotto:
1

Choose Usage-Based Billing Product Type

Vai alla pagina di creazione o modifica del prodotto e seleziona Usage Based Billing come tipo di prezzo.
2

Select Associated Meter

Fai clic su Associated Meters per aprire il pannello di selezione dei meter.Questo pannello ti consente di configurare quali meter monitoreranno l’utilizzo per questo prodotto.
3

Add Your Meter

Nel pannello di selezione dei meter:
  1. Fai clic su Add Meters per visualizzare i meter disponibili
  2. Seleziona dall’elenco a discesa il meter che hai creato
  3. Il meter selezionato apparirà nella configurazione del prodotto
4

Configure Price Per Unit

Imposta il prezzo per ogni unità di utilizzo monitorata dal meter.
number
obbligatorio
Definisci quanto addebitare per ogni unità misurata dal meter.Esempio: Impostare $0.50 per unità significa:
  • 1.000 unità consumate = 1.000 × $0.50 = $500.00 addebitati
  • 500 unità consumate = 500 × $0.50 = $250.00 addebitati
  • 100 unità consumate = 100 × $0.50 = $50.00 addebitati
5

Set Free Threshold (Optional)

Configura una quantità di utilizzo gratuita prima dell’inizio della fatturazione.
number
Numero di unità che i clienti possono consumare gratuitamente prima dell’inizio del calcolo dell’utilizzo a pagamento.Come funziona:
  • Soglia gratuita: 100 unità
  • Prezzo per unità: $0.50
  • Utilizzo del cliente: 250 unità
  • Calcolo: (250 - 100) × $0.50 = $75.00 addebitati
Le soglie gratuite sono ideali per i modelli freemium, i periodi di prova o per offrire ai clienti una quantità di base inclusa nel piano.
La soglia gratuita si applica a ogni ciclo di fatturazione, offrendo ai clienti nuove quantità disponibili ogni mese o secondo il tuo programma di fatturazione.
6

Save Configuration

Esamina la configurazione del meter e dei prezzi, quindi fai clic su Save Changes per completare la configurazione.
Il prodotto è ora configurato per la fatturazione basata sull’utilizzo e addebiterà automaticamente i clienti in base al consumo misurato.
Cosa succede dopo:
  • Gli eventi di utilizzo inviati al meter verranno monitorati e aggregati
  • I calcoli di fatturazione applicheranno automaticamente le regole di prezzo
  • Ai clienti verrà addebitato il consumo effettivo durante ogni ciclo di fatturazione
Puoi aggiungere fino a 50 meter per prodotto, abilitando un monitoraggio sofisticato dell’utilizzo su più dimensioni, come chiamate API, archiviazione, tempo di calcolo e metriche personalizzate.

Invio degli eventi di utilizzo

Dopo aver configurato il meter, puoi iniziare a inviare eventi di utilizzo dalla tua applicazione per monitorare l’utilizzo dei clienti.

Struttura degli eventi

Ogni evento di utilizzo deve includere i seguenti campi obbligatori:
string
obbligatorio
Un identificatore univoco per questo evento specifico. Deve essere univoco tra tutti gli eventi.
string
obbligatorio
L’ID cliente Dodo Payments a cui deve essere attribuito questo utilizzo.
string
obbligatorio
Il nome dell’evento che corrisponde alla configurazione del meter. I nomi degli eventi attivano il meter appropriato.
string
Timestamp ISO 8601 del momento in cui si è verificato l’evento. Se non viene fornito, il valore predefinito è il timestamp UTC corrente. Deve rientrare nell’intervallo di 1 ora nel passato e 5 minuti nel futuro: i timestamp al di fuori di tale intervallo vengono rifiutati.
object
Proprietà aggiuntive per il filtraggio e l’aggregazione. Includi tutti i valori a cui si fa riferimento nelle condizioni “Over Property” o di filtraggio del meter.

Esempi di API per gli eventi di utilizzo

Invia gli eventi di utilizzo ai meter configurati utilizzando l’Events API:

Elementi fondamentali per un’acquisizione affidabile

Segui queste pratiche per mantenere il monitoraggio dell’utilizzo accurato e resiliente in produzione.
Usa event_id deterministici e idempotenti. event_id deve essere univoco tra tutti gli eventi e funge da chiave di idempotenza. Un event_id riutilizzato viene trattato come duplicato e non viene contato nuovamente, quindi i retry non causano mai una doppia fatturazione. Deriva l’ID dall’azione invece di usare un valore casuale, ad esempio `${customer_id}_${action}_${timestamp}`.
Raggruppa gli eventi, fino a 1.000 per richiesta. L’endpoint /events/ingest impone un limite massimo rigido di 1.000 eventi per richiesta. I batch più grandi vengono rifiutati, quindi suddividi i volumi elevati in più chiamate. Per carichi di lavoro elevati, memorizza temporaneamente gli eventi e inviali in batch invece di mandare una richiesta per ogni evento.
Ripeti i tentativi per 5xx e 429, mai per altri 4xx. Esegui retry in caso di errori del server (5xx) e limiti di frequenza (429) con exponential backoff. Non ripetere i tentativi per gli errori di validazione 400/422: il payload è malformato e fallirà ogni volta. Correggilo e invialo nuovamente. Accoda gli eventi che continuano a fallire dopo i retry, così non ne viene perso nessuno.
Imposta intenzionalmente i timestamp. Ometti timestamp per gli eventi in tempo reale: il valore predefinito sarà il timestamp UTC corrente. Impostalo esplicitamente (ISO 8601) per gli eventi ritardati o raggruppati, così l’utilizzo viene registrato nel periodo di fatturazione corretto. Tieni presente che l’intervallo accettato è ristretto: gli eventi con timestamp anteriori di oltre 1 ora o posteriori di oltre 5 minuti vengono rifiutati. Il backfill storico non è supportato: invia gli eventi memorizzati entro un’ora.
Invia i metadati aggregati come numeri, non come stringhe. Qualsiasi proprietà a cui fa riferimento il meter Over Property (Sum, Max, Last) deve essere di tipo numerico: { "tokens": 150 }, non { "tokens": "150" }. I valori stringa non vengono aggregati.

Analisi della fatturazione basata sull’utilizzo

Monitora e analizza i dati della fatturazione basata sull’utilizzo con una dashboard di analisi completa. Tieni traccia dei modelli di consumo dei clienti, delle prestazioni dei meter e delle tendenze di fatturazione per ottimizzare la strategia di prezzo e comprendere i comportamenti di utilizzo.

Analisi panoramica

La scheda Overview offre una visione completa delle prestazioni della fatturazione basata sull’utilizzo:

Metriche dell’attività

Monitora le principali statistiche di utilizzo su periodi diversi:
metric
Mostra l’attività di utilizzo per il periodo di fatturazione corrente, aiutandoti a comprendere i modelli di consumo mensili.
metric
Visualizza le statistiche di utilizzo cumulative dall’inizio del monitoraggio, fornendo informazioni sulla crescita a lungo termine.
Usa il selettore del periodo di tempo per confrontare l’utilizzo tra mesi diversi e identificare tendenze stagionali o modelli di crescita.

Grafico delle quantità dei meter

Grafico delle quantità dei meter che mostra le tendenze di utilizzo nel tempo con una visualizzazione a gradiente viola
Il grafico delle quantità dei meter visualizza le tendenze di utilizzo nel tempo con le seguenti funzionalità:
  • Visualizzazione delle serie temporali: monitora i modelli di utilizzo per giorni, settimane o mesi
  • Supporto di più meter: visualizza contemporaneamente i dati di meter diversi
  • Analisi delle tendenze: identifica picchi di utilizzo, modelli e traiettorie di crescita
Il grafico si ridimensiona automaticamente in base al volume di utilizzo e all’intervallo di tempo selezionato, offrendo una visibilità chiara sia delle piccole fluttuazioni sia dei cambiamenti significativi nell’utilizzo.

Analisi degli eventi

Tabella degli eventi che mostra nomi degli eventi, ID e controlli di paginazione per un'analisi dettagliata degli eventi
La scheda Events offre una visibilità granulare sui singoli eventi di utilizzo:

Visualizzazione delle informazioni sugli eventi

La tabella degli eventi offre una visione chiara dei singoli eventi di utilizzo con le seguenti colonne:
  • Nome evento: l’azione o il trigger specifico che ha generato l’evento di utilizzo
  • ID evento: un identificatore univoco per ogni istanza dell’evento
  • ID cliente: il cliente associato all’evento
  • Timestamp: il momento in cui si è verificato l’evento
Questa vista consente di monitorare e tenere traccia dei singoli eventi di utilizzo tra tutti i clienti, offrendo trasparenza sui calcoli di fatturazione e sui modelli di utilizzo.

Analisi dei clienti

La scheda Customers offre una visualizzazione dettagliata in formato tabella dei dati di utilizzo dei clienti con le seguenti informazioni:

Colonne di dati disponibili

string
L’indirizzo email del cliente per l’identificazione.
string
Un identificatore univoco per l’abbonamento del cliente.
number
Numero di unità gratuite incluse nel piano del cliente prima dell’applicazione degli addebiti.
currency
Il costo per unità dell’utilizzo oltre la soglia gratuita.
timestamp
Timestamp dell’evento di utilizzo più recente del cliente.
currency
Importo totale addebitato al cliente per la fatturazione basata sull’utilizzo.
number
Numero totale di unità consumate dal cliente.
number
Numero di unità che supera la soglia gratuita e viene addebitato.

Funzionalità della tabella

  • Filtraggio delle colonne: usa la funzionalità “Edit Columns” per mostrare o nascondere colonne di dati specifiche
  • Aggiornamenti in tempo reale: i dati di utilizzo riflettono le metriche di consumo più aggiornate

Esempi di aggregazione

Ecco alcuni esempi pratici del funzionamento dei diversi tipi di aggregazione:

Comprendere i tipi di aggregazione

I diversi tipi di aggregazione sono adatti a scenari di fatturazione differenti. Scegli il tipo corretto in base a come desideri misurare e addebitare l’utilizzo.

Esempi pratici di implementazione

Questi esempi illustrano applicazioni reali di ogni tipo di aggregazione con eventi di esempio e risultati previsti:
Scenario: monitora il numero totale di richieste APIConfigurazione del meter:
  • Nome evento: api.call
  • Tipo di aggregazione: Count
  • Unità di misura: calls
Eventi di esempio:
Risultato: 3 chiamate addebitate al cliente
Scenario: fattura in base al totale dei byte trasferitiConfigurazione del meter:
  • Nome evento: data.transfer
  • Tipo di aggregazione: Sum
  • Over Property: bytes
  • Unità di misura: GB
Eventi di esempio:
Risultato: 1,5 GB di trasferimento totale addebitato al cliente
Scenario: fattura in base al numero massimo di utenti simultaneiConfigurazione del meter:
  • Nome evento: concurrent.users
  • Tipo di aggregazione: Max
  • Over Property: count
  • Unità di misura: users
Eventi di esempio:
Risultato: 23 utenti simultanei di picco addebitati al cliente

Esempi di filtraggio degli eventi

Conta solo le chiamate API a endpoint specifici:Configurazione del filtro:
  • Proprietà: endpoint
  • Comparatore: equals
  • Valore: /v1/orders
Evento di esempio:
Risultato: vengono contati gli eventi che corrispondono ai criteri del filtro. Gli eventi con endpoint diversi vengono ignorati.

Risoluzione dei problemi

Risolvi i problemi comuni dell’implementazione della fatturazione basata sull’utilizzo e assicurati che il monitoraggio e la fatturazione siano accurati.

Problemi comuni

La maggior parte dei problemi relativi alla fatturazione basata sull’utilizzo rientra nelle seguenti categorie:
  • Problemi di consegna ed elaborazione degli eventi
  • Problemi di configurazione dei meter
  • Errori di tipo e formattazione dei dati
  • Problemi relativi all’ID cliente e all’autenticazione

Passaggi di debug

Durante la risoluzione dei problemi relativi alla fatturazione basata sull’utilizzo:
  1. Verifica la consegna degli eventi nella scheda di analisi Events
  2. Controlla che la configurazione del meter corrisponda alla struttura degli eventi
  3. Convalida gli ID cliente e l’autenticazione API
  4. Esamina le condizioni di filtraggio e le impostazioni di aggregazione

Soluzioni e correzioni

Cause comuni:
  • Il nome dell’evento non corrisponde esattamente alla configurazione del meter
  • Le condizioni di filtraggio degli eventi escludono i tuoi eventi
  • L’ID cliente non esiste nel tuo account Dodo Payments
  • Il timestamp dell’evento è al di fuori del periodo di fatturazione corrente
Soluzioni:
  • Verifica l’ortografia del nome dell’evento e la distinzione tra maiuscole e minuscole
  • Esamina e testa le condizioni di filtraggio
  • Conferma che l’ID cliente sia valido e attivo
  • Controlla che i timestamp degli eventi siano recenti e formattati correttamente
Cause comuni:
  • Il nome di Over Property non corrisponde alle chiavi dei metadati dell’evento
  • I valori dei metadati hanno il tipo di dati errato (stringa invece di numero)
  • Mancano proprietà dei metadati obbligatorie
Soluzioni:
  • Assicurati che le chiavi dei metadati corrispondano esattamente all’impostazione Over Property
  • Converti i numeri stringa in numeri reali nei tuoi eventi
  • Includi tutte le proprietà obbligatorie in ogni evento
Cause comuni:
  • I nomi delle proprietà del filtro non corrispondono ai metadati dell’evento
  • Comparatore errato per il tipo di dati (stringa invece di numero)
  • Distinzione tra maiuscole e minuscole nei confronti tra stringhe
Soluzioni:
  • Verifica attentamente che i nomi delle proprietà corrispondano esattamente
  • Usa comparatori appropriati per i tuoi tipi di dati
  • Tieni conto della distinzione tra maiuscole e minuscole quando filtri le stringhe

Riferimenti API correlati

Create Meter

Riferimento API per la creazione e la configurazione dei meter di utilizzo per monitorare il consumo dei clienti.

Ingest Usage Events

Riferimento API per l’invio degli eventi di utilizzo ai meter configurati per i calcoli di fatturazione.
Ultima modifica il 26 settembre 2026