Paginação e Filtros

Os endpoints que retornam listas de recursos (como cards, contatos, tarefas e produtos) suportam parâmetros unificados de paginação, ordenação e filtros.

Paginação

A API utiliza paginação baseada em páginas (page) por padrão. Os parâmetros aceitos são:

pagination[page]: O número da página solicitada (padrão: 1).
pagination[pageSize]: A quantidade de registros retornados por página (padrão: 25, máximo: 100).

# Solicitar página 2 com 50 itens por página
curl -G "https://api.perpetuus.com.br/api/boards/BOARD_ID/cards" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "x-tenant-id: acme" \
  --data-urlencode "pagination[page]=2" \
  --data-urlencode "pagination[pageSize]=50"

Exemplo em JavaScript: Paginação em Loop

Para integrações do tipo ETL (sincronização de dados de contatos ou cards para armazéns locais), utilize o padrão em loop abaixo para consumir todas as páginas disponíveis de forma segura:

async function fetchAllContacts(token, tenant) {
  const pageSize = 100;
  let page = 1;
  let allContacts = [];

  while (true) {
    const params = new URLSearchParams({
      'pagination[page]': String(page),
      'pagination[pageSize]': String(pageSize),
      'sort': 'createdAt:asc'
    });

    const response = await fetch(`https://api.perpetuus.com.br/api/contacts?${params}`, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'x-tenant-id': tenant
      }
    });

    if (!response.ok) {
      throw new Error(`Erro HTTP: ${response.status}`);
    }

    const payload = await response.json();
    const data = payload.data || [];
    allContacts = allContacts.concat(data);

    const pagination = payload.meta?.pagination;
    if (!pagination || allContacts.length >= pagination.total) {
      break;
    }
    
    page++;
  }

  return allContacts;
}

Filtros

A filtragem utiliza a notação de query do Strapi (parâmetros de array aninhados). Os principais operadores suportados são:

Operador	Significado	Exemplo de Query Parameter
`$eq`	Igual a	`filters[email][$eq]=lead@cliente.com`
`$ne`	Diferente de	`filters[active][$ne]=false`
`$contains`	Contém (case-sensitive)	`filters[name][$contains]=Silva`
`$containsi`	Contém (case-insensitive)	`filters[title][$containsi]=urgente`
`$in`	Está na lista (array)	`filters[currentPhase][documentId][$in][0]=fase1&filters[currentPhase][documentId][$in][1]=fase2`
`$gte`	Maior ou igual a	`filters[createdAt][$gte]=2026-07-01T00:00:00Z`
`$lte`	Menor ou igual a	`filters[createdAt][$lte]=2026-07-09T23:59:59Z`

Exemplo Prático de Filtro

Para listar cards com o título contendo "ACME" e que estejam na fase com ID phase_draft_123:

curl -G "https://api.perpetuus.com.br/api/boards/BOARD_ID/cards" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "x-tenant-id: acme" \
  --data-urlencode "filters[title][$containsi]=ACME" \
  --data-urlencode "filters[currentPhase][documentId]=$eq:phase_draft_123"

Ordenação (Sort)

Ordene os resultados informando o atributo e a direção (asc para ascendente, desc para descendente):

sort=createdAt:desc (mais recentes primeiro)
sort=dueDate:asc (vencimento mais próximo primeiro)

Para múltiplos critérios, envie um array ou separe por vírgula conforme o endpoint: sort[0]=dueDate:asc&sort[1]=createdAt:desc

Paginação

Exemplo em JavaScript: Paginação em Loop

Filtros

Exemplo Prático de Filtro

Ordenação (Sort)

On this page