API Reference / Report

Report

Aggregazioni server-side per grafici e KPI: raggruppa e misura i record di qualsiasi modulo (base o custom) senza scaricarli. Il permesso di lettura e lo scope dell'utente sono applicati dentro la query: ognuno aggrega solo ciò che può vedere.

Endpoint

Metodo	Endpoint	Cosa fa
POST	/api/reports/aggregate	Aggregazione per campo o nel tempo (serie per i grafici).
POST	/api/reports/kpi	Valore singolo con confronto sul periodo precedente.
POST	/api/reports/export	La stessa aggregazione, scaricata come CSV o XLSX.
GET	/api/reports/overview	Panoramica per modulo (conteggi): solo admin.

01Aggregazione

POST /api/reports/aggregate bearer richiesto

Due modalità: mode: "field" raggruppa per il valore di una colonna (es. trattative per stage); mode: "time" costruisce una serie temporale su un campo data.

Body

Campo	Tipo		Descrizione
module	string	richiesto	Chiave del modulo (base o custom).
mode	string	richiesto	`field` o `time`.
groupBy	string	per mode=field	La colonna su cui raggruppare.
dateField	string	per mode=time	Il campo data della serie.
metric	string	opzionale	`count` (default), `sum`, `avg`, `min`, `max`, `distinct`, `ratio`: tutte tranne count richiedono `valueField`.
valueField	string	opzionale	La colonna numerica da misurare (es. `amount`).
filters	array	opzionale	Condizioni nello stesso formato dei filtri avanzati.
dateFrom / dateTo	string	opzionale	Intervallo sul campo periodo (`periodField`).

Richiesta

curl -X POST https://crm.tuodominio.it/api/reports/aggregate \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "module": "deals", "mode": "field", "groupBy": "stage", "metric": "sum", "valueField": "amount" }'

const res = await fetch("https://crm.tuodominio.it/api/reports/aggregate", {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ module: "deals", mode: "field", groupBy: "stage", metric: "sum", valueField: "amount" }),
});

Risposta · 200

json

{
  "success": true,
  "data": {
    "mode": "field",
    "total": 125000,
    "data": [
      { "name": "negotiation", "value": 78000 },
      { "name": "proposal",    "value": 47000 }
    ]
  }
}

02KPI

POST /api/reports/kpi bearer richiesto

Un valore singolo (la card KPI della dashboard): stessa semantica di misura di aggregate, più il confronto opzionale col periodo precedente.

Body

Campo	Tipo		Descrizione
module · metric · valueField · filters	·	come aggregate	La misura da calcolare.
ratioValue	string	opzionale	Per metriche a rapporto (percentuale su un valore di riferimento).
period / periodField	string	opzionale	La finestra temporale del KPI e il campo data su cui applicarla.
compare	boolean	opzionale	`true` → calcola anche il periodo precedente e la crescita %.

Risposta · 200

json

{ "success": true, "data": { "value": 125000, "previous": 98000, "growthPct": 27.55, "metric": "sum", "period": "month" } }

03Export

POST /api/reports/export bearer richiesto

Accetta lo stesso body di aggregate più format (csv, default, o xlsx) e opzionalmente groupLabel/valueLabel per intestare le colonne. La risposta è il file binario (Content-Disposition: attachment), non l'envelope JSON.

Nota

Le colonne utilizzabili in groupBy/valueField/filters sono quelle del catalogo del modulo: una colonna non prevista risponde 422. I risultati sono messi in cache lato server per qualche decina di secondi: un dato appena scritto può apparire con un piccolo ritardo.

← PrecedenteRicerca globale Successiva →Merge e duplicati