API Reference / Picklist

Picklist

Le picklist sono elenchi di opzioni gestite e riusabili: le associ ai campi di tipo picklist dei moduli, così le scelte restano coerenti e si aggiornano in un punto solo. Sono due risorse: le picklist (l'elenco) e le loro opzioni.

Prima di iniziare

La lettura è aperta a ogni utente autenticato (serve a popolare i menu); la scrittura è riservata agli amministratori. Envelope ed errori: vedi Introduzione alle API.

01Endpoint

Metodo	Path		Cosa fa
GET	/api/picklists	auth	Elenco delle picklist.
POST	/api/picklists	admin	Crea una picklist.
PUT	/api/picklists/:id	admin	Aggiorna una picklist.
DELETE	/api/picklists/:id	admin	Elimina una picklist (e a cascata le sue opzioni).
GET	/api/picklist-options	auth	Opzioni, filtrabili per picklist.
POST	/api/picklist-options	admin	Aggiunge un'opzione.
PUT	/api/picklist-options/:id	admin	Aggiorna un'opzione.
DELETE	/api/picklist-options/:id	admin	Elimina un'opzione.

02L'oggetto Picklist

Una picklist è la testata di un elenco: identifica il campo che governa (module + field_name) e decide come ordinare e rendere le sue opzioni. La coppia modulo/campo è univoca.

Attributo	Tipo	Descrizione
id	integer	Identificativo della picklist.
module	string	Slug del modulo di appartenenza (minuscolo).
field_name	string	Slug del campo che usa questa picklist. Univoco con `module`.
display_name	string	Etichetta leggibile. 1–120 caratteri.
sort_strategy	string	Ordinamento delle opzioni: `manual`, `asc` o `desc`. Default `manual`.
display_style	string	Resa a schermo: `text` o `badge`. Default `text`.
created_at	string	Data/ora di creazione (ISO 8601).
updated_at	string	Data/ora ultima modifica (ISO 8601).

json · l'oggetto Picklist

{
  "id": 12,
  "module": "accounts",
  "field_name": "status",
  "display_name": "Stato cliente",
  "sort_strategy": "manual",
  "display_style": "badge",
  "created_at": "2026-07-07T15:24:00.000Z",
  "updated_at": "2026-07-07T15:24:00.000Z"
}

03L'oggetto Opzione

Ogni opzione è una voce della picklist. Il value è lo slug salvato sul record; il label è ciò che vede l'utente. La terna module + field_name + value è univoca.

Attributo	Tipo	Descrizione
id	integer	Identificativo dell'opzione.
picklist_id	integer	Picklist a cui appartiene (FK, cancellazione a cascata).
module	string	Slug del modulo (allineato alla picklist).
field_name	string	Slug del campo (allineato alla picklist).
value	string	Slug memorizzato sul record. Solo `a-z0-9_-`, 1–80 caratteri.
label	string	Etichetta visibile. 1–120 caratteri.
color_code	string \| null	Colore HEX `#rrggbb` per la resa a badge. Default `#64748b`.
sort_order	integer	Posizione manuale, 0–9999. Default 0.
created_at	string	Data/ora di creazione (ISO 8601).
updated_at	string	Data/ora ultima modifica (ISO 8601).

json · l'oggetto Opzione

{
  "id": 340,
  "picklist_id": 12,
  "module": "accounts",
  "field_name": "status",
  "value": "cliente",
  "label": "Cliente",
  "color_code": "#10b981",
  "sort_order": 10,
  "created_at": "2026-07-07T15:24:00.000Z",
  "updated_at": "2026-07-07T15:24:00.000Z"
}

04Elencare le picklist

GET /api/picklists bearer richiesto

Restituisce le picklist definite. La lettura è aperta a ogni utente autenticato: serve a popolare i menu a tendina dei form.

Parametri query

Parametro	Tipo		Descrizione
module	string	opzionale	Filtra per slug del modulo.
field_name	string	opzionale	Filtra per slug del campo.

Richiesta

curl "https://crm.tuodominio.it/api/picklists?module=accounts" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/picklists?module=accounts", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{ "success": true, "data": { "items": [ { "id": 12, "module": "accounts", "field_name": "status", … } ] } }

05Creare una picklist

POST /api/picklists admin

Parametri body

Campo	Tipo		Note
module	string	richiesto	Slug del modulo. Solo `a-z0-9_-`, 1–80. Alias: `moduleName`.
field_name	string	richiesto	Slug del campo. Solo `a-z0-9_-`, 1–80. Alias: `fieldName`.
display_name	string	richiesto	Etichetta. 1–120 caratteri. Alias: `displayName`.
sort_strategy	string	richiesto	Uno tra `manual`, `asc`, `desc`.
display_style	string	opzionale	`text` o `badge`. Default `text`.

Richiesta

curl -X POST https://crm.tuodominio.it/api/picklists \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "module": "accounts", "field_name": "status", "display_name": "Stato cliente", "sort_strategy": "manual", "display_style": "badge" }'

const res = await fetch("https://crm.tuodominio.it/api/picklists", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    module: "accounts", field_name: "status",
    display_name: "Stato cliente", sort_strategy: "manual", display_style: "badge",
  }),
});
const { data } = await res.json();

Risposta · 201

json

{ "success": true, "data": { "id": 12, "module": "accounts", "field_name": "status", … } }

Esiti

Stato	Codice	Quando
201	·	Picklist creata.
401	`UNAUTHORIZED`	Token assente o non valido.
403	`FORBIDDEN`	Utente non amministratore.
422	`VALIDATION_ERROR`	Slug non valido, `sort_strategy` fuori dai valori ammessi o campo mancante.

06Elencare le opzioni

GET /api/picklist-options bearer richiesto

Restituisce le opzioni, tipicamente filtrate sul campo di cui popolare il menu.

Parametri query

Parametro	Tipo		Descrizione
module	string	opzionale	Filtra per slug del modulo.
field_name	string	opzionale	Filtra per slug del campo.

Richiesta

curl "https://crm.tuodominio.it/api/picklist-options?module=accounts&field_name=status" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/picklist-options?module=accounts&field_name=status", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{ "success": true, "data": { "items": [ { "id": 340, "value": "cliente", "label": "Cliente", … } ] } }

07Aggiungere un'opzione

POST /api/picklist-options admin

Indica la picklist con picklist_id, oppure con la coppia module + field_name se non conosci l'id.

Parametri body

Campo	Tipo		Note
picklist_id	integer	condizionale	Intero positivo. In alternativa fornisci `module` + `field_name`.
module	string	condizionale	Slug del modulo. Usato se manca `picklist_id`.
field_name	string	condizionale	Slug del campo. Usato se manca `picklist_id`.
value	string	richiesto	Slug memorizzato. Solo `a-z0-9_-`, 1–80.
label	string	richiesto	Etichetta. 1–120 caratteri.
color_code	string	opzionale	HEX `#rrggbb`. Default `#64748b`.
sort_order	integer	opzionale	0–9999. Default 0.

Richiesta

curl -X POST https://crm.tuodominio.it/api/picklist-options \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "picklist_id": 12, "value": "cliente", "label": "Cliente", "color_code": "#10b981", "sort_order": 10 }'

const res = await fetch("https://crm.tuodominio.it/api/picklist-options", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ picklist_id: 12, value: "cliente", label: "Cliente", color_code: "#10b981", sort_order: 10 }),
});
const { data } = await res.json();

Risposta · 201

json

{ "success": true, "data": { "id": 340, "picklist_id": 12, "value": "cliente", … } }

Esiti

Stato	Codice	Quando
201	·	Opzione aggiunta.
403	`FORBIDDEN`	Utente non amministratore.
422	`VALIDATION_ERROR`	`value`/`label` non valido, colore non HEX, `sort_order` fuori dal range 0–9999, o riferimento alla picklist assente.

08Aggiornare ed eliminare

PUT/api/picklists/:id · /api/picklist-options/:idadmin

Aggiornamento parziale: invia solo i campi da cambiare (almeno uno). Per la picklist sono modificabili display_name, sort_strategy, display_style; per l'opzione value, label, color_code, sort_order. Risponde 200 con l'oggetto aggiornato, 422 se non passi alcun campo valido.

DELETE/api/picklists/:id · /api/picklist-options/:idadmin

Elimina la risorsa. Cancellare una picklist rimuove a cascata le sue opzioni (FK ON DELETE CASCADE). Risponde 200.

Picklist vs select

Un campo picklist punta a un elenco gestito qui (riusabile, aggiornabile a caldo). Un campo select, invece, porta le sue opzioni statiche definite direttamente sul campo: vedi Tipi di campo.

← PrecedenteUtenti e team Successiva →Connessioni