Skip to main content
L’API Gateway Blueprint invia un evento di utilizzo a Dodo Payments per ogni chiamata API gestita dal tuo servizio, mentre un contatore Count trasforma questi eventi in un addebito per chiamata per ogni cliente. Usalo per monitorare l’utilizzo degli endpoint API, fornire informazioni sui limiti di frequenza e fatturare l’utilizzo delle API. È incluso nel pacchetto npm @dodopayments/ingestion-blueprints come trackAPICall(), che invia un evento per chiamata, e createBatch(), che accoda gli eventi per volumi elevati di richieste.

Casi d’uso

L’API Gateway Blueprint è adatto ai seguenti scenari:

API-as-a-Service

Monitora le chiamate per cliente su una piattaforma API e addebita in base al numero di chiamate.

Rate Limiting

Registra il volume di chiamate di ogni cliente per fornire informazioni sui limiti di frequenza basati sull’utilizzo. Il blueprint registra l’utilizzo, ma non applica i limiti.

Performance Monitoring

Registra i tempi di risposta e gli status code con ogni evento, così i tassi di errore sono affiancati ai dati di fatturazione.

Multi-Tenant SaaS

Fattura i clienti per il loro consumo delle API sui diversi endpoint.
Ogni evento richiede il Dodo Payments customer ID del cliente a cui addebiti, che inizia con cus_. Salvalo insieme al record dell’utente quando crei il cliente e passalo come customerId.

Guida rapida

Per monitorare le chiamate API, installa il pacchetto, crea un meter e invia un evento per ogni chiamata.
1

Install the SDK

Installa il pacchetto Dodo Payments Ingestion Blueprints:
2

Get Your API Keys

Crea una API key di Dodo Payments in Developer → API Keys nella dashboard di Dodo Payments e salvala nella variabile d’ambiente DODO_PAYMENTS_API_KEY. Usa una chiave in modalità test durante lo sviluppo. Una chiave in modalità test funziona solo con test_mode.
3

Create a Meter

Nella dashboard di Dodo Payments, vai su Products → Meters e fai clic su Create Meter. Configura questi campi:
  • Meter Name: un nome descrittivo, ad esempio API Calls.
  • Event Name: api_call, oppure un nome a tua scelta. Deve corrispondere esattamente a eventName nel codice (maiuscole e minuscole incluse).
  • Aggregation Type: Count, per fatturare in base al numero di chiamate.
  • Measurement Unit: l’unità mostrata nelle fatture, ad esempio calls.
Per conteggiare solo alcune chiamate, attiva Enable Event Filtering e aggiungi condizioni sulle chiavi dei metadati, come endpoint, method o status_code.
4

Track API Calls

Crea un’unica istanza Ingestion con la tua API key e il nome dell’evento, quindi scegli un pattern: un evento per chiamata, un batch per volumi elevati oppure un middleware Express.js che monitori ogni richiesta. Nel middleware, req.user proviene dal tuo middleware di autenticazione e il suo id deve essere un Dodo Payments customer ID. Le richieste senza un utente autenticato vengono inviate con il customer ID anonymous, che non corrisponde ad alcun cliente.

Configurazione

Configurazione dell’ingestion

Passa queste opzioni a new Ingestion():
string
obbligatorio
La tua API key di Dodo Payments dalla dashboard.
string
Modalità dell’ambiente: test_mode o live_mode. Il valore predefinito è test_mode. Gli SDK di Dodo Payments usano invece live_mode come valore predefinito, quindi imposta esplicitamente live_mode in produzione.
string
obbligatorio
Nome dell’evento che corrisponde a Event Name del meter (maiuscole e minuscole incluse). Ogni evento inviato da questa istanza lo utilizza.

Opzioni per il monitoraggio delle chiamate API

Passa queste opzioni a trackAPICall() e batch.add():
string
obbligatorio
Il Dodo Payments customer ID a cui addebitare la chiamata, ad esempio cus_123.
object
Metadati facoltativi sulla chiamata API, come endpoint, method, status code e tempo di risposta. Ogni valore deve essere una stringa, un numero o un booleano. L’API rifiuta oggetti annidati, array e valori null.

Configurazione dei batch

createBatch(ingestion, options) accoda gli eventi in memoria e restituisce un oggetto con tre metodi: add() accoda un evento, flush() invia gli eventi accodati e cleanup() li invia e arresta il timer. Un flush invia una richiesta di ingestion per ogni evento, in parallelo.
number
Numero di eventi accodati che attiva un flush immediato. Valore predefinito: 100.
number
Millisecondi di attesa dopo l’ultimo add() prima del flush del batch. Ogni add() riavvia il timer. Valore predefinito: 5000 (5 secondi).

Best practice

Usa il batching per volumi elevati: per le applicazioni ad alto traffico, usa createBatch(). batch.add() restituisce immediatamente il controllo, quindi il tracciamento non aggiunge latenza al gestore delle richieste.
Un batch conserva gli eventi in memoria fino al flush e non ritenta l’invio degli eventi che non è riuscito a inviare. Un flush automatico registra l’errore con console.error. Una chiamata a flush() o cleanup() genera l’errore.
Pulisci i batch durante l’arresto: chiama batch.cleanup() quando l’applicazione si arresta, così gli eventi in sospeso vengono inviati invece di andare persi.
Ultima modifica il 28 settembre 2026