Órdenes

Lee y filtra órdenes — el registro comercial que agrupa los intentos de pago detrás de cada compra, checkout, renovación y flujo de configuración.

Una orden es el registro comercial de una única intención de compra. Es el anclaje duradero y legible por humanos que agrupa uno o más intentos de pago — las transacciones que Tokeflow orquesta a través de tus proveedores conectados — bajo un identificador estable que puedes mostrar en un recibo, conciliar contra tu libro contable o consultar en soporte.

Nunca creas una orden directamente. Tokeflow abre una automáticamente en el momento en que se inicia un cobro, y luego mantiene su estado en sincronía con la transacción subyacente a medida que avanza por tus reglas de enrutamiento.

Tokeflow es orquestación de pagos, no un procesador de pagos. Una orden registra y estandariza el evento comercial; el proveedor conectado autoriza, captura y liquida los fondos. Tokeflow nunca mueve ni liquida dinero.

Cómo se crean las órdenes

Cada ruta de cobro produce exactamente una orden, distinguida por su order_type:

`order_type`	Se crea cuando	`recurrence` típica
`api`	Llamas directamente a `POST /transactions`.	`none`
`checkout`	Se paga una sesión de Checkout alojada o incrustada.	`none` o `initial`
`renewal`	Una suscripción factura un nuevo ciclo.	`subsequent`
`trial_setup`	Se aprovisiona una suscripción de prueba y se ejecuta su primer cobro / cobro de configuración.	`initial`
`card_setup`	Se verifica y tokeniza una tarjeta sin una venta inmediata (una verificación de cero / solo autorización).	`none`

El status de la orden se deriva de la transacción que agrupa. A medida que la transacción se autoriza, reembolsa o recibe un contracargo, Tokeflow avanza el estado de la orden y añade una entrada a su historial de estados.

Hoy una orden agrupa una única transacción de pago principal. El modelo de datos está construido para agrupar múltiples intentos (por ejemplo, un fallback en cascada entre proveedores) bajo una sola orden, así que trata siempre la orden — no una única transacción — como la unidad de conciliación.

El objeto order

{
  "id": "ord_9f8e7d6c5b4a3210",
  "merchant_id": "mrc_8a1b2c3d4e5f",
  "organization_id": "org_1a2b3c4d5e6f",
  "customer_id": "cust_kj3x8rabc123",
  "external_order_id": "shop_order_456",
  "checkout_session_id": "cks_a1b2c3d4e5",
  "order_type": "checkout",
  "recurrence": "initial",
  "total_amount": 9900,
  "currency": "BRL",
  "status": "authorized",
  "metadata": {
    "cart_id": "cart_7788",
    "campaign": "winter_sale"
  },
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:04.000Z",
  "items": [
    {
      "id": "f3a1c2d4-1111-4a2b-9c3d-5e6f7a8b9c0d",
      "product_id": "prd_a1b2c3d4e5",
      "offer_id": "ofr_a1b2c3d4e5",
      "product_name": "Premium Plan",
      "offer_name": "Annual Discount",
      "billing_cycle": "yearly",
      "cycle_limit": 12,
      "is_first_charge": true,
      "quantity": 1,
      "unit_amount": 9900,
      "total_amount": 9900,
      "currency": "BRL",
      "installments": 1,
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "status_history": [
    {
      "from_status": null,
      "to_status": "pending",
      "triggered_by": "api",
      "created_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "from_status": "pending",
      "to_status": "authorized",
      "triggered_by": "psp_webhook",
      "created_at": "2026-01-15T12:30:04.000Z"
    }
  ]
}

Campos

Field	Type	Description
`id`	string	Identificador único de la orden, con prefijo `ord_`.
`merchant_id`	string	Merchant propietario de la orden (`mrc_`).
`organization_id`	string	Organization a la que pertenece el Merchant (`org_`).
`customer_id`	string	Cliente al que pertenece la orden (`cust_`).
`external_order_id`	string \| null	Tu propia referencia de orden, devuelta de vuelta para conciliación. `null` cuando no se proporciona.
`checkout_session_id`	string \| null	Sesión de checkout de origen (`cks_`) para órdenes `checkout` / `trial_setup`; `null` en caso contrario.
`order_type`	string	Cómo se originó la orden. Uno de `api`, `checkout`, `renewal`, `trial_setup`, `card_setup`.
`recurrence`	string	Posición en una serie recurrente: `none`, `initial`, `subsequent` o `unscheduled`.
`total_amount`	integer	Total en unidades menores (centavos). `9900` = R$99.00.
`currency`	string	Código de moneda ISO 4217 (p. ej. `BRL`).
`status`	string	Estado actual de la orden. Consulta Estado de la orden.
`metadata`	object \| null	Datos arbitrarios de clave/valor que adjuntas en la creación.
`created_at`	string	Marca de tiempo de creación en UTC ISO 8601.
`updated_at`	string	Marca de tiempo de última actualización en UTC ISO 8601.
`items`	array	Líneas de detalle capturadas como snapshot en la creación de la orden. Devueltas por el endpoint de orden individual; vacías/omitidas en los resultados de lista.
`status_history`	array	Transiciones de estado ordenadas. Devueltas por el endpoint de orden individual.

Los resultados de lista (GET /orders) devuelven las cabeceras de la orden — los campos de nivel superior de arriba. Los arrays items y status_history solo se rellenan cuando recuperas una única orden por ID.

Campos de la línea de detalle

Cada línea de detalle es un snapshot inmutable del producto y la oferta en el momento en que se creó la orden, de modo que las órdenes históricas se mantienen precisas incluso después de que cambies tu catálogo.

Field	Type	Description
`id`	string	Identificador de la línea de detalle (UUID).
`product_id`	string \| null	Referencia del producto (`prd_`).
`offer_id`	string \| null	Referencia de la oferta (`ofr_`).
`product_name`	string	Snapshot del nombre del producto.
`offer_name`	string \| null	Snapshot del nombre de la oferta.
`billing_cycle`	string \| null	Snapshot del ciclo de facturación de la oferta (p. ej. `monthly`, `yearly`). `null` para artículos de pago único.
`cycle_limit`	integer \| null	Snapshot del límite de ciclos de la oferta, si lo hay.
`is_first_charge`	boolean	`true` cuando se aplicó el precio del primer cobro / configuración.
`quantity`	integer	Cantidad comprada.
`unit_amount`	integer	Precio unitario en unidades menores (refleja el precio del primer cobro cuando `is_first_charge` es `true`).
`total_amount`	integer	Total de la línea en unidades menores (`unit_amount` × `quantity`).
`currency`	string	Código de moneda ISO 4217.
`installments`	integer \| null	Cuotas elegidas en el checkout. `null` o `1` significa un único cobro.
`created_at`	string	Marca de tiempo en UTC ISO 8601.

Campos del historial de estados

Field	Type	Description
`from_status`	string \| null	Estado antes de la transición. `null` para la primera entrada.
`to_status`	string	Estado después de la transición.
`triggered_by`	string	Qué impulsó el cambio (p. ej. `api`, `system`, `psp_webhook`).
`created_at`	string	Marca de tiempo en UTC ISO 8601 de la transición.

Estado de la orden

Status	Significado
`pending`	Orden creada; el cobro aún no se ha completado.
`pre_authorized`	Hay una retención de autorización en curso, a la espera de captura.
`authorized`	El cobro tuvo éxito (autorizado/capturado).
`failed`	El cobro no tuvo éxito. Terminal.
`canceled`	La orden se canceló antes de completarse. Terminal.
`refund_pending`	Se ha solicitado un reembolso y se está procesando.
`partially_refunded`	Se ha reembolsado parte del monto.
`refunded`	Se ha reembolsado el monto completo.
`charged_back`	Se registró un contracargo contra la orden.

El estado de la orden refleja el ciclo de vida de la transacción subyacente. Para inspeccionar el detalle a nivel de pago detrás de un estado — resultados del proveedor, capturas, anulaciones — lee la transacción vinculada y sus reembolsos.

Endpoints

URL base: https://api.tokeflow.com — todas las rutas están bajo /api/v1.

Las órdenes son de solo lectura a través de la API. Autentícate con una clave secreta del lado del servidor (Authorization: Bearer sk_live_…). Consulta Autenticación para conocer la anatomía y los scopes de las claves. Ambos endpoints requieren el scope orders:read.

Las claves secretas (sk_*) son exclusivas del lado del servidor — nunca las expongas en código de navegador o móvil.

GET`/api/v1/orders`

Auth: Organization key (con merchant_id) o Merchant key.

Devuelve una lista paginada de cabeceras de órdenes para el Merchant resuelto, con los datos más recientes primero. Una clave de Merchant infiere su Merchant automáticamente. Una clave de Organization abarca todos los Merchants de la Organization, por lo que debe pasar merchant_id para acotar la consulta.

Parámetros de query

Field	Type	Required	Description
`merchant_id`	string	Condicional	Requerido para claves de Organization; omítelo para claves de Merchant (inferido).
`status`	string	No	Filtra por estado de la orden. Repite el parámetro o pasa una lista separada por comas para múltiples valores (p. ej. `status=authorized,refunded`).
`customer_id`	string	No	Devuelve solo las órdenes de este cliente (`cust_`).
`external_order_id`	string	No	Coincide con tu propia referencia de orden.
`order_type`	string	No	Uno de `api`, `checkout`, `renewal`, `trial_setup`, `card_setup`.
`currency`	string	No	Código de moneda ISO 4217 (p. ej. `BRL`).
`date_from`	string	No	Incluye órdenes creadas en o después de esta marca de tiempo ISO 8601.
`date_to`	string	No	Incluye órdenes creadas en o antes de esta marca de tiempo ISO 8601.
`page`	integer	No	Número de página, indexado desde 1. Predeterminado `1`.
`limit`	integer	No	Elementos por página. Predeterminado `20`, máx. `100`.

Request

curl -G "https://api.tokeflow.com/api/v1/orders" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=authorized,refunded" \
  --data-urlencode "order_type=checkout" \
  --data-urlencode "currency=BRL" \
  --data-urlencode "date_from=2026-01-01T00:00:00Z" \
  --data-urlencode "date_to=2026-01-31T23:59:59Z"

Con una clave de Organization, añade merchant_id a la cadena de consulta para acotar la lista a un solo Merchant: GET /api/v1/orders?merchant_id=mrc_8a1b2c3d4e5f&status=authorized

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "ord_9f8e7d6c5b4a3210",
      "merchant_id": "mrc_8a1b2c3d4e5f",
      "organization_id": "org_1a2b3c4d5e6f",
      "customer_id": "cust_kj3x8rabc123",
      "external_order_id": "shop_order_456",
      "checkout_session_id": "cks_a1b2c3d4e5",
      "order_type": "checkout",
      "recurrence": "initial",
      "total_amount": 9900,
      "currency": "BRL",
      "status": "authorized",
      "metadata": { "cart_id": "cart_7788" },
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:04.000Z"
    },
    {
      "id": "ord_1122334455667788",
      "merchant_id": "mrc_8a1b2c3d4e5f",
      "organization_id": "org_1a2b3c4d5e6f",
      "customer_id": "cust_kj3x8rabc123",
      "external_order_id": null,
      "checkout_session_id": null,
      "order_type": "api",
      "recurrence": "none",
      "total_amount": 15000,
      "currency": "BRL",
      "status": "refunded",
      "metadata": null,
      "created_at": "2026-01-12T09:05:00.000Z",
      "updated_at": "2026-01-13T17:42:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b9d7e",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET`/api/v1/orders/:id`

Auth: Organization key (con merchant_id) o Merchant key.

Recupera una única orden con sus items y status_history. La orden se devuelve solo si pertenece al Merchant resuelto (y, para claves de Organization, al merchant_id especificado dentro de tu Organization).

Parámetros de path

Field	Type	Required	Description
`id`	string	Sí	El ID de la orden (`ord_`).

Parámetros de query

Field	Type	Required	Description
`merchant_id`	string	Condicional	Requerido para claves de Organization; omítelo para claves de Merchant.

Request

curl "https://api.tokeflow.com/api/v1/orders/ord_9f8e7d6c5b4a3210" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "ord_9f8e7d6c5b4a3210",
    "merchant_id": "mrc_8a1b2c3d4e5f",
    "organization_id": "org_1a2b3c4d5e6f",
    "customer_id": "cust_kj3x8rabc123",
    "external_order_id": "shop_order_456",
    "checkout_session_id": "cks_a1b2c3d4e5",
    "order_type": "checkout",
    "recurrence": "initial",
    "total_amount": 9900,
    "currency": "BRL",
    "status": "authorized",
    "metadata": { "cart_id": "cart_7788", "campaign": "winter_sale" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:04.000Z",
    "items": [
      {
        "id": "f3a1c2d4-1111-4a2b-9c3d-5e6f7a8b9c0d",
        "product_id": "prd_a1b2c3d4e5",
        "offer_id": "ofr_a1b2c3d4e5",
        "product_name": "Premium Plan",
        "offer_name": "Annual Discount",
        "billing_cycle": "yearly",
        "cycle_limit": 12,
        "is_first_charge": true,
        "quantity": 1,
        "unit_amount": 9900,
        "total_amount": 9900,
        "currency": "BRL",
        "installments": 1,
        "created_at": "2026-01-15T12:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from_status": null,
        "to_status": "pending",
        "triggered_by": "api",
        "created_at": "2026-01-15T12:30:00.000Z"
      },
      {
        "from_status": "pending",
        "to_status": "authorized",
        "triggered_by": "psp_webhook",
        "created_at": "2026-01-15T12:30:04.000Z"
      }
    ]
  },
  "request_id": "req_7b2d1e0c8f6a",
  "timestamp": "2026-01-15T12:30:05.000Z"
}

Response `404 Not Found`

Se devuelve cuando la orden no existe o no pertenece al Merchant resuelto.

{
  "error": {
    "type": "not_found_error",
    "code": "ORDER_NOT_FOUND",
    "message": "Order ord_9f8e7d6c5b4a3210 not found or does not belong to your merchant",
    "details": {},
    "request_id": "req_3c9a7f2b1d8e",
    "timestamp": "2026-01-15T12:31:00.000Z"
  }
}

Errores

Las órdenes usan el sobre de error estándar. Casos comunes:

HTTP	`type`	Cuándo
401	`authentication_error`	Clave de API faltante o inválida.
403	`authorization_error`	La clave carece del scope `orders:read`, o una clave de Organization omitió `merchant_id`.
404	`not_found_error`	Orden no encontrada, o no perteneciente al Merchant resuelto.
429	`rate_limit_error`	Límite de tasa excedido (predeterminado 600 solicitudes / minuto por clave en cada ruta de órdenes). Respeta `Retry-After`, aplica retroceso y reintenta.

Relacionado

Transacciones — los intentos de pago que agrupa una orden, y donde viven los reembolsos.
Checkout — sesiones que crean órdenes checkout.
Suscripciones — el origen de las órdenes renewal y trial_setup.
Autenticación — tipos de claves, scopes y la regla de merchant_id para claves de Organization.

Órdenes

GET/api/v1/orders

GET/api/v1/orders/:id

En esta página

GET`/api/v1/orders`

GET`/api/v1/orders/:id`