Skip to main content
Il Rust SDK offre alle applicazioni Rust asincrone un accesso tipizzato alla REST API di Dodo Payments. È basato su Tokio e reqwest, utilizza struct tipizzate per richieste e risposte, trasmette in streaming i risultati paginati e ritenta le richieste non riuscite.

Installazione

Aggiungi l’SDK al tuo progetto con Cargo:
Oppure aggiungilo manualmente al tuo Cargo.toml:
Il SDK richiede Rust 1.75 o versioni successive.

Guida Rapida

Client::from_env() legge la tua API key dalla variabile d’ambiente DODO_PAYMENTS_API_KEY. Crea un client, quindi crea una sessione di checkout:
Se DODO_PAYMENTS_API_KEY non è impostata, Client::from_env() restituisce un Error::Config. Il client si connette alla modalità live, a meno che tu non scelga un altro ambiente, come mostrato in Ambienti. Una API key di test funziona solo in modalità test.
Conserva le API key nelle variabili d’ambiente o in un secrets manager. Non inserirle mai direttamente nel codice sorgente.

Funzionalità principali

Async First

Basato su Tokio e reqwest, con async/await per ogni richiesta.

Strong Typing

Struct tipizzate per richieste e risposte, con controlli in fase di compilazione.

Auto-Pagination

Trasmetti in streaming ogni elemento tra le pagine oppure procedi una pagina alla volta.

Configurable

Imposta l’ambiente, l’URL di base, il timeout e il numero di tentativi per ogni client.

Configurazione

Variabili d’ambiente

Client::from_env() legge la tua API key da DODO_PAYMENTS_API_KEY. Utilizza l’URL della modalità live, a meno che tu non imposti DODO_PAYMENTS_BASE_URL:
Il Rust SDK non legge DODO_PAYMENTS_WEBHOOK_KEY e non dispone di un metodo che verifichi le firme dei webhook. Per verificarle, segui Webhooks. Puoi anche configurare esplicitamente il client. Client::new restituisce un Result, quindi esegui l’unwrap con ? all’interno di una funzione che restituisce dodopayments::Result:

Ambienti

Il SDK dispone di due ambienti: L’URL di base predefinito è https://live.dodopayments.com. Per selezionare un altro ambiente, usa l’enum Environment invece di un URL hardcoded:
Per continuare a leggere la API key da DODO_PAYMENTS_API_KEY con from_env(), ma indirizzarla a un altro ambiente, sovrascrivi l’ambiente nella configurazione:

Timeout

Il timeout predefinito delle richieste è di 30 secondi. Sovrascrivilo per un client con with_timeout:
Il client ritenta gli errori di connessione e le risposte con status 408, 409, 429 o 500 e superiori. Per impostazione predefinita esegue due tentativi, con exponential backoff, e attende l’header Retry-After quando l’API ne invia uno. Per modificare il numero di tentativi, chiama with_max_retries su ClientConfig, ad esempio .with_max_retries(0) per disabilitare i tentativi.

Operazioni comuni

Gli esempi di questa sezione utilizzano client da Avvio rapido.

Creare una sessione di checkout

Crea una sessione di checkout con un URL di ritorno:
Reindirizza il cliente a session.checkout_url. Ogni URL di checkout funziona una sola volta e scade dopo 24 ore. Per tutte le opzioni della sessione, consulta Sessioni di checkout.

Gestire i clienti

Crea un cliente con un indirizzo email e un nome, quindi recuperalo tramite ID:

Gestire gli abbonamenti

Crea un abbonamento per un cliente esistente.
POST /subscriptions (il metodo subscriptions().create() del SDK) è deprecato. Funziona ancora per le integrazioni esistenti, ma le nuove integrazioni devono creare gli abbonamenti tramite una sessione di checkout.
billing richiede solo country, una variante dell’enum CountryCode come CountryCode::Us. customer è un enum CustomerRequest: passa AttachExistingCustomer per un cliente esistente o NewCustomer per crearne uno. Per addebitare un abbonamento on-demand, chiama client.subscriptions().charge().subscription_id(...) con un body SubscriptionsChargeParams. I campi degli importi come product_price sono espressi nell’unità monetaria più piccola (ad esempio, 2500 equivale a $25.00).

Fatturazione basata sull’utilizzo

Acquisire eventi di utilizzo

Invia eventi di utilizzo per un cliente:
event_id è la chiave di idempotenza, quindi assegna a ogni evento un valore univoco. Se timestamp è None, l’evento utilizza l’ora corrente.

Elencare gli eventi di utilizzo

Elenca gli eventi filtrati per cliente e nome dell’evento. I filtri vanno inseriti in un oggetto JSON di query:

Paginazione

Gli endpoint di elenco restituiscono una pagina tipizzata il cui campo items contiene la pagina corrente dei risultati. Per trasmettere in streaming ogni elemento di tutte le pagine, chiama into_stream:
Per procedere una pagina alla volta, chiama get_next_page. Restituisce None dopo l’ultima pagina:

Gestione degli errori

Ogni metodo restituisce un dodopayments::Result<T>. Gli errori sono varianti dell’enum dodopayments::Error: Api per uno status di errore restituito dall’API, Http per errori di trasporto, Json per errori di serializzazione, Config per errori di configurazione e MissingPathParam o MissingBody per richieste incomplete. Esegui il match su questo valore per gestire separatamente gli errori dell’API e gli errori di trasporto:

Endpoint non documentati

Per chiamare un endpoint che non dispone di un metodo tipizzato, usa il builder di basso livello request. Applica l’autenticazione e l’URL di base. Per denominare reqwest::Method, aggiungi reqwest 0.12 alle dipendenze:

Risorse

GitHub Repository

Codice sorgente, release e l’elenco completo dei metodi.

Crates.io

Il crate pubblicato e le relative versioni.

API Reference

Ogni endpoint, parametro e risposta.

Discord Community

Fai domande e parla con altri sviluppatori.

Supporto

Per ricevere assistenza con il Rust SDK:

Contribuire

Per contribuire, leggi le linee guida per i contributi.
Ultima modifica il 26 settembre 2026