Rust

Il Rust SDK fornisce un accesso comodo e orientato all’async al REST API di Dodo Payments dalle applicazioni scritte in Rust. Offre richieste e risposte fortemente tipizzate, helper di paginazione integrati e timeout e ambienti configurabili.

Installazione

Aggiungi l’SDK al tuo progetto con Cargo:

cargo add dodopayments

Oppure aggiungilo manualmente al tuo Cargo.toml:

[dependencies]
dodopayments = "1.106.0"
tokio = { version = "1", features = ["full"] }
serde_json = "1"
futures = "0.3" # required for streaming paginated results

L’SDK richiede Rust 1.75 o successivi, sfruttando le moderne funzionalità async per prestazioni ottimali.

Guida Rapida

Il client legge la tua key API dalla variabile di ambiente DODO_PAYMENTS_API_KEY per impostazione predefinita. Inizializza il client e crea la tua prima sessione di checkout:

use dodopayments::Client;

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
    let client = Client::from_env()?;

    let result = client
        .checkout_sessions()
        .create()
        .body(dodopayments::models::CheckoutSessionsCreateParams {
            product_cart: Some(vec![dodopayments::models::ProductItemReq {
                product_id: "product_id".to_string(),
                quantity: 1,
                addons: None,
                amount: None,
                credit_entitlements: None,
            }]),
            ..Default::default()
        })
        .await?;

    println!("{result:?}");
    Ok(())
}

Archivia sempre le tue key API in modo sicuro utilizzando variabili di ambiente. Non inserirle mai nel tuo codice sorgente.

Funzionalità Principali

Async First

Basato su Tokio e reqwest con supporto async/await

Strong Typing

Richieste e risposte fortemente tipizzate per la sicurezza durante la compilazione

Auto-Pagination

Trasmetti ogni elemento attraverso le pagine o avanza una pagina alla volta

Configurable

Configura ambienti, timeout e URL di base per cliente

Configurazione

Variabili di Ambiente

Per impostazione predefinita, Client::from_env() legge la tua key API dalla variabile di ambiente DODO_PAYMENTS_API_KEY e utilizza l’URL di base predefinito a meno che tu non imposti DODO_PAYMENTS_BASE_URL:

export DODO_PAYMENTS_API_KEY="your_api_key"
export DODO_PAYMENTS_BASE_URL="https://test.dodopayments.com" # optional

Puoi anche configurare esplicitamente il client. Client::new restituisce un Result, quindi estrailo con ? all’interno di una funzione che restituisce dodopayments::Result:

use dodopayments::{Client, ClientConfig};

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
    let client = Client::new(
        ClientConfig::new("https://live.dodopayments.com").with_api_key("My API Key"),
    )?;
    println!("{}", client.base_url());
    Ok(())
}

Ambienti

Nome	URL di Base
`live_mode`	`https://live.dodopayments.com`
`test_mode`	`https://test.dodopayments.com`

L’URL di base predefinito è https://live.dodopayments.com. Seleziona un altro ambiente con l’enum Environment invece di codificare gli URL:

use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(
    ClientConfig::from_environment(Environment::TestMode).with_api_key("My API Key"),
)?;

Per continuare a leggere la key API da DODO_PAYMENTS_API_KEY tramite from_env() mentre si punta a un ambiente non predefinito, sostituirlo nella configurazione:

use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(ClientConfig::from_env()?.with_environment(Environment::TestMode))?;

Timeout

Il timeout di richiesta predefinito è di 30 secondi. Sostituirlo per cliente:

use std::time::Duration;
use dodopayments::{Client, ClientConfig};

let client = Client::new(
    ClientConfig::new("https://live.dodopayments.com")
        .with_api_key("My API Key")
        .with_timeout(Duration::from_secs(60)),
)?;

Operazioni Comuni

Crea una Sessione di Checkout

Genera una sessione di checkout:

let session = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "pdt_123".to_string(),
            quantity: 1,
            addons: None,
            amount: None,
            credit_entitlements: None,
        }]),
        return_url: Some("https://yourdomain.com/return".to_string()),
        ..Default::default()
    })
    .await?;

println!("{session:?}");

Gestisci Clienti

Crea e recupera informazioni sui clienti:

// Create a customer
let customer = client
    .customers()
    .create()
    .body(dodopayments::models::CustomerCreateParams {
        email: "customer@example.com".to_string(),
        name: "John Doe".to_string(),
        ..Default::default()
    })
    .await?;

// Retrieve a customer
let customer = client
    .customers()
    .retrieve()
    .customer_id("cus_123")
    .await?;

println!("{customer:?}");

Gestisci Abbonamenti

Crea e gestisci abbonamenti ricorrenti:

POST /subscriptions (the SDK’s subscriptions.create method) è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è consigliabile creare le sottoscrizioni tramite una Checkout Session.

let subscription = client
    .subscriptions()
    .create()
    .body(dodopayments::models::SubscriptionCreateParams {
        billing: dodopayments::models::BillingAddress {
            country: "US".to_string(),
            city: "San Francisco".to_string(),
            state: "CA".to_string(),
            street: "1 Market St".to_string(),
            zipcode: "94105".to_string(),
        },
        customer: dodopayments::models::CustomerRequest::AttachExisting(
            dodopayments::models::AttachExistingCustomer {
                customer_id: "cus_123".to_string(),
            },
        ),
        product_id: "pdt_456".to_string(),
        quantity: 1,
        ..Default::default()
    })
    .await?;

println!("{subscription:?}");

billing richiede almeno il codice ISO a due lettere country. customer è un’enum CustomerRequest — passa AttachExisting per un cliente esistente o New per uno nuovo. I campi relativi agli importi, come product_price, sono espressi nella denominazione più piccola della valuta (ad esempio, 2500 = 25,00 $ USD).

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Monitora gli eventi personalizzati:

let response = client
    .usage_events()
    .ingest()
    .body(dodopayments::models::UsageEventsIngestParams {
        events: Some(vec![dodopayments::models::EventInput {
            customer_id: "cus_abc123".to_string(),
            event_id: "api_call_12345".to_string(),
            event_name: "api_request".to_string(),
            metadata: None,
            timestamp: None,
        }]),
        ..Default::default()
    })
    .await?;

println!("{response:?}");

Elenco degli eventi di utilizzo

let events = client
    .usage_events()
    .list()
    .query(serde_json::json!({
        "customer_id": "cus_abc123",
        "event_name": "api_request",
    }))
    .await?;

for event in &events.items {
    println!("{event:?}");
}

Paginazione

Gli endpoint di elenco restituiscono una pagina tipizzata il cui campo items contiene la pagina corrente dei risultati. Scorri ogni elemento di tutte le pagine con into_stream:

use futures::StreamExt;

let mut items = Box::pin(
    client
        .payments()
        .list()
        .query(serde_json::json!({}))
        .await?
        .into_stream(),
);

while let Some(item) = items.next().await {
    let item = item?;
    println!("{item:?}");
}

In alternativa, avanza di una pagina alla volta con get_next_page:

let mut page = client
    .payments()
    .list()
    .query(serde_json::json!({}))
    .await?;

loop {
    for item in &page.items {
        println!("{item:?}");
    }
    match page.get_next_page().await? {
        Some(next) => page = next,
        None => break,
    }
}

Gestione degli errori

Ogni metodo restituisce un dodopayments::Result<T>. Gli errori sono rappresentati dall’enum dodopayments::Error. Esegui il confronto su di esso per gestire separatamente gli errori API dagli errori di trasporto:

let result = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "product_id".to_string(),
            quantity: 1,
            addons: None,
            amount: None,
            credit_entitlements: None,
        }]),
        ..Default::default()
    })
    .await;

match result {
    Ok(value) => println!("{value:?}"),
    Err(dodopayments::Error::Api { status, message }) => {
        eprintln!("API returned {status}: {message}");
    }
    Err(err) => eprintln!("request failed: {err}"),
}

Endpoint non documentati

Per chiamare un endpoint che non è ancora esposto come metodo tipizzato, usa il builder di basso livello request, che applica l’autenticazione e l’URL di base:

let response = client
    .request(reqwest::Method::GET, "/some/path")
    .send()
    .await?;

Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

Crates.io

Visualizza il crate pubblicato e le versioni

API Reference

Documentazione completa dell’API

Discord Community

Ricevi assistenza e connettiti con gli sviluppatori

Supporto

Hai bisogno di aiuto con l’Rust SDK?

Discord: unisciti al nostro server della community per ricevere assistenza in tempo reale
Email: contattaci all’indirizzo support@dodopayments.com
GitHub: apri una segnalazione nel repository

Contribuire

I contributi sono benvenuti! Consulta le linee guida per contribuire per iniziare.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Installazione

Guida Rapida

Funzionalità Principali

Async First

Strong Typing

Auto-Pagination

Configurable

Configurazione

Variabili di Ambiente

Ambienti

Timeout

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci Clienti

Gestisci Abbonamenti

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Elenco degli eventi di utilizzo

Paginazione

Gestione degli errori

Endpoint non documentati

Risorse

GitHub Repository

Crates.io

API Reference

Discord Community

Supporto

Contribuire

​Installazione

​Guida Rapida

​Funzionalità Principali

Async First

Strong Typing

Auto-Pagination

Configurable

​Configurazione

​Variabili di Ambiente

​Ambienti

​Timeout

​Operazioni Comuni

​Crea una Sessione di Checkout

​Gestisci Clienti

​Gestisci Abbonamenti

​Fatturazione basata sull’utilizzo

​Acquisizione degli eventi di utilizzo

​Elenco degli eventi di utilizzo

​Paginazione

​Gestione degli errori

​Endpoint non documentati

​Risorse

GitHub Repository

Crates.io

API Reference

Discord Community

​Supporto

​Contribuire

Installazione

Guida Rapida

Funzionalità Principali

Configurazione

Variabili di Ambiente

Ambienti

Timeout

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci Clienti

Gestisci Abbonamenti

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Elenco degli eventi di utilizzo

Paginazione

Gestione degli errori

Endpoint non documentati

Risorse

Supporto

Contribuire