Rust - Dodo Payments Documentation

O SDK Rust fornece acesso conveniente, orientado a async, à API REST do Dodo Payments a partir de aplicações escritas em Rust. Oferece requisições e respostas fortemente tipadas, auxiliares de paginação embutidos, e timeouts e ambientes configuráveis.

Instalação

Adicione o SDK ao seu projeto com Cargo:

cargo add dodopayments

Ou adicione manualmente ao seu Cargo.toml:

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

O SDK requer Rust 1.75 ou posterior, aproveitando os recursos modernos de async para um desempenho otimizado.

Início Rápido

O cliente lê sua chave de API do ambiente DODO_PAYMENTS_API_KEY por padrão. Inicialize o cliente e crie sua primeira sessão de 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(())
}

Sempre armazene suas chaves de API de forma segura usando variáveis de ambiente. Nunca as codifique diretamente no seu código-fonte.

Recursos Principais

Async First

Construído sobre Tokio e reqwest com suporte a async/await em toda a aplicação

Strong Typing

Requisições e respostas fortemente tipadas para segurança em tempo de compilação

Auto-Pagination

Transmita cada item através das páginas ou avance uma página por vez

Configurable

Configure ambientes, timeouts e URLs base por cliente

Configuração

Variáveis de Ambiente

Por padrão, Client::from_env() lê sua chave de API da variável de ambiente DODO_PAYMENTS_API_KEY e usa o URL base padrão, a menos que você defina DODO_PAYMENTS_BASE_URL:

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

Você também pode configurar o cliente explicitamente. Client::new retorna um Result, então descompacte-o com ? dentro de uma função que retorna 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(())
}

Ambientes

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

O URL base padrão é https://live.dodopayments.com. Selecione outro ambiente com o enum Environment em vez de codificar URLs diretamente:

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

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

Para continuar lendo a chave de API de DODO_PAYMENTS_API_KEY via from_env() enquanto direciona para um ambiente não padrão, sobreponha isso na configuração:

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

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

Timeouts

O timeout padrão para requisições é de 30 segundos. Sobrescreva-o 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)),
)?;

Operações Comuns

Criar uma Sessão de Checkout

Gere uma sessão de checkout:

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

Gerenciar Clientes

Crie e recupere informações do cliente:

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

Gerenciar Assinaturas

Crie e gerencie assinaturas recorrentes:

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 requer no mínimo o código ISO de duas letras country. customer é um enum CustomerRequest — passe AttachExisting para um cliente existente ou New para um novo. Campos de valor como product_price estão na menor denominação de moeda (por exemplo, 2500 = $25,00 USD).

Cobrança Baseada em Uso

Ingestão de Eventos de Uso

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

Paginação

Os endpoints de lista retornam uma página tipada cujo campo items contém a página atual de resultados. Transmita cada item em todas as páginas com 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:?}");
}

Ou avance uma página por vez com 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,
    }
}

Tratamento de Erros

Todos os métodos retornam um dodopayments::Result<T>. Falhas são representadas pelo enum dodopayments::Error. Faça um match para lidar com erros da API distintamente de erros 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 Não Documentados

Para chamar um endpoint ainda não exposto como método tipado, use o construtor de baixo nível request, que aplica autenticação e o URL base:

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

Recursos

GitHub Repository

Visualizar código-fonte e contribuir

Crates.io

Visualizar o crate publicado e versões

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Suporte

Precisa de ajuda com o SDK Rust?

Discord: Junte-se ao nosso servidor da comunidade para suporte em tempo real
Email: Entre em contato pelo suporte@dodopayments.com
GitHub: Abra uma issue no repositório

Contribuição

Nós recebemos contribuições! Confira as diretrizes de contribuição para começar.

​Instalação

​Início Rápido

​Recursos Principais

Async First

Strong Typing

Auto-Pagination

Configurable

​Configuração

​Variáveis de Ambiente

​Ambientes

​Timeouts

​Operações Comuns

​Criar uma Sessão de Checkout

​Gerenciar Clientes

​Gerenciar Assinaturas

​Cobrança Baseada em Uso

​Ingestão de Eventos de Uso

​Listar Eventos de Uso

​Paginação

​Tratamento de Erros

​Endpoints Não Documentados

​Recursos

GitHub Repository

Crates.io

API Reference

Discord Community

​Suporte

​Contribuição

Instalação

Início Rápido

Recursos Principais

Configuração

Variáveis de Ambiente

Ambientes

Timeouts

Operações Comuns

Criar uma Sessão de Checkout

Gerenciar Clientes

Gerenciar Assinaturas

Cobrança Baseada em Uso

Ingestão de Eventos de Uso

Listar Eventos de Uso

Paginação

Tratamento de Erros

Endpoints Não Documentados

Recursos

Suporte

Contribuição