Pular para o conteúdo principal
O SDK TypeScript fornece acesso conveniente ao lado do servidor à API REST de pagamentos Dodo para aplicações TypeScript e JavaScript. Ele apresenta definições de tipo abrangentes, tratamento de erros, tentativas, timeouts e auto-paginação para um processamento de pagamentos sem interrupções.

Instalação

Instale o SDK usando seu gerenciador de pacotes de sua escolha:
npm install dodopayments

Início Rápido

Inicialize o cliente com sua chave de API e comece a processar pagamentos:
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
  environment: 'test_mode', // defaults to 'live_mode'
});

const checkoutSessionResponse = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'product_id', quantity: 1 }],
});

console.log(checkoutSessionResponse.session_id);
Sempre armazene suas chaves de API de forma segura usando variáveis de ambiente. Nunca as comite no controle de versão ou as exponha em código do lado do cliente.

Recursos Principais

TypeScript First

Suporte total a TypeScript com definições de tipo abrangentes para todos os endpoints da API

Auto-Paginação

Paginação automática para respostas de lista torna o trabalho com grandes conjuntos de dados sem esforço

Tratamento de Erros

Tipos de erro integrados com mensagens detalhadas para diferentes cenários de falha

Tentativas Inteligentes

Tentativas automáticas configuráveis com backoff exponencial para erros transitórios

Configuração

Variáveis de Ambiente

Defina variáveis de ambiente para configuração segura:
.env
DODO_PAYMENTS_API_KEY=your_api_key_here

Configuração de Timeout

Configure timeouts de requisição globalmente ou por requisição: TODO: PLACEHOLDER_DE_CÓDIGO_d9422b829dcf570e0d6ea69d34928d6d

Configuração de Tentativas

Configure o comportamento de tentativas automáticas: TODO: PLACEHOLDER_DE_CÓDIGO_8ec75888d9859a1d5d88346864f4e8db
O SDK tenta automaticamente novamente requisições que falham devido a erros de rede ou problemas no servidor (respostas 5xx) com backoff exponencial.

Operações Comuns

Criar uma Sessão de Checkout

Gere uma sessão de checkout para coletar informações de pagamento:
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_123',
      quantity: 1
    }
  ],
  return_url: 'https://yourdomain.com/return'
});

console.log('Redirect to:', session.url);

Gerenciar Clientes

Crie e recupere informações de clientes:
// Create a customer
const customer = await client.customers.create({
  email: 'customer@example.com',
  name: 'John Doe',
  metadata: {
    user_id: '12345'
  }
});

// Retrieve customer
const retrieved = await client.customers.retrieve('cus_123');
console.log(`Customer: ${retrieved.name} (${retrieved.email})`);

Gerenciar Assinaturas

Crie e gerencie assinaturas recorrentes:
// Create a subscription
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_456',
  price_id: 'price_789'
});

// Retrieve subscription usage history
const usageHistory = await client.subscriptions.retrieveUsageHistory('sub_123', {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-03-31T23:59:59Z'
});

Cobrança Baseada em Uso

Ingestão de Eventos de Uso

Rastreie eventos personalizados para cobrança baseada em uso:
await client.usageEvents.ingest({
  events: [
    {
      event_id: 'api_call_12345',
      customer_id: 'cus_abc123',
      event_name: 'api_request',
      timestamp: '2024-01-15T10:30:00Z',
      metadata: {
        endpoint: '/api/v1/users',
        method: 'GET',
        tokens_used: '150'
      }
    }
  ]
});
Os eventos devem ter valores únicos de event_id para idempotência. IDs duplicados dentro da mesma solicitação são rejeitados, e solicitações subsequentes com IDs existentes são ignoradas.

Recuperar Eventos de Uso

Busque informações detalhadas sobre eventos de uso:
// Get a specific event
const event = await client.usageEvents.retrieve('api_call_12345');

// List events with filtering
const events = await client.usageEvents.list({
  customer_id: 'cus_abc123',
  event_name: 'api_request',
  start: '2024-01-14T10:30:00Z',
  end: '2024-01-15T10:30:00Z'
});

Configuração de Proxy

Configure as configurações de proxy para diferentes ambientes de execução:

Node.js (usando undici)

import DodoPayments from 'dodopayments';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new DodoPayments({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

Bun

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

Deno

import DodoPayments from 'npm:dodopayments';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
  fetchOptions: {
    client: httpClient,
  },
});

Registro

Controle a verbosidade do log usando variáveis de ambiente ou opções do cliente:
// Via client option
const client = new DodoPayments({
  logLevel: 'debug', // Show all log messages
});
# Via environment variable
export DODO_PAYMENTS_LOG=debug
Níveis de log disponíveis:
  • 'debug' - Mostrar mensagens de depuração, informações, avisos e erros
  • 'info' - Mostrar mensagens de informações, avisos e erros
  • 'warn' - Mostrar avisos e erros (padrão)
  • 'error' - Mostrar apenas erros
  • 'off' - Desativar todos os logs
No nível de depuração, todas as requisições e respostas HTTP são registradas, incluindo cabeçalhos e corpos. Alguns cabeçalhos de autenticação são ocultados, mas dados sensíveis nos corpos ainda podem ser visíveis.

Migração do SDK Node.js

Se você está atualizando do SDK Node.js legado, o SDK TypeScript oferece segurança de tipo e recursos aprimorados:

Ver Guia de Migração

Aprenda como migrar do SDK Node.js para o SDK TypeScript

Auto-Paginação

Os métodos de listagem na API DodoPayments são paginados. Você pode usar a sintaxe for await … of para iterar através dos itens em todas as páginas: TODO: PLACEHOLDER_DE_CÓDIGO_20831acc0088b6925fa9c28b685e3a40 Alternativamente, você pode solicitar uma única página por vez: TODO: PLACEHOLDER_DE_CÓDIGO_87be751d1b2ac11515bd21053c8b98aa

Requisitos

Os seguintes ambientes de execução são suportados:
  • Navegadores da web (Chrome, Firefox, Safari, Edge e mais atualizados)
  • Node.js 20 LTS ou versões posteriores (non-EOL)
  • Deno v1.28.0 ou superior
  • Bun 1.0 ou posterior
  • Cloudflare Workers
  • Vercel Edge Runtime
  • Jest 28 ou superior com o ambiente "node"
  • Nitro v2.6 ou superior
TypeScript >= 4.9 é suportado.

Recursos

Suporte

Precisa de ajuda com o SDK TypeScript?

Contribuindo

Agradecemos contribuições! Confira as diretrizes de contribuição para começar.