Paginação e filtragem

Todo endpoint de listagem da Tokeflow retorna resultados em páginas. Você solicita uma página; a Tokeflow retorna essa fatia mais um bloco meta.pagination que descreve onde você está no conjunto completo de resultados. As mesmas convenções se aplicam em todos os lugares — transações, pedidos, clientes, produtos, assinaturas e muito mais — então, uma vez que você as aprenda para um recurso, você as conhece para todos.

Esta página cobre duas coisas:

• Paginação — page / limit, o bloco meta.pagination e um loop que percorre todas as páginas.
• Filtragem — intervalos de datas, filtros de status com múltiplos valores e filtros de entidade/moeda que restringem uma lista antes de você paginá-la.

Paginação

Parâmetros de query

Dois parâmetros de query controlam a paginação. Ambos são opcionais.

Solicitar page=1&limit=20 retorna os primeiros 20 itens. Solicitar page=2&limit=20 retorna os itens 21–40, e assim por diante. Valores fora do intervalo permitido retornam 400 validation_error.

O bloco meta.pagination

Respostas paginadas envolvem o array no envelope de sucesso padrão. O array fica em data; os detalhes de paginação ficam em meta.pagination.

Iterando por todas as páginas

Para processar um conjunto inteiro de resultados, solicite a página 1 e continue avançando enquanto has_next for true. Pare quando ele se tornar false.

O helper em Node abaixo percorre todas as páginas de um endpoint de listagem e emite cada item. Ele usa o limit máximo para minimizar as requisições e se apoia em has_next em vez de calcular offsets manualmente.

/**
 * 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);
}

Filtragem

Filtros são parâmetros de query adicionais que restringem uma lista antes de a paginação ser aplicada. Combine quantos o endpoint suportar; eles são combinados com AND. Os filtros disponíveis variam por recurso — verifique cada referência de endpoint para o conjunto exato — mas as convenções são consistentes.

Filtros por intervalo de datas

A maioria dos endpoints de listagem suporta uma janela de criação por meio de date_from e date_to. Ambos aceitam timestamps ISO 8601 em UTC. Qualquer um pode ser fornecido isoladamente.

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

Filtros de múltiplos valores (status)

Filtros de status aceitam múltiplos valores. Você pode passá-los de duas formas equivalentes:

• Repetir o parâmetro: ?status=authorized&status=refunded
• Separar os valores por vírgula: ?status=authorized,refunded

Ambos produzem o mesmo resultado — qualquer item cujo status corresponda a qualquer um dos valores listados. Use os valores de enum exatos para o recurso (por exemplo, status de transação como authorized, refunded, partially_refunded; veja a referência de endpoint para o enum de cada recurso).

Filtros de entidade e moeda

Os endpoints de listagem expõem filtros que limitam os resultados a uma entidade ou atributo relacionado. O conjunto exato depende do recurso. Exemplos comuns:

Exemplo: uma requisição filtrada e paginada

Liste a primeira página de transações que estejam authorized ou refunded, em BRL, criadas durante janeiro de 2026. (Auth: chave de Organization com merchant_id, ou chave 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"

Resposta (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 é true, solicite page=2 com os mesmos filtros para continuar, e prossiga até que has_next seja false.

Erros

Exemplo (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"
  }
}

Veja Erros para a referência completa dos tipos de erro.

Leitura relacionada

• Visão geral da API — URL base, versionamento e os envelopes de sucesso/erro.
• Autenticação — tipos de chave, escopos e a regra de merchant_id para chaves de Organization.
• Idempotência e limites de taxa — mutações seguras para retry e throughput por chave.
• Erros — todos os tipos de erro e o mapeamento de status HTTP.