> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript
> Integre os pagamentos Dodo em suas aplicações TypeScript e Node.js com segurança de tipo e suporte moderno a async/await
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 o gerenciador de pacotes de sua preferência:
```bash npm theme={null}
npm install dodopayments
```
```bash yarn theme={null}
yarn add dodopayments
```
```bash pnpm theme={null}
pnpm add dodopayments
```
## Início Rápido
Inicialize o cliente com sua chave de API e comece a processar pagamentos:
```javascript theme={null}
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 com segurança usando variáveis de ambiente. Nunca as comprometa no controle de versão ou as exponha em código do lado do cliente.
## Recursos Principais
Suporte completo ao TypeScript com definições abrangentes de tipos para todos os endpoints da API
Paginação automática para respostas de listagem torna o trabalho com grandes conjuntos de dados simples
Tipos de erro embutidos com mensagens detalhadas para diferentes cenários de falha
Retentativas 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:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
### Configuração de Timeout
Configure timeouts de requisição globalmente ou por requisição:
```typescript theme={null}
// 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: 1 }] },
{ timeout: 5 * 1000 },
);
```
### Configuração de Tentativas
Configure o comportamento de tentativas automáticas:
```javascript theme={null}
// 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: 1 }] },
{ maxRetries: 5 },
);
```
O SDK automaticamente refaz 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:
```typescript theme={null}
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.checkout_url);
```
### Gerenciar Clientes
Crie e recupere informações de clientes:
```typescript theme={null}
// 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:
```typescript theme={null}
// Create a subscription
const subscription = await client.subscriptions.create({
billing: {
country: 'US',
city: 'San Francisco',
state: 'CA',
street: '1 Market St',
zipcode: '94105',
},
customer: {
customer_id: 'cus_123', // or pass { email, name } to create a new customer
},
product_id: 'pdt_456',
quantity: 1,
});
// Charge an on-demand subscription
// product_price is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
const chargeResponse = await client.subscriptions.charge(subscription.subscription_id, {
product_price: 2500,
});
// Retrieve subscription usage history (for metered subscriptions)
const usageHistory = await client.subscriptions.retrieveUsageHistory(subscription.subscription_id, {
start_date: '2024-01-01T00:00:00Z',
end_date: '2024-03-31T23:59:59Z',
});
```
`billing` requer, no mínimo, o código de país ISO de duas letras. `customer` é uma união de `{ customer_id }` (para anexar um cliente existente) ou `{ email, name? }` (para criar um novo). `product_price` é expressa na menor denominação de moeda.
## Faturamento Baseado em Uso
### Registrar Eventos de Uso
Acompanhe eventos personalizados para faturamento baseado em uso:
```typescript theme={null}
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 `event_id` únicos 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:
```typescript theme={null}
// 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 runtimes:
### Node.js (usando undici)
```typescript theme={null}
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
```typescript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
fetchOptions: {
proxy: 'http://localhost:8888',
},
});
```
### Deno
```typescript theme={null}
import DodoPayments from 'npm:dodopayments';
const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
fetchOptions: {
client: httpClient,
},
});
```
## Logging
Controle a verbosidade do log usando variáveis de ambiente ou opções de cliente:
```typescript theme={null}
// Via client option
const client = new DodoPayments({
logLevel: 'debug', // Show all log messages
});
```
```bash theme={null}
# Via environment variable
export DODO_PAYMENTS_LOG=debug
```
**Níveis de log disponíveis:**
* `'debug'` - Mostra mensagens de debug, informações, avisos e erros
* `'info'` - Mostra mensagens de informação, avisos e erros
* `'warn'` - Mostra avisos e erros (padrão)
* `'error'` - Mostra apenas erros
* `'off'` - Desativa todos os logs
No nível de debug, todas as solicitações e respostas HTTP são registradas, incluindo cabeçalhos e corpos. Alguns cabeçalhos de autenticação são redigidos, mas dados sensíveis nos corpos ainda podem estar visíveis.
## Migração do SDK Node.js
Se você está atualizando do SDK Node.js legado, o SDK TypeScript oferece melhorias na segurança de tipos e recursos:
Saiba como migrar do SDK Node.js para o SDK TypeScript
## Paginação Automática
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:
```typescript theme={null}
async function fetchAllPayments() {
const allPayments = [];
// Automatically fetches more pages as needed.
for await (const paymentListResponse of client.payments.list()) {
allPayments.push(paymentListResponse);
}
return allPayments;
}
```
Alternativamente, você pode solicitar uma única página por vez:
```typescript theme={null}
let page = await client.payments.list();
for (const paymentListResponse of page.items) {
console.log(paymentListResponse);
}
// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
page = await page.getNextPage();
// ...
}
```
## Requisitos
Os seguintes runtimes são suportados:
* Navegadores web (Chrome, Firefox, Safari, Edge, e mais atualizados)
* Node.js 20 LTS ou versões posteriores ([non-EOL](https://endoflife.date/nodejs))
* 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
Veja o código fonte e contribua
Documentação completa da API
Obtenha ajuda e conecte-se com desenvolvedores
Relate bugs ou solicite recursos
## Suporte
Precisa de ajuda com o SDK TypeScript?
* **Discord**: Junte-se ao nosso [servidor da comunidade](https://discord.gg/bYqAp4ayYh) para suporte em tempo real
* **Email**: Contate-nos em [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Abra uma issue no [repositório](https://github.com/dodopayments/dodopayments-typescript)
## Contribuição
Contribuições são bem-vindas! Confira as [diretrizes de contribuição](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md) para começar.