> ## 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.
# Guida all'integrazione della fatturazione basata sull'uso
> Scopri come configurare i contatori e inviare eventi di utilizzo per abilitare una fatturazione basata sull'uso accurata con Dodo Payments.
Accedi alla documentazione API completa per l'ingestione degli eventi di utilizzo e prova interattivamente le richieste e le risposte di ingestione degli eventi.
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:
Configura i dettagli fondamentali del tuo meter.
Scegli un nome chiaro e descrittivo che identifichi cosa monitora questo meter.
Esempi: "Tokens", "API Calls", "Storage Usage", "Compute Hours"
Fornisci una spiegazione dettagliata di cosa misura questo meter.
Esempio: "Counts each POST /v1/orders request made by the customer"
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.
Definisci come il meter calcola l'utilizzo dai tuoi eventi.
Seleziona come devono essere aggregati gli eventi:
Conta semplicemente il numero di eventi ricevuti.
Caso d'uso: chiamate API, visualizzazioni di pagina, caricamenti di file
Calcolo: Numero totale di eventi
Somma i valori di una proprietà specifica nei tuoi eventi.
Caso d'uso: trasferimento dati, consumo di storage, tempo di elaborazione
Calcolo: Somma di tutti i valori della proprietà
Registra il valore più alto di una determinata proprietà durante il periodo di fatturazione.
Caso d'uso: utenti simultanei di picco, massimo storage utilizzato, massima larghezza di banda
Calcolo: Valore massimo della proprietà osservato
Usa il valore più recente di una proprietà specifica.
Caso d'uso: livello attuale del piano, ultima impostazione di configurazione
Calcolo: Ultimo valore della proprietà registrato
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.
Definisci l'etichetta dell'unità per la visualizzazione nei report e nella fatturazione.
Esempi: "calls", "GB", "hours", "tokens"
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 eventi**
Attiva **Abilita il filtraggio degli eventi** per attivare l'elaborazione condizionale degli eventi.
**Scegli la logica di filtro**
Seleziona 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"`
Almeno una condizione deve essere vera affinché un evento venga conteggiato. Usalo quando vuoi includere eventi che soddisfano uno qualsiasi di diversi criteri.
**Esempio:** Conta gli eventi dove `method = "POST"` OR `method = "PUT"` OR `method = "DELETE"`
**Impostazione delle condizioni di filtro**
Clicca **Aggiungi condizione** per creare una nuova regola di filtro.
Specifica il nome della proprietà nei tuoi metadati dell'evento.
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
Imposta il valore di riferimento per il confronto.
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.
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:
Vai alla pagina di creazione o modifica del prodotto e seleziona **Basato sull'utilizzo** come tipo di prodotto.
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.
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
Imposta il prezzo per ciascuna unità di utilizzo monitorata dal tuo meter.
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
Configura una soglia di utilizzo gratuita prima dell'inizio della fatturazione.
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 = **$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.
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:
Identificatore univoco per questo evento specifico. Deve essere unico tra tutti gli eventi.
L'ID cliente Dodo Payments a cui attribuire questo utilizzo.
Il nome dell'evento che corrisponde alla configurazione del tuo meter. I nomi degli eventi attivano il meter appropriato.
Timestamp ISO 8601 in cui si è verificato l'evento. Se non fornito, predefinito all'ora corrente.
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:
```javascript Node.js theme={null}
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
}
}
]
})
});
```
```python Python theme={null}
import requests
from datetime import datetime
response = requests.post(
'https://test.dodopayments.com/events/ingest',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
},
json={
'events': [
{
'event_id': 'api_call_1234',
'customer_id': 'cus_atXa1lklCRRzMicTqfiw2',
'event_name': 'api.call',
'timestamp': datetime.now().isoformat(),
'metadata': {
'endpoint': '/v1/orders',
'method': 'POST',
'response_size': 1024
}
}
]
}
)
```
```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": "api_call_1234",
"customer_id": "cus_atXa1lklCRRzMicTqfiw2",
"event_name": "api.call",
"timestamp": "2024-01-15T10:30:00Z",
"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:
Mostra l'attività di utilizzo nel periodo di fatturazione corrente, aiutandoti a comprendere i modelli mensili di consumo.
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
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
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
Indirizzo email del cliente per identificazione.
Identificatore univoco per l'abbonamento del cliente.
Numero di unità gratuite incluse nel piano del cliente prima che si applichino addebiti.
Il costo per unità dell'utilizzo oltre la soglia gratuita.
Timestamp dell'evento di utilizzo più recente del cliente.
Importo totale addebitato al cliente per la fatturazione basata sull'utilizzo.
Numero totale di unità consumate dal cliente.
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 API
Configurazione del meter:
* Nome evento: `api.call`
* Tipo di aggregazione: Count
* Unità di misura: `calls`
**Eventi di esempio**:
```json theme={null}
{
"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 trasferiti
Configurazione del meter:
* Nome evento: `data.transfer`
* Tipo di aggregazione: Sum
* Over Property: `bytes`
* Unità di misura: `GB`
**Eventi di esempio**:
```json theme={null}
{
"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 simultanei
Configurazione del meter:
* Nome evento: `concurrent.users`
* Tipo di aggregazione: Max
* Over Property: `count`
* Unità di misura: `users`
**Eventi di esempio**:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
Conta solo i caricamenti di file di grandi dimensioni:
Configurazione del filtro:
* Proprietà: `file_size`
* Comparatore: `greater_than`
* Valore: `1048576` (1MB in byte)
Evento di esempio:
```json theme={null}
{
"event_id": "upload_1",
"customer_id": "cus_123",
"event_name": "file.upload",
"metadata": {
"file_size": 5242880,
"file_type": "image"
}
}
```
Risultato: I file più grandi di 1MB verrebbero conteggiati. I file più piccoli verrebbero ignorati.
Conta le chiamate API premium durante l'orario lavorativo:
Configurazione del filtro (utilizzando la logica AND):
* Proprietà: `plan_type`, Comparatore: `equals`, Valore: `premium`
* Proprietà: `hour`, Comparatore: `greater_than_or_equals`, Valore: `9`
* Proprietà: `hour`, Comparatore: `less_than`, Valore: `17`
Evento di esempio:
```json theme={null}
{
"event_id": "call_1",
"customer_id": "cus_123",
"event_name": "api.call",
"metadata": {
"plan_type": "premium",
"hour": 14,
"endpoint": "/v1/analytics"
}
}
```
Risultato: Le chiamate API premium durante l'orario lavorativo (9 AM - 5 PM) verrebbero conteggiate.
## 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
## Riferimenti API Correlati
Riferimento API per la creazione e configurazione di contatori d'uso per monitorare il consumo dei clienti
Riferimento API per inviare eventi di utilizzo ai tuoi contatori configurati per i calcoli di fatturazione