TypeScript SDK
El SDK oficial @toreador/sdk ofrece una interfaz TypeScript con tipado seguro para la API de Toreador. Compatible con Node.js 18+, Deno y navegadores modernos.
Installation
Inicio rápido
Métodos disponibles
client.checkouts.create(params)
Crear una solicitud de pago en USD o EUR: el pagador elige la stablecoin y la red en la página alojada. El recurso canónico para una integración.
Devuelve: { checkoutId, url, allowedRails, expiresAt, ... }
client.payments.retrieve(id)
Objeto de pago unificado por id de checkout (co_…) o id de sesión: estado, hash de transacción, cronología.
Devuelve: { id, status, token, chain, amount, txHash, timeline, ... }
client.qrcode.generate(params)
Generar un código QR para tokens nativos (BTC, ETH, SOL, POL) o tokens SPL de Solana.
Devuelve: { success, type, qrData, qrCodeURL, token, chain, amount, recipientAddress }
client.qrcode.history()
Listar sus últimas 50 generaciones de códigos QR.
Devuelve: { data: PaymentRecord[], has_more, next_cursor }
client.sessions.create(params)
Crear una sesión de pago para tokens EVM no nativos (USDC, USDT, EURC).
Devuelve: { sessionId, url, expiresIn, ... }
client.sessions.list()
Listar sus últimas 50 sesiones de pago.
Devuelve: { data: SessionRecord[], has_more, next_cursor }
client.sessions.getStatus(sessionId)
Consultar el estado de una sesión de pago.
Devuelve: { status: 'pending' | 'submitted' | 'confirming' | 'completed' | 'expired' | 'failed', ... }
client.account.establishments()
Listar los establecimientos de su organización. Cada pago lleva su establecimiento, sin importar qué miembro del equipo lo creó.
Devuelve: { data: Establishment[] }
client.payments.export(options)
Exportar los pagos confirmados en JSON o CSV, o como archivo de importación de transacciones bancarias de un software de contabilidad (quickbooks, xero, odoo, pennylane).
Devuelve: { count, truncated, data: ExportRecord[] } | string
Ejemplo: sesión de pago en USDC
Manejo de errores
Opciones del constructor
| Option | Type | Obligatorio | Description |
|---|---|---|---|
apiKey | string | Sí | Su clave API (tor_live_… o tor_test_…) |
baseURL | string | No | URL base de la API. Valor predeterminado: https://toreador.io/api/v1/public |
fetch | function | No | Implementación personalizada de fetch. Valor predeterminado: globalThis.fetch |
Webhooks
Reciba en tiempo real eventos firmados con HMAC-SHA256 cuando sus sesiones cambian de estado. Configure los endpoints desde su panel.
Eventos emitidos
| Event | Disparador |
|---|---|
session.created | Cuando /create-session se ejecuta con éxito |
session.submitted | El pagador difundió la transacción |
session.confirming | Primera confirmación en la blockchain |
session.completed | Se alcanzaron las confirmaciones requeridas |
session.expired | Venció el plazo de 15 minutos |
session.failed | La transacción falló en la blockchain |
checkout.created | Cuando /checkout se ejecuta con éxito |
Verificación de la firma
Cada envío incluye un encabezado Toreador-Signature: t=<unix>,v1=<hex>. La firma es un HMAC-SHA256 sobre <timestamp>.<rawBody> con el secreto de su endpoint. Verifique siempre la firma antes de procesar el evento.
Encabezados enviados
| Header | Valor |
|---|---|
Toreador-Signature | t=1761123121,v1=0xabc... |
Toreador-Event-Id | evt_xxx — idempotencia del lado del consumidor |
Toreador-Event-Type | session.completed |
Toreador-Delivery-Id | whd_xxx |
Toreador-Attempt | número de intento (1, 2, 3, ...) |
Ejemplo: Express + SDK oficial
Política de reintentos
Si su endpoint responde con un código distinto de 2xx o no responde en 10 segundos, Toreador reintenta con espera exponencial: 0s, 5s, 5min, 30min, 2h, 5h, 10h, 24h, 48h (9 intentos en total durante ~4 días), y luego pasa al estado failed. Un endpoint se desactiva automáticamente tras 50 fallos consecutivos.
Los envíos se pueden reintentar manualmente desde el panel. Idempotencia del lado del consumidor: use el encabezado Toreador-Event-Id para detectar duplicados.
¿Listo para empezar?
Cree una cuenta gratuita para obtener su clave API — una clave de prueba para el entorno de pruebas, una clave de producción para la red principal (mainnet) — y empiece a integrar Toreador.
Ver precios