> ## 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
> Usa el SDK de TypeScript de Dodo Payments para crear sesiones de checkout, clientes, suscripciones y eventos de uso desde Node.js y otros runtimes de JavaScript.
El SDK de TypeScript proporciona acceso tipado a la API REST de Dodo Payments para código TypeScript y JavaScript del lado del servidor. Incluye definiciones de tipos para cada solicitud y respuesta, errores tipados, reintentos automáticos, timeouts y paginación automática.
## Instalación
Instala el paquete `dodopayments` con tu gestor de paquetes:
```bash npm theme={null}
npm install dodopayments
```
```bash yarn theme={null}
yarn add dodopayments
```
```bash pnpm theme={null}
pnpm add dodopayments
```
## Inicio rápido
Crea un cliente y, después, crea una sesión de checkout:
```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: 'pdt_123', quantity: 1 }],
});
console.log(checkoutSessionResponse.session_id);
```
Si omites `bearerToken`, el cliente lee la variable de entorno `DODO_PAYMENTS_API_KEY`. Si omites `environment`, el cliente se conecta al modo live. Una clave de API del modo de prueba solo funciona con `environment: 'test_mode'`.
Guarda las claves de API en variables de entorno o en un gestor de secretos. Nunca las confirmes en el control de versiones ni las expongas en código del lado del cliente.
## Funciones principales
Definiciones de tipos para cada parámetro de solicitud y campo de respuesta, mostradas en tu editor.
Los métodos de lista obtienen la página siguiente automáticamente cuando iteras con `for await...of`.
Una clase de error tipada para cada estado de error HTTP, con el estado, los encabezados y el cuerpo de la respuesta.
Dos reintentos de forma predeterminada, con retroceso exponencial, para errores de conexión y códigos de estado reintentables.
## Configuración
### Variables de entorno
Guarda tu clave de API en una variable de entorno:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
El cliente lee estas variables cuando no pasas la opción correspondiente:
| Variable | Opción del cliente | Propósito |
| - | - | - |
| `DODO_PAYMENTS_API_KEY` | `bearerToken` | Tu clave de API. El cliente genera un error si ninguna de las dos está definida. |
| `DODO_PAYMENTS_WEBHOOK_KEY` | `webhookKey` | Tu secreto de firma de webhook, utilizado para verificar webhooks. |
| `DODO_PAYMENTS_BASE_URL` | `baseURL` | Una URL de API personalizada que reemplaza la URL de `environment`. |
| `DODO_PAYMENTS_LOG` | `logLevel` | El nivel de registro. Consulta [Registro](#logging). |
Si se establece una URL base y además pasas `environment`, el constructor genera un error de "Ambiguous URL". Para usar `environment` en ese caso, pasa `baseURL: null`.
Para verificar un webhook, pasa el cuerpo sin procesar de la solicitud y los encabezados a `client.webhooks.unwrap(rawBody, { headers })`. Comprueba la firma con tu clave de webhook y devuelve el evento analizado. `client.webhooks.unsafeUnwrap(rawBody)` analiza el cuerpo sin verificarlo, así que úsalo únicamente para pruebas. Consulta [Webhooks](/developer-resources/webhooks).
### Configuración del timeout
Las solicitudes agotan el tiempo de espera después de 1 minuto de forma predeterminada. Establece `timeout`, en milisegundos, en el cliente o en una sola 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: 'pdt_123', quantity: 1 }] },
{ timeout: 5 * 1000 },
);
```
Cuando una solicitud agota el tiempo de espera, el SDK genera `APIConnectionTimeoutError`. Las solicitudes cuyo tiempo de espera se agotó se reintentan, por lo que una llamada puede tardar más que `timeout` antes de fallar.
### Configuración de reintentos
Establece `maxRetries` en el cliente o en una sola solicitud:
```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: 'pdt_123', quantity: 1 }] },
{ maxRetries: 5 },
);
```
El SDK reintenta los errores de conexión y las respuestas con estado 408, 409, 429 o 500 y superiores. De forma predeterminada, realiza dos reintentos con retroceso exponencial.
Cuando una solicitud sigue fallando, el SDK genera una subclase de `DodoPayments.APIError`. Cada error tiene las propiedades `status`, `headers` y `error` (el cuerpo de la respuesta). Comprueba una clase específica con `instanceof`, por ejemplo `err instanceof DodoPayments.RateLimitError`:
| Estado | Clase de error |
| - | - |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| 500 y superiores | `InternalServerError` |
| Sin respuesta | `APIConnectionError` |
## Operaciones comunes
Los ejemplos de esta sección utilizan `client` de [Inicio rápido](#quick-start).
### Crear una sesión de checkout
Crea una sesión de checkout y, después, redirige al cliente a `checkout_url` devuelto:
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{
product_id: 'pdt_123',
quantity: 1
}
],
return_url: 'https://yourdomain.com/return'
});
console.log('Redirect to:', session.checkout_url);
```
Cada `checkout_url` funciona una vez y caduca después de 24 horas. Consulta [Sesiones de checkout](/developer-resources/checkout-session) para ver todas las opciones de sesión.
### Gestionar clientes
Crea un cliente con una dirección de correo electrónico y un nombre y, después, recupéralo por ID:
```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})`);
```
### Gestionar suscripciones
Crea una suscripción, cobra una suscripción on-demand y consulta el historial de uso de una suscripción.
`POST /subscriptions` (el método `subscriptions.create` del SDK) está **obsoleto**. Sigue funcionando para integraciones existentes, pero las nuevas integraciones deben crear suscripciones mediante una [sesión de checkout](/developer-resources/checkout-session).
```typescript expandable 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` solo requiere `country`, un código de país ISO de dos letras. `customer` acepta `{ customer_id }` para asociar un cliente existente o `{ email, name? }` para crear uno. `charge` es para [suscripciones on-demand](/developer-resources/ondemand-subscriptions), y `product_price` está expresado en la unidad monetaria más pequeña. `retrieveUsageHistory` devuelve una lista paginada que puedes iterar como se muestra en [Paginación automática](#auto-pagination).
## Facturación basada en el uso
### Ingerir eventos de uso
Envía eventos de uso para un cliente:
```typescript theme={null}
await client.usageEvents.ingest({
events: [
{
event_id: 'api_call_12345',
customer_id: 'cus_abc123',
event_name: 'api_request',
timestamp: new Date().toISOString(),
metadata: {
endpoint: '/api/v1/users',
method: 'GET',
tokens_used: '150'
}
}
]
});
```
`event_id` es la clave de idempotencia, así que asigna un valor único a cada evento. Si el mismo `event_id` aparece dos veces en una solicitud, se rechaza la solicitud completa. Si ya se había ingerido un `event_id`, se ignora el evento nuevo. Una solicitud acepta hasta 1.000 eventos. `timestamp` toma de forma predeterminada la hora actual y se rechaza si es de hace más de 1 hora o si está más de 5 minutos en el futuro.
### Recuperar eventos de uso
Recupera un evento individual mediante su `event_id` o muestra una lista de eventos filtrados por cliente, nombre del evento y rango temporal:
```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'
});
```
`usageEvents.list` también acepta `meter_id` y devuelve una lista paginada.
## Configuración del proxy
Para enviar solicitudes a través de un proxy, pasa la configuración del proxy de tu runtime en `fetchOptions`.
### Node.js (usando Undici)
Pasa un `ProxyAgent` de undici como `dispatcher`:
```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
Establece la opción `proxy`:
```typescript theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
fetchOptions: {
proxy: 'http://localhost:8888',
},
});
```
### Deno
Crea un cliente HTTP con `Deno.createHttpClient` y pásalo como `client`:
```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
Establece el nivel de registro con la opción de cliente `logLevel` o la variable de entorno `DODO_PAYMENTS_LOG`. La opción del cliente sustituye a la variable de entorno.
En el nivel `debug`, el SDK registra cada solicitud y respuesta HTTP, incluidos los encabezados y cuerpos. Algunos encabezados de autenticación se redactan, pero los datos confidenciales de los cuerpos aún pueden quedar visibles.
```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
```
Los niveles de registro, de mayor a menor verbosidad, son:
* `'debug'`: mensajes de depuración, información, advertencias y errores.
* `'info'`: mensajes de información, advertencias y errores.
* `'warn'`: advertencias y errores. Este es el valor predeterminado.
* `'error'`: solo errores.
* `'off'`: sin registros.
El SDK registra en `console` de forma predeterminada. Para usar `pino`, `winston` u otra biblioteca de registro, pasa tu logger como opción `logger`; `logLevel` sigue controlando qué mensajes recibe. Los mensajes de registro son únicamente para depuración y su formato puede cambiar entre versiones.
## Migración desde el SDK de Node.js
Si usas el SDK antiguo de Node.js, sigue la guía de migración para actualizarlo. El SDK actual utiliza la API integrada `fetch` en lugar de `node-fetch`, requiere Node.js 20, TypeScript 4.9 y Jest 28 o posteriores, e incluye una herramienta de migración que actualiza la mayor parte de tu código.
Aprende a migrar del SDK de Node.js al SDK de TypeScript
## Paginación automática
Los métodos de lista devuelven resultados paginados. Itera con `for await...of` para obtener elementos de todas las páginas. El SDK solicita la página siguiente cuando la necesita:
```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;
}
```
Para trabajar con una página a la vez, lee `page.items` y llama a `hasNextPage()` y `getNextPage()`:
```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();
// Process page.items here
}
```
Para establecer el tamaño de página, pasa `page_size` al método de lista, por ejemplo `client.payments.list({ page_size: 50 })`.
## Requisitos
El SDK admite TypeScript 4.9 o posterior y estos runtimes:
* Navegadores web (versiones actualizadas de Chrome, Firefox, Safari, Edge y otros)
* Node.js 20 LTS o versiones posteriores ([no EOL](https://endoflife.date/nodejs))
* Deno 1.28.0 o posterior
* Bun 1.0 o posterior
* Cloudflare Workers
* Vercel Edge Runtime
* Jest 28 o posterior con el entorno `"node"` (el entorno `"jsdom"` no es compatible)
* Nitro 2.6 o posterior
React Native no es compatible.
## Recursos
Código fuente, versiones y la lista completa de métodos.
Cada endpoint, parámetro y respuesta.
Haz preguntas y conversa con otros desarrolladores.
Informa de errores o solicita funciones.
## Soporte
Para obtener ayuda con el SDK de TypeScript:
* **Discord**: Únete al [servidor de la comunidad](https://discord.gg/bYqAp4ayYh) para obtener ayuda en tiempo real.
* **Correo electrónico**: Contacta con [support@dodopayments.com](mailto:support@dodopayments.com).
* **GitHub**: Abre un issue en el [repositorio](https://github.com/dodopayments/dodopayments-typescript).
## Contribuciones
Para contribuir, lee las [directrices de contribución](https://github.com/dodopayments/dodopayments-typescript/blob/main/CONTRIBUTING.md).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.