> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginação, ordenação e idempotência

> Como percorrer listagens, ordenar resultados e evitar cobranças e processamentos duplicados quando algo dá errado na rede.

Três assuntos valem para a API inteira: como as listagens devolvem os dados em páginas, em que ordem os resultados vêm e como evitar que uma falha de rede vire uma cobrança duplicada. Esta página reúne os três, com as diferenças entre rotas que você precisa tratar no código.

> [!NOTE]
>
> **Para o negócio:** a API da Finvia não tem proteção automática contra requisições repetidas. Se o sistema reenvia uma criação de cobrança depois de uma falha de rede, o cliente pode ser cobrado duas vezes. O procedimento desta página evita isso e deve estar no escopo de qualquer integração.

## Paginação

Todas as listagens paginadas da API usam os mesmos dois parâmetros de consulta:

| Parâmetro | Tipo | Padrão | Descrição |
| - | - | - | - |
| `page` | integer | `1` | Número da página. Começa em 1 |
| `size` | integer | `10` | Quantidade de itens por página |

> [!WARNING]
>
> O parâmetro de tamanho é `size`. A API ignora `limit` sem dar erro: `limit=10` parece funcionar só porque 10 já é o padrão, e `limit=50` continua devolvendo 10 itens. O mesmo vale para qualquer parâmetro desconhecido, que é ignorado em silêncio. Confira sempre o nome do filtro na referência da rota.

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/charges?page=2&size=20" \
  -u "$FINVIA_API_KEY:"
```

### Formato da resposta em cada listagem

Há dois modelos de resposta paginada e algumas rotas que devolvem a lista inteira, sem paginação.

**Modelo A: totais na raiz do objeto**

```json theme={null}
{
  "data": [ ],
  "total": 100,
  "page": 1,
  "size": 10,
  "pages": 10
}
```

**Modelo B: totais dentro de `meta`**

```json theme={null}
{
  "data": [ ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}
```

No modelo B, o `meta.limit` da resposta é só o tamanho da página que você pediu em `size`. Ele não é um parâmetro de consulta.

| Rota | Paginada | Formato da resposta | Ordem dos resultados | Filtros |
| - | - | - | - | - |
| [`GET /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/listar) | Sim | Modelo A | Sempre da mais recente para a mais antiga. `orderBy` é ignorado | `status`, `currency`, `createdAtStart` + `createdAtEnd`, `searchFor`, `merchantId` |
| [`GET /v1/submerchants`](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas) | Sim | Modelo A | Mais recentes primeiro. Aceita `orderBy` com nomes em snake\_case | `status`, `search`, `createdFrom`, `createdTo`, `completeness`, `companyTaxId`, `legalName`, `tradeName` |
| [`GET /v1/payout-requests`](https://docs.fastpaybrasil.com/referencia/saques/listar) | Sim | Modelo A, com o campo extra `pendingCount` | Mais recentes primeiro. Não use `orderBy` | `merchantId`, `status`, `currency`, `createdAtStart`, `createdAtEnd` |
| [`GET /v1/customers`](https://docs.fastpaybrasil.com/referencia/clientes/listar) | Sim | Modelo A | Mais recentes primeiro | `search`, `email`, `documentId` |
| [`GET /v1/subscription-plans`](https://docs.fastpaybrasil.com/referencia/planos/listar) | Sim | Modelo B | Não aceita `orderBy` | `merchantId`, `status` |
| [`GET /v1/subscriptions`](https://docs.fastpaybrasil.com/referencia/assinaturas/listar) | Sim | Modelo B | Não aceita `orderBy` | `merchantId`, `customerId`, `status`, `search` |
| [`GET /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints) | Sim | Modelo A | Não aceita `orderBy` | `merchantId`, `search` |
| [`GET /v1/submerchants/{merchantId}/legal-representatives`](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-representantes) | Não | Objeto com `data` (lista) | Representante legal primeiro | `include=documents` |
| [`GET /v1/apple-pay/domains`](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios) | Não | Objeto com `data` (lista) | Mais recentes primeiro | Nenhum |
| [`GET /v1/cards`](https://docs.fastpaybrasil.com/referencia/cartoes/listar) | Não | Lista (array) direto na raiz, com no máximo os 20 cartões mais recentes | Mais recentes primeiro | `customerId` |
| [`GET /v1/wallets`](https://docs.fastpaybrasil.com/referencia/carteiras/listar) | Não | Lista (array) direto na raiz | Não se aplica | `merchantId` (obrigatório), `currency` |
| [`GET /v1/payment-methods`](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar) | Não | Lista (array) direto na raiz | Não se aplica | `merchantId`, `currency` |

> [!TIP]
>
> **Para o desenvolvedor:** escreva um leitor de paginação que aceite os dois modelos. No modelo A, o total de páginas está em `pages`. No modelo B, está em `meta.totalPages`. Rotas que devolvem array não têm página seguinte.

### Como percorrer todas as páginas

```javascript Node.js theme={null}
// listar-tudo.mjs (Node.js 18+, ESM, await no topo)
const API_URL = 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

async function listarTudo(rota, filtros = {}) {
  const itens = [];
  let page = 1;
  let totalPaginas = 1;

  do {
    const params = new URLSearchParams({ ...filtros, page: String(page), size: '50' });
    const res = await fetch(`${API_URL}${rota}?${params}`, {
      headers: { Authorization: `Basic ${credentials}` },
    });
    if (!res.ok) throw new Error(`Falha ${res.status} em ${rota}`);
    const corpo = await res.json();

    itens.push(...corpo.data);
    // Modelo A (pages) ou modelo B (meta.totalPages)
    totalPaginas = corpo.pages ?? corpo.meta?.totalPages ?? 1;
    page += 1;
  } while (page <= totalPaginas);

  return itens;
}

const pagas = await listarTudo('/v1/charges', { status: 'paid' });
console.log(`${pagas.length} cobranças pagas`);
```

> [!NOTE]
>
> A documentação não informa um valor máximo para `size`. Comece com valores moderados, como 20 ou 50, e ajuste conforme o tempo de resposta. Em clientes, `page` ou `size` menor que 1, ou não numérico, volta ao padrão.

## Ordenação

A maior parte das listagens devolve os registros do mais recente para o mais antigo, e essa ordem não pode ser trocada. O parâmetro `orderBy` só funciona em `GET /v1/submerchants`.

| Rota | Como fica a ordem |
| - | - |
| `GET /v1/charges` | Sempre da mais recente para a mais antiga. A rota ignora `orderBy` |
| `GET /v1/payout-requests` | Do mais recente para o mais antigo. Não envie `orderBy`: valores como `createdAt,-amount` geram erro `500` |
| `GET /v1/submerchants` | Sem `orderBy`, por data de criação decrescente. Com `orderBy`, use os nomes das colunas em snake\_case |
| Demais listagens | A ordem padrão de cada rota, descrita na referência |

Formato do `orderBy` em subcontas:

| Formato | Direção | Exemplo |
| - | - | - |
| `campo` | Crescente (mais antigo primeiro, A a Z) | `orderBy=created_at` |
| `-campo` | Decrescente (mais novo primeiro, Z a A) | `orderBy=-created_at` |
| Vários campos | Separados por vírgula, aplicados em ordem | `orderBy=legal_name,-created_at` |

> [!WARNING]
>
> Em subcontas, o `orderBy` com nomes em camelCase (como `legalName,-createdAt`) gera erro `500`. Use `legal_name,-created_at`.

```bash theme={null}
# Subcontas em ordem alfabética de razão social
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants?page=1&size=20&orderBy=legal_name,-created_at" \
  -u "$FINVIA_API_KEY:"
```

> [!TIP]
>
> **Para o desenvolvedor:** em cobranças, novos registros entram no início da listagem. Se você percorre muitas páginas enquanto novas cobranças chegam, um item pode aparecer em duas páginas seguidas. Deduplique pelo `id` ou restrinja a leitura a um período fechado com `createdAtStart` e `createdAtEnd`.

## Idempotência

Idempotência é a garantia de que repetir uma operação produz o mesmo efeito que executá-la uma vez. Ela importa sempre que a sua aplicação não sabe se uma requisição chegou ao destino, como num timeout ou numa queda de conexão.

> [!WARNING]
>
> O cabeçalho `Idempotency-Key` não existe hoje na API da Finvia. `POST /v1/charges` não lê nenhum cabeçalho de idempotência, então cada chamada cria uma cobrança nova. Reenviar a criação depois de um timeout pode gerar uma segunda cobrança para o mesmo pedido; no cartão, isso é cobrança em dobro.

### Regra geral

Repita uma requisição só depois de confirmar que a primeira não produziu efeito.

| Situação | É seguro repetir? | O que fazer |
| - | - | - |
| Resposta `4xx` (`400`, `401`, `403`, `404`, `422`) | Não, sem corrigir antes | A requisição foi rejeitada. Corrija o problema e só então envie de novo |
| Resposta `5xx` ou timeout em uma criação | Só depois de verificar | O resultado é incerto. Siga o procedimento abaixo |
| Timeout em uma consulta (`GET`) | Sim | Consultas não alteram nada |

### Procedimento depois de um timeout ao criar cobrança

Depois de um timeout, você não tem o `id` da cobrança. Consultar `GET /v1/charges/{id}` com o número do seu pedido não resolve: para um `id` que não existe, a API responde hoje `200` com corpo vazio, sem `404`. O caminho é este:

O desenho abaixo resume a decisão depois de uma criação de cobrança sem resposta clara. Os passos a seguir detalham cada etapa.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    A(["POST /v1/charges com<br/>metadata.orderId do pedido"]):::lojista
    Q1{"Que resposta<br/>chegou?"}:::decisao
    OK["Guarde o id<br/>junto com o pedido"]:::ok
    E4["Nada foi criado<br/>corrija e só então reenvie"]:::erro
    NO["Não reenvie o POST<br/>de imediato"]:::alerta
    Q2{"charge.created<br/>com o orderId?"}:::decisao
    BUS["Busque em GET /v1/charges<br/>mesma chave e mesmo dia<br/>searchFor: doc. ou e-mail"]:::lojista
    Q3{"Mesmo metadata<br/>e amount?"}:::decisao
    MID["Perto da meia-noite UTC?<br/>repita com o dia vizinho"]:::neutro
    ACH(["Associe o id ao pedido<br/>e siga o fluxo"]):::ok
    NOVO(["Não foi criada:<br/>é seguro criar de novo"]):::ok
    A --> Q1
    Q1 -->|"2xx"| OK
    Q1 -->|"400 · 401 · 403<br/>404 · 422"| E4
    Q1 -->|"5xx ou timeout"| NO
    NO --> Q2
    Q2 -->|"sim"| ACH
    Q2 -->|"não"| BUS
    BUS --> Q3
    Q3 -->|"sim"| ACH
    Q3 -->|"não"| MID
    MID -->|"ainda não achou"| NOVO
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

**1. Não reenvie o POST de imediato**

Se a primeira chamada chegou, um novo `POST /v1/charges` cria uma segunda cobrança.

**2. Mande sempre o identificador do pedido em metadata**

Em toda criação, envie o número do seu pedido em `metadata`, por exemplo `{"orderId": "PED-1001"}`. É ele que liga a cobrança ao pedido quando o `id` se perde.

**3. Recupere o id pelo webhook charge.created**

Cadastre um endpoint de webhook com o evento `charge.created`. Ele é emitido assim que a cobrança é gravada, antes da resposta do processador, e traz em `data` o `id` da cobrança e o `metadata` com as chaves exatamente como você enviou. É a forma mais confiável de recuperar o `id` depois de um timeout.

**4. Busque na listagem**

Se o webhook não chegou, procure a cobrança com a **mesma chave** usada na criação (a chave de teste lista só cobranças de teste, e a de produção só as de produção):

`GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=<termo>&size=50`

Use como termo o documento ou o e-mail do comprador. Depois compare `metadata` e `amount` do seu lado.

**5. Decida**

Encontrou a cobrança: associe o `id` ao pedido e siga o fluxo. Não encontrou: a cobrança não foi criada e é seguro tentar de novo.

Regras da busca em `GET /v1/charges`:

| Item | Regra |
| - | - |
| `createdAtStart` e `createdAtEnd` | Datas `AAAA-MM-DD`. Precisam vir juntas. O filtro pega o dia inteiro, no fuso do servidor (UTC) |
| `searchFor` | Busca parcial, sem diferenciar maiúsculas, em: nome, e-mail, documento e telefone do comprador; seis primeiros e quatro últimos dígitos do cartão; título do primeiro item; `pspRefId`; `endToEndId` do Pix; e nome da conta |
| Outros filtros | `status`, `currency`, `page` e `size` |
| Ordem | Sempre da mais recente para a mais antiga |
| Tentativas agrupadas | No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra só a principal do grupo; as demais aparecem em `groupCharges` no `GET /v1/charges/{id}` da principal |
| Chaves de `metadata` | Envie em camelCase (`orderId`) para ler a mesma chave na listagem e no webhook. Chaves em snake\_case voltam convertidas nas respostas de `GET`. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata) |

> [!TIP]
>
> **Para o desenvolvedor:** use um timeout de cliente generoso na criação, por exemplo 60 segundos. O cartão é processado de forma síncrona, e um timeout curto aumenta as chances de você não saber o resultado.

```javascript Node.js theme={null}
// localizar-cobranca.mjs (Node.js 18+, ESM, await no topo)
const API_URL = 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

async function localizarCobranca(pedido) {
  const dia = new Date(pedido.tentativaEm).toISOString().slice(0, 10); // AAAA-MM-DD em UTC
  const params = new URLSearchParams({
    createdAtStart: dia,
    createdAtEnd: dia,
    searchFor: pedido.email,
    page: '1',
    size: '50',
  });

  const res = await fetch(`${API_URL}/v1/charges?${params}`, {
    headers: { Authorization: `Basic ${credentials}` },
  });
  const { data } = await res.json();

  // A chave orderId foi enviada em camelCase e volta igual na listagem.
  return data.find((c) =>
    c.amount === pedido.amount &&
    c.metadata?.orderId === pedido.orderId
  );
}

const encontrada = await localizarCobranca({
  orderId: 'PED-1001',
  amount: 150,
  email: 'maria.souza@email.com',
  tentativaEm: Date.now(),
});
console.log(encontrada ? `Cobrança já existe: ${encontrada.id}` : 'Nenhuma cobrança encontrada: pode criar de novo');
```

> [!NOTE]
>
> Se a tentativa aconteceu perto da meia-noite em UTC, repita a busca com o dia anterior ou o seguinte, porque o filtro de datas usa o fuso do servidor.

### Proteções que a própria API oferece

Algumas operações já têm comportamento que evita duplicidade. Use-as a seu favor, sem dispensar a verificação acima.

| Operação | Comportamento |
| - | - |
| Estorno (`POST /v1/refunds`) | Cada cobrança aceita um único estorno. Um segundo pedido recebe `422` com `Já existe um reembolso para esta cobrança`. Uma cobrança que já não está `paid` (inclusive já estornada) recebe `404` com `Cobrança não encontrada` |
| Registro de domínio Apple Pay (`POST /v1/apple-pay/domains`) | Registrar de novo o mesmo hostname na mesma conta devolve o mesmo registro, também com `201` |
| Validação de cartão no trial grátis | Reenviar a mesma criação de assinatura (mesmo cliente, cartão e plano) em até 15 minutos reaproveita a validação aprovada e não cobra o R\$ 1,00 de novo. Uma validação do mesmo cartão em andamento responde `409` com `CARD_VALIDATION_IN_PROGRESS` |

> [!WARNING]
>
> O reaproveitamento da validação no trial grátis não impede a criação de uma segunda assinatura. Antes de repetir `POST /v1/subscriptions` depois de um timeout, liste as assinaturas do cliente com `GET /v1/subscriptions?customerId=...` e confira se a primeira foi criada.

## Idempotência no recebimento de webhooks

O mesmo evento pode chegar mais de uma vez. Isso acontece, por exemplo, quando a mesma URL está cadastrada como endpoint e como `postbackUrl`, ou em novas tentativas de entrega (veja a política de entrega em [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)). O seu receptor precisa reconhecer eventos repetidos. A chave de deduplicação de cada formato (envelope padrão, `charge.updated`, saque e conta) está na [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos), com exemplo completo em Node.js e PHP.

> [!TIP]
>
> **Para o desenvolvedor:** guarde as chaves processadas em armazenamento persistente (banco ou Redis), não em memória. Um `Set` em memória se perde a cada reinício do servidor.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| A listagem ignora o tamanho pedido | Uso de `limit` na query | Use `size` |
| A ordem não muda em cobranças | `GET /v1/charges` ignora `orderBy` | A ordem é sempre da mais recente para a mais antiga. Use `createdAtStart` e `createdAtEnd` para restringir o período |
| Erro `500` ao listar subcontas ou saques com `orderBy` | Nomes em camelCase em subcontas, ou `orderBy` em saques | Em subcontas, use snake\_case (`legal_name,-created_at`). Em saques, não envie `orderBy` |
| Filtro sem efeito | Parâmetro com nome que a rota não conhece (ex.: `createdAt` em saques) | A API ignora parâmetros desconhecidos sem erro. Confira o nome na referência da rota |
| O código quebra ao ler `pages` em planos ou assinaturas | Essas rotas usam o modelo B, com `meta.totalPages` | Leia os dois modelos |
| O código quebra ao ler `data` em cartões ou carteiras | `GET /v1/cards` e `GET /v1/wallets` devolvem array direto | Trate a resposta como lista |
| `metadata.order_id` não encontrado na listagem | Chaves enviadas em snake\_case voltam em camelCase nas respostas de `GET` | Leia `metadata.orderId` ou envie as chaves em camelCase. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata) |
| Cobrança duplicada para o mesmo pedido | Reenvio automático de `POST /v1/charges` depois de timeout | Siga o procedimento de timeout desta página |
| Pedido liberado duas vezes | Webhook repetido processado de novo | Aplique a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos) |

## Perguntas frequentes

> [accordion] Posso buscar uma cobrança pelo número do meu pedido?
>
> Não diretamente. `GET /v1/charges` não filtra por `metadata`. Guarde o `id` devolvido na criação junto com o pedido. Para recuperar uma cobrança sem o `id`, use o webhook `charge.created` ou a busca por período e `searchFor`, descritos no procedimento de timeout.

> [accordion] Qual é o tamanho padrão da página?
>
> `10`, em todas as listagens paginadas (cobranças, clientes, planos, assinaturas, subcontas, saques e endpoints de webhook).

> [accordion] Todas as listagens aceitam orderBy?
>
> Não. Só `GET /v1/submerchants` aceita `orderBy`, com nomes em snake\_case. Em cobranças ele é ignorado, e em saques gera erro. As demais listagens têm ordem fixa.

> [accordion] Existe Idempotency-Key?
>
> Não existe hoje. Use o identificador do pedido em `metadata` e o procedimento de timeout desta página.

> [accordion] Se o webhook chegar duas vezes, a Finvia considera erro?
>
> Não. Reentregas fazem parte do funcionamento. Responda com status `2xx` também para o evento repetido e apenas não o processe de novo.

## Como testar

* Liste cobranças com `page` e `size` e confira a paginação (base do cenário **CHG-06** do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)).
* Use `POST /v1/charges/{id}/resend-webhook` duas vezes com o mesmo status e confirme que o seu receptor responde `2xx` nas duas vezes e não repete o efeito, como liberar o pedido (cenários **CHG-08** e **CHG-09**). Cada simulação gera um evento com `id` novo, então quem segura a repetição é a checagem do pedido.
* Simule um timeout no seu código (por exemplo, abortando a requisição antes da resposta) e confira se a rotina encontra a cobrança pelo `charge.created` ou pela listagem antes de criar outra.

## Veja também

> [card] [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md)
>
> Quando repetir e quando corrigir uma requisição.

> [card] [Listar cobranças](https://docs.fastpaybrasil.com/referencia/cobrancas/listar.md)
>
> Referência de `GET /v1/charges`.

> [card] [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Entrega e segurança das notificações.

> [card] [Catálogo de eventos](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md)
>
> Todos os eventos e seus envelopes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.