Paginação e filtros

Parâmetros page e per_page

Toda listagem aceita dois parâmetros na query string:

per_page acima de 100 responde 400 invalid_request, com message vazia. Uma página depois da última responde 200 com data vazio.

Formato da resposta

Toda listagem responde com data e meta:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "identifier": "PPO9876543210",
      "status": "PAID",
      "total_amount": 97
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 58,
    "total_pages": 3
  }
}

Resposta resumida. Os campos de cada item estão na Referência da API.

Ordem dos resultados

Todas as listagens vêm da mais nova para a mais antiga, pela data de criação (created_at). Não há parâmetro para mudar a ordem.

Filtros de cada listagem

Cada listagem aceita só os filtros da tabela, além de page e per_page. Um filtro que a rota não aplica, ou um valor fora da lista, responde 400 invalid_request.

Os valores aceitos em status, payment_method e type estão em cada rota da Referência da API. O status de GET /sales usa as situações da venda, e o de GET /subscriptions, as da assinatura: um não vale no outro.

Você pode combinar filtros na mesma chamada. A listagem traz só os itens que atendem a todos eles.

Como cada tipo de filtro compara

Detalhes que evitam surpresas:

• GET /sales?product_id= traz as vendas que têm o produto em algum item. A venda vem com todos os itens, inclusive os de outros produtos.
• GET /products não lista planos. Para planos, use GET /plans. Por isso type aceita só DIGITAL, PHYSICAL e PACKAGE.
• Documento com outra quantidade de dígitos, ou com letras, responde 400 invalid_request.
• Na busca por texto, % e _ valem como caracteres comuns, não como curinga.

Exemplo: vendas pagas de um cliente, buscando pelo CPF.

curl "https://api.pagpolar.com/v1/sales?status=PAID&customer_document=123.456.789-09" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"

Percorra todas as páginas sem perder registros

Novas vendas entram no topo da lista enquanto você pagina. Isso empurra os itens para a página seguinte, e um mesmo item pode aparecer duas vezes.

Para evitar isso:

1. Fixe created_to com a data e hora em que você começou a busca.
2. Use per_page=100 para fazer menos chamadas.
3. Guarde os itens pelo id. Se um id repetir, ignore.

Os exemplos abaixo usam um token de acesso. Veja Autenticação.

curl "https://api.pagpolar.com/v1/sales?page=1&per_page=100&created_from=2026-09-01T00:00:00-03:00&created_to=2026-09-15T23:59:59-03:00" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>"

const apiUrl = 'https://api.pagpolar.com/v1';
const accessToken = '<SEU_TOKEN_DE_ACESSO>';
const createdTo = new Date().toISOString();
const salesById = new Map();

let page = 1;
let totalPages = 1;

do {
  const query = new URLSearchParams({
    page: String(page),
    per_page: '100',
    created_from: '2026-09-01T00:00:00-03:00',
    created_to: createdTo,
  });

  const response = await fetch(`${apiUrl}/sales?${query}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });

  if (!response.ok) {
    throw new Error(`Erro ${response.status}: ${await response.text()}`);
  }

  const body = await response.json();

  for (const sale of body.data) {
    salesById.set(sale.id, sale);
  }

  totalPages = body.meta.total_pages;
  page += 1;
} while (page <= totalPages);

console.log(`${salesById.size} vendas encontradas`);

Próximos passos