Paginação
Como ler listas por partes, entender o bloco meta e saber quando parar.
Toda listagem da API devolve os dados em páginas. Se você ler só a primeira, vai perder registros — e não vai perceber.
A regra que evita dados faltando
Continue enquanto links.next não for null. Quando next é null, você chegou ao fim.
O laço termina quando next é nulo — não quando a página vem vazia.
Estrutura da resposta
JSONjson
{
"data": [
{ "id": "1", "name": "Minha loja" }
],
"links": {
"first": "https://api.hubiss.com.br/v1/stores?page=1",
"last": "https://api.hubiss.com.br/v1/stores?page=3",
"prev": null,
"next": "https://api.hubiss.com.br/v1/stores?page=2"
},
"meta": {
"current_page": 1,
"per_page": 20,
"last_page": 3,
"from": 1,
"to": 20,
"total": 42
}
}
| Campo | Serve para |
|---|---|
data |
Os registros desta página |
links.next |
Próxima página pronta para chamar (null = fim) |
meta.current_page |
Página atual |
meta.last_page |
Total de páginas |
meta.total |
Total de registros |
meta.per_page |
Registros por página aplicados |
Parâmetros
| Parâmetro | O que faz | Exemplo |
|---|---|---|
per_page |
Registros por página (padrão 20, máximo 20) | 20 |
current_page |
Página desejada | 2 |
page |
Alias de current_page em vários endpoints |
2 |
Exemplo em linha de comandobash
curl --request GET \
--url 'https://api.hubiss.com.br/v1/orders?per_page=20¤t_page=2' \
--header 'Authorization: Bearer SEU_TOKEN'
Exemplo completo de laço
Exemplo em PHPphp
$url = 'https://api.hubiss.com.br/v1/orders?per_page=20';
while ($url !== null) {
$resposta = Http::withToken($token)->acceptJson()->get($url);
if ($resposta->status() === 429) {
sleep(2);
continue;
}
foreach ($resposta->json('data') as $pedido) {
// processa o pedido
}
$url = $resposta->json('links.next');
}
Por que parar por next e não por current_page < last_page? Por usar o link que a API devolve, você não depende de calcular página manualmente nem de o total mudar durante a leitura.
Cuidado com dados mudando durante a leitura
Se registros são criados enquanto você pagina, a ordem pode deslocar. Para conciliação, prefira filtrar por data e reprocessar o período.
Próximo passo
Veja como tratar cada falha em Erros.