Paginação

Endpoints de listagem devolvem os registros em blocos. Você navega com o parâmetro page, e a maioria dos endpoints aceita per para escolher o tamanho do bloco.

curl --request GET \
  --url 'https://app.azchat.digital/api/v1/accounts/1/products?page=2&per=50' \
  --header 'api_access_token: SUA_CHAVE_AQUI'

Parâmetro	Padrão	Descrição
page	1	Página desejada, começando em 1.
per	15	Registros por página.

O teto é 200 registros por página: valores acima disso são silenciosamente reduzidos para 200, sem erro.

:::caution Nem todo endpoint aceita per per está disponível nos endpoints de CRM (produtos, serviços, organizações, entre outros). Vários endpoints mais antigos — contatos e conversas, por exemplo — têm o tamanho de página fixo em 15 e ignoram o parâmetro. Confira o endpoint específico na Referência. :::

Descobrindo o total

Endpoints paginados costumam devolver a contagem total junto do payload, o que permite calcular quantas páginas existem:

{
  "payload": [ ... ],
  "meta": {
    "count": 342,
    "current_page": 2
  }
}

O formato do meta varia entre endpoints — alguns usam count, outros total_count, e alguns não retornam contagem. Trate a ausência de resultados como fim da lista.

Percorrendo tudo

O padrão seguro é pedir páginas até vir uma vazia:

async function todosOsProdutos(host, accountId, token) {
  const registros = [];
  let page = 1;

  for (;;) {
    const resposta = await fetch(
      `${host}/api/v1/accounts/${accountId}/products?page=${page}&per=200`,
      { headers: { api_access_token: token } }
    );
    const { payload } = await resposta.json();

    if (!payload?.length) return registros;

    registros.push(...payload);
    page += 1;
  }
}

:::tip Cuidado com o rate limit Percorrer muitas páginas em sequência é a forma mais comum de esbarrar nos limites de requisição. Use per=200 para reduzir o número de chamadas, e trate o 429. :::

Listas que mudam durante a leitura

A paginação é por offset: se registros forem criados ou removidos enquanto você percorre as páginas, um item pode aparecer duas vezes ou ser pulado. Para sincronizações grandes, prefira filtrar por um intervalo de datas estável, ou deduplicar por id no final.