API Reference / Account

Account

Gli account sono le aziende (o organizzazioni) con cui lavori: il contenitore a cui si collegano contatti, trattative e attività. Espongono la CRUD completa più export, import massivo e ripristino.

Prima di iniziare

Envelope delle risposte, codici di errore, limit/offset, ordinamento e advanced_filters sono comuni a tutte le risorse: vedi Introduzione alle API. Ogni richiesta richiede l'header Authorization: Bearer <accessToken>.

01L'oggetto Account

Ogni account restituito dall'API ha questa forma. Le date sono stringhe ISO 8601 in UTC; i campi non leggibili dal tuo ruolo vengono omessi dalla risposta.

Attributo	Tipo	Descrizione
id	integer	Identificativo univoco dell'account.
name	string	Ragione sociale.
email	string \| null	Email aziendale.
phone	string \| null	Telefono.
website	string \| null	Sito web.
industry	string \| null	Settore merceologico.
status	string \| null	Stato applicativo (valore libero).
owner_user_id	integer \| null	Utente proprietario del record.
assigned_user_id	integer \| null	Utente assegnatario.
created_by	integer \| null	Utente che ha creato il record.
updated_by	integer \| null	Ultimo utente che l'ha modificato.
is_deleted	boolean	`true` se in cestino (soft delete).
created_at	string	Data/ora di creazione (ISO 8601).
updated_at	string	Data/ora ultima modifica (ISO 8601).

json · l'oggetto Account

{
  "id": 128,
  "name": "Acme S.r.l.",
  "email": "info@acme.it",
  "phone": "+39 02 1234567",
  "website": "https://acme.it",
  "industry": "Manifatturiero",
  "status": "cliente",
  "owner_user_id": 7,
  "assigned_user_id": 7,
  "created_by": 7,
  "updated_by": 7,
  "is_deleted": false,
  "created_at": "2026-07-07T15:24:00.000Z",
  "updated_at": "2026-07-07T15:24:00.000Z"
}

02Endpoint

Metodo	Path	Azione	Cosa fa
GET	/api/accounts	read	Elenco paginato e filtrabile.
GET	/api/accounts/:id	read	Un singolo account.
GET	/api/accounts/:id/history	read	Storico modifiche del record.
GET	/api/accounts/lookup	read	Opzioni per i campi lookup (id + etichetta).
POST	/api/accounts	create	Crea un account.
PATCH	/api/accounts/:id	update	Modifica parziale.
PATCH	/api/accounts/bulk	update	Aggiornamento massivo.
DELETE	/api/accounts/:id	delete	Soft delete.
POST	/api/accounts/:id/restore	update	Ripristina un record eliminato.
GET	/api/accounts/export.csv · .xlsx	export	Esporta l'elenco filtrato.
POST	/api/accounts/import/preview · /execute	create	Import CSV.

03Elencare gli account

GET /api/accounts bearer richiesto

Restituisce gli account visibili all'utente (secondo lo scope del ruolo), paginati.

Parametri query

Parametro	Tipo		Descrizione
limit	integer	opzionale	Righe per pagina. Default 50, max 200.
offset	integer	opzionale	Righe da saltare (default 0).
sort_by	string	opzionale	Colonna di ordinamento (es. `name`, `created_at`).
sort_dir	string	opzionale	`asc` o `desc`.
advanced_filters	string (JSON)	opzionale	Array di condizioni: vedi Filtri avanzati.

Richiesta

curl "https://crm.tuodominio.it/api/accounts?limit=2&sort_by=created_at&sort_dir=desc" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/accounts?limit=2&sort_by=created_at&sort_dir=desc", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{
  "success": true,
  "data": {
    "items": [ { "id": 128, "name": "Acme S.r.l.", … }, { "id": 127, … } ],
    "pagination": { "limit": 2, "offset": 0, "count": 2, "sortBy": "created_at", "sortDir": "desc" }
  }
}

04Recuperare un account

GET /api/accounts/:id bearer richiesto

Parametri path

Parametro	Tipo	Descrizione
id	integer	Id dell'account.

Esiti

Stato	Corpo
200	`{ success: true, data: { …account } }`
404	`NOT_FOUND`: inesistente o fuori dal tuo scope.

05Creare un account

POST /api/accounts bearer richiesto

Parametri body

Campo	Tipo		Note
name	string	richiesto	Ragione sociale. 1–255 caratteri.
email	string	opzionale	Email aziendale, validata.
phone	string	opzionale	Max 40 caratteri.
website	string	opzionale	Max 255.
industry	string	opzionale	Settore. Max 120.
status	string	opzionale	Stato libero. Max 40.
owner_user_id	integer	opzionale	Proprietario. Assegnabile solo a sé o a un sottoposto nella gerarchia dei ruoli (admin: chiunque). Vedi Utenti e team.
assigned_user_id	integer	opzionale	Utente assegnatario.

Richiesta

curl -X POST https://crm.tuodominio.it/api/accounts \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme S.r.l.", "industry": "Manifatturiero", "email": "info@acme.it" }'

const res = await fetch("https://crm.tuodominio.it/api/accounts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme S.r.l.", industry: "Manifatturiero", email: "info@acme.it" }),
});
const { data } = await res.json();

Risposta · 201

json

{ "success": true, "data": { "id": 128, "name": "Acme S.r.l.", "is_deleted": false, … } }

Esiti

Stato	Codice	Quando
201	·	Account creato; nel corpo l'oggetto completo.
422	`VALIDATION_ERROR`	`name` mancante o campo fuori misura.
403	`FORBIDDEN`	Campo non scrivibile dal ruolo (nei `details` l'elenco dei campi negati).

06Aggiornare un account

PATCH/api/accounts/:idbearer richiesto

Modifica parziale: invia solo i campi da cambiare (gli stessi del body di creazione, tutti opzionali). Risponde 200 con l'oggetto aggiornato, 404 se fuori scope, 422 in validazione.

curl

curl -X PATCH https://crm.tuodominio.it/api/accounts/128 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "cliente" }'

07Eliminare e ripristinare

DELETE/api/accounts/:idbearer richiesto

Soft delete: il record viene marcato eliminato (is_deleted: true), non cancellato. Risponde 200 { deleted: true, id }.

POST/api/accounts/:id/restorebearer richiesto

Ripristina un account eliminato (richiede il permesso update). Risponde 200 con l'oggetto ripristinato.

08Aggiornamento massivo

PATCH/api/accounts/bulkbearer richiesto

Applica gli stessi valori a una lista di record. Gli id fuori dal tuo scope vengono saltati; la risposta riporta quanti record sono stati effettivamente aggiornati.

Body

json

{ "ids": [12, 15, 22], "changes": { "status": "cliente" } }

Risposta · 200

json

{ "success": true, "data": { "requested": 3, "updated": 2 } }

09Import ed export

Export: GET /export.csv o /export.xlsx rispettano gli stessi filtri della lista (advanced_filters, ordinamento). Richiedono il permesso export.
Import: POST /import/preview restituisce un'anteprima con la mappatura colonne e gli errori riga per riga; POST /import/execute applica. L'import richiede scope all e rispetta i permessi di scrittura per campo.

← PrecedenteAutenticazione Successiva →Contatti