Rust - Dodo Payments Documentation

El SDK de Rust proporciona acceso conveniente y orientado a asincronía a la API REST de Dodo Payments desde aplicaciones escritas en Rust. Ofrece solicitudes y respuestas fuertemente tipadas, auxiliares de paginación integrados, y límites de tiempo y entornos configurables.

Instalación

Agrega el SDK a tu proyecto con Cargo:

cargo add dodopayments

O agrégalo manualmente a tu Cargo.toml:

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

El SDK requiere Rust 1.75 o posterior, aprovechando características modernas asincrónicas para un rendimiento óptimo.

Inicio Rápido

El cliente lee tu clave API del entorno de la variable DODO_PAYMENTS_API_KEY por defecto. Inicializa el cliente y crea tu primera sesión de pago:

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(())
}

Siempre almacena tus claves API de forma segura usando variables de entorno. Nunca las codifiques directamente en tu código fuente.

Características Principales

Async First

Construido sobre Tokio y reqwest con soporte async/await en todo momento

Strong Typing

Solicitudes y respuestas fuertemente tipadas para seguridad en tiempo de compilación

Auto-Pagination

Recorre cada elemento a través de páginas o avanza una página a la vez

Configurable

Configura entornos, límites de tiempo, y URLs base por cliente

Configuración

Variables de Entorno

Por defecto, Client::from_env() lee tu clave API de la variable de entorno DODO_PAYMENTS_API_KEY y utiliza la URL base predeterminada a menos que configures DODO_PAYMENTS_BASE_URL:

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

También puedes configurar el cliente explícitamente. Client::new devuelve un Result, así que desenvuélvelo con ? dentro de una función que devuelva 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(())
}

Entornos

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

La URL base predeterminada es https://live.dodopayments.com. Selecciona otro entorno con la enumeración Environment en lugar de codificar URLs directamente:

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

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

Para seguir leyendo la clave API de DODO_PAYMENTS_API_KEY a través de from_env() mientras apuntas a un entorno diferente al predeterminado, sobrescríbelo en la configuración:

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

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

Límites de Tiempo

El tiempo de espera predeterminado para solicitudes es de 30 segundos. Sobrescríbelo por 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)),
)?;

Operaciones Comunes

Crear una Sesión de Pago

Genera una sesión de pago:

let session = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "prod_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:?}");

Gestionar Clientes

Crea y recupera información de clientes:

// 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("cus_123")
    .await?;

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

Manejar Suscripciones

Crea y gestiona suscripciones recurrentes:

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 requiere al menos el código ISO country de dos letras. customer es una enumeración CustomerRequest — pasa AttachExisting para un cliente existente o New para uno nuevo. Los campos de cantidad como product_price están en la denominación de moneda más baja (por ejemplo, 2500 = $25.00 USD).

Facturación Basada en Uso

Ingestar Eventos de Uso

Rastrea eventos personalizados:

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

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

Listar Eventos de Uso

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:?}");
}

Paginación

Las funciones de listado devuelven una página tipada cuyo campo items contiene la página actual de resultados. Recorre cada elemento a través de todas las páginas 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:?}");
}

O avanza una página a la vez 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,
    }
}

Manejo de Errores

Cada método devuelve un dodopayments::Result<T>. Los fallos se representan mediante la enumeración dodopayments::Error. Haz un match en él para manejar los errores de API de manera distinta a los errores de transporte:

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}"),
}

Endpoints No Documentados

Para llamar a un endpoint que aún no está expuesto como un método tipado, utiliza el constructor de bajo nivel request, que aplica autenticación y la URL base:

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

Recursos

GitHub Repository

Ver código fuente y contribuir

Crates.io

Ver el crate publicado y sus versiones

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conéctate con desarrolladores

Soporte

¿Necesitas ayuda con el SDK de Rust?

Discord: Únete a nuestro servidor de la comunidad para obtener soporte en tiempo real
Email: Contáctanos en support@dodopayments.com
GitHub: Abre un issue en el repositorio

Contribuyendo

¡Damos la bienvenida a las contribuciones! Revisa las directrices de contribución para comenzar.

​Instalación

​Inicio Rápido

​Características Principales

Async First

Strong Typing

Auto-Pagination

Configurable

​Configuración

​Variables de Entorno

​Entornos

​Límites de Tiempo

​Operaciones Comunes

​Crear una Sesión de Pago

​Gestionar Clientes

​Manejar Suscripciones

​Facturación Basada en Uso

​Ingestar Eventos de Uso

​Listar Eventos de Uso

​Paginación

​Manejo de Errores

​Endpoints No Documentados

​Recursos

GitHub Repository

Crates.io

API Reference

Discord Community

​Soporte

​Contribuyendo

Instalación

Inicio Rápido

Características Principales

Configuración

Variables de Entorno

Entornos

Límites de Tiempo

Operaciones Comunes

Crear una Sesión de Pago

Gestionar Clientes

Manejar Suscripciones

Facturación Basada en Uso

Ingestar Eventos de Uso

Listar Eventos de Uso

Paginación

Manejo de Errores

Endpoints No Documentados

Recursos

Soporte

Contribuyendo