Installazione
Aggiungi l’SDK al tuo progetto con Cargo: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:
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.
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:
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:
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 conwith_timeout:
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 utilizzanoclient da Avvio rapido.
Creare una sessione di checkout
Crea una sessione di checkout con un URL di ritorno: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.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 campoitems contiene la pagina corrente dei risultati. Per trasmettere in streaming ogni elemento di tutte le pagine, chiama into_stream:
get_next_page. Restituisce None dopo l’ultima pagina:
Gestione degli errori
Ogni metodo restituisce undodopayments::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 livellorequest. 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:- Discord: Unisciti al server della community per ricevere assistenza in tempo reale.
- Email: Contatta support@dodopayments.com.
- GitHub: Apri una issue nel repository.