Skip to main content

API Reference - Events Ingestion

Accedi alla documentazione API completa per l’ingestione degli eventi di utilizzo e prova interattivamente le richieste e le risposte di ingestione degli eventi.

API Reference - Meters Creation

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

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 completa per configurare il tuo contatore di utilizzo:
1

Configure Basic Information

Configura i dettagli fondamentali del tuo meter.
string
obbligatorio
Scegli un nome chiaro e descrittivo che identifichi cosa monitora questo meter.Esempi: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”
string
Fornisci una spiegazione dettagliata di cosa misura questo meter.Esempio: “Counts each POST /v1/orders request made by the customer”
string
obbligatorio
Specifica l’identificatore 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 semplicemente 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
Definisci l’etichetta dell’unità per la visualizzazione 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 sottostringa
  • does_not_contain - Filtro di esclusione 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

Rivedi la configurazione del meter e clicca su Crea meter.
Il tuo meter è ora pronto per ricevere e aggregare gli eventi di utilizzo.

Collegare il contatore a un prodotto

Una volta creato il tuo contatore, devi collegarlo a un prodotto per abilitare la fatturazione basata sull’uso. Questo processo collega i dati di utilizzo del tuo contatore alle regole di prezzo per la fatturazione dei clienti. Collegare i contatori ai prodotti stabilisce la connessione tra il tracciamento dell’uso e la fatturazione:
  • I prodotti definiscono le regole di prezzo e il comportamento di fatturazione
  • I contatori forniscono dati di utilizzo per i calcoli di fatturazione
  • Più contatori possono essere collegati a un singolo prodotto per scenari di fatturazione complessi

Processo di configurazione del prodotto

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

Choose Usage-Based Billing Product Type

Vai alla pagina di creazione o modifica del prodotto e seleziona Basato sull’utilizzo come tipo di prodotto.
2

Select Associated Meter

Clicca su Meter associato per aprire il pannello di selezione meter dal lato.Questo pannello ti consente di configurare quali meter monitoreranno l’utilizzo per questo prodotto.
3

Add Your Meter

Nella barra di selezione del meter:
  1. Clicca su Aggiungi contatori per visualizzare i contatori disponibili
  2. Seleziona il contatore che hai creato dall’elenco a discesa
  3. Il contatore selezionato apparirà nella configurazione del tuo prodotto
4

Configure Price Per Unit

Imposta il prezzo per ciascuna unità di utilizzo monitorata dal tuo meter.
number
obbligatorio
Definisci quanto addebitare per ogni unità misurata dal tuo meter.Esempio: impostando $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 soglia di utilizzo gratuita prima dell’inizio della fatturazione.
number
Numero di unità che i clienti possono consumare gratuitamente prima che inizi il calcolo dell’utilizzo a pagamento.Come funziona:
  • Soglia gratuita: 100 unità
  • Prezzo per unità: $0.50
  • Utilizzo cliente: 250 unità
  • Calcolo: (250 - 100) × 0.50=0.50 = **75.00** addebitati
Le soglie gratuite sono ideali per modelli freemium, periodi di prova o per fornire ai clienti un’allocazione base inclusa nel piano.
La soglia gratuita si applica a ogni ciclo di fatturazione, offrendo ai clienti nuove allocazioni mensili o secondo il tuo programma.
6

Save Configuration

Rivedi la configurazione del meter e dei prezzi, quindi clicca Salva modifiche per finalizzare.
Il tuo 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 tuo meter verranno tracciati e aggregati
  • I calcoli di fatturazione applicheranno automaticamente le tue regole di prezzo
  • I clienti verranno addebitati in base al consumo reale durante ogni ciclo di fatturazione
Ricorda che puoi aggiungere fino a 10 meter per prodotto, abilitando monitoraggi sofisticati dell’utilizzo su più dimensioni come chiamate API, storage, tempo di calcolo e metriche personalizzate.

Invio di eventi di utilizzo

Una volta configurato il tuo contatore, puoi iniziare a inviare eventi di utilizzo dalla tua applicazione per monitorare l’uso dei clienti.

Struttura dell’evento

Ogni evento di utilizzo deve includere questi campi obbligatori:
string
obbligatorio
Identificatore univoco per questo evento specifico. Deve essere unico tra tutti gli eventi.
string
obbligatorio
L’ID cliente Dodo Payments a cui attribuire questo utilizzo.
string
obbligatorio
Il nome dell’evento che corrisponde alla configurazione del tuo meter. I nomi degli eventi attivano il meter appropriato.
string
Timestamp ISO 8601 in cui si è verificato l’evento. Se non fornito, predefinito all’ora corrente.
object
Proprietà aggiuntive per il filtraggio e l’aggregazione. Includi tutti i valori riferiti nella tua impostazione “Over Property” o nelle condizioni di filtraggio.

Esempi di API per eventi di utilizzo

Invia eventi di utilizzo ai tuoi contatori configurati utilizzando l’API degli eventi:

Elementi chiave da conoscere per un’ingestione 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 conteggiato nuovamente, quindi i retry non generano doppi addebiti. Ricava 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 chiamata; i batch più grandi vengono rifiutati, quindi suddividi i volumi elevati in più chiamate. Per i carichi di lavoro ad alto volume, memorizza temporaneamente gli eventi e inviali in batch invece di effettuare una richiesta per ogni evento.
Ripeti 5xx e 429, mai 4xx. Esegui il retry in caso di errori del server (5xx) e di limiti di frequenza (429), utilizzando un backoff esponenziale. Non eseguire il retry per gli errori di convalida 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 andrà perso nessuno.
Imposta i timestamp intenzionalmente. Ometti timestamp per gli eventi in tempo reale: verrà impostato automaticamente sull’ora di ingestione. Impostalo esplicitamente (ISO 8601) durante il backfill o quando invii eventi ritardati/in batch, affinché l’utilizzo venga assegnato al periodo di fatturazione corretto.
Invia i metadati aggregati come numeri, non come stringhe. Qualsiasi proprietà a cui fa riferimento la voce Over Property di un meter (Sum, Max, Last) deve essere di tipo numerico: { "tokens": 150 }, non { "tokens": "150" }. I valori stringa non verranno aggregati.

Analisi della fatturazione basata sull’utilizzo

Monitora e analizza i dati della tua 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 tua strategia di prezzo e comprendere i comportamenti di utilizzo.

Analisi della panoramica

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

Metriche dell’attività

Monitora le principali statistiche di utilizzo su periodi di tempo diversi:
metric
Mostra l’attività di utilizzo per il periodo di fatturazione corrente, aiutandoti a comprendere i modelli di consumo mensili.
metric
Mostra le statistiche cumulative sull’utilizzo 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 individuare 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 su giorni, settimane o mesi
  • Supporto per più meter: visualizza contemporaneamente i dati di meter diversi
  • Analisi delle tendenze: individua picchi di utilizzo, modelli e traiettorie di crescita
Il grafico si adatta automaticamente in base al volume di utilizzo e all’intervallo di tempo selezionato, offrendo una visibilità chiara sia sulle piccole fluttuazioni sia sui cambiamenti significativi nell’utilizzo.

Analisi degli eventi

Tabella degli eventi che mostra nomi e ID degli eventi e i controlli di paginazione per un'analisi dettagliata degli eventi
La scheda Events offre una visibilità dettagliata 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: 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 ti consente di monitorare i singoli eventi di utilizzo tra tutti i tuoi clienti, offrendo trasparenza nei calcoli di fatturazione e nei 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
Indirizzo email del cliente per l’identificazione.
string
Identificatore univoco dell’abbonamento del cliente.
number
Numero di unità gratuite incluse nel piano del cliente prima dell’applicazione degli addebiti.
currency
Il costo per unità per l’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 che 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 diversi scenari di fatturazione. Scegli il tipo corretto in base a come vuoi misurare e addebitare l’utilizzo.

Esempi pratici di implementazione

Questi esempi illustrano applicazioni reali di ciascun 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 addebitati al cliente
Scenario: fattura in base al numero massimo di utenti contemporaneiConfigurazione del meter:
  • Nome evento: concurrent.users
  • Tipo di aggregazione: Max
  • Over Property: count
  • Unità di misura: users
Eventi di esempio:
Risultato: 23 utenti contemporanei di picco addebitati al cliente

Esempi di filtraggio degli eventi

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

Risoluzione dei problemi

Risolvi i problemi comuni nell’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 in queste categorie:
  • Problemi di consegna ed elaborazione degli eventi
  • Problemi di configurazione dei meter
  • Errori relativi al tipo e alla formattazione dei dati
  • Problemi relativi all’ID cliente e all’autenticazione

Passaggi per il debug

Quando risolvi i problemi della 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 non rientra nel 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 un 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 memorizzati come stringhe in numeri effettivi 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
  • Considera la distinzione tra maiuscole e minuscole quando filtri le stringhe

Riferimenti API correlati

Create Meter

Riferimento API per creare e configurare meter di utilizzo per monitorare il consumo dei clienti

Ingest Usage Events

Riferimento API per inviare eventi di utilizzo ai meter configurati per i calcoli di fatturazione
Ultima modifica il 31 luglio 2026