PayZuDocs
Boas práticas

Paginação

Explica como percorrer listas longas com page e limit e quando trocar a listagem pelo relatório em CSV.

Endpoints que listam recursos usam paginação por page + limit, mas o envelope da resposta muda de rota para rota. Nenhuma das três devolve hasNextPage no topo da resposta.

EndpointEnvelope da respostaCondição de parada
GET /user/transactions{ total, pages, transactions }page >= pages
GET /user/callbacks{ pagination: { page, limit, hasNextPage }, callbacks }pagination.hasNextPage é falso
GET /user/infractions{ pagination: { page, limit, totalItems, totalPages }, infractions }page >= pagination.totalPages

Padrão de loop em /user/transactions

PAGE=1
LIMIT=100

while : ; do
  RESP=$(curl -s "https://api.payzu.processamento.com/v1/user/transactions?dateFrom=2025-11-01&page=$PAGE&limit=$LIMIT" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json")

  echo "$RESP" | jq -c '.transactions[]'

  PAGES=$(echo "$RESP" | jq -r '.pages')
  [ "$PAGE" -ge "$PAGES" ] && break
  PAGE=$((PAGE+1))
done
async function* iterateTransactions(filters: Record<string, string>) {
  let page = 1;
  const limit = 100;
  while (true) {
    const params = new URLSearchParams({ ...filters, page: String(page), limit: String(limit) });
    const res = await fetch(`https://api.payzu.processamento.com/v1/user/transactions?${params}`, {
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });
    const { pages, transactions } = await res.json();
    for (const tx of transactions) yield tx;
    if (page >= pages) return;
    page++;
  }
}

for await (const tx of iterateTransactions({ dateFrom: '2025-11-01' })) {
  await process(tx);
}

Em /user/callbacks, itere sobre callbacks e pare quando pagination.hasNextPage for false. Em /user/infractions, itere sobre infractions e pare quando page alcançar pagination.totalPages.

Filtros disponíveis

FiltroQuando usar
dateFrom / dateToJanela temporal (ISO 8601).
clientReferenceEncontra a transação correspondente ao seu pedido.
virtualAccountFiltro por tenant (multi-loja).
statusCSV: COMPLETED,PENDING. Aceita múltiplos.
typeCSV: DEPOSIT,WITHDRAW,COMMISSION.
endToEndIdIdentificador único Bacen.
document, nameFiltros por pagador. document apenas dígitos (11 ou 14).
amountFiltro por valor exato.

Limite e tamanho da página

Endpointlimit máximoDefault
GET /user/transactions100010
GET /user/callbacks10010
GET /user/infractions10010

Acima do máximo da rota, a requisição é recusada com 400 e errorCode PZV001. Páginas grandes demais degradam latência. Se precisa de período longo (mês, ano) ou exportar tudo, prefira o relatório assíncrono.

Quando usar relatório assíncrono em vez de paginar

CenárioRecomendação
Listagem em tela (dashboard)GET /user/transactions com paginação.
Verificação pontualGET /user/transactions?clientReference=order-1234.
Conciliação diária (< 10k transações)GET /user/transactions paginado.
Conciliação mensal/anualPOST /user/report (CSV assíncrono).
BI/Data WarehousePOST /user/report rodado diariamente, ingestão por ETL.

O relatório assíncrono gera arquivo CSV com URL assinada de download. Não tem limite de linhas e roda em background. Veja o tutorial de Conciliação.

Armadilhas comuns

ArmadilhaSintoma
Pegar tudo sem dateFrom em conta com volumeResposta lenta, possível timeout
limit acima do máximo da rota (1000 em /user/callbacks)Erro 400 com errorCode PZV001
Ler hasNextPage no topo da respostaValor ausente, o loop para na primeira página
Repetir a mesma condição de parada nas três rotasPerda silenciosa de páginas
Página fixa (page=1 sempre)Só lê a primeira página, perde o resto
Passar document com pontuação (123.456.789-00)Erro 400, regex aceita só dígitos

Nesta página