API Reference / Attività

Attività

Le attività sono task e appuntamenti: un oggetto, una scadenza, uno stato, e, tratto distintivo, un collegamento polimorfico che le aggancia a qualunque record (un account, un contatto, una trattativa, un modulo custom…).

Prima di iniziare

Envelope, errori, paginazione e advanced_filters sono comuni: vedi Introduzione alle API. Ogni richiesta richiede Authorization: Bearer <accessToken>.

01L'oggetto Attività

Ogni attività restituita dall'API ha questa forma. Le date sono stringhe ISO 8601 in UTC; i campi non leggibili dal tuo ruolo vengono omessi. La coppia related_module + related_record_id è il collegamento polimorfico (entrambi null se l'attività non è agganciata).

Attributo	Tipo	Descrizione
id	integer	Identificativo univoco dell'attività.
type	string	Tipo (default `task`; es. `call`, `meeting`).
subject	string	Oggetto dell'attività.
description	string \| null	Note libere.
status	string	Stato (default `open`).
due_date	string \| null	Scadenza (ISO 8601).
completed_at	string \| null	Data/ora di completamento (ISO 8601).
related_module	string \| null	Modulo del record collegato: vedi Collegamento.
related_record_id	integer \| null	Id del record collegato.
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 Attività

{
  "id": 512,
  "type": "call",
  "subject": "Richiamare il cliente",
  "description": null,
  "status": "open",
  "due_date": "2026-07-15T00:00:00.000Z",
  "completed_at": null,
  "related_module": "deals",
  "related_record_id": 88,
  "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/activities	read	Elenco paginato e filtrabile.
GET	/api/activities/:id	read	Una singola attività.
GET	/api/activities/:id/history	read	Storico modifiche del record.
POST	/api/activities	create	Crea un'attività.
PATCH	/api/activities/:id	update	Modifica parziale.
PATCH	/api/activities/bulk	update	Aggiornamento massivo.
DELETE	/api/activities/:id	delete	Soft delete.
GET	/api/activities/export.csv · .xlsx	export	Esporta l'elenco filtrato.
POST	/api/activities/import/preview · /execute	create	Import CSV.

03Collegamento a un record

Un'attività si aggancia a qualsiasi record indicando la coppia related_module + related_record_id. I moduli base ammessi sono:

accounts · contacts · leads · deals · activities · notes
…più la chiave di qualsiasi modulo custom (es. tickets): il collegamento a un modulo custom è valido allo stesso modo.

Nota

Fornisci sempre related_module e related_record_id insieme: ometterne solo uno restituisce 422. L'esistenza del record collegato è verificata lato server: un id inesistente o fuori dal tuo scope viene rifiutato.

04Elencare le attività

GET /api/activities bearer richiesto

Restituisce le attività visibili all'utente (secondo lo scope del ruolo), paginate. Per filtrare quelle di un record usa advanced_filters su related_module e related_record_id.

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. `due_date`, `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/activities?limit=2&sort_by=due_date&sort_dir=asc" \
  -H "Authorization: Bearer <accessToken>"

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

Risposta · 200

json

{
  "success": true,
  "data": {
    "items": [ { "id": 512, "subject": "Richiamare il cliente", … }, { "id": 511, … } ],
    "pagination": { "limit": 2, "offset": 0, "count": 2, "sortBy": "due_date", "sortDir": "asc" }
  }
}

05Recuperare un'attività

GET /api/activities/:id bearer richiesto

Parametri path

Parametro	Tipo	Descrizione
id	integer	Id dell'attività.

Esiti

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

06Creare un'attività

POST /api/activities bearer richiesto

Parametri body

Campo	Tipo		Note
subject	string	richiesto	Oggetto dell'attività. 1–255 caratteri.
type	string	opzionale	Tipo. Default `task`. Max 40.
description	string	opzionale	Note libere. Max 5000.
status	string	opzionale	Stato. Default `open`. Max 40.
due_date	date	opzionale	Scadenza.
completed_at	date	opzionale	Data di completamento.
related_module	enum	opzionale	Modulo del record collegato. Va insieme a `related_record_id`.
related_record_id	integer	opzionale	Id del record collegato. Va insieme a `related_module`.
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/activities \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Richiamare il cliente", "type": "call", "due_date": "2026-07-15", "related_module": "deals", "related_record_id": 88 }'

const res = await fetch("https://crm.tuodominio.it/api/activities", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject: "Richiamare il cliente", type: "call", due_date: "2026-07-15",
    related_module: "deals", related_record_id: 88,
  }),
});
const { data } = await res.json();

Risposta · 201

json

{ "success": true, "data": { "id": 512, "subject": "Richiamare il cliente", "related_module": "deals", "related_record_id": 88, … } }

Esiti

Stato	Codice	Quando
201	·	Attività creata; nel corpo l'oggetto completo.
422	`VALIDATION_ERROR`	`subject` mancante, `related_*` forniti solo a metà o record collegato inesistente.
403	`FORBIDDEN`	Campo non scrivibile dal ruolo (nei `details` l'elenco dei campi negati).

07Aggiornare un'attività

PATCH/api/activities/:idbearer richiesto

Modifica parziale: invia solo i campi da cambiare (gli stessi del body di creazione, tutti opzionali). Esempio tipico: chiudere il task impostando status e completed_at. Risponde 200 con l'oggetto aggiornato, 404 se fuori scope, 422 in validazione.

curl

curl -X PATCH https://crm.tuodominio.it/api/activities/512 \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "done", "completed_at": "2026-07-15T10:30:00.000Z" }'

08Eliminare

DELETE/api/activities/:idbearer richiesto

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

09Aggiornamento massivo

PATCH/api/activities/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": [512, 511, 509], "changes": { "status": "done" } }

Risposta · 200

json

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

10Import 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.

← PrecedenteTrattative Successiva →Note e allegati