Desarrolladores

Documentación

Todo lo que necesita para integrar Toreador en su aplicación.

REST API Referencia completa de la API HTTP: endpoints, autenticación, errores, paginación. Ver la referencia TypeScript SDK El SDK oficial @toreador/sdk para Node.js, Deno y entornos edge. Leer la guía Webhooks Notificaciones HTTPS firmadas con HMAC-SHA256 cuando sus sesiones cambian de estado. Leer la guía Plugin de WordPress Instale el plugin, conecte su sitio y cobre en cripto con WooCommerce y sus formularios. Leer la guía Preguntas frecuentes Custodia, pagos, wallets, planes y verificación: las respuestas, por tema. Leer las respuestas
Índice

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

Terminal
npm install @toreador/sdk

Inicio rápido

TypeScript
import Toreador from "@toreador/sdk";

// Initialize the client
const client = new Toreador({ apiKey: "tor_live_your_key_here" });

// Generate a Bitcoin QR code
const qr = await client.qrcode.generate({
  token: "BTC",
  chainId: "bitcoin",
  amount: "0.001",
  recipientAddress: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
});

console.log(qr.qrCodeURL); // data:image/png;base64,...

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

TypeScript
import Toreador from "@toreador/sdk";

const client = new Toreador({ apiKey: "tor_live_your_key_here" });

// Create a USDC payment session on Ethereum
const session = await client.sessions.create({
  token: "USDC",
  chainId: "ethereum",
  amount: "100",
  recipientAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
});

console.log(session.url);       // Payment page URL
console.log(session.expiresIn); // Seconds until expiry

// Check status later
const status = await client.sessions.getStatus(session.sessionId);
console.log(status.status); // 'pending' | 'completed' | ...

Manejo de errores

TypeScript
import { Toreador, ToreadorError } from "@toreador/sdk";

try {
  await client.qrcode.generate({ /* ... */ });
} catch (err) {
  if (err instanceof ToreadorError) {
    console.error(err.message); // "Missing required fields: ..."
    console.error(err.status);  // 400
    console.error(err.body);    // Full error response
  }
}

Opciones del constructor

OptionTypeObligatorioDescription
apiKeystringSíSu clave API (tor_live_… o tor_test_…)
baseURLstringNoURL base de la API. Valor predeterminado: https://toreador.io/api/v1/public
fetchfunctionNoImplementació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

EventDisparador
session.createdCuando /create-session se ejecuta con éxito
session.submittedEl pagador difundió la transacción
session.confirmingPrimera confirmación en la blockchain
session.completedSe alcanzaron las confirmaciones requeridas
session.expiredVenció el plazo de 15 minutos
session.failedLa transacción falló en la blockchain
checkout.createdCuando /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

HeaderValor
Toreador-Signaturet=1761123121,v1=0xabc...
Toreador-Event-Idevt_xxx — idempotencia del lado del consumidor
Toreador-Event-Typesession.completed
Toreador-Delivery-Idwhd_xxx
Toreador-Attemptnúmero de intento (1, 2, 3, ...)

Ejemplo: Express + SDK oficial

TypeScript
import { webhooks, WebhookSignatureError } from "@toreador/sdk";
import express from "express";

const app = express();

// Raw body, not parsed JSON: the signature covers the exact bytes
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await webhooks.constructEvent(
      req.body.toString("utf8"),
      req.headers["toreador-signature"] as string,
      process.env.TOREADOR_WEBHOOK_SECRET!
    );

    if (event.type === "session.completed") {
      // fulfill order, update DB, send receipt, etc.
    }

    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(400);
    throw err;
  }
});

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

Respetamos su privacidad

Usamos cookies analíticas para mejorar nuestro servicio. Estas cookies solo se activan con su consentimiento. Las cookies esenciales (autenticación, idioma, etc.) están siempre activas.