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: 
// Configure default timeout for all requests (default is 1 minute)
const client = new DodoPayments({
  timeout: 20 * 1000, // 20 seconds
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 0 }] },
  { timeout: 5 * 1000 }
);

​
Configuração de Tentativas

Configure o comportamento de tentativas automáticas: 
// Configure default for all requests (default is 2 retries)
const client = new DodoPayments({
  maxRetries: 0, // disable retries
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 0 }] },
  { maxRetries: 5 }
);
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: '[email protected]',
  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 event_id para idempotência. IDs duplicados dentro da mesma requisição são rejeitados, e requisiçõ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' - Mostra mensagens de depuração, informações, avisos e erros
  • 'info' - Mostra mensagens de informações, avisos e erros
  • 'warn' - Mostra avisos e erros (padrão)
  • 'error' - Mostra apenas erros
  • 'off' - Desabilita 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

​
Recursos

Repositório GitHub

Veja o código-fonte e contribua

Referência da API

Documentação completa da API

Comunidade Discord

Obtenha ajuda e conecte-se com desenvolvedores

Relatar Problemas

Relate bugs ou solicite recursos

​
Suporte

Precisa de ajuda com o SDK TypeScript?

​
Contribuindo

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