Paginación y filtrado

Cada endpoint de listado de Tokeflow devuelve los resultados en páginas. Tú solicitas una página; Tokeflow devuelve ese segmento más un bloque meta.pagination que describe en qué punto del conjunto completo de resultados te encuentras. Las mismas convenciones se aplican en todas partes — transacciones, órdenes, clientes, productos, suscripciones y más — así que una vez que las aprendas para un recurso, las conoces para todos.

Esta página cubre dos cosas:

• Paginación — page / limit, el bloque meta.pagination y un bucle que recorre cada página.
• Filtrado — rangos de fechas, filtros de estado de múltiples valores y filtros de entidad/moneda que acotan una lista antes de paginarla.

Paginación

Parámetros de consulta

Dos parámetros de consulta controlan la paginación. Ambos son opcionales.

Solicitar page=1&limit=20 devuelve los primeros 20 elementos. Solicitar page=2&limit=20 devuelve los elementos 21–40, y así sucesivamente. Los valores fuera del rango permitido devuelven 400 validation_error.

El bloque meta.pagination

Las respuestas paginadas envuelven el arreglo en el sobre de éxito estándar. El arreglo vive en data; los detalles de paginación viven en meta.pagination.

Iterar cada página

Para procesar un conjunto de resultados completo, solicita la página 1 y sigue avanzando mientras has_next sea true. Detente cuando cambie a false.

El helper de Node que aparece a continuación recorre cada página de un endpoint de listado y produce cada elemento. Usa el limit máximo para minimizar las solicitudes y se apoya en has_next en lugar de calcular desplazamientos a mano.

/**
 * Async generator that yields every item across all pages of a Tokeflow list endpoint.
 * `path` is a resource path, e.g. "/api/v1/customers".
 * `params` are extra filters, e.g. { currency: "BRL" }.
 */
async function* paginate(path, params = {}, { limit = 100 } = {}) {
  let page = 1;

  for (;;) {
    const url = new URL(`https://api.tokeflow.com${path}`);
    url.searchParams.set("page", String(page));
    url.searchParams.set("limit", String(limit));
    for (const [key, value] of Object.entries(params)) {
      url.searchParams.set(key, value);
    }

    const res = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.TOKEFLOW_SECRET_KEY}`,
        Accept: "application/json",
      },
    });
    const body = await res.json();

    for (const item of body.data) {
      yield item;
    }

    if (!body.meta.pagination.has_next) break;
    page += 1;
  }
}

// Usage — collect every BRL customer.
const customers = [];
for await (const customer of paginate("/api/v1/customers", { currency: "BRL" })) {
  customers.push(customer);
}

Filtrado

Los filtros son parámetros de consulta adicionales que acotan una lista antes de que se aplique la paginación. Combina tantos como el endpoint admita; se unen con AND. Los filtros disponibles varían por recurso — consulta cada referencia de endpoint para conocer el conjunto exacto — pero las convenciones son coherentes.

Filtros de rango de fechas

La mayoría de los endpoints de listado admiten una ventana de fecha de creación mediante date_from y date_to. Ambos toman marcas de tiempo ISO 8601 en UTC. Cualquiera de los dos puede suministrarse por sí solo.

?date_from=2026-01-01T00:00:00Z&date_to=2026-01-31T23:59:59Z

Filtros de múltiples valores (estado)

Los filtros de estado aceptan múltiples valores. Puedes pasarlos de dos maneras equivalentes:

• Repite el parámetro: ?status=authorized&status=refunded
• Separa los valores por comas: ?status=authorized,refunded

Ambas producen el mismo resultado — cualquier elemento cuyo estado coincida con alguno de los valores enumerados. Usa los valores enum exactos del recurso (por ejemplo, estados de transacción como authorized, refunded, partially_refunded; consulta la referencia de endpoint para conocer el enum de cada recurso).

Filtros de entidad y moneda

Los endpoints de listado exponen filtros que acotan los resultados a una entidad o atributo relacionado. El conjunto exacto depende del recurso. Ejemplos comunes:

Ejemplo: una solicitud filtrada y paginada

Lista la primera página de transacciones que están authorized o refunded, en BRL, creadas durante enero de 2026. (Auth: clave de Organization con merchant_id, o clave de Merchant.)

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

Respuesta (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "tx_9a8b7c6d",
      "status": "authorized",
      "amount": 15000,
      "currency": "BRL",
      "payment_method": "credit_card",
      "charge_type": "payment",
      "customer_id": "cust_7h2k9",
      "created_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "id": "tx_5f4e3d2c",
      "status": "refunded",
      "amount": 9900,
      "currency": "BRL",
      "payment_method": "pix",
      "charge_type": "payment",
      "customer_id": "cust_3p9q1",
      "created_at": "2026-01-09T08:12:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a91",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

Como has_next es true, solicita page=2 con los mismos filtros para continuar, y sigue hasta que has_next sea false.

Errores

Ejemplo (400 validation_error):

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_VALUE",
    "message": "limit must not be greater than 100",
    "details": { "field": "limit", "max": 100 },
    "request_id": "req_1b2c3d4e",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Consulta Errores para la referencia completa de tipos de error.

Lecturas relacionadas

• Descripción general de la API — URL base, versionado y los sobres de éxito/error.
• Autenticación — tipos de clave, alcances y la regla merchant_id para claves de Organization.
• Idempotencia y límites de tasa — mutaciones seguras ante reintentos y rendimiento por clave.
• Errores — cada tipo de error y su mapeo de estado HTTP.