Paginação

Como percorrer listagens com page/pageSize, hasMore e total. Padrões para evitar timeouts e race conditions.

Todos os endpoints de listagem (GET /people, GET /deals, ...) usam paginação offset-based com os parâmetros page e pageSize. Esse guia cobre os padrões e armadilhas comuns.

V1 sem filtros

A v1 atual aceita apenas page e pageSize nas listagens — filtros por campo (ex.: por owner, por estágio, por e-mail) ainda não estão disponíveis na API pública. Se você precisa filtrar, pagine tudo e filtre no cliente, ou use webhooks para reagir a mudanças incrementais.

Parâmetros

Parâmetro	Tipo	Padrão	Máximo	Descrição
`page`	number	`1`	—	Número da página (1-indexado).
`pageSize`	number	`25`	`100`	Itens por página. Acima de 100 → erro 400.

Resposta

Toda listagem retorna o mesmo envelope:

Text

{
  "data": [ /* array de objetos */ ],
  "page": 1,
  "pageSize": 25,
  "total": 1248,
  "hasMore": true
}

data — itens da página atual.
page — eco do parâmetro enviado.
pageSize — eco do parâmetro enviado.
total — quantidade total de itens no workspace.
hasMore — true se existe pelo menos mais uma página.

Iterando todas as páginas

Em JavaScript:

Text

async function* fetchAllPeople(token: string) {
  let page = 1;
  while (true) {
    const res = await fetch(
      `https://api.mixycrm.com.br/api/v1/people?page=${page}&pageSize=100`,
      { headers: { Authorization: `Bearer ${token}` } },
    );
    const json = await res.json();
    yield* json.data;
    if (!json.hasMore) break;
    page++;
  }
}

for await (const person of fetchAllPeople(token)) {
  console.log(person.fullName);
}

Em Python:

Text

def fetch_all_people(token: str):
    page = 1
    while True:
        res = requests.get(
            "https://api.mixycrm.com.br/api/v1/people",
            params={"page": page, "pageSize": 100},
            headers={"Authorization": f"Bearer {token}"},
        )
        body = res.json()
        yield from body["data"]
        if not body["hasMore"]:
            break
        page += 1

Tamanho de página recomendado

pageSize=25 (padrão): bom pra UIs e listagens interativas.
pageSize=100 (máximo): bom pra ETL, exportações, sync inicial. Usa menos requests, mas paga mais rate limit por chamada (cada 100 itens conta como uma chamada).

Race conditions

Paginação offset-based não é estável sob escritas concorrentes. Se alguém criar uma pessoa nova entre page=1 e page=2, você pode pular ou duplicar itens.

Como mitigar enquanto não há filtro temporal

A v1 ainda não expõe filtro updatedSince na API pública. Enquanto isso:

Sync via webhooks: depois do sync inicial via paginação, assine person.created / person.updated (etc.) e aplique deltas em tempo real. Seu cache local fica consistente sem repollar tudo.
Pagine em janelas curtas (ex.: poucas chamadas seguidas, fora de horário de pico) e tolere uma pequena janela de inconsistência.

Ordenação

A ordenação atual é fixa: createdAt DESC (mais recentes primeiro). Parâmetro sort ainda não está disponível na v1 pública.