Vai al contenuto principale

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.
​
Meter Name
string
obbligatorio
Scegli un nome chiaro e descrittivo che identifichi cosa monitora questo meter.Esempi: “Tokens”, “API Calls”, “Storage Usage”, “Compute Hours”
​
Description
string
Fornisci una spiegazione dettagliata di cosa misura questo meter.Esempio: “Counts each POST /v1/orders request made by the customer”
​
Event Name
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.
​
Aggregation Type
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
​
Over Property
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.
​
Measurement Unit
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 la 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.
​
Price Per Unit
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.
​
Free Threshold
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:
​
event_id
string
obbligatorio
Identificatore univoco per questo evento specifico. Deve essere unico tra tutti gli eventi.
​
customer_id
string
obbligatorio
L’ID cliente Dodo Payments a cui attribuire questo utilizzo.
​
event_name
string
obbligatorio
Il nome dell’evento che corrisponde alla configurazione del tuo meter. I nomi degli eventi attivano il meter appropriato.
​
timestamp
string
Timestamp ISO 8601 in cui si è verificato l’evento. Se non fornito, predefinito all’ora corrente.
​
metadata
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: 
const response = 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_atXa1lklCRRzMicTqfiw2", 
        event_name: "api.call",
        timestamp: new Date().toISOString(),
        metadata: {
          endpoint: "/v1/orders",
          method: "POST",
          response_size: 1024
        }
      }
    ]
  })
});

​
Analisi della fatturazione basata sull’uso

Monitora e analizza i tuoi dati di fatturazione basata sull’uso con un dashboard analitico completo. Monitora i modelli di consumo dei clienti, le prestazioni dei contatori e le tendenze di fatturazione per ottimizzare la tua strategia di prezzo e comprendere i comportamenti di utilizzo.

​
Analisi panoramica

La scheda Panoramica fornisce una visione completa delle prestazioni della tua fatturazione basata sull’uso:

​
Metriche di attività

Monitora le statistiche chiave di utilizzo su diversi periodi di tempo:
​
Current Month
metric
Mostra l’attività di utilizzo nel periodo di fatturazione corrente, aiutandoti a comprendere i modelli mensili di consumo.
​
All Time
metric
Mostra statistiche cumulative dall’inizio del tracciamento, offrendo approfondimenti sulla crescita a lungo termine.
Usa il selettore del periodo per confrontare l’utilizzo in mesi diversi e identificare tendenze stagionali o schemi di crescita.

​
Grafico delle quantità dei contatori

Meter quantities chart showing usage trends over time with purple gradient visualization
Il grafico delle quantità dei contatori visualizza le tendenze di utilizzo nel tempo con le seguenti caratteristiche:
  • Visualizzazione temporale: Monitora i modelli di utilizzo su giorni, settimane o mesi
  • Supporto per più contatori: Visualizza i dati di diversi contatori simultaneamente
  • Analisi delle tendenze: Identifica picchi di utilizzo, modelli e traiettorie di crescita
Il grafico si adatta automaticamente in base al volume di utilizzo e al range temporale selezionato, offrendo visibilità chiara sia sulle piccole fluttuazioni che sui maggiori cambiamenti.

​
Analisi degli eventi

Tabella eventi che mostra nomi degli eventi, ID e controlli di paginazione per un'analisi dettagliata degli eventi
La scheda Eventi fornisce visibilità granulare sugli eventi di utilizzo individuali:

​
Visualizzazione delle informazioni sugli eventi

La tabella degli eventi fornisce una chiara visione degli eventi di utilizzo individuali con le seguenti colonne:
  • Nome dell’evento: L’azione o il trigger specifico che ha generato l’evento di utilizzo
  • ID evento: Identificatore unico per ogni istanza di evento
  • ID cliente: Il cliente associato all’evento
  • Timestamp: Quando si è verificato l’evento
Questa visualizzazione ti consente di monitorare eventi di utilizzo individuali su tutta la base clienti, fornendo trasparenza nei calcoli di fatturazione e nei modelli di utilizzo.

​
Analisi dei clienti

La scheda Clienti fornisce una vista tabellare dettagliata dei dati di utilizzo dei clienti con le seguenti informazioni:

​
Colonne di dati disponibili

​
Customer Email
string
Indirizzo email del cliente per identificazione.
​
Subscription ID
string
Identificatore univoco per l’abbonamento del cliente.
​
Free Threshold
number
Numero di unità gratuite incluse nel piano del cliente prima che si applichino addebiti.
​
Price Per Unit
currency
Il costo per unità dell’utilizzo oltre la soglia gratuita.
​
Last Event
timestamp
Timestamp dell’evento di utilizzo più recente del cliente.
​
Total Price
currency
Importo totale addebitato al cliente per la fatturazione basata sull’utilizzo.
​
Consumed Units
number
Numero totale di unità consumate dal cliente.
​
Chargeable Units
number
Numero di unità che superano la soglia gratuita e vengono addebitate.

​
Caratteristiche della tabella

  • Filtraggio delle colonne: Usa la funzione “Modifica colonne” per mostrare/nascondere colonne di dati specifiche
  • Aggiornamenti in tempo reale: I dati di utilizzo riflettono le metriche di consumo più attuali

​
Esempi di aggregazione

Ecco esempi pratici di come funzionano i diversi tipi di aggregazione:

​
Comprendere i tipi di aggregazione

Diversi tipi di aggregazione servono a diversi scenari di fatturazione. Scegli il tipo giusto in base a come desideri misurare e addebitare per l’uso.

​
Esempi di implementazione pratica

Questi esempi dimostrano applicazioni reali di ciascun tipo di aggregazione con eventi di esempio e risultati attesi.
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:
{
  "events": [
    {"event_id": "call_1", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_2", "customer_id": "cus_123", "event_name": "api.call"},
    {"event_id": "call_3", "customer_id": "cus_123", "event_name": "api.call"}
  ]
}
Risultato: 3 chiamate fatturate al cliente
Scenario: Fattura in base al totale di byte trasferitiConfigurazione del meter:
  • Nome evento: data.transfer
  • Tipo di aggregazione: Sum
  • Over Property: bytes
  • Unità di misura: GB
Eventi di esempio:
{
  "events": [
    {
      "event_id": "transfer_1",
      "customer_id": "cus_123", 
      "event_name": "data.transfer",
      "metadata": {"bytes": 1073741824}
    },
    {
      "event_id": "transfer_2",
      "customer_id": "cus_123",
      "event_name": "data.transfer", 
      "metadata": {"bytes": 536870912}
    }
  ]
}
Risultato: 1.5 GB di trasferimento totale fatturati al cliente
Scenario: Fattura basata sul 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:
{
  "events": [
    {
      "event_id": "peak_1",
      "customer_id": "cus_123",
      "event_name": "concurrent.users", 
      "metadata": {"count": 15}
    },
    {
      "event_id": "peak_2",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 23}
    },
    {
      "event_id": "peak_3",
      "customer_id": "cus_123",
      "event_name": "concurrent.users",
      "metadata": {"count": 18}
    }
  ]
}
Risultato: 23 utenti concorrenti di picco fatturati 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:
{
  "event_id": "call_1",
  "customer_id": "cus_123",
  "event_name": "api.call",
  "metadata": {
    "endpoint": "/v1/orders",
    "method": "POST"
  }
}
Risultato: Gli eventi che soddisfano i criteri del filtro verrebbero conteggiati. Gli eventi con endpoint diversi verrebbero ignorati.

​
Risoluzione dei problemi

Risolvi i problemi comuni con l’implementazione della fatturazione basata sull’uso e assicurati un tracciamento e una fatturazione accurati.

​
Problemi comuni

La maggior parte dei problemi di fatturazione basata sull’uso rientra in queste categorie:
  • Problemi di consegna e elaborazione degli eventi
  • Problemi di configurazione del contatore
  • Errori di tipo di dati e formattazione
  • Problemi di ID cliente e autenticazione

​
Passi per il debug

Quando risolvi i problemi della fatturazione basata sull’uso:
  1. Verifica la consegna degli eventi nella scheda analitica degli eventi
  2. Controlla che la configurazione del contatore corrisponda alla struttura del tuo evento
  3. Valida gli ID cliente e l’autenticazione API
  4. Rivedi 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 escludono i tuoi eventi
  • L’ID cliente non esiste nel tuo account Dodo Payments
  • Il timestamp dell’evento è fuori dal periodo di fatturazione corrente
Soluzioni:
  • Verifica ortografia e maiuscole del nome dell’evento
  • Rivedi 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 sono del tipo di dato sbagliato (stringa vs numero)
  • Mancano proprietà dei metadati richieste
Soluzioni:
  • Assicurati che le chiavi dei metadati corrispondano esattamente alla tua impostazione Over Property
  • Converti le stringhe numeriche in numeri effettivi nei tuoi eventi
  • Includi tutte le proprietà richieste in ogni evento
Cause comuni:
  • I nomi delle proprietà del filtro non corrispondono ai metadati dell’evento
  • Comparatore sbagliato per il tipo di dato (stringa vs numero)
  • Sensibilità al maiuscolo/minuscolo nei confronti delle stringhe
Soluzioni:
  • Ricontrolla che i nomi delle proprietà corrispondano esattamente
  • Usa comparatori appropriati per i tuoi tipi di dato
  • Considera la sensibilità al maiuscolo/minuscolo quando filtri le stringhe