Paginação
limit, offset e total — e como percorrer uma lista sem perder linhas.
Todos os endpoints de listagem paginam igual, com limit e offset na query string.
curl "https://api.trama.so/v1/customers?limit=50&offset=100" \
-H "Authorization: Bearer $TRAMA_API_KEY"| Parâmetro | Padrão | Máximo |
|---|---|---|
limit | 25 | 100 |
offset | 0 | — |
Pedir mais de 100 não é cortado em silêncio: dá um 400 com VALIDATION_FAILED. É de propósito — uma requisição que devolve menos linhas do que você pediu sem avisar é a forma como uma integração perde dados sem ninguém perceber.
O formato da resposta
{
"data": [ /* … */ ],
"pagination": { "limit": 50, "offset": 100, "total": 1284 }
}total é a contagem dos filtros que você enviou, não da organização inteira. É o que permite saber se há outra página para pedir, sem precisar pedi-la e receber um array vazio.
async function buscarTudo(path) {
const items = [];
let offset = 0;
for (;;) {
const res = await fetch(`https://api.trama.so${path}?limit=100&offset=${offset}`, {
headers: { Authorization: `Bearer ${process.env.TRAMA_API_KEY}` },
});
const { data, pagination } = await res.json();
items.push(...data);
offset += pagination.limit;
if (offset >= pagination.total) return items;
}
}Os offsets se movem embaixo dos seus pés. Uma lista é uma consulta viva, não uma foto: se enquanto você a percorre linhas são criadas ou reordenadas — e no catálogo, editar um produto o reordena — uma linha pode pular de página e você vai vê-la duas vezes ou nenhuma.
Se você está sincronizando em vez de olhando, não conte com ter percorrido todas as páginas de forma limpa. Indexe pelo id do recurso e refaça a varredura periodicamente, em vez de assumir que uma passada ficou completa.
Não há paginação por cursor, e é uma decisão e não um esquecimento: um cursor estável precisa de uma ordem que hoje não conseguimos prometer em todas as listas. Se o seu catálogo ou a sua base de clientes crescer até isso doer, conte para a gente: é do tipo de coisa que se versiona, não que se remenda.