Paginação e filtros

Todas as listagens de /v1 usam o mesmo formato.

Parâmetros

Parâmetro	Padrão	Descrição
`page`	`1`	Página, começando em 1
`limit`	`20`	Itens por página, máximo 100
`order`	`desc`	`asc` ou `desc` (nas rotas que aceitam ordenação)
`sort`	varia	Campo de ordenação, onde existir (ex.: tíquetes e contatos)

Valores fora da faixa são corrigidos sem erro: limit=500 vira 100; limit=abc vira o padrão.

Resposta

{
  "items": [ … ],
  "total": 1342,
  "page": 1,
  "limit": 20,
  "pages": 68
}

total é o total de itens com os filtros aplicados.
pages é no mínimo 1, mesmo sem resultados.
Exceção: GET /v1/ticket-status devolve um array simples, sem paginação.

Percorrer todas as páginas

async function todos(rota, filtros = {}) {
  const itens = [];
  for (let page = 1; ; page++) {
    const qs = new URLSearchParams({ ...filtros, page, limit: 100 });
    const r = await fetch(`https://api.picchat.com.br${rota}?${qs}`, {
      headers: { Authorization: `Bearer ${process.env.PICCHAT_TOKEN}` },
    });
    const { items, pages } = await r.json();
    itens.push(...items);
    if (page >= pages) return itens;
  }
}

const abertos = await todos("/v1/tickets", { open: "true" });

Filtros de data

from / to filtram pela data de criação; updated_from / updated_to (em tíquetes) pela última atualização.
Use ISO 8601 com fuso: 2026-11-01T00:00:00-03:00. Só a data (2026-11-01) é lida como meia-noite UTC — 21h do dia anterior no horário de Brasília.
Data inválida responde 400 com errorCode API_V1_DATE_PARAM_INVALID.

Outros filtros

IDs (channel_id, contact_id, tag_id…) precisam ser UUIDs válidos.
Enums (status, type…) aceitam só os valores listados em cada endpoint.
Booleanos usam true / false.
Busca (search) procura sem diferenciar maiúsculas.
Propriedades de contato: property.<internal_name>=valor em GET /v1/contacts.

Hoje um ID fora do formato UUID ou um valor de enum desconhecido respondem 500 em vez de 400. Valide os valores antes de enviar.