Rust

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

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

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

Gerenciar Assinaturas

Crie e gerencie assinaturas recorrentes:

POST /subscriptions (the SDK’s subscriptions.create method) está obsoleto. Ele ainda funciona para integrações existentes, mas novas integrações devem criar assinaturas por meio de uma 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 exige, 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. Os campos de valor, como product_price, estão na denominação mais baixa da moeda (por exemplo, 2500 = US$ 25,00).

Faturamento baseado em uso

Ingerir eventos de uso

Acompanhe eventos personalizados:

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

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 listagem retornam uma página tipada cujo campo items contém a página atual de resultados. Transmita cada item de 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>. As falhas são representadas pelo enum dodopayments::Error. Faça a correspondência com ele para tratar os erros da API de forma distinta dos 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 que ainda não foi exposto como um método tipado, use o builder de baixo nível request, que aplica a autenticação e a URL base:

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

Recursos

GitHub Repository

Visualize o código-fonte e contribua

Crates.io

Visualize o crate publicado e as versões

API Reference

Documentação completa da API

Discord Community

Obtenha ajuda e conecte-se com desenvolvedores

Suporte

Precisa de ajuda com o Rust SDK?

Discord: participe do nosso servidor da comunidade para obter suporte em tempo real
E-mail: entre em contato conosco pelo e-mail support@dodopayments.com
GitHub: abra uma issue no repositório

Contribuição

Aceitamos contribuições! Consulte as diretrizes de contribuição para começar.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

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

Faturamento baseado em uso

Ingerir 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

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

​Faturamento baseado em uso

​Ingerir 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

Faturamento baseado em uso

Ingerir eventos de uso

Listar eventos de uso

Paginação

Tratamento de erros

Endpoints não documentados

Recursos

Suporte

Contribuição