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.
| Endpoint | Envelope da resposta | Condiçã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))
doneasync 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
| Filtro | Quando usar |
|---|---|
dateFrom / dateTo | Janela temporal (ISO 8601). |
clientReference | Encontra a transação correspondente ao seu pedido. |
virtualAccount | Filtro por tenant (multi-loja). |
status | CSV: COMPLETED,PENDING. Aceita múltiplos. |
type | CSV: DEPOSIT,WITHDRAW,COMMISSION. |
endToEndId | Identificador único Bacen. |
document, name | Filtros por pagador. document apenas dígitos (11 ou 14). |
amount | Filtro por valor exato. |
Limite e tamanho da página
| Endpoint | limit máximo | Default |
|---|---|---|
GET /user/transactions | 1000 | 10 |
GET /user/callbacks | 100 | 10 |
GET /user/infractions | 100 | 10 |
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ário | Recomendação |
|---|---|
| Listagem em tela (dashboard) | GET /user/transactions com paginação. |
| Verificação pontual | GET /user/transactions?clientReference=order-1234. |
| Conciliação diária (< 10k transações) | GET /user/transactions paginado. |
| Conciliação mensal/anual | POST /user/report (CSV assíncrono). |
| BI/Data Warehouse | POST /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
| Armadilha | Sintoma |
|---|---|
Pegar tudo sem dateFrom em conta com volume | Resposta 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 resposta | Valor ausente, o loop para na primeira página |
| Repetir a mesma condição de parada nas três rotas | Perda 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 |