Índice

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.

Base URL 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.

cURL
curl https://toreador.io/api/v1/public/sessions \
  -H "X-API-Key: tor_live_a1b2c3..."

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).

Response · 4xx
{
  "error": "Invalid amount: must be a decimal number between 0 and 1,000,000",
  "error_details": {
    "code": "invalid_amount",
    "type": "invalid_request",
    "message": "Invalid amount...",
    "request_id": "req_3f9a1c2b4d5e6f70",
    "doc_url": "https://toreador.io/docs/errors#invalid_amount"
  }
}

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

GET

/ping

Clave requerida

Verifica 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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/ping" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "ok": true,
  "env": "live",
  "plan": "pro",
  "apiVersion": "1.0.0"
}
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.

GET

/account

Clave requerida

Estado 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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/account" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "plan": "plus",
  "env": "live",
  "subscription": { "status": "trialing", "realPlan": "free", "onTrial": true, "trialEndsAt": 1782329542, "trialDaysRemaining": 10 },
  "quota": { "used": 0, "limit": 5000, "remaining": 5000 },
  "limits": { "ratePerMinute": 600, "apiKeysMax": 10, "walletsMax": 50 }
}
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.

GET

/tokens

Clave requerida

Matriz 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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/tokens" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "env": "live",
  "chains": [ { "id": "base", "name": "Base", "nativeToken": "ETH", "family": "evm",
                "explorerTx": "https://basescan.org/tx/{hash}" } ],
  "tokens": [
    { "symbol": "ETH", "decimals": 18, "isNative": true,
      "chains": [ { "chain": "base", "type": "native", "contract": null } ] },
    { "symbol": "USDC", "decimals": 6, "isNative": false,
      "chains": [ { "chain": "base", "type": "erc20", "contract": "0x833589fC…" } ] }
  ]
}
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.

GET

/screen

Clave requerida

Verifica 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).

Clave requerida (plan gratuito incluido). Límite de solicitudes por minuto según su plan. Direcciones EVM: listas descargadas (OFAC, UE, Reino Unido, Suiza) + oráculo de Chainalysis. Direcciones Bitcoin y Solana: solo listas descargadas. 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

200 OK400 falta la dirección401 clave no válida429 límite de solicitudes superado

Solicitud

curl "https://toreador.io/api/v1/public/screen?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "address": "0x098B716B…",
  "status": "sanctioned",
  "sanctioned": true,
  "source": "chainalysis_oracle"
}
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.

POST

/generate-qr

Clave requerida

Genera 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.

Clave requerida (plan gratuito incluido). Límite de solicitudes por minuto según su plan. El QR siempre apunta a una wallet registrada en su cuenta. Encabezados 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

200 OK400 entrada no válida / endpoint incorrecto401 clave no válida409 conflicto de Idempotency-Key429 límite de solicitudes

Solicitud

curl -X POST "https://toreador.io/api/v1/public/generate-qr" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token":"BTC","chainId":"bitcoin","amount":"0.001","recipientAddress":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"}'

Respuesta

Response · 200 OK
{
  "success": true,
  "type": "native",
  "qrData": "bitcoin:bc1q...?amount=0.001",
  "format": "png",
  "qrCodeURL": "data:image/png;base64,iVBORw0KGgo...",  // format=svg → "qrCodeSvg" · format=text → "qrCodeText"
  "token": { "symbol": "BTC", "name": "Bitcoin", "decimals": 8 },
  "chain": { "id": "bitcoin", "name": "Bitcoin", "symbol": "BTC" },
  "amount": "0.001",
  "recipientAddress": "bc1q..."
}
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.

POST

/create-session

Clave requerida

Crea 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.

Una clave de prueba (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

200 OK400 entrada no válida401 clave no válida402 cuota mensual agotada409 conflicto de Idempotency-Key429 límite de solicitudes

Solicitud

curl -X POST "https://toreador.io/api/v1/public/create-session" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"token":"USDC","chainId":"base","amount":"100","recipientAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"}'

Respuesta

Response · 200 OK
{
  "success": true,
  "sessionId": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "url": "https://pay.toreador.io/pay/3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "expiresAt": 1718000000,
  "expiresIn": 900,
  "token": { "symbol": "USDC", "name": "USD Coin", "decimals": 6 },
  "chain": { "id": "base", "name": "Base", "symbol": "ETH" },
  "amount": "100",
  "recipientAddress": "0x742d35Cc..."
}
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.

GET

/wallets

Clave requerida

Lista (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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/wallets" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "wallets": [
    { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "family": "evm", "label": "Treasury", "source": "self_custodial", "custodial": false, "ownershipProven": true, "acceptedRails": null },
    { "address": "0xb14d1444f13984dd573056254c15a32783e05996", "family": "evm", "label": "Binance", "source": "binance", "custodial": true, "ownershipProven": true, "acceptedRails": [{ "token": "USDC", "chain": "polygon" }, { "token": "USDT", "chain": "arbitrum" }] }
  ]
}
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.

POST

/checkout

Clave requerida

Crea 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

200 OK400 entrada no válida / moneda no admitida401 clave no válida402 cuota mensual agotada409 sin wallet / sin rail429 límite de solicitudes

Solicitud

curl -X POST "https://toreador.io/api/v1/public/checkout" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount":"50","currency":"USD","description":"Order #42","conversion":"off","reference":"wc-order-42","recipientAddress":"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"}'

Respuesta

Response · 200 OK
{
  "success": true,
  "checkoutId": "co_00a527da53a144c5bc2f1267a0fac074",
  "reference": "wc-order-42",
  "url": "https://pay.toreador.io/pay/co_00a527da53a144c5bc2f1267a0fac074",
  "amount": 50,
  "currency": "USD",
  "conversion": false,
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "allowedRails": [ { "token": "USDC", "chain": "base" } ],
  "expiresAt": 1718003600,
  "expiresIn": 3600
}
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.

POST

/webhooks

Clave requerida

Registra (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.

Firma: encabezado Toreador-Signature = t=…,v1=… (HMAC-SHA256 en hexadecimal de la cadena {t}.{rawBody}). Eventos: session.created/submitted/confirming/completed/expired/failed, checkout.created. Entrega: 2xx = éxito; de lo contrario, reintentos (hasta 9, con espera exponencial). GET /webhooks los lista (sin el secreto); DELETE /webhooks/{id} lo elimina.

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

200 OK400 URL no válida / no HTTPS401 clave no válida403 URL fuera del dominio de la clave

Solicitud

curl -X POST "https://toreador.io/api/v1/public/webhooks" \
  -H "X-API-Key: tor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-store.com/wp-json/toreador/v1/webhook"}'

Respuesta

Response · 200 OK
{
  "success": true,
  "id": "whk_…",
  "url": "https://your-store.com/wp-json/toreador/v1/webhook",
  "events": [ "session.completed", "session.failed", "session.expired" ],
  "secret": "whsec_…",
  "created": true
}
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.

GET

/payment/{id}

Clave requerida

Obtiene 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

200 OK404 no encontrado

Solicitud

curl "https://toreador.io/api/v1/public/payment/3f9a1c2b4d5e6f708192a3b4c5d6e7f8" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "id": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
  "object": "payment",
  "type": "session",
  "status": "completed",
  "token": "USDC",
  "chain": "base",
  "amount": "100",
  "recipient": "0x742d35Cc...",
  "txHash": "0x89bca0...",
  "confirmations": 1,
  "requiredConfirmations": 1,
  "createdAt": 1718000000,
  "completedAt": 1718000045,
  "checkoutId": "co_00a527da53a144c5bc2f1267a0fac074",
  "reference": "wc-order-42",
  "timeline": [ { "type": "completed", "at": 1718000045 } ]
}
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.

GET

/payment/{id}/status

Clave requerida

Devuelve 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

200 OK404 no encontrado

Solicitud

curl "https://toreador.io/api/v1/public/payment/3f9a1c2b4d5e6f708192a3b4c5d6e7f8/status" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "sessionId": "3f9a1c2b...",
  "status": "confirming",
  "token": "USDC",
  "chainId": "base",
  "amount": "100",
  "recipientAddress": "0x742d35Cc...",
  "txHash": "0x89bca0...",
  "confirmations": 0,
  "requiredConfirmations": 1,
  "expiresAt": 1718000900,
  "completedAt": null
}
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.

GET

/establishments

Clave requerida

Lista (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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/establishments" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "data": [
    { "id": "est_3f9a…", "name": "Main street", "isDefault": true, "organizationId": "org_81c2…", "organizationName": "Corner Books" },
    { "id": "est_b07d…", "name": "Harbour", "isDefault": false, "organizationId": "org_81c2…", "organizationName": "Corner Books" }
  ]
}
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.

GET

/history

Clave requerida

Lista 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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/history?limit=20" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "data": [ { "id": "...", "type": "native", "amount": "0.001", "createdAt": 1718000000 } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6..."
}
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.

GET

/sessions

Clave requerida

Lista 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

200 OK401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/sessions?limit=20" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "data": [ { "id": "...", "status": "completed", "token": "EURC", "amount": "43.226420", "amountUsd": 50, "fxRate": 0.8645, "fxSource": "ecb", "checkoutId": "co_00a527…", "reference": "wc-order-42", "invoice": { "currency": "USD", "amount": 50 } } ],
  "has_more": false,
  "next_cursor": null
}
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.

GET

/export

Clave requerida

Exportació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.

Guía de campos: 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

200 OK400 parámetro no válido, o moneda obligatoria401 clave no válida

Solicitud

curl "https://toreador.io/api/v1/public/export?format=json" \
  -H "X-API-Key: tor_live_..."

Respuesta

Response · 200 OK
{
  "success": true,
  "count": 2,
  "truncated": false,
  "data": [ { "id": "...", "completedAt": 1781344545, "invoiceCurrency": "USD", "invoiceAmount": 50, "settlementToken": "EURC", "settlementAmount": "43.226420", "amountUsd": 50, "fxRate": 0.8645, "fxSource": "ecb", "txHash": "0x…" } ]
}
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
Verificación de firma y ejemplo completo →

Changelog

v1.0.0

La 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.

v1.0.0 2026-06-13
  • 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 png o svg mediante el parámetro format.
  • AddedEncabezado API-Version en cada respuesta; envoltorio de error tipado + idempotencia (Idempotency-Key).
  • AddedEstablecimientos: GET /establishments, establishmentId y establishmentName en los pagos, filtro establishment_id en 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).

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.