> ## 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.
# Misuratori
> Trasforma eventi di utilizzo grezzi in quantità fatturabili con aggregazione e filtraggio.
I contatori convertono eventi grezzi in quantità fatturabili. Filtrano gli eventi e applicano funzioni di aggregazione (Count, Sum, Max, Last) per calcolare l’utilizzo per cliente.
## Risorse API
Crea contatori in modo programmatico tramite API.
Recupera tutti i contatori nel tuo account.
Recupera i dettagli di uno specifico contatore tramite ID.
Archivia un contatore per interrompere il monitoraggio dell’utilizzo.
Ripristina un contatore archiviato per riprendere il monitoraggio.
## Creazione di un Misuratore
Nome descrittivo (es. “API Requests”, “Token Usage”)
Nome esatto dell’evento da corrispondere (sensibile alle maiuscole). Esempi: `api.call`, `image.generated`
Scegli come vengono aggregati gli eventi:
* **Count**: numero totale di eventi (chiamate API, upload)
* **Sum**: somma dei valori numerici (token, byte)
* **Max**: valore massimo nel periodo (picco utenti)
* **Last**: valore più recente
Chiave dei metadati da aggregare (richiesta per tutti i tipi tranne Count). Esempi: `tokens`, `bytes`, `duration_ms`
Etichetta dell’unità per le fatture. Esempi: `calls`, `tokens`, `GB`, `hours`
Aggiungi condizioni per filtrare quali eventi vengono conteggiati:
* **Logica AND**: Tutte le condizioni devono corrispondere
* **Logica OR**: Qualsiasi condizione può corrispondere
**Comparatori**: uguale, diverso, maggiore di, minore di, contiene
Abilita il filtraggio, scegli la logica e aggiungi condizioni con chiave della proprietà, comparatore e valore.
Controlla la configurazione e fai clic su **Create Meter**.
## Visualizzazione Analitiche
Il tuo cruscotto dei misuratori mostra:
* **Panoramica**: Utilizzo totale e grafico dell'utilizzo
* **Eventi**: Eventi individuali ricevuti
* **Clienti**: Utilizzo e addebiti per cliente
## Fatturazione in crediti invece che in valuta
Di default, i contatori addebitano i clienti per unità in dollari (o nella valuta configurata). Puoi invece configurare un contatore per **dedurre da un saldo di crediti**: così l’utilizzo consuma crediti anziché generare un addebito monetario.
La deduzione basata sui crediti richiede un [Credit Entitlement](/features/credit-based-billing) collegato allo stesso prodotto. Crea prima il tuo credito, poi collegalo al contatore.
### Quando usare la deduzione basata sui crediti
| Scenario | Standard (valuta) | Basato sui crediti |
| -------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
| Prezzo per unità semplice (\$0,01/chiamata) | ✅ Migliore soluzione | Sovraccarico inutile |
| Pacchetti prepagati di crediti (acquista 10K token, usali nel tempo) | ❌ Impossibile esprimere | ✅ Ideale |
| Uso incluso con gli abbonamenti (il piano Pro include 100K chiamate) | Possibile tramite la soglia gratuita | ✅ Meglio - i crediti si accumulano, scadono, vengono mostrati nel portale |
| Prodotti multi-contatore che condividono un pool di crediti | ❌ Ogni contatore fattura separatamente | ✅ Tutti i contatori prelevano da un unico saldo |
### Configurare un contatore per dedurre crediti
Per prima cosa, crea un credito in **Prodotti → Crediti**. Definisci l’unità (ad es. “API Calls”, “Tokens”), la precisione e le impostazioni del ciclo di vita (scadenza, rollover, overage).
Consulta la [Guida alla fatturazione basata sui crediti](/features/credit-based-billing) per istruzioni dettagliate.
Vai al tuo prodotto basato sull’utilizzo e apri la sezione di configurazione del **Contatore**.
Fai clic sul pulsante **+** per collegare un contatore. Configura il nome dell’evento, il tipo di aggregazione e l’unità di misura come sempre.
Attiva **Fattura utilizzo in crediti** nella configurazione del contatore. Questo rivela le impostazioni del credito:
Seleziona quale Credit Entitlement deve essere utilizzato da questo contatore.
Il numero di unità di utilizzo necessario per dedurre 1 credito. Ad esempio:
* `1` = ogni evento del contatore deduce 1 credito
* `100` = 100 eventi del contatore deducono 1 credito
* `1000` = 1.000 chiamate API consumano 1 credito
La **Soglia gratuita** è ancora applicabile: gli eventi al di sotto di questa soglia non deducono crediti.
**Esempio**: con soglia gratuita di 1.000 e unità del contatore per credito pari a 1:
* Il cliente utilizza 2.500 chiamate API
* Le prime 1.000 sono gratuite
* Le restanti 1.500 deducono 1.500 crediti dal loro saldo
### Come funziona la deduzione dei crediti
Una volta configurata, la pipeline di deduzione viene eseguita automaticamente:
1. **Arrivo degli eventi** - La tua applicazione invia eventi di utilizzo tramite l’[Event Ingestion API](/features/usage-based-billing/event-ingestion)
2. **Aggregazione del contatore** - Gli eventi vengono aggregati in base alla configurazione del contatore (Count, Sum, Max, Last)
3. **Elaborazione dal worker in background** - Ogni minuto, un worker recupera i nuovi eventi dall’ultimo checkpoint
4. **I crediti vengono dedotti** - L’utilizzo aggregato viene convertito in crediti tramite il tasso `meter_units_per_credit` e dedotto usando l’ordinamento **FIFO** (i grant più vecchi vengono consumati per primi)
5. **Monitoraggio degli overage** - Se il saldo raggiunge zero e l’overage è abilitato, l’utilizzo continua e l’overage viene gestito secondo il comportamento configurato (ignorato al reset, fatturato alla fattura successiva o riportato come deficit)
```mermaid theme={null}
flowchart LR
A[Usage Event] --> B[Meter Aggregation]
B --> C{Credits Available?}
C -->|Yes| D[Deduct from Balance]
C -->|No| E{Overage Enabled?}
E -->|Yes| F[Track Overage]
E -->|No| G[Block Usage]
D --> H[Update Ledger]
F --> H
```
La deduzione dei crediti viene eseguita in modo asincrono (ogni \~1 minuto). Potrebbe esserci un breve ritardo tra l’ingestione degli eventi e la deduzione dal saldo. Progetta la tua applicazione per gestire questo ritardo: non basarti su controlli di saldo in tempo reale per il controllo accessi su singole richieste.
### Più contatori, un unico pool di crediti
Puoi collegare più contatori dello stesso prodotto allo **stesso credit entitlement**. Tutti i contatori prelevano da un saldo condiviso.
**Esempio**: una piattaforma AI con due contatori:
* `text.generation` - 1 credito ogni 1.000 token
* `image.generation` - 10 crediti per immagine
Entrambi deducono dallo stesso pool “AI Credits”. Il cliente vede un unico saldo unificato nel portale.
Usa tassi `meter_units_per_credit` differenti tra i contatori per esprimere costi relativi. Le operazioni costose (generazione di immagini) richiedono meno unità del contatore per credito rispetto a quelle economiche (completamento di testo).
Visualizza l’intera cronologia di deduzione dei crediti per un cliente.
Controlla il saldo di crediti attuale di un cliente tramite API.
## Risoluzione dei problemi
* Il nome dell’evento deve corrispondere esattamente (distinzioni tra maiuscole e minuscole)
* Controlla che i filtri del contatore non stiano escludendo gli eventi
* Verifica che gli ID dei clienti esistano
* Disabilita temporaneamente i filtri per testare
* Verifica che Over Property corrisponda esattamente alla chiave dei metadati
* Usa numeri, non stringhe: `tokens: 150` invece di `"150"`
* Includi le proprietà richieste in tutti gli eventi
* Rispetta esattamente le maiuscole/minuscole
* Usa gli operatori corretti per il tipo di dato
* Assicurati che gli eventi includano le proprietà filtrate
* Controlla la scheda Eventi per contare gli eventi effettivamente ricevuti
* Verifica il tipo di aggregazione (Count vs Sum)
* Assicurati che i valori siano numerici per Sum/Max
## Prossimi passi
Inizia a inviare eventi di utilizzo dalla tua applicazione ai contatori.
Usa configurazioni di contatori preconfezionate per casi d’uso comuni.