Paginação

Endpoints que retornam listas (GET /contacts, GET /deals, etc.) suportam paginação por offset via query params page e pageSize.

Parâmetros

Param	Tipo	Default	Limite
page	número	1	sem limite (mas latência cresce com offset alto)
pageSize	número	50	100

Exemplo:

curl "https://app.indutivacrm.com.br/api/v1/contacts?page=2&pageSize=100" \
  -H "X-API-Key: crm_live_..."

Shape da resposta

{
  "data": [
    { "id": "...", "firstName": "...", ... },
    ...
  ],
  "pagination": {
    "page": 2,
    "pageSize": 100,
    "total": 4823,
    "totalPages": 49,
    "hasNext": true,
    "hasPrev": true
  }
}

• total é o número total de registros que satisfazem os filtros (não da página atual)
• totalPages = Math.ceil(total / pageSize)
• hasNext / hasPrev simplificam a lógica de UI

Listagens sem paginação são DEPRECATED

Alguns endpoints legados retornam o array direto (sem o wrapper { data, pagination }) por compatibilidade. Esses serão migrados pra paginação completa em uma versão futura — vai ser anunciado com 90 dias de antecedência. Se você está construindo integração nova, sempre use page/pageSize mesmo quando o retorno atual é só array.

Performance

Offset alto fica lento. Pra base de 100k contatos, page=1000&pageSize=100 faz o banco varrer 100k registros pra pular 100k. Recomendações:

1. Filtre primeiro — use filtros de busca pra reduzir o conjunto antes de paginar
2. Ordene por campo indexado — sortKey=createdAt&sortOrder=desc é rápido; sortKey=campoCustom pode ser lento
3. Pra sync incremental, use timestamp em vez de offset:

   curl "https://app.indutivacrm.com.br/api/v1/contacts?updatedAfter=2026-05-22T00:00:00Z"

   updatedAfter aceita ISO 8601. Retorna só contatos modificados depois desse momento. Muito mais eficiente que percorrer todas as páginas pra detectar mudanças.

Iteração completa em código

async function* allContacts(apiKey) {
  let page = 1
  while (true) {
    const res = await fetch(
      `https://app.indutivacrm.com.br/api/v1/contacts?page=${page}&pageSize=100`,
      { headers: { 'X-API-Key': apiKey } },
    )
    const { data, pagination } = await res.json()
    for (const c of data) yield c
    if (!pagination.hasNext) break
    page++
  }
}

// Uso:
for await (const contact of allContacts(process.env.CRM_API_KEY)) {
  console.log(contact.email)
}

Combine com backoff em 429 — uma base grande vai bater rate limit se você não respeitar Retry-After.