REST API
La API HTTP pública de Toreador: genere códigos QR cripto y cree sesiones de pago sin custodia. Toreador nunca custodia fondos — cada pago va directamente de la wallet del pagador a la del comercio, en la blockchain.
https://toreador.io/api/v1/public
Especificación legible por máquina: openapi.json (OpenAPI 3.1).
Authentication
La mayoría de los endpoints requieren una clave API, enviada en el encabezado X-API-Key. La clave identifica su cuenta; sus derechos de uso (plan, cuota) se evalúan en cada solicitud. Genere sus claves desde su panel.
tor_test_…
Entorno de pruebas en testnet, abierto a todos, fuera de cuota. Para desarrollo y pruebas.
tor_live_…
Producción (mainnet). Sujeta al plan y a la cuota de pagos confirmados en la blockchain.
Límites de solicitudes
El límite de solicitudes se aplica por cuenta (no por clave). Si se supera, se devuelve 429 con un encabezado Retry-After. Todos los endpoints requieren una clave (el plan gratuito incluye una).
- Límite por minuto según el plan (encabezados
X-RateLimit-*en cada respuesta).
| Plan | Límite de la API | Claves API | Pagos confirmados en la blockchain / mes |
|---|---|---|---|
| Free | 10/min | 1 | Ilimitado |
| Starter | 30/min | 1 | 150 |
| Pro | 120/min | 3 | 1000 |
| Plus | 600/min | 10 | 5000 |
| Entreprise | Ilimitado | Ilimitado | Ilimitado |
Valores de la tabla predeterminada; su límite exacto puede variar según su región y se muestra en su panel. El límite de solicitudes con clave se aplica por cuenta (crear varias claves no lo multiplica).
Idempotencia
En las solicitudes POST, agregue un encabezado Idempotency-Key: repetir la solicitud con la misma clave devuelve la respuesta original (encabezado Idempotent-Replayed: true), sin volver a crear una sesión. Misma clave + cuerpo distinto → 409.
Errores
Los errores usan un envoltorio de doble forma: error sigue siendo una cadena (compatibilidad con versiones anteriores) y error_details contiene el detalle tipado (code, type, message, request_id, doc_url).
Códigos de error
| code | HTTP | Cuándo |
|---|---|---|
| missing_field | 400 | Falta un campo obligatorio (token, chainId, amount, recipientAddress). |
| invalid_parameter | 400 | Token, cadena o formato desconocido. |
| invalid_address | 400 | La dirección del destinatario no es válida para esta cadena. |
| invalid_amount | 400 | El monto no es un decimal o está fuera de rango (0–1,000,000). |
| incompatible_token_chain | 400 | Este token no existe en esta cadena (p. ej., BTC en Ethereum). |
| wrong_endpoint | 400 | Endpoint incorrecto: nativo ↔ ERC-20 (use el otro). |
| missing_api_key | 401 | Falta la clave API. |
| invalid_api_key | 401 | Clave API no válida o revocada. |
| quota_exceeded | 402 | Cuota mensual de pagos confirmados en la blockchain agotada (incluye used/limit/upgrade_url). |
| forbidden | 403 | La clave no tiene permiso para acceder a este recurso. |
| recipient_blocked | 403 | La dirección de destino figura en una lista de sanciones: no se crea ningún código QR ni ninguna página de pago. |
| session_not_found | 404 | Sesión no encontrada (o vencida/purgada). |
| payment_not_found | 404 | Pago no encontrado. |
| idempotency_conflict | 409 | La misma Idempotency-Key se reutilizó con un cuerpo distinto. |
| no_rail | 409 | No hay ninguna vía utilizable para este pago: el par token/red no es acreditable por la wallet de exchange conectada, o el emisor de la stablecoin congeló la dirección de recepción en esa red. |
| rate_limited | 429 | Límite superado (encabezado Retry-After). |
| internal_error | 500 | Error inesperado del servidor: vuelva a intentarlo y, si persiste, contacte al soporte. |
Pagination
Los endpoints de lista (/history, /sessions) se paginan por cursor: envíe limit (1–100, 20 de forma predeterminada) y cursor. La respuesta incluye has_more y next_cursor — vuelva a enviar este último para obtener la página siguiente.
Endpoints
Referencia de endpoints
/ping
Clave requeridaVerifica la conectividad y la clave API. Devuelve el entorno (test/live), el plan y la versión de la API. Ideal para un botón «Probar conexión».
Sin parámetros.
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/account
Clave requeridaEstado de la cuenta: plan efectivo, entorno, suscripción (período de prueba o de pago), cuota mensual (used/limit/remaining) y límites (solicitudes, claves, wallets). El campo subscription (status trialing/active, realPlan, trialEndsAt en epoch s, trialDaysRemaining) debe determinar la insignia del plan — no el campo plan por sí solo, que vale 'plus' durante el período de prueba.
Sin parámetros.
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/tokens
Clave requeridaMatriz de pagos compatibles (tokens × cadenas), derivada de la configuración (fuente única de verdad, contratos verificados en la blockchain). Consúltela en lugar de escribir la lista a mano → se mantiene sincronizada cuando se agregan cadenas o tokens. Solo se devuelven los pares PAGABLES (nativos, o ERC-20/SPL con contrato). Los contratos dependen del entorno de la clave (test/live).
Sin parámetros.
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/screen
Clave requeridaVerifica si una dirección cripto figura en las listas de SANCIONES que consultamos (listas de la OFAC, la UE, el Reino Unido y Suiza, descargadas por nosotros; además, el oráculo de Chainalysis en la blockchain para las direcciones EVM). Devuelve sanctioned (true/false), o null cuando la dirección no puede verificarse (no válida, cadena no compatible, oráculo no disponible). Llámelo antes de enviar o recibir fondos. El resultado se guarda en caché (vigencia de ~24 h).
sanctioned: null = no se pudo verificar (dirección no válida, lista desactualizada, oráculo no disponible). Información de cumplimiento, no asesoramiento legal.address (query, obligatorio) — la dirección que se va a verificar.
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/generate-qr
Clave requeridaGenera un código QR (PNG en base64) que codifica una URI de pago estándar (BIP-21, EIP-681, Solana Pay). Para tokens nativos (BTC, ETH, SOL, POL) y USDC en Solana. Para las stablecoins ERC-20 en EVM, use /create-session.
X-RateLimit-* en cada respuesta.Body
| token* | string — BTC, ETH, SOL, POL, USDC (Solana) |
| chainId* | string — bitcoin, ethereum, polygon, base, solana |
| amount* | string — Decimal canónico (p. ej., "0.001") |
| recipientAddress* | string — Dirección del destinatario (validada para la cadena) |
| format | string — Formato de salida: png (predeterminado, data-URI en base64), svg (marcado vectorial) o text (caracteres de bloque para mostrar en una terminal; se devuelve en qrCodeText). |
| textBackground | string — Para format: text: el fondo de la terminal donde se mostrará el texto, dark (predeterminado) o light. Un fondo incorrecto produce un código QR invertido que muchos celulares no pueden leer. |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/create-session
Clave requeridaCrea una sesión de pago alojada (pago de wallet a wallet, directamente a la dirección del comercio) para las stablecoins ERC-20 (USDC, USDT, EURC) en Ethereum, Polygon y Base. Devuelve una URL /pay para compartir con el pagador. La sesión vence 15 minutos después de su creación.
tor_test_…) crea una sesión en el entorno de pruebas en testnet, fuera de cuota — ideal para desarrollar un plugin. Una clave de producción (tor_live_…) cuenta para la cuota mensual de pagos confirmados en la blockchain (402 cuando se agota).Body
| token* | string — USDC, USDT, EURC, PYUSD, USDG, RLUSD, USAT, OUSD |
| chainId* | string — ethereum, polygon, base |
| amount* | string — Decimal canónico (p. ej., "100") |
| recipientAddress* | string — Dirección EVM del destinatario (validada en el núcleo) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/wallets
Clave requeridaLista (SOLO LECTURA) las direcciones de recepción de la cuenta. Cada wallet devuelve address, family, label, source, ownershipProven (true = propiedad demostrada mediante un mensaje firmado, o dirección leída desde un exchange conectado), custodial (true = dirección de depósito de la propia cuenta de exchange DEL COMERCIO, p. ej. Binance/Coinbase, en poder del exchange, nunca de Toreador) y acceptedRails: null = sin restricción (wallet autoalojada, todas las redes de la familia); de lo contrario, los pares (token, cadena) que la fuente de custodia acredita EN ESTA dirección. IMPORTANTE: para una wallet de custodia, limite su matriz de pago a acceptedRails — un par no acreditado no se ofrece al pagador (el exchange no lo acreditaría y los fondos se perderían). Las wallets se agregan o eliminan en el panel autenticado (passkey) — nunca mediante la API.
Sin parámetros.
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/checkout
Clave requeridaCrea un checkout expresado en moneda FIDUCIARIA (USD/EUR): el comercio fija un monto en moneda fiduciaria, el pagador conecta una wallet en la página alojada /pay (pago de wallet a wallet, directamente a la dirección del comercio) y elige la stablecoin y la cadena. Recomendado para integraciones (el comercio no necesita entender «USDC en Base»).
conversion:"off" (predeterminado) solo ofrece stablecoins de la misma moneda (USD→USDC/USDT). conversion:"on" también ofrece stablecoins de la otra moneda: el monto a pagar se calcula a partir de un tipo de cambio de referencia indicativo (fuente y marca de tiempo registradas), que queda fijado cuando se elige la vía de pago. Toreador no realiza ninguna conversión: el pagador envía esa stablecoin directamente a la wallet del comercio.Body
| amount* | number — Monto en MONEDA (p. ej., 50), no en token |
| currency* | string — USD, EUR |
| recipientAddress* | string — Dirección de recepción (EVM 0x… o Solana). La proporciona SU sistema, que gestiona la rotación. |
| description | string — Etiqueta que ve el pagador (≤ 500 caracteres) |
| conversion | string — "off" (predeterminado) o "on" |
| acceptNative | boolean — Ofrecer TAMBIÉN el pago en cripto nativa (ETH/POL); monto calculado al tipo de cambio del momento (referencia indicativa). El comerciante asume la volatilidad. |
| reference | string — Referencia libre (p. ej., id de pedido), devuelta en el checkout, /payment/{id} y /sessions, para correlacionar el pago de su lado (≤ 255 caracteres). |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/webhooks
Clave requeridaRegistra (o actualiza, de forma IDEMPOTENTE por URL) el endpoint de webhook de la cuenta para recibir eventos por PUSH. Una integración lo llama automáticamente después de Connect. Devuelve el secreto HMAC UNA SOLA VEZ — guárdelo cifrado. La URL debe ser HTTPS pública y, si la clave se emitió mediante Connect, pertenecer al dominio de la clave.
Body
| url* | string — Endpoint HTTPS público (en el dominio de la clave) |
| events | string[] — Eventos suscritos (predeterminado: session.completed/failed/expired) |
| description | string — Etiqueta (≤ 200 caracteres) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/payment/{id}
Clave requeridaObtiene un objeto Payment unificado — QR nativo (type: native) o sesión ERC-20 (type: session) — con su cronología de eventos. TAMBIÉN acepta un id de checkout (co_…): se resuelve en el pago de ese checkout (ideal para seguir un pedido por su checkoutId, sin conocer el id de sesión).
Parámetro de ruta
| id* | string — Id de pago / sesión, O un id de checkout (co_…) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/payment/{id}/status
Clave requeridaDevuelve el estado actual de una sesión de pago. Para el seguimiento en tiempo real del lado del pagador, la página /pay usa un flujo SSE; del lado del servidor, prefiera los webhooks firmados (vea más abajo).
Parámetro de ruta
| id* | string — Id de sesión (devuelto por /create-session) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/establishments
Clave requeridaLista (SOLO LECTURA) los establecimientos de la clave: id, name, isDefault. Un id se usa como establishment_id, tanto al crear una solicitud de pago como para filtrar /sessions, /history y /export.
Sin parámetros.
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/history
Clave requeridaLista paginada de los códigos QR generados por la organización de la clave y su equipo (los más recientes primero). Cada elemento incluye establishmentId y establishmentName. Una clave solo devuelve los pagos de su propio entorno: una clave de producción nunca devuelve pagos de prueba, y una clave de prueba solo devuelve pagos de prueba.
Parámetros de consulta
| limit | integer — 1–100, predeterminado 20 |
| cursor | string — Cursor opaco (next_cursor de la página anterior) |
| establishment_id | string — Solo los pagos de este establecimiento (un id devuelto por GET /establishments) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/sessions
Clave requeridaLista paginada de las sesiones de pago de la organización de la clave y su equipo (las más recientes primero). Cada elemento incluye establishmentId y establishmentName. Una clave solo devuelve los pagos de su propio entorno: una clave de producción nunca devuelve pagos de prueba, y una clave de prueba solo devuelve pagos de prueba.
fxRate, fxSource y fxQuotedAt describen el tipo de cambio de referencia indicativo utilizado para calcular el monto en tokens (valor, fuente, marca de tiempo). Toreador no realiza ninguna conversión: token y amount son lo que el pagador envió en la blockchain, desde su propia wallet, a la wallet del comercio.Parámetros de consulta
| limit | integer — 1–100, predeterminado 20 |
| cursor | string — Cursor de paginación opaco |
| establishment_id | string — Solo los pagos de este establecimiento (un id devuelto por GET /establishments) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
/export
Clave requeridaExportación CONTABLE de los pagos confirmados en la blockchain, con el tipo de cambio de referencia (monto facturado ↔ monto pagado en la blockchain + tipo de cambio indicativo + fuente + marca de tiempo + tx). En CSV (predeterminado, descargable) o JSON. Período opcional (from/to). Con format=quickbooks, xero, odoo o pennylane: el archivo de importación de transacciones bancarias de ese software, una moneda por archivo. Una clave solo devuelve los pagos de su propio entorno: una clave de producción nunca devuelve pagos de prueba, y una clave de prueba solo devuelve pagos de prueba.
settlementToken, settlementChain y settlementAmount = token, red y monto efectivamente pagados en la blockchain por el pagador, desde su propia wallet, a la wallet del comercio (Toreador no liquida nada); fxRate, fxSource y fxQuotedAt = el tipo de cambio de referencia indicativo utilizado para calcular ese monto, su fuente y su marca de tiempo (informativo, no se realiza ninguna conversión); invoiceAmount / invoiceCurrency = el monto facturado por el comercio.Parámetros de consulta
| format | string — "csv" (predeterminado) o "json": la exportación completa. "quickbooks", "xero", "odoo" o "pennylane": un archivo para la importación de transacciones bancarias de ese software de contabilidad |
| currency | string — Solo archivos de importación: la moneda del archivo. Opcional cuando el período contiene una sola moneda |
| from | integer — Inicio del período (epoch en s, sobre completed_at) |
| to | integer — Fin del período (epoch en s) |
| establishment_id | string — Solo los pagos de este establecimiento (un id devuelto por GET /establishments) |
Códigos de respuesta
Solicitud
Respuesta
Probar este endpoint
La solicitud se envía a la API real, en su nombre. Use una clave de prueba (tor_test_…) — una llamada en producción crea datos reales. La clave nunca se almacena ni se envía a otro lugar.
Webhooks
Para recibir avisos de los cambios de estado del lado del servidor (sin sondeo periódico), registre un endpoint de webhook. Toreador envía por POST un evento firmado con HMAC-SHA256 (encabezado Toreador-Signature: t=…,v1=…) en cada transición.
session.createdsession.submittedsession.confirmingsession.completedsession.expiredsession.failedcheckout.created
Changelog
v1.0.0La versión mayor figura en la URL (/v1/). Los cambios compatibles con versiones anteriores (nuevos campos, parámetros opcionales, endpoints) se enumeran aquí y nunca rompen la v1; un cambio incompatible se publicaría como /v2/. Cada respuesta incluye el encabezado API-Version.
- AddedAPI pública v1: generación de QR (nativos + Solana SPL), sesiones de pago ERC-20 alojadas (de wallet a wallet, directamente a la dirección del comerciante), consulta de pagos y estados, historial y sesiones paginados.
- AddedWebhooks firmados con HMAC-SHA256 (session.created/submitted/confirming/completed/expired/failed).
- AddedClaves de prueba/producción (entorno de pruebas en testnet, fuera de cuota); salida QR en
pngosvgmediante el parámetroformat. - AddedEncabezado
API-Versionen cada respuesta; envoltorio de error tipado + idempotencia (Idempotency-Key). - AddedEstablecimientos:
GET /establishments,establishmentIdyestablishmentNameen los pagos, filtroestablishment_iden las listas y en la exportación; una clave lee los pagos creados por todo el equipo. - AddedArchivos de importación contable:
GET /export?format=quickbooks|xero|odoo|pennylane, una moneda por archivo. - AddedLos entornos están separados: una clave de producción solo lee pagos de producción, y una clave de prueba solo lee pagos de prueba (listas, exportación, lectura por id).