Paginação

Visão Geral

A API Selectwin utiliza um sistema de paginação consistente em todos os endpoints que retornam listas de recursos. Este mecanismo permite controlar a quantidade de dados retornados em cada requisição, facilitando o gerenciamento de conjuntos grandes de informações e melhorando o desempenho das aplicações.

Este documento detalha como funciona a paginação na API, como utilizar os parâmetros de controle e como interpretar os metadados de paginação nas respostas.

Estrutura da Resposta Paginada

Todas as respostas paginadas da API Selectwin seguem uma estrutura padrão no nível raiz (o corpo da resposta HTTP é o objeto paginado diretamente), como mostrado abaixo:

{
  "offset": 0,
  "limit": 25,
  "total": 1,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 }
  },
  "data": [
    {
      "id": "wall_01hqzvabc",
      "name": "Nubank",
      "bankName": "260 - Nu Pagamentos",
      "bankCode": "260",
      "holderName": "João Santos",
      "routingNumber": "0001",
      "accountNumber": "11111111-5",
      "primary": true,
      "enabled": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "GET",
      "description": "List all wallets."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "POST",
      "description": "Create a new wallet."
    }
  }
}

Nota: Os itens dentro de data são projeções leves específicas do recurso (nem todos os campos do objeto completo — por exemplo, a lista de carteiras não inclui accountType nos itens, apenas o objeto individual via GET /v1/wallets/{walletId}). O objeto merchant e os _links HATEOAS estão presentes na maioria das respostas paginadas de listagem padrão. Endpoints list-all retornam um array direto (sem envelope de paginação, merchant ou _links), e analytics/risk-health retornam objetos customizados próprios.

Campos da Resposta Paginada

Parâmetros de Paginação

Ao fazer requisições para endpoints que suportam paginação, você pode controlar os resultados usando os seguintes parâmetros de consulta:

Combinando Paginação com Filtros

Você pode combinar parâmetros de paginação com filtros específicos do recurso:

// Exemplo: Paginação com filtros
const axios = require('axios');

async function listFilteredTransactions() {
  const response = await axios({
    method: 'get',
    url: 'https://api.selectwin.io/v1/transactions',
    headers: {
      'SelectKey': 'sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
    },
    params: {
      offset: 0,
      limit: 20,
      sort: 'descending',
      ... Outros parâmetros
    }
  });
  
  console.log(`Encontradas ${response.data.total} transações com sucesso em janeiro de 2023`);
  console.log(`Exibindo ${response.data.data.length} transações na página atual`);
  
  return response.data;
}

Perguntas Frequentes

Os resultados são sempre retornados na mesma ordem?

A ordem padrão varia de acordo com o recurso, mas geralmente é por sort data de criação decrescente. Para garantir consistência na paginação, use o parâmetro de ordenação específico do recurso.

Posso contar com o número total de registros (total) para calcular manualmente os offsets?

Sim, o valor de total fornecido na resposta é preciso e pode ser usado para cálculos manuais de paginação. Porém, recomendamos usar os valores page.offset.* fornecidos na resposta para navegação.

A paginação afeta os limites de rate da API?

Sim, cada requisição paginada conta para o seu limite de rate. Ao implementar iteração por todas as páginas, considere adicionar intervalos entre as requisições para evitar atingir limites de rate.