Visión general de la referencia de la API

La API de Tokeflow es una interfaz JSON sobre HTTPS para la orquestación de pagos. Úsala para gestionar clientes, ejecutar sesiones de checkout, crear y capturar transacciones, emitir reembolsos, modelar tu catálogo e impulsar suscripciones — todo estandarizado bajo tu propia marca, en cada proveedor de pagos que conectes.

Tokeflow orquesta pagos; no procesa ni liquida fondos. La autorización, la captura y la liquidación las realizan los proveedores de pagos conectados. Tokeflow normaliza su comportamiento detrás de una API consistente para que tu integración siga siendo la misma sin importar quién esté detrás.

Esta página es el centro de convenciones. Léela una vez y cada página de endpoint de esta referencia se comportará de la manera que esperas.

URL base y versionado

Todas las solicitudes van a una única URL base:

https://api.tokeflow.com

La API utiliza versionado por URI. Cada endpoint vive bajo un prefijo de versión, y la versión actual es v1:

https://api.tokeflow.com/api/v1/{resource}

Los cambios incompatibles se publican bajo un nuevo prefijo de versión (por ejemplo /api/v2). Los cambios aditivos y retrocompatibles — nuevos campos, nuevos valores de enum, nuevos endpoints — pueden aparecer dentro de v1, así que construye clientes que ignoren los campos desconocidos.

Autenticación

Autentica las solicitudes servidor a servidor con una clave secreta de API en el encabezado Authorization usando el esquema Bearer:

Authorization: Bearer sk_live_mer_…

Las claves están limitadas a exactamente una entidad:

Las claves públicas (pk_live_org_… / pk_live_mer_…) están restringidas a alcances seguros para el cliente y es seguro incrustarlas en código de navegador. Las claves secretas (sk_*) nunca deben exponerse en el lado del cliente.

Los permisos siguen un modelo resource:action (por ejemplo transactions:read, products:write). Una solicitud que se autentica pero carece del alcance requerido devuelve 403 (authorization_error).

Consulta Autenticación para conocer la anatomía de las claves, la rotación y los detalles de alcance.

Claves de Organization y merchant_id

Cuando usas una clave de Organization contra un recurso limitado a un Merchant, debes indicarle a Tokeflow a qué Merchant te refieres:

• En las solicitudes de listado y obtención, pasa merchant_id como parámetro de consulta.
• En las solicitudes de creación, pasa merchant_id en el cuerpo de la solicitud.

Las claves de Merchant nunca necesitan esto — el Merchant se deriva de la clave.

# Organization key: merchant_id is required
curl https://api.tokeflow.com/api/v1/customers?merchant_id=mrc_a1b2c3 \
  -H "Authorization: Bearer sk_live_org_…"

# Merchant key: merchant is inferred
curl https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_…"

Formato de solicitud

Envía y acepta JSON.

Una solicitud típica:

curl -X POST https://api.tokeflow.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Joao da Silva",
    "email": "joao@example.com"
  }'

Envoltorio de respuesta

Cada respuesta se envuelve en un envoltorio consistente. Tu código lee success para ramificar y luego data para la carga útil — nunca el objeto de nivel superior directamente.

Envoltorio de éxito

Una respuesta exitosa establece success: true y transporta el recurso (o el arreglo de recursos) en data:

{
  "success": true,
  "data": {
    "id": "cust_9a8b7c",
    "name": "Joao da Silva",
    "email": "joao@example.com",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Dónde vive cada cosa:

Para un endpoint de listado, data es el arreglo y meta.pagination describe la página:

{
  "success": true,
  "data": [
    { "id": "cust_9a8b7c", "name": "Joao da Silva" },
    { "id": "cust_4d5e6f", "name": "Maria Souza" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c…",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Envoltorio de error

Los errores nunca se envuelven en data. Utilizan una forma dedicada con un code estable y legible por máquina:

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_FIELD",
    "message": "The 'currency' field must be a valid ISO 4217 code.",
    "details": {
      "field": "currency"
    },
    "request_id": "req_8f3c…",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

El estado HTTP se corresponde directamente con el type del error:

Ramifica según error.code (una cadena estable), no según error.message (legible por humanos y sujeto a cambios). Consulta Errores para ver el catálogo completo.

const body = await res.json();

if (!res.ok) {
  // body.error.type, body.error.code, body.error.message
  throw new Error(`[${body.error.code}] ${body.error.message}`);
}

return body.data;

IDs de recursos

Cada recurso de Tokeflow tiene un ID estable y opaco con un prefijo de tipo. El prefijo te indica el tipo de recurso de un vistazo — trata el resto como una cadena opaca y nunca la analices.

Formatos de datos

Tokeflow estandariza los formatos para que tus datos sean inequívocos entre proveedores y regiones.

Dinero

Los montos son enteros en las unidades menores de la moneda (por ejemplo, centavos). Nunca envíes un decimal.

Empareja siempre un monto con su código currency ISO 4217 (por ejemplo "BRL", "USD"). Un monto sin moneda es ambiguo y se rechaza.

País, moneda y fechas

Idempotencia

Las mutaciones de creación y cobro son idempotentes. Envía un encabezado Idempotency-Key único (o un campo idempotency_key en el cuerpo) y Tokeflow garantiza que la operación se ejecute como máximo una vez.

curl -X POST https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-7b3d-4d2a-9f10-2e5a8c1b6d44" \
  -d '{ "amount": 15000, "currency": "BRL", "payment_method": "pix" }'

Reproducir la misma clave devuelve el resultado original — HTTP 200 en una reproducción frente a HTTP 201 en la primera creación — en lugar de crear un duplicado. Genera una clave nueva (como un UUID) por operación lógica y reutilízala al reintentar tras un fallo de red.

Consulta Idempotencia para conocer la semántica completa.

Límites de tasa

Las solicitudes están limitadas por tasa por clave de API y por endpoint, en ventanas de 60 segundos. Las rutas de pago y de lectura permiten 600 solicitudes por minuto de forma predeterminada; las rutas sin clase permiten 100. Superar un límite devuelve HTTP 429 con un rate_limit_error y un encabezado Retry-After.

Maneja 429 con retroceso exponencial y jitter, y distribuye las operaciones masivas en el tiempo en lugar de enviarlas en ráfagas. Consulta Límites de tasa para más detalles.

Paginación y filtrado

Los endpoints de listado se paginan con dos parámetros de consulta:

La respuesta transporta el estado de la página en meta.pagination:

curl "https://api.tokeflow.com/api/v1/customers?page=2&limit=50" \
  -H "Authorization: Bearer sk_live_mer_…"

La mayoría de los endpoints de listado también aceptan filtros específicos del recurso (por ejemplo estado, rango de fechas, moneda). Cada página de endpoint documenta sus propios filtros. Consulta Paginación y filtrado para conocer las convenciones compartidas.

Cómo fluye una solicitud

Tokeflow autentica la clave, aplica tus reglas de enrutamiento (incluyendo resiliencia y respaldo), reenvía al proveedor seleccionado y normaliza la respuesta del proveedor en el envoltorio estándar. Tu cliente siempre ve la misma forma.

Grupos de recursos

Cada endpoint a continuación acepta una clave de Organization o de Merchant. Con una clave de Organization, añade merchant_id donde el endpoint esté limitado a un Merchant (como se indica en cada página).

El catálogo de un vistazo

El catálogo modela lo que vendes y cómo se le pone precio.

Próximos pasos

• Autenticación — aprovisiona claves y comprende los alcances.
• Errores — el catálogo completo de errores y códigos.
• Idempotencia y Límites de tasa — reintentos seguros a escala.
• Webhooks — recibe y verifica eventos firmados.