API Reference / Paginazione e filtri

Paginazione e filtri

Paginare, ordinare e filtrare le liste: parametri limit/offset/sort, l'oggetto pagination e i filtri avanzati con gli operatori per tipo.

01Paginazione

Tutte le liste (moduli base e custom) accettano gli stessi parametri di query.

Parametro	Tipo		Descrizione
limit	integer	opzionale	Righe per pagina. Default 50, massimo 200 (valori più alti vengono ridotti).
offset	integer	opzionale	Righe da saltare (default 0).
sort_by	string	opzionale	Colonna di ordinamento; ogni modulo dichiara le colonne ammesse (una non ammessa → 422).
sort_dir	string	opzionale	`asc` o `desc`.
advanced_filters	string (JSON)	opzionale	Array di condizioni URL-encoded: vedi sotto.

La risposta incapsula righe e stato della paginazione dentro data:

json · risposta di lista

{
  "success": true,
  "data": {
    "items": [ … ],
    "pagination": { "limit": 50, "offset": 0, "count": 50, "sortBy": "id", "sortDir": "desc" }
  }
}

Nota

count è il numero di righe in questa pagina, non il totale. Una pagina piena (count == limit) suggerisce che esiste una pagina successiva: incrementa offset di limit.

02Ordinamento

Ordina con sort_by + sort_dir. Le colonne ammesse dipendono dal modulo (tipicamente id, created_at, updated_at e i campi principali). Una colonna non prevista restituisce 422.

curl

curl "https://crm.tuodominio.it/api/deals?limit=50&offset=50&sort_by=amount&sort_dir=desc" \
  -H "Authorization: Bearer <accessToken>"

03Filtri avanzati

Il parametro advanced_filters è un array JSON (URL-encoded) di condizioni combinate in AND. Ogni condizione è un oggetto { column, op, value }:

json · advanced_filters

[
  { "column": "stage",  "op": "eq",       "value": "negotiation" },
  { "column": "amount", "op": "gte",      "value": 10000 },
  { "column": "name",   "op": "contains", "value": "rinnovo" }
]

04Operatori per tipo

Gli operatori ammessi dipendono dal tipo della colonna filtrata.

Tipo	Operatori ammessi
text	`eq` `neq` `contains` `in` `is_null`
enum	`eq` `neq` `in` `is_null`
integer / number	`eq` `neq` `gt` `gte` `lt` `lte` `in` `is_null`
date	`eq` `neq` `gt` `gte` `lt` `lte` `is_null`

05Semantica e limiti

in: value è un array (fino a 200 valori).
is_null: value: true per «è vuoto», false per «non è vuoto» (default true se omesso).
contains: sottostringa (solo colonne testo).
Massimo 25 condizioni per richiesta; il JSON non può superare ~8000 caratteri.
Colonne filtrabili = quelle del catalogo del modulo; una colonna non filtrabile → 422.

Nota

Su un modulo custom valgono le stesse regole, sulle colonne definite dal modulo. Vedi Record generici.

← PrecedenteErrori e envelope Successiva →Account