Paginação

As listas da API são divididas em páginas, para que as respostas sejam rápidas e leves. Os endpoints paginados hoje são Listar viagens e Listar depoimentos. Os demais endpoints retornam um único objeto.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
page	inteiro, mínimo 1	1	O número da página.
per_page	inteiro, de 1 a 50	15	Quantos itens vêm em cada página.

Exemplo — a segunda página, com 10 viagens por página:

curl "https://minhaagencia.avoei.com.br/api/v1/travels?page=2&per_page=10" \
  -H "Authorization: Bearer SEU_TOKEN"

Valores fora dos limites (como per_page=100 ou page=0) resultam em erro 422; a API não os ajusta em silêncio. Veja Erros.

A resposta

Os itens da página ficam em data.data. Os demais campos de data descrevem a paginação:

{
  "success": true,
  "message": "Travels retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [],
    "first_page_url": "https://minhaagencia.avoei.com.br/api/v1/travels?page=1",
    "from": 1,
    "last_page": 3,
    "last_page_url": "https://minhaagencia.avoei.com.br/api/v1/travels?page=3",
    "links": [
      { "url": null, "label": "« Anterior", "page": null, "active": false },
      { "url": "https://minhaagencia.avoei.com.br/api/v1/travels?page=1", "label": "1", "page": 1, "active": true },
      { "url": "https://minhaagencia.avoei.com.br/api/v1/travels?page=2", "label": "Próximo »", "page": 2, "active": false }
    ],
    "next_page_url": "https://minhaagencia.avoei.com.br/api/v1/travels?page=2",
    "path": "https://minhaagencia.avoei.com.br/api/v1/travels",
    "per_page": 15,
    "prev_page_url": null,
    "to": 15,
    "total": 42
  },
  "errors": [],
  "status": 200
}

Campo	Descrição
data.data	Os itens da página atual (aqui, resumida como []).
current_page	O número da página atual.
per_page	Quantos itens cabem em uma página.
total	O total de itens que correspondem à busca, somando todas as páginas.
last_page	O número da última página.
from / to	A posição do primeiro e do último item da página. São null em uma página vazia.
next_page_url / prev_page_url	O endereço da página seguinte e da anterior, ou null quando não existem.
first_page_url / last_page_url	O endereço da primeira e da última página.
path	O endereço da lista, sem os parâmetros.
links	Itens prontos para montar uma barra de paginação. Para uma integração, next_page_url costuma bastar.

Os endereços de página (next_page_url e os demais) mantêm os filtros e a ordenação que você enviou, como search e sort. Você pode segui-los sem remontar a consulta.

Página vazia

Uma lista sem resultados, ou uma página além da última, retorna 200 com data.data vazio:

{
  "success": true,
  "message": "Travels retrieved successfully",
  "data": { "current_page": 9, "data": [], "from": null, "to": null, "total": 3 },
  "errors": [],
  "status": 200
}

Percorrendo todas as páginas

Siga next_page_url até que ele seja null. Em cada chamada, use o cabeçalho Authorization, e respeite o limite de requisições.

JavaScript

const headers = {
  Authorization: `Bearer ${process.env.AVOEI_TOKEN}`,
  Accept: 'application/json',
};

let url = 'https://minhaagencia.avoei.com.br/api/v1/travels?per_page=50';
const travels = [];

while (url) {
  const response = await fetch(url, { headers });
  const { data } = await response.json();

  travels.push(...data.data);
  url = data.next_page_url;
}

PHP

$url = 'https://minhaagencia.avoei.com.br/api/v1/travels?per_page=50';
$travels = [];

while ($url) {
    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('AVOEI_TOKEN'),
            'Accept: application/json',
        ],
    ]);

    $page = json_decode(curl_exec($curl), true)['data'];
    curl_close($curl);

    array_push($travels, ...$page['data']);
    $url = $page['next_page_url'];
}

Python

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['AVOEI_TOKEN']}",
    "Accept": "application/json",
}

url = "https://minhaagencia.avoei.com.br/api/v1/travels?per_page=50"
travels = []

while url:
    page = requests.get(url, headers=headers).json()["data"]
    travels.extend(page["data"])
    url = page["next_page_url"]

Dicas

• Use per_page=50 (o máximo) quando precisar ler a lista inteira: são menos requisições.
• Se você exibe a lista em uma tela, use um valor menor e busque as páginas conforme a pessoa navega.
• Os dados podem mudar entre uma requisição e outra. Ao percorrer várias páginas, a lista de uma agência que cadastra viagens no mesmo instante pode mudar de posição. Para leituras completas, prefira uma ordenação estável, como a padrão. Veja Ordenação.