> ## 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
> Integra Dodo Payments en tus aplicaciones de TypeScript y Node.js con seguridad de tipos y soporte moderno de async/await
El SDK de TypeScript proporciona acceso conveniente del lado del servidor a la API REST de Dodo Payments para aplicaciones de TypeScript y JavaScript. Cuenta con definiciones de tipos completas, manejo de errores, reintentos, tiempos de espera y auto-paginación para un procesamiento de pagos sin problemas.
## Instalación
Instala el SDK usando el administrador de paquetes de tu preferencia:
```bash npm theme={null}
npm install dodopayments
```
```bash yarn theme={null}
yarn add dodopayments
```
```bash pnpm theme={null}
pnpm add dodopayments
```
## Inicio Rápido
Inicializa el cliente con tu clave API y comienza a procesar pagos:
```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);
```
Siempre guarda tus claves API de forma segura utilizando variables de entorno. Nunca las comites en el control de versiones ni las expongas en código del lado del cliente.
## Características Principales
Soporte completo para TypeScript con definiciones de tipos exhaustivas para todos los endpoints de la API
La paginación automática para respuestas de listas facilita el trabajo con conjuntos de datos extensos
Tipos de errores integrados con mensajes detallados para distintos escenarios de fallos
Reintentos automáticos configurables con retroceso exponencial para errores transitorios
## Configuración
### Variables de Entorno
Establece variables de entorno para una configuración segura:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
### Configuración de Tiempo de Espera
Configura los tiempos de espera de las solicitudes a nivel global o por solicitud:
```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 },
);
```
### Configuración de Reintentos
Configura el comportamiento de reintentos automáticos:
```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 },
);
```
El SDK vuelve a intentar automáticamente las solicitudes que fallan debido a errores de red o problemas del servidor (respuestas 5xx) con retroceso exponencial.
## Operaciones Comunes
### Crear una Sesión de Pago
Genera una sesión de pago para recopilar información de pago:
```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);
```
### Gestionar Clientes
Crea y recupera información 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})`);
```
### Manejar Suscripciones
Crea y gestiona suscripciones recurrentes:
```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` requiere al menos el código de país ISO de dos letras. `customer` es una unión de `{ customer_id }` (para adjuntar un cliente existente) o `{ email, name? }` (para crear uno nuevo). `product_price` se expresa en la denominación más baja de la moneda.
## Facturación Basada en Uso
### Registrar Eventos de Uso
Rastrea eventos personalizados para la facturación basada en 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'
}
}
]
});
```
Los eventos deben tener valores únicos `event_id` para idempotencia. Los IDs duplicados dentro de la misma solicitud son rechazados y las solicitudes posteriores con IDs existentes son ignoradas.
### Recuperar Eventos de Uso
Obtén información detallada 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'
});
```
## Configuración del Proxy
Configura la configuración de proxy para diferentes entornos de ejecución:
### 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,
},
});
```
## Registro
Controla la verbosidad del registro utilizando variables de entorno u opciones del 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
```
**Niveles de registro disponibles:**
* `'debug'` - Mostrar mensajes de depuración, información, advertencias y errores
* `'info'` - Mostrar mensajes de información, advertencias y errores
* `'warn'` - Mostrar advertencias y errores (predeterminado)
* `'error'` - Mostrar solo errores
* `'off'` - Deshabilitar todo el registro
Al nivel de depuración, se registran todas las solicitudes y respuestas HTTP, incluidas las cabeceras y los cuerpos. Algunas cabeceras de autenticación están redactadas, pero los datos sensibles en los cuerpos pueden seguir siendo visibles.
## Migración desde Node.js SDK
Si estás actualizando desde el SDK de Node.js heredado, el SDK de TypeScript ofrece mejoras en la seguridad de tipos y características:
Aprende cómo migrar del SDK de Node.js al SDK de TypeScript
## Auto-Paginación
Los métodos de lista en la API de DodoPayments son paginados. Puedes usar la sintaxis `for await … of` para iterar a través de elementos en todas las 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, puedes solicitar una sola página a la 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
Se soportan los siguientes entornos de ejecución:
* Navegadores web (Chrome, Firefox, Safari, Edge y más actualizados)
* Node.js 20 LTS o posterior ([non-EOL](https://endoflife.date/nodejs)) versiones
* Deno v1.28.0 o superior
* Bun 1.0 o posterior
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28 o mayor con el entorno `"node"`
* Nitro v2.6 o mayor
Se soporta TypeScript >= 4.9.
## Recursos
Ver código fuente y contribuir
Documentación completa de la API
Obtén ayuda y conecta con desarrolladores
Reportar errores o solicitar funciones
## Soporte
¿Necesitas ayuda con el SDK de TypeScript?
* **Discord**: Únete a nuestro [servidor de la comunidad](https://discord.gg/bYqAp4ayYh) para soporte en tiempo real
* **Email**: Contáctanos en [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Abre un issue en el [repositorio](https://github.com/dodopayments/dodopayments-typescript)
## Contribuciones
¡Damos la bienvenida a las contribuciones! Consulta las [directrices de contribución](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md) para comenzar.