Documentazione

API FiscoFlow

Integra l'Agenzia delle Entrate nei tuoi sistemi: fatture ricevute, corrispettivi, credenziali ADE/SPID e workspace. Tutto via API REST.

Introduzione

Le API FiscoFlow ti permettono di collegare il tuo gestionale, ERP o CRM al portale dell'Agenzia delle Entrate senza gestire manualmente credenziali e download. Puoi:

Scaricare fatture ricevute e corrispettivi in automatico
Gestire credenziali Fisconline o SPID in modo sicuro
Isolare i dati per cliente o sede con i workspace
Usare dashboard e AI per analisi e classificazione

Base URL

https://api.fiscoflow.cloud

Come funziona

Il flusso tipico per integrare FiscoFlow nel tuo software:

1
Connetti le credenziali
L'utente inserisce credenziali Fisconline/Entratel o effettua login SPID. FiscoFlow le crittografa e le usa per accedere al portale AdE in modo sicuro.
2
Configura workspace e API key
Crea un workspace per ogni cliente o sede. Genera una API key per il tuo software e usa gli header X-Workspace-Id o X-Workspace-Key per isolare i dati.
3
Sincronizza i dati
Chiama gli endpoint per fatture ricevute, corrispettivi, clienti e fornitori. Puoi usare batch sync per import massivi o invoice-sync per automazione continua.

Quick start

Dopo aver creato un account e generato una API key dall'app:

# Esempio: scarica fatture ricevute
curl -X POST "https://api.fiscoflow.cloud/api/v1/ade/fatture/ricevute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"anno": 2025, "mese": 1}'

# Con workspace specifico
curl -X GET "https://api.fiscoflow.cloud/api/v1/ade/fatture/saved" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-Key: cliente_123"

Autenticazione

Tutte le chiamate richiedono una API Key. Generala dalla sezione API Keys nell'app e inviala nell'header:

Authorization: Bearer <API_KEY>

Per gestire più clienti o contesti, usa gli header workspace (opzionali):

X-Workspace-Id – ID UUID del workspace
X-Workspace-Key – Chiave esterna (es. user_12345)

Credenziali ADE

Salva, verifica e gestisci le credenziali Fisconline/Entratel. Per l'accesso con SPID usa la sezione Login SPID.

Tutte le chiamate richiedono Authorization: Bearer <API_KEY>. Per workspace multipli aggiungi X-Workspace-Id o X-Workspace-Key.

1. Impostare le credenziali

Salva codice fiscale, password e PIN (Fisconline/Entratel). Le credenziali sono crittografate.codiceFiscale max 16 caratteri, password max 20, pin max 10. spidExpiryDate opzionale (YYYY-MM-DD).

▶Request body (POST /api/v1/ade/credentials)

{
  "codiceFiscale": "RSSMRA80A01H501Z",
  "password": "tua_password",
  "pin": "1234",
  "spidExpiryDate": "2025-12-31"
}

▶Response 200

{
  "success": true,
  "message": "Credentials saved successfully"
}

▶Response 400 (errore validazione)

{
  "error": "Bad Request",
  "message": "Validation error message"
}

2. Verificare le credenziali

Controlla se le credenziali sono configurate (senza esporre i dati).

▶Response 200 (GET /api/v1/ade/credentials)

{
  "hasCredentials": true,
  "message": "Credentials are configured",
  "spidExpiryDate": "2025-12-31"
}

Se non configurate: hasCredentials: false, spidExpiryDate assente.

3. Testare le credenziali

Verifica che le credenziali siano valide eseguendo un tentativo di login.

▶Response 200 (POST /api/v1/ade/credentials/test)

{
  "success": true,
  "message": "Credenziali valide. Accesso al portale ADE verificato."
}

▶Response 200 (credenziali non valide)

{
  "success": false,
  "message": "Autenticazione fallita. Verifica codice fiscale, password e PIN."
}

Elimina e reset

Nessun request body per entrambi.

▶Response DELETE /api/v1/ade/credentials

{
  "success": true,
  "message": "Credentials deleted successfully"
}

▶Response POST /api/v1/ade/credentials/reset

{
  "success": true,
  "message": "Credentials reset successfully. You can now save new credentials."
}

4. Login con credenziali (flusso completo)

Per accedere al portale ADE con le credenziali salvate, segui questo ordine:

init – Avvia il login, ottieni sessionId
continue – Polling fino a completamento (l’utente non interagisce)
incarico-options – Se serve scegliere un incarico, recupera le opzioni
finalize – Completa con incaricoValue (se richiesto)

4a. Init

▶Response 200 (POST /api/v1/ade/login-credentials/init)

{
  "success": true,
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Login form submitted successfully"
}

4b. Continue

Query: sessionId, timeoutSec (default 30)

▶Response 200 (POST /api/v1/ade/login-credentials/continue)

{
  "success": true,
  "status": "utenza-options",
  "currentUrl": "https://ivaservizi.agenziaentrate.gov.it/...",
  "message": "Login continuation completed"
}

status: await-continue (polling), utenza-options (serve incarico), done (completato).

4c. Incarico options

▶Response 200 (GET /api/v1/ade/login-credentials/incarico-options?sessionId=...)

{
  "success": true,
  "incaricoOptions": [
    { "value": "INC001", "text": "Incarico Amministrativo" },
    { "value": "INC002", "text": "Incarico Tecnico" }
  ],
  "message": "Incarico options retrieved"
}

4d. Finalize

Query: sessionId, incaricoValue, incaricoLabel (opzionale)

▶Response 200 (POST /api/v1/ade/login-credentials/finalize)

{
  "success": true,
  "status": "done",
  "currentUrl": "https://ivaservizi.agenziaentrate.gov.it/...",
  "message": "Login finalized successfully"
}

Riferimento endpoint

Metodo	Endpoint	Descrizione
`POST`	/api/v1/ade/credentials	Salva o aggiorna credenziali Fisconline/Entratel
`GET`	/api/v1/ade/credentials	Verifica se le credenziali sono configurate
`DELETE`	/api/v1/ade/credentials	Elimina le credenziali
`POST`	/api/v1/ade/credentials/test	Testa le credenziali
`POST`	/api/v1/ade/credentials/reset	Reset credenziali
`POST`	/api/v1/ade/login-credentials/init	Inizializza login al portale ADE
`POST`	/api/v1/ade/login-credentials/continue	Continua login (con sessionId)
`GET`	/api/v1/ade/login-credentials/incarico-options	Opzioni incarico disponibili
`POST`	/api/v1/ade/login-credentials/finalize	Finalizza login con incarico selezionato
`GET`	/api/v1/ade/login-credentials/status	Stato sessione login
`GET`	/api/v1/ade/last-session	Ultima sessione non scaduta

Login SPID

Accedi al portale ADE tramite SPID (es. PosteID). L'utente scansiona il QR code e completa il consenso.

Il login SPID richiede interazione dell’utente: scansione QR e consenso sul provider. Usa le credenziali Fisconline se vuoi un flusso completamente automatico.

Flusso login SPID

init – Avvia sessione, scegli provider (es. posteid), ottieni sessionId e qrDataUri
continue – Polling: l’utente scansiona il QR e completa il consenso sul provider
finalize – Se serve scegliere un incarico, passa value e label; altrimenti completa la sessione

Init

▶Request body (POST /api/v1/spid/init)

{
  "provider": "posteid",
  "headless": true
}

▶Response 200

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "qrDataUri": "data:image/png;base64,iVBORw0KGgo...",
  "qrPayload": "spid://...",
  "note": "OK"
}

Continue

Path: /api/v1/spid/continue/{sessionId} · Query: timeoutSec (default 180)

▶Response 200 (status utenza-options)

{
  "status": "utenza-options",
  "currentUrl": "https://ivaservizi.agenziaentrate.gov.it/...",
  "options": [
    { "value": "INC001", "text": "Incarico Amministrativo" },
    { "value": "INC002", "text": "Incarico Tecnico" }
  ]
}

▶Response 200 (status done)

{
  "status": "done",
  "currentUrl": "https://ivaservizi.agenziaentrate.gov.it/..."
}

Finalize

▶Request body (POST /api/v1/spid/finalize/{'{sessionId}'})

{
  "value": "INC001",
  "label": "Incarico Amministrativo"
}

value obbligatorio se incarico richiesto. label opzionale.

▶Response 200 (cookies)

{
  "cookies": [
    {
      "name": "FATSC",
      "value": "encrypted-value",
      "domain": ".agenziaentrate.gov.it",
      "path": "/",
      "expires": 1234567890,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ]
}

Riferimento endpoint SPID

Metodo	Endpoint	Descrizione
`POST`	/api/v1/spid/init	Inizializza login SPID (body: provider, headless)
`POST`	/api/v1/spid/continue/{sessionId}	Continua login SPID (polling QR/consenso)
`POST`	/api/v1/spid/finalize/{sessionId}	Finalizza login con incarico (se richiesto)
`GET`	/api/v1/spid/status/{sessionId}	Stato sessione SPID
`GET`	/api/v1/spid/sessions	Lista sessioni SPID
`GET`	/api/v1/spid/last-session	Ultima sessione SPID
`DELETE`	/api/v1/spid/session/{sessionId}	Elimina sessione
`POST`	/api/v1/spid/session/{sessionId}/cancel	Annulla sessione
`POST`	/api/v1/spid/sessions/cancel-all	Annulla tutte le sessioni

Fatture (portale ADE)

Scarica fatture ricevute ed emesse direttamente dal portale Agenzia delle Entrate. I dati vengono recuperati in tempo reale.

Fatture ricevute

GET: query dal, al (dd-MM-yyyy), sessionId opzionale.

▶Request body (POST /api/v1/ade/fatture/ricevute)

{
  "dal": "01-01-2025",
  "al": "31-01-2025",
  "sessionId": "uuid-opzionale"
}

▶Response 200

{
  "fatture": [
    {
      "identificativo": "IT01234567890_ABCDE",
      "numero": "1",
      "data": "2025-01-15",
      "importo": 1234.56,
      "cedentePrestatore": { "denominazione": "...", "partitaIva": "..." }
    }
  ],
  "totaleFatture": 1,
  "importedCount": 1
}

Fatture emesse

Stessa struttura di ricevute. GET/POST con dal, al.

Download XML

GET: /api/v1/ade/fatture/{id}/xml · POST: body con sessionId se serve scaricare da AdE.

▶Response (application/octet-stream)

Binary XML file (Content-Disposition: attachment)

Righe fattura

Restituisce le righe dettagliate di una fattura (descrizione, quantità, prezzo unitario, totale riga, aliquota IVA). Disponibile solo per fatture con XML scaricato.

▶Response 200 (GET /api/v1/ade/fatture/{'{id}'}/lines)

{
  "invoiceId": "IT01234567890_ABCDE",
  "xmlAvailable": true,
  "lineCount": 2,
  "lines": [
    {
      "lineNo": 1,
      "description": "Servizio di consulenza software",
      "quantity": 8,
      "unitPrice": 125.00,
      "lineTotal": 1000.00,
      "vatRate": 22.0
    },
    {
      "lineNo": 2,
      "description": "Licenza annuale software",
      "quantity": 1,
      "unitPrice": 480.00,
      "lineTotal": 480.00,
      "vatRate": 22.0
    }
  ]
}

Metodo	Endpoint	Descrizione
`GET`	/api/v1/ade/fatture/ricevute	Scarica fatture ricevute
`POST`	/api/v1/ade/fatture/ricevute	Scarica fatture ricevute (con parametri)
`GET`	/api/v1/ade/fatture/emesse	Scarica fatture emesse
`POST`	/api/v1/ade/fatture/emesse	Scarica fatture emesse (con parametri)
`GET`	/api/v1/ade/fatture/{id}/xml	Download XML fattura
`POST`	/api/v1/ade/fatture/{id}/xml	Scarica XML fattura dal portale
`GET`	/api/v1/ade/fatture/{id}/lines	Righe dettagliate (quantità, prezzo unitario, IVA)

Fatture salvate

Accedi alle fatture già sincronizzate e salvate nel database FiscoFlow. Ideale per integrazioni con gestionale o CRM.

Query: type (ricevute|emesse), limit (default 50).

▶Response 200 (GET /api/v1/ade/fatture/saved?type=ricevute&limit=50)

[
  {
    "id": "range-id",
    "type": "ricevute",
    "dal": "01-01-2025",
    "al": "31-01-2025",
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

▶Response 200 (GET /api/v1/ade/fatture/saved/{'{id}'})

{
  "id": "range-id",
  "workspaceId": "ws-uuid",
  "type": "ricevute",
  "dal": "01-01-2025",
  "al": "31-01-2025",
  "payload": {
    "fatture": [...],
    "totaleFatture": 45
  },
  "createdAt": "2025-01-15T10:00:00Z"
}

Metodo	Endpoint	Descrizione
`GET`	/api/v1/ade/fatture/saved	Lista range fatture salvate (type, limit)
`GET`	/api/v1/ade/fatture/saved/{id}	Dettaglio range con fatture

Corrispettivi

Scarica e consulta i corrispettivi giornalieri dal portale AdE, oppure quelli già salvati.

GET: query dal, al (dd-MM-yyyy). POST: body con stessi campi.

▶Request body (POST /api/v1/ade/corrispettivi)

{
  "dal": "01-01-2025",
  "al": "31-01-2025",
  "sessionId": "uuid-opzionale"
}

▶Response 200

{
  "corrispettivi": [...],
  "totaleCorrispettivi": 30
}

▶Response 200 (GET /api/v1/ade/corrispettivi/saved?limit=50)

[
  {
    "id": "record-id",
    "dal": "01-01-2025",
    "al": "31-01-2025",
    "piva": "12345678901",
    "tipoCorrispettivo": "RT",
    "createdAt": "2025-01-15T10:00:00Z"
  }
]

▶Response 200 (GET /api/v1/ade/corrispettivi/saved/{'{id}'})

{
  "id": "record-id",
  "workspaceId": "ws-uuid",
  "dal": "01-01-2025",
  "al": "31-01-2025",
  "piva": "12345678901",
  "tipoCorrispettivo": "RT",
  "payload": { ... },
  "createdAt": "2025-01-15T10:00:00Z"
}

Metodo	Endpoint	Descrizione
`GET`	/api/v1/ade/corrispettivi	Scarica corrispettivi dal portale
`POST`	/api/v1/ade/corrispettivi	Scarica corrispettivi (con parametri)
`GET`	/api/v1/ade/corrispettivi/saved	Lista corrispettivi salvati
`GET`	/api/v1/ade/corrispettivi/saved/{id}	Dettaglio corrispettivo salvato

Workspace

I workspace isolano i dati per cliente, sede o contesto. Perfetti per studi commercialisti e aziende multi-sede.

▶Request (POST /api/v1/workspaces)

{
  "key": "user_12345",
  "name": "Azienda A"
}

▶Response 200

{
  "id": "workspace-uuid",
  "key": "user_12345",
  "ownerId": "user-doc-id",
  "name": "Azienda A",
  "isDefault": false,
  "incaricoOptions": [{"value": "INC001", "label": "Incarico Amministrativo"}],
  "defaultIncaricoValue": null,
  "defaultIncaricoLabel": null,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

▶Response 200 (GET /api/v1/workspaces)

{
  "workspaces": [
    {
      "id": "workspace-1",
      "key": "user_123",
      "name": "Azienda A",
      "isDefault": true,
      "incaricoOptions": [],
      "defaultIncaricoValue": null,
      "defaultIncaricoLabel": null,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

▶Request (POST /api/v1/workspaces/by-key/{'{key}'}/default-incarico)

{
  "defaultIncaricoValue": "INC001",
  "defaultIncaricoLabel": "Incarico Amministrativo"
}

▶Request (PATCH /api/v1/workspaces/by-key/{'{key}'})

{
  "name": "Nuovo nome workspace"
}

Metodo	Endpoint	Descrizione
`POST`	/api/v1/workspaces	Crea o ottieni workspace (idempotente)
`GET`	/api/v1/workspaces	Lista workspace
`GET`	/api/v1/workspaces/by-key/{key}	Workspace per chiave
`DELETE`	/api/v1/workspaces/by-key/{key}	Elimina workspace (204)
`POST`	/api/v1/workspaces/by-key/{key}/default-incarico	Imposta incarico default
`PATCH`	/api/v1/workspaces/by-key/{key}	Aggiorna nome workspace
`POST`	/api/v1/workspaces/by-key/{key}/set-default	Imposta workspace come default

Clienti e fornitori

Gestisci anagrafiche clienti e fornitori collegate ai documenti fiscali.

Clienti

GET: query q (ricerca), limit (default 50).

▶Request (POST /api/v1/clients)

{
  "name": "Cliente S.r.l.",
  "vatNumber": "IT12345678901",
  "email": "cliente@example.com",
  "phone": "+39 02 1234567",
  "address": "Via Roma 1, Milano"
}

▶Response 200 (singolo cliente)

{
  "id": "client-id",
  "workspaceId": "ws-uuid",
  "name": "Cliente S.r.l.",
  "vatNumber": "IT12345678901",
  "email": "cliente@example.com",
  "phone": "+39 02 1234567",
  "address": "Via Roma 1, Milano",
  "imageUrl": null,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

PUT: stesso body (campi opzionali). DELETE: 204 No Content.

Metodo	Endpoint	Descrizione
`GET`	/api/v1/clients	Lista clienti (q, limit)
`GET`	/api/v1/clients/{id}	Dettaglio cliente
`POST`	/api/v1/clients	Crea cliente
`PUT`	/api/v1/clients/{id}	Aggiorna cliente
`DELETE`	/api/v1/clients/{id}	Elimina cliente (204)

Fornitori

Stessa struttura di clienti. name obbligatorio.

▶Request (POST /api/v1/suppliers)

{
  "name": "Fornitore S.r.l.",
  "vatNumber": "IT98765432109",
  "email": "fornitore@example.com",
  "phone": null,
  "address": null
}

Metodo	Endpoint	Descrizione
`GET`	/api/v1/suppliers	Lista fornitori (q, limit)
`GET`	/api/v1/suppliers/{id}	Dettaglio fornitore
`POST`	/api/v1/suppliers	Crea fornitore
`PUT`	/api/v1/suppliers/{id}	Aggiorna fornitore
`DELETE`	/api/v1/suppliers/{id}	Elimina fornitore (204)

Sincronizzazione

Batch sync per import massivi, invoice-sync per automazione continua. Centri di costo per classificazione.

Batch Sync

▶Request (POST /api/v1/batch-sync/start)

{
  "periodType": "YEAR",
  "year": 2025,
  "month": null,
  "dateFrom": null,
  "dateTo": null,
  "downloadXml": true,
  "calculateCostCenter": false,
  "useSegmented": true
}

▶Response 202 Accepted

{
  "jobId": "job-uuid",
  "recordId": "record-uuid",
  "year": 2025,
  "periodType": "YEAR",
  "status": "ACCEPTED",
  "totalSteps": 12,
  "message": "Sincronizzazione batch avviata..."
}

▶Response 200 (GET /api/v1/batch-sync/years)

{
  "years": [
    {
      "year": 2025,
      "periodType": "YEAR",
      "status": "COMPLETED",
      "recordId": "...",
      "jobId": "...",
      "completedSteps": 12,
      "totalSteps": 12
    }
  ]
}

▶Response 200 (GET /api/v1/batch-sync/{'{recordId}'})

{
  "id": "record-id",
  "workspaceId": "ws-uuid",
  "year": 2025,
  "status": "COMPLETED",
  "steps": [{"type": "LIST_CHUNK", "dal": "01-01-2025", "al": "31-01-2025", "status": "COMPLETED"}],
  "completedSteps": 12,
  "totalSteps": 12,
  "stats": { "fattureRicevute": 150, "fattureEmesse": 80 }
}

Invoice Sync

▶Response 200 (GET /api/v1/invoice-sync/config)

{
  "enabled": true,
  "downloadXml": true,
  "calculateCostCenter": false,
  "nextRunAt": "2025-01-16T02:00:00Z",
  "canEnable": true,
  "canTriggerManualSync": true
}

▶Request (PUT /api/v1/invoice-sync/config)

{
  "enabled": true,
  "downloadXml": true,
  "calculateCostCenter": false
}

▶Response 202 (POST /api/v1/invoice-sync/trigger)

{
  "jobId": "job-uuid",
  "status": "ACCEPTED",
  "message": "Job enqueued. Use GET /v1/jobs/{id} for status."
}

Centri di costo

▶Request (POST /api/v1/cost-centers/classify)

{
  "body": { "FatturaElettronica": { ... } },
  "invoiceId": "IT01234567890_ABCDE"
}

▶Request (POST /api/v1/cost-centers/classify-by-invoice-id)

{
  "invoiceId": "IT01234567890_ABCDE",
  "sessionId": "session-uuid"
}

▶Response 200

{
  "lines": [
    {"lineNumber": 1, "description": "...", "costCenter": "UFFICIO", "confidence": 0.95}
  ],
  "summary": {"totalLines": 5, "classified": 5},
  "invoiceId": "IT01234567890_ABCDE",
  "used_saved_result": false
}

Metodo	Endpoint	Descrizione
`POST`	/api/v1/batch-sync/start	Avvia sincronizzazione batch
`GET`	/api/v1/batch-sync/years	Anni disponibili per sync
`GET`	/api/v1/batch-sync/{recordId}	Stato record di sincronizzazione
`GET`	/api/v1/invoice-sync/config	Configurazione sync automatica
`PUT`	/api/v1/invoice-sync/config	Aggiorna configurazione
`POST`	/api/v1/invoice-sync/trigger	Avvia sync manuale
`POST`	/api/v1/cost-centers/classify	Classifica centro costo da body
`POST`	/api/v1/cost-centers/classify-by-invoice-id	Classifica per id fattura (scarica da AdE)
`GET`	/api/v1/cost-centers/by-invoice/{invoiceId}	Centro costo salvato per fattura

Dashboard

Metriche e report per acquisti e vendite: spesa totale, trend, top fornitori, centri di costo. Tutti gli endpoint sono GET e accettano i parametri dal e al (formato YYYY-MM-DD).

Acquisti

Query obbligatorie: dal, al (YYYY-MM-DD). Auth: Bearer o X-Api-Key + X-Workspace-Id/X-Workspace-Key.

▶GET /acquisti/spesa-totale → response

{ "totale": 12450.00, "documentCount": 45 }

▶GET /acquisti/spesa-media-mensile → response

{ "mediaMensile": 3112.50, "totale": 12450.00, "mesi": 4 }

▶GET /acquisti/documenti-fornitori → response

{ "documenti": 45, "fornitori": 12 }

▶GET /acquisti/percentuale-classificati → response

{ "classificati": 38, "totali": 45, "percentuale": 84.4 }

▶GET /acquisti/top-centri-costo?limit=3 → response

{
  "items": [
    { "costCenter": "marketing", "amount": 5200.00 },
    { "costCenter": "it", "amount": 3100.00 },
    { "costCenter": "operations", "amount": 2100.00 }
  ]
}

▶GET /acquisti/variazione?mode=MoM → response

{
  "corrente": 12450.00,
  "precedente": 10800.00,
  "percentualeCambio": 15.3
}

▶GET /acquisti/trend?granularity=month → response

{
  "points": [
    { "label": "2025-01_month", "amount": 12450.00 },
    { "label": "2025-02_month", "amount": 9800.00 }
  ]
}

▶GET /acquisti/ripartizione-centro-costo → response

{
  "items": [
    { "costCenter": "marketing", "amount": 5200.00, "percent": 41.8 },
    { "costCenter": "it", "amount": 3100.00, "percent": 24.9 }
  ],
  "totale": 12450.00
}

▶GET /acquisti/ripartizione-centro-costo/fatture?costCenter=marketing → response

[
  {
    "identificativo": "IT01234567890_ABCDE",
    "numero": "FPA/2025/001",
    "dataFattura": "2025-01-10",
    "fornitore": "Agenzia Marketing Srl",
    "amount": 2400.00
  }
]

▶GET /acquisti/ripartizione-centro-costo/fatture/{invoiceId}/righe?costCenter=marketing → response

[
  {
    "description": "Campagna social media Q1 2025",
    "costCenter": "marketing",
    "amount": 1500.00
  },
  {
    "description": "Materiali promozionali",
    "costCenter": "marketing",
    "amount": 900.00
  }
]

▶GET /acquisti/top-fornitori?limit=10&sort=spesa → response

{
  "items": [
    { "nome": "Fornitore Alpha Srl", "spesa": 4800.00, "documenti": 8, "imageUrl": null },
    { "nome": "Beta Services SpA", "spesa": 3200.00, "documenti": 5, "imageUrl": null }
  ]
}

▶GET /acquisti/top-fornitori?limit=10&sort=growth → response

{
  "items": [
    { "nome": "Gamma Tech Srl", "spesa": 1200.00, "growthPct": 45.2, "imageUrl": null },
    { "nome": "Delta Consulting", "spesa": 900.00, "growthPct": 22.0, "imageUrl": null }
  ]
}

▶GET /acquisti/top-categorie?limit=10 → response

{
  "items": [
    { "costCenter": "it", "amount": 3100.00 },
    { "costCenter": "marketing", "amount": 2800.00 }
  ]
}

Metodo	Endpoint	Descrizione
`GET`	/api/v1/dashboard/acquisti/spesa-totale	Spesa totale periodo
`GET`	/api/v1/dashboard/acquisti/spesa-media-mensile	Spesa media mensile
`GET`	/api/v1/dashboard/acquisti/documenti-fornitori	Documenti per fornitore
`GET`	/api/v1/dashboard/acquisti/percentuale-classificati	% acquisti classificati
`GET`	/api/v1/dashboard/acquisti/top-centri-costo	Top centri di costo (query: limit)
`GET`	/api/v1/dashboard/acquisti/variazione	Variazione MoM/YoY (query: mode)
`GET`	/api/v1/dashboard/acquisti/trend	Trend spesa (query: granularity)
`GET`	/api/v1/dashboard/acquisti/ripartizione-centro-costo	Ripartizione per centro di costo
`GET`	/api/v1/dashboard/acquisti/ripartizione-centro-costo/fatture	Fatture per centro di costo (query: costCenter)
`GET`	/api/v1/dashboard/acquisti/ripartizione-centro-costo/fatture/{invoiceId}/righe	Righe fattura per centro di costo (query: costCenter)
`GET`	/api/v1/dashboard/acquisti/top-fornitori	Top fornitori (query: limit, sort)
`GET`	/api/v1/dashboard/acquisti/top-categorie	Top categorie (query: limit)

Vendite

Query obbligatorie: dal, al (YYYY-MM-DD).

▶GET /vendite/vendite-totale → response

{
  "totale": 28750.00,
  "totaleFattureEmesse": 21000.00,
  "totaleCorrispettivi": 7750.00,
  "fattureEmesseCount": 32,
  "corrispettiviCount": 15
}

▶GET /vendite/vendita-media-mensile → response

{ "mediaMensile": 7187.50, "totale": 28750.00, "mesi": 4 }

▶GET /vendite/corrispettivi-registrati → response

{
  "registrati": 15,
  "attesi": 20,
  "giorniPeriodo": 31,
  "alert": true,
  "scostamento": -5
}

▶GET /vendite/trend?granularity=month → response

{
  "points": [
    { "label": "2025-01_month", "amount": 28750.00 },
    { "label": "2025-02_month", "amount": 24100.00 }
  ]
}

▶GET /vendite/variazione?mode=MoM → response

{
  "corrente": 28750.00,
  "precedente": 26600.00,
  "percentualeCambio": 8.1,
  "periodoPrecedenteDal": "2024-12-01",
  "periodoPrecedenteAl": "2024-12-31"
}

▶GET /vendite/trend-giorni-settimana → response

{
  "points": [
    { "day": "lunedì", "dayOfWeek": 1, "amount": 4800.00, "documentCount": 6 },
    { "day": "martedì", "dayOfWeek": 2, "amount": 5200.00, "documentCount": 7 },
    { "day": "mercoledì", "dayOfWeek": 3, "amount": 4100.00, "documentCount": 5 }
  ]
}

Metodo	Endpoint	Descrizione
`GET`	/api/v1/dashboard/vendite/vendite-totale	Totale vendite (fatture + corrispettivi)
`GET`	/api/v1/dashboard/vendite/vendita-media-mensile	Vendita media mensile
`GET`	/api/v1/dashboard/vendite/corrispettivi-registrati	Corrispettivi registrati con alert
`GET`	/api/v1/dashboard/vendite/trend	Trend vendite (query: granularity)
`GET`	/api/v1/dashboard/vendite/variazione	Variazione MoM/YoY (query: mode)
`GET`	/api/v1/dashboard/vendite/trend-giorni-settimana	Trend per giorno della settimana

AI Chat

Chat con AI per analisi e domande sui dati fiscali. Auth: Bearer o X-Api-Key. Usa X-Workspace-Id o X-Workspace-Key per il workspace.

▶Request (POST /api/ai/chat)

{
  "conversationId": "uuid-opzionale",
  "message": "Qual è la spesa totale di gennaio 2025?",
  "locale": "it",
  "timezone": "Europe/Rome",
  "conversationHistory": [
    {"role": "user", "content": "Ciao"},
    {"role": "assistant", "content": "Ciao! Come posso aiutarti?"}
  ],
  "assistantName": "Flowe",
  "tone": "neutrale",
  "attachments": []
}

▶Response 200

{
  "conversationId": "uuid",
  "text": "Nel periodo indicato la spesa totale è di € 12.450,00 per 45 documenti.",
  "creditsUsed": 5,
  "sources": [
    {"tool": "purchases_spending_summary", "count": 1, "period": {"dal": "01-01-2025", "al": "31-01-2025"}}
  ],
  "metadata": {
    "iterations": 1,
    "toolCalls": 1,
    "durationMs": 1200
  }
}

▶Response 200 (GET /api/ai/conversations?limit=20)

[
  {
    "id": "conv-uuid",
    "title": "Spesa gennaio 2025",
    "messageCount": 4,
    "updatedAt": "2025-01-15T10:00:00Z"
  }
]

▶Response 200 (GET /api/ai/conversations/{'{id}'})

{
  "id": "conv-uuid",
  "title": "Spesa gennaio 2025",
  "messages": [
    {"role": "user", "content": "Quanto ho speso?", "sources": []},
    {"role": "assistant", "content": "€ 12.450,00...", "sources": [...]}
  ],
  "createdAt": "2025-01-15T09:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

POST /api/ai/chat/stream: stesso body, response text/event-stream (SSE). DELETE /api/ai/conversations/{id}: 204.

Metodo	Endpoint	Descrizione
`POST`	/api/ai/chat	Chat con AI (risposta JSON)
`POST`	/api/ai/chat/stream	Chat con AI (streaming SSE)
`GET`	/api/ai/conversations	Lista conversazioni (limit)
`GET`	/api/ai/conversations/{id}	Dettaglio conversazione
`DELETE`	/api/ai/conversations/{id}	Elimina conversazione (204)

Altri endpoint

API Keys

Richiedono JWT (login dall'app). Non usare API key per creare/revocare.

▶Request (POST /api/v1/apikeys)

{
  "name": "Cliente XYZ"
}

▶Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

▶Response 200 (GET /api/v1/apikeys)

[
  {
    "id": "key-id",
    "userId": "user-id",
    "name": "Cliente XYZ",
    "kid": "uuid",
    "createdAt": "2025-01-01T00:00:00Z",
    "revokedAt": null,
    "lastUsedAt": "2025-01-15T10:00:00Z",
    "sessionsUsed": 5,
    "adeCallsUsed": 120,
    "scopes": []
  }
]

Utilizzo

▶Response 200 (GET /api/v1/usage) - con API key

{
  "type": "api-key",
  "kid": "uuid",
  "name": "Cliente XYZ",
  "userId": "user-id",
  "sessionsUsed": 5,
  "adeCallsUsed": 120,
  "lastUsedAt": "2025-01-15T10:00:00Z"
}

▶Response 200 (GET /api/v1/usage) - con JWT

{
  "type": "jwt",
  "userId": "user-id",
  "apiKeys": [{"id": "...", "kid": "...", "name": "...", "sessionsUsed": 5, "adeCallsUsed": 120}],
  "total": {"sessionsUsed": 10, "adeCallsUsed": 250, "lastUsedAt": "..."}
}

Jobs

▶Response 200 (GET /api/v1/jobs/{'{id}'})

{
  "id": "job-uuid",
  "type": "INVOICE_SYNC",
  "status": "COMPLETED",
  "attempts": 1,
  "maxAttempts": 3,
  "lastError": null,
  "createdAt": "2025-01-15T09:00:00Z",
  "updatedAt": "2025-01-15T09:05:00Z"
}

Subscription

▶Response 200 (GET /api/v1/subscription/me)

{
  "subscriptionPlanKey": "pro",
  "subscriptionPlanName": "Pro",
  "subscriptionExpired": false,
  "subscriptionStartDate": "2025-01-01",
  "subscriptionEndDate": "2025-12-31",
  "limits": {"maxWorkspaces": 10},
  "usage": {"workspacesCount": 3},
  "tokenUsage": {"allocated": 50000, "used": 12000, "remaining": 38000},
  "entitlements": ["export", "ai", "cost-center"],
  "subscriptionHistory": []
}

Top-up

▶Request (POST /api/v1/topup/checkout)

{
  "credits": 5000
}

▶Response 200

{
  "url": "https://checkout.stripe.com/..."
}

▶Response 200 (GET /api/v1/topup/available)

{
  "available": true
}

Notifiche

▶Response 200 (GET /api/v1/notifications/workspace/{'{workspaceId}'})

[
  {
    "id": "notif-id",
    "workspaceId": "ws-uuid",
    "type": "spid_expired",
    "status": "active",
    "title": "Sessione SPID scaduta",
    "message": "Riconnetti le credenziali SPID",
    "createdAt": "2025-01-15T00:00:00Z"
  }
]

Metodo	Endpoint	Descrizione
`POST`	/api/v1/apikeys	Crea API key (JWT only)
`GET`	/api/v1/apikeys	Lista API key
`DELETE`	/api/v1/apikeys/{id}	Revoca API key (204)
`GET`	/api/v1/apikeys/usage	Utilizzo per API key (JWT only)
`GET`	/api/v1/usage	Utilizzo risorse (API key o JWT)
`GET`	/api/v1/jobs/{id}	Stato job
`GET`	/api/v1/notifications/workspace/{workspaceId}	Notifiche per workspace
`GET`	/api/v1/subscription/me	Profilo subscription
`POST`	/api/v1/topup/checkout	Crea sessione checkout top-up
`GET`	/api/v1/topup/available	Top-up disponibile

Prova le API nel Playground

Testa le chiamate API direttamente dall'app, senza scrivere codice. Accedi e vai alla sezione Playground.

Accedi all'app →

API FiscoFlow

Introduzione

Come funziona

Connetti le credenziali

Configura workspace e API key

Sincronizza i dati

Quick start

Autenticazione

Credenziali ADE

1. Impostare le credenziali

2. Verificare le credenziali

3. Testare le credenziali

Elimina e reset

4. Login con credenziali (flusso completo)

4a. Init

4b. Continue

4c. Incarico options

4d. Finalize

Riferimento endpoint

Login SPID

Flusso login SPID

Init

Continue

Finalize

Riferimento endpoint SPID

Fatture (portale ADE)

Fatture ricevute

Fatture emesse

Download XML

Righe fattura

Fatture salvate

Corrispettivi

Workspace

Clienti e fornitori

Clienti

Fornitori

Sincronizzazione

Batch Sync

Invoice Sync

Centri di costo

Dashboard

Acquisti

Vendite

AI Chat

Altri endpoint

API Keys

Utilizzo

Jobs

Subscription

Top-up

Notifiche

Prova le API nel Playground