### GET /api/v1/topup/available

Source: https://fiscoflow.cloud/docs

Checks if top-up functionality is available.

```APIDOC
## GET /api/v1/topup/available

### Description
Checks if top-up functionality is available.

### Method
GET

### Endpoint
/api/v1/topup/available

### Response
#### Success Response (200)
- **available** (boolean) - Indicates if top-up is available.

#### Response Example
{
  "available": true
}
```

--------------------------------

### GET /api/v1/invoice-sync/config

Source: https://fiscoflow.cloud/docs

Retrieves the current configuration for automated invoice synchronization.

```APIDOC
## GET /api/v1/invoice-sync/config

### Description
Returns the current settings for the automated invoice sync service.

### Method
GET

### Endpoint
/api/v1/invoice-sync/config

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether sync is enabled
- **nextRunAt** (string) - Timestamp of the next scheduled run
```

--------------------------------

### Acquisti API Responses

Source: https://fiscoflow.cloud/docs

JSON response examples for purchase-related dashboard endpoints.

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

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

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

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

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

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

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

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

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

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

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

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

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

--------------------------------

### GET /api/v1/ade/fatture/{id}/xml

Source: https://fiscoflow.cloud/docs

Downloads the XML file for a specific invoice.

```APIDOC
## GET /api/v1/ade/fatture/{id}/xml

### Description
Downloads the XML file associated with a specific invoice ID.

### Method
GET

### Endpoint
/api/v1/ade/fatture/{id}/xml

### Parameters
#### Path Parameters
- **id** (string) - Required - The invoice identifier

### Response
#### Success Response (200)
- **Content-Type** (application/octet-stream) - Binary XML file
```

--------------------------------

### GET /api/v1/batch-sync/years

Source: https://fiscoflow.cloud/docs

Retrieves a list of years available for synchronization.

```APIDOC
## GET /api/v1/batch-sync/years

### Description
Returns the list of years and their synchronization status.

### Method
GET

### Endpoint
/api/v1/batch-sync/years

### Response
#### Success Response (200)
- **years** (array) - List of synchronization records per year
```

--------------------------------

### GET /api/v1/dashboard/acquisti/top-centri-costo

Source: https://fiscoflow.cloud/docs

Retrieves the top cost centers based on spending.

```APIDOC
## GET /api/v1/dashboard/acquisti/top-centri-costo

### Description
Returns a list of top cost centers ranked by total spending.

### Method
GET

### Endpoint
/api/v1/dashboard/acquisti/top-centri-costo

### Parameters
#### Query Parameters
- **dal** (string) - Required - Start date in YYYY-MM-DD format
- **al** (string) - Required - End date in YYYY-MM-DD format
- **limit** (integer) - Optional - Number of items to return

### Response
#### Success Response (200)
- **items** (array) - List of cost centers

#### Response Example
{
  "items": [
    { "costCenter": "marketing", "amount": 5200.00 },
    { "costCenter": "it", "amount": 3100.00 }
  ]
}
```

--------------------------------

### GET /api/v1/ade/login-credentials/incarico-options

Source: https://fiscoflow.cloud/docs

Retrieves available incarico options for the current session.

```APIDOC
## GET /api/v1/ade/login-credentials/incarico-options

### Description
Retrieves available incarico options if required during login.

### Method
GET

### Endpoint
/api/v1/ade/login-credentials/incarico-options

### Query Parameters
- **sessionId** (string) - Required - Session ID

### Response
#### Success Response (200)
- **incaricoOptions** (array) - List of available options
```

--------------------------------

### Vendite API Responses

Source: https://fiscoflow.cloud/docs

JSON response examples for sales-related dashboard endpoints.

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

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

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

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

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

--------------------------------

### GET /api/v1/ade/credentials

Source: https://fiscoflow.cloud/docs

Checks if ADE credentials are configured for the current workspace.

```APIDOC
## GET /api/v1/ade/credentials

### Description
Checks if the credentials are configured without exposing sensitive data.

### Method
GET

### Endpoint
/api/v1/ade/credentials

### Response
#### Success Response (200)
- **hasCredentials** (boolean) - Whether credentials exist
- **message** (string) - Status message
- **spidExpiryDate** (string) - Optional - Expiry date if configured
```

--------------------------------

### GET /api/v1/dashboard/vendite/vendite-totale

Source: https://fiscoflow.cloud/docs

Retrieves the total sales including invoices and receipts.

```APIDOC
## GET /api/v1/dashboard/vendite/vendite-totale

### Description
Retrieves the total sales (invoices + receipts).

### Method
GET

### Endpoint
/api/v1/dashboard/vendite/vendite-totale
```

--------------------------------

### GET /api/v1/dashboard/vendite/vendite-totale

Source: https://fiscoflow.cloud/docs

Retrieves total sales metrics including invoices and receipts.

```APIDOC
## GET /api/v1/dashboard/vendite/vendite-totale

### Description
Provides a summary of total sales, split between invoices and receipts.

### Method
GET

### Endpoint
/api/v1/dashboard/vendite/vendite-totale

### Parameters
#### Query Parameters
- **dal** (string) - Required - Start date in YYYY-MM-DD format
- **al** (string) - Required - End date in YYYY-MM-DD format

### Response
#### Success Response (200)
- **totale** (number) - Total sales amount
- **totaleFattureEmesse** (number) - Total from invoices
- **totaleCorrispettivi** (number) - Total from receipts

#### Response Example
{
  "totale": 28750.00,
  "totaleFattureEmesse": 21000.00,
  "totaleCorrispettivi": 7750.00
}
```

--------------------------------

### GET /api/v1/ade/fatture/saved

Source: https://fiscoflow.cloud/docs

Retrieves saved invoices, optionally filtered by workspace.

```APIDOC
## GET /api/v1/ade/fatture/saved

### Description
Retrieves a list of saved invoices. Use the X-Workspace-Key header to filter results by a specific workspace.

### Method
GET

### Endpoint
https://api.fiscoflow.cloud/api/v1/ade/fatture/saved

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **X-Workspace-Key** (string) - Optional - The workspace identifier to isolate data.
```

--------------------------------

### GET /api/v1/notifications/workspace/{workspaceId}

Source: https://fiscoflow.cloud/docs

Retrieves notifications for a specific workspace.

```APIDOC
## GET /api/v1/notifications/workspace/{workspaceId}

### Description
Retrieves a list of notifications for the specified workspace.

### Method
GET

### Endpoint
/api/v1/notifications/workspace/{workspaceId}

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - The unique identifier of the workspace.

### Response
#### Success Response (200)
- **id** (string) - Notification ID
- **workspaceId** (string) - Workspace UUID
- **type** (string) - Notification type
- **status** (string) - Notification status
- **title** (string) - Notification title
- **message** (string) - Notification message
- **createdAt** (string) - ISO timestamp of creation

#### Response Example
[
  {
    "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"
  }
]
```

--------------------------------

### GET /api/v1/batch-sync/{recordId}

Source: https://fiscoflow.cloud/docs

Retrieves the status and details of a specific synchronization record.

```APIDOC
## GET /api/v1/batch-sync/{recordId}

### Description
Fetches detailed status and statistics for a specific synchronization record.

### Method
GET

### Endpoint
/api/v1/batch-sync/{recordId}

### Parameters
#### Path Parameters
- **recordId** (string) - Required - The unique ID of the sync record

### Response
#### Success Response (200)
- **id** (string) - Record ID
- **status** (string) - Current status
- **stats** (object) - Statistics including invoice counts
```

--------------------------------

### GET /api/v1/ade/corrispettivi/saved

Source: https://fiscoflow.cloud/docs

Retrieves a list of daily receipts already saved in the system.

```APIDOC
## GET /api/v1/ade/corrispettivi/saved

### Description
Retrieves a list of daily receipts already saved in the system.

### Method
GET

### Endpoint
/api/v1/ade/corrispettivi/saved

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of results to return (default 50)

### Response
#### Success Response (200)
- **id** (string) - Record identifier
- **dal** (string) - Start date
- **al** (string) - End date
- **piva** (string) - VAT number
- **tipoCorrispettivo** (string) - Type of receipt
- **createdAt** (string) - Creation timestamp
```

--------------------------------

### GET /api/v1/subscription/me

Source: https://fiscoflow.cloud/docs

Retrieves the current user's subscription plan details and usage limits.

```APIDOC
## GET /api/v1/subscription/me

### Description
Retrieves subscription plan information and usage limits.

### Method
GET

### Endpoint
/api/v1/subscription/me

### Response
#### Success Response (200)
- **subscriptionPlanKey** (string) - Plan identifier
- **subscriptionPlanName** (string) - Plan display name
- **subscriptionExpired** (boolean) - Expiration status
- **limits** (object) - Usage limits
- **usage** (object) - Current usage statistics
- **tokenUsage** (object) - AI token usage details
```

--------------------------------

### GET /api/v1/dashboard/acquisti/spesa-totale

Source: https://fiscoflow.cloud/docs

Retrieves the total spending and document count for a specified date range.

```APIDOC
## GET /api/v1/dashboard/acquisti/spesa-totale

### Description
Returns the total expenditure and the number of documents processed within the given date range.

### Method
GET

### Endpoint
/api/v1/dashboard/acquisti/spesa-totale

### Parameters
#### Query Parameters
- **dal** (string) - Required - Start date in YYYY-MM-DD format
- **al** (string) - Required - End date in YYYY-MM-DD format

### Response
#### Success Response (200)
- **totale** (number) - Total spending amount
- **documentCount** (integer) - Total number of documents

#### Response Example
{
  "totale": 12450.00,
  "documentCount": 45
}
```

--------------------------------

### GET /api/v1/ade/fatture/saved

Source: https://fiscoflow.cloud/docs

Retrieves a list of invoice ranges that have been synchronized and saved in the FiscoFlow database.

```APIDOC
## GET /api/v1/ade/fatture/saved

### Description
Retrieves a list of invoice ranges that have been synchronized and saved in the FiscoFlow database.

### Method
GET

### Endpoint
/api/v1/ade/fatture/saved

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by 'ricevute' or 'emesse'
- **limit** (integer) - Optional - Number of results to return (default 50)

### Response
#### Success Response (200)
- **id** (string) - Range identifier
- **type** (string) - Type of invoice
- **dal** (string) - Start date
- **al** (string) - End date
- **createdAt** (string) - Creation timestamp
```

--------------------------------

### GET /api/v1/ade/fatture/{id}/lines

Source: https://fiscoflow.cloud/docs

Retrieves detailed line items for a specific invoice.

```APIDOC
## GET /api/v1/ade/fatture/{id}/lines

### Description
Returns detailed invoice lines including description, quantity, unit price, total, and VAT rate. Available only for invoices with downloaded XML.

### Method
GET

### Endpoint
/api/v1/ade/fatture/{id}/lines

### Parameters
#### Path Parameters
- **id** (string) - Required - The invoice identifier

### Response
#### Success Response (200)
- **invoiceId** (string) - The invoice identifier
- **xmlAvailable** (boolean) - Indicates if XML is available
- **lineCount** (integer) - Number of lines
- **lines** (array) - List of invoice lines

#### Response Example
{
  "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
    }
  ]
}
```

--------------------------------

### GET /api/v1/ade/fatture/saved/{id}

Source: https://fiscoflow.cloud/docs

Retrieves the detailed content of a specific saved invoice range.

```APIDOC
## GET /api/v1/ade/fatture/saved/{id}

### Description
Retrieves the detailed content of a specific saved invoice range.

### Method
GET

### Endpoint
/api/v1/ade/fatture/saved/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the saved range

### Response
#### Success Response (200)
- **id** (string) - Range identifier
- **workspaceId** (string) - Workspace UUID
- **type** (string) - Type of invoice
- **dal** (string) - Start date
- **al** (string) - End date
- **payload** (object) - Contains list of invoices and total count
- **createdAt** (string) - Creation timestamp
```

--------------------------------

### GET /api/v1/cost-centers/by-invoice/{invoiceId}

Source: https://fiscoflow.cloud/docs

Retrieves saved cost center classification for a specific invoice.

```APIDOC
## GET /api/v1/cost-centers/by-invoice/{invoiceId}

### Description
Returns the previously saved cost center classification for the specified invoice.

### Method
GET

### Endpoint
/api/v1/cost-centers/by-invoice/{invoiceId}

### Parameters
#### Path Parameters
- **invoiceId** (string) - Required - The invoice identifier
```

--------------------------------

### POST /api/v1/spid/init

Source: https://fiscoflow.cloud/docs

Initializes a new SPID login session by selecting a provider and obtaining the necessary QR code data.

```APIDOC
## POST /api/v1/spid/init

### Description
Initializes a new SPID login session.

### Method
POST

### Endpoint
/api/v1/spid/init

### Request Body
- **provider** (string) - Required - The SPID provider (e.g., "posteid")
- **headless** (boolean) - Required - Whether to run in headless mode

### Request Example
{
  "provider": "posteid",
  "headless": true
}

### Response
#### Success Response (200)
- **sessionId** (string) - Unique session identifier
- **qrDataUri** (string) - Base64 encoded QR code image
- **qrPayload** (string) - SPID protocol payload
- **note** (string) - Status message

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

--------------------------------

### POST /api/v1/ade/login-credentials/init

Source: https://fiscoflow.cloud/docs

Initializes the login process to the ADE portal.

```APIDOC
## POST /api/v1/ade/login-credentials/init

### Description
Starts the login process and returns a session ID.

### Method
POST

### Endpoint
/api/v1/ade/login-credentials/init

### Response
#### Success Response (200)
- **success** (boolean) - Status
- **sessionId** (string) - UUID for the session
- **message** (string) - Status message
```

--------------------------------

### POST /api/v1/batch-sync/start

Source: https://fiscoflow.cloud/docs

Initiates a batch synchronization process for invoices.

```APIDOC
## POST /api/v1/batch-sync/start

### Description
Starts a batch synchronization process based on the provided period and configuration.

### Method
POST

### Endpoint
/api/v1/batch-sync/start

### Request Body
- **periodType** (string) - Required - Type of period (e.g., YEAR)
- **year** (integer) - Optional - The year to sync
- **month** (integer) - Optional - The month to sync
- **dateFrom** (string) - Optional - Start date
- **dateTo** (string) - Optional - End date
- **downloadXml** (boolean) - Optional - Whether to download XML files
- **calculateCostCenter** (boolean) - Optional - Whether to calculate cost centers
- **useSegmented** (boolean) - Optional - Whether to use segmented sync

### Response
#### Success Response (202)
- **jobId** (string) - Unique identifier for the job
- **recordId** (string) - Unique identifier for the record
- **status** (string) - Status of the request
```

--------------------------------

### Initialize SPID Login

Source: https://fiscoflow.cloud/docs

Initiates the SPID authentication session by specifying the provider.

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

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

--------------------------------

### POST /api/v1/workspaces

Source: https://fiscoflow.cloud/docs

Creates or retrieves a workspace.

```APIDOC
## POST /api/v1/workspaces

### Description
Creates or retrieves a workspace (idempotent).

### Method
POST

### Endpoint
/api/v1/workspaces

### Request Body
- **key** (string) - Required - Unique identifier key
- **name** (string) - Required - Workspace name

### Request Example
{
  "key": "user_12345",
  "name": "Azienda A"
}

### Response
#### Success Response (200)
- **id** (string) - Workspace ID
- **key** (string) - Workspace key
- **ownerId** (string) - Owner ID
- **name** (string) - Workspace name
- **isDefault** (boolean) - Default status
- **incaricoOptions** (array) - List of incarico options
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Update timestamp
```

--------------------------------

### POST /api/v1/topup/checkout

Source: https://fiscoflow.cloud/docs

Creates a checkout session for credit top-ups.

```APIDOC
## POST /api/v1/topup/checkout

### Description
Creates a checkout session for credit top-ups.

### Method
POST

### Endpoint
/api/v1/topup/checkout

### Request Body
- **credits** (integer) - Required - The amount of credits to purchase.

### Response
#### Success Response (200)
- **url** (string) - The URL for the Stripe checkout session.

#### Response Example
{
  "url": "https://checkout.stripe.com/..."
}
```

--------------------------------

### POST /api/v1/ade/login-credentials/continue

Source: https://fiscoflow.cloud/docs

Continues the login process using a session ID.

```APIDOC
## POST /api/v1/ade/login-credentials/continue

### Description
Continues the login process via polling.

### Method
POST

### Endpoint
/api/v1/ade/login-credentials/continue

### Query Parameters
- **sessionId** (string) - Required - Session ID
- **timeoutSec** (integer) - Optional - Timeout in seconds (default 30)

### Response
#### Success Response (200)
- **success** (boolean) - Status
- **status** (string) - Current status (await-continue, utenza-options, done)
- **currentUrl** (string) - Current portal URL
```

--------------------------------

### Avviare Sincronizzazione Batch

Source: https://fiscoflow.cloud/docs

Richiesta POST per avviare un processo di sincronizzazione batch.

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

--------------------------------

### Create Client Request

Source: https://fiscoflow.cloud/docs

Payload for creating a new client.

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

--------------------------------

### POST /api/v1/apikeys

Source: https://fiscoflow.cloud/docs

Creates a new API key for the authenticated user.

```APIDOC
## POST /api/v1/apikeys

### Description
Creates a new API key.

### Method
POST

### Endpoint
/api/v1/apikeys

### Request Body
- **name** (string) - Required - Name for the API key

### Response
#### Success Response (200)
- **token** (string) - The generated JWT token
```

--------------------------------

### Top-up Checkout Request

Source: https://fiscoflow.cloud/docs

Initiate a top-up checkout session by specifying the number of credits.

```json
{
  "credits": 5000
}
```

--------------------------------

### Risposta Sincronizzazione Batch

Source: https://fiscoflow.cloud/docs

Risposte API per il monitoraggio e lo stato dei job di sincronizzazione batch.

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

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

```json
{
  "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 }
}
```

--------------------------------

### POST /api/v1/clients

Source: https://fiscoflow.cloud/docs

Creates a new client record.

```APIDOC
## POST /api/v1/clients

### Description
Creates a new client record associated with the workspace.

### Method
POST

### Endpoint
/api/v1/clients

### Request Body
- **name** (string) - Required - Client name
- **vatNumber** (string) - Optional - VAT number
- **email** (string) - Optional - Email address
- **phone** (string) - Optional - Phone number
- **address** (string) - Optional - Physical address

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

### Response
#### Success Response (200)
- **id** (string) - Client ID
- **workspaceId** (string) - Workspace ID
- **name** (string) - Client name
```

--------------------------------

### List Workspaces Response

Source: https://fiscoflow.cloud/docs

Response object containing a list of workspaces.

```json
{
  "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"
    }
  ]
}
```

--------------------------------

### Create Workspace Request

Source: https://fiscoflow.cloud/docs

Payload for creating a new workspace.

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

--------------------------------

### Configurazione Invoice Sync

Source: https://fiscoflow.cloud/docs

Gestione della configurazione per la sincronizzazione automatica delle fatture.

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

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

--------------------------------

### Top-up Availability Response

Source: https://fiscoflow.cloud/docs

Indicates whether top-up functionality is currently available.

```json
{
  "available": true
}
```

--------------------------------

### Trigger Manuale Invoice Sync

Source: https://fiscoflow.cloud/docs

Risposta alla richiesta di avvio manuale della sincronizzazione fatture.

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

--------------------------------

### Workspace Response

Source: https://fiscoflow.cloud/docs

Response object returned after creating a workspace.

```json
{
  "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"
}
```

--------------------------------

### Subscription Details Response

Source: https://fiscoflow.cloud/docs

Response format for retrieving current subscription plan and usage limits.

```json
{
  "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": []
}
```

--------------------------------

### POST /api/v1/ade/login-credentials/finalize

Source: https://fiscoflow.cloud/docs

Finalizes the login process with a selected incarico.

```APIDOC
## POST /api/v1/ade/login-credentials/finalize

### Description
Completes the login process using the selected incarico value.

### Method
POST

### Endpoint
/api/v1/ade/login-credentials/finalize

### Query Parameters
- **sessionId** (string) - Required - Session ID
- **incaricoValue** (string) - Required - Selected incarico value
- **incaricoLabel** (string) - Optional - Label for the incarico
```

--------------------------------

### POST /api/v1/suppliers

Source: https://fiscoflow.cloud/docs

Creates a new supplier record.

```APIDOC
## POST /api/v1/suppliers

### Description
Creates a new supplier record.

### Method
POST

### Endpoint
/api/v1/suppliers

### Request Body
- **name** (string) - Required - Supplier name
- **vatNumber** (string) - Optional - VAT number
- **email** (string) - Optional - Email address
- **phone** (string) - Optional - Phone number
- **address** (string) - Optional - Physical address

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

--------------------------------

### Client Response

Source: https://fiscoflow.cloud/docs

Response object for a single client.

```json
{
  "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"
}
```

--------------------------------

### Response for daily receipts download

Source: https://fiscoflow.cloud/docs

Successful response containing the downloaded daily receipts.

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

--------------------------------

### POST /api/v1/ade/corrispettivi

Source: https://fiscoflow.cloud/docs

Downloads daily receipts from the AdE portal based on provided date ranges.

```APIDOC
## POST /api/v1/ade/corrispettivi

### Description
Downloads daily receipts from the AdE portal based on provided date ranges.

### Method
POST

### Endpoint
/api/v1/ade/corrispettivi

### Parameters
#### Request Body
- **dal** (string) - Required - Start date (dd-MM-yyyy)
- **al** (string) - Required - End date (dd-MM-yyyy)
- **sessionId** (string) - Optional - Session identifier

### Response
#### Success Response (200)
- **corrispettivi** (array) - List of receipts
- **totaleCorrispettivi** (integer) - Total count
```

--------------------------------

### List API Keys Response

Source: https://fiscoflow.cloud/docs

Response format for listing all API keys associated with the user.

```json
[
  {
    "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": []
  }
]
```

--------------------------------

### Resource and Job Monitoring

Source: https://fiscoflow.cloud/docs

Endpoints for monitoring resource usage and job status.

```APIDOC
## Resource and Job Monitoring

- **GET /api/v1/usage**: Utilizzo risorse (API key o JWT)
- **GET /api/v1/jobs/{id}**: Stato job
- **GET /api/v1/subscription/me**: Profilo subscription
```

--------------------------------

### Create Supplier Request

Source: https://fiscoflow.cloud/docs

Payload for creating a new supplier.

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

--------------------------------

### PUT /api/v1/invoice-sync/config

Source: https://fiscoflow.cloud/docs

Updates the configuration for automated invoice synchronization.

```APIDOC
## PUT /api/v1/invoice-sync/config

### Description
Updates the automated invoice sync settings.

### Method
PUT

### Endpoint
/api/v1/invoice-sync/config

### Request Body
- **enabled** (boolean) - Required - Enable or disable sync
- **downloadXml** (boolean) - Required - Enable or disable XML download
- **calculateCostCenter** (boolean) - Required - Enable or disable cost center calculation
```

--------------------------------

### POST /api/v1/ade/fatture/ricevute

Source: https://fiscoflow.cloud/docs

Retrieves a list of received invoices from the AdE portal for a specified date range.

```APIDOC
## POST /api/v1/ade/fatture/ricevute

### Description
Retrieves received invoices from the Agenzia delle Entrate portal.

### Method
POST

### Endpoint
/api/v1/ade/fatture/ricevute

### Request Body
- **dal** (string) - Required - Start date (dd-MM-yyyy)
- **al** (string) - Required - End date (dd-MM-yyyy)
- **sessionId** (string) - Optional - Session identifier

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

### Response
#### Success Response (200)
- **fatture** (array) - List of invoices
- **totaleFatture** (integer) - Total count of invoices
- **importedCount** (integer) - Count of imported invoices

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

--------------------------------

### POST /api/v1/ade/credentials/test

Source: https://fiscoflow.cloud/docs

Tests the validity of the saved credentials by attempting a login.

```APIDOC
## POST /api/v1/ade/credentials/test

### Description
Verifies that the saved credentials are valid by performing a login attempt.

### Method
POST

### Endpoint
/api/v1/ade/credentials/test

### Response
#### Success Response (200)
- **success** (boolean) - Result of the test
- **message** (string) - Status message
```

--------------------------------

### Top-up Checkout Response

Source: https://fiscoflow.cloud/docs

Returns the URL for the Stripe checkout session.

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

--------------------------------

### API Key Management

Source: https://fiscoflow.cloud/docs

Endpoints for creating, listing, and revoking API keys.

```APIDOC
## API Key Management

- **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)
```

--------------------------------

### Retrieve invoices and receipts via cURL

Source: https://fiscoflow.cloud/docs

Use these commands to fetch received invoices or saved documents by providing an API key and optional workspace headers.

```bash
# 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"
```

--------------------------------

### Classificazione Centri di Costo

Source: https://fiscoflow.cloud/docs

Richieste per classificare i centri di costo basandosi sul corpo della fattura o sull'ID.

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

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

--------------------------------

### Download XML Response

Source: https://fiscoflow.cloud/docs

Response format for downloading an invoice XML file.

```text
Binary XML file (Content-Disposition: attachment)
```

--------------------------------

### Manage ADE Credentials

Source: https://fiscoflow.cloud/docs

Endpoints for saving, verifying, testing, and resetting ADE credentials.

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

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

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

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

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

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

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

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

--------------------------------

### POST /api/v1/ade/credentials

Source: https://fiscoflow.cloud/docs

Saves or updates Fisconline/Entratel credentials.

```APIDOC
## POST /api/v1/ade/credentials

### Description
Saves or updates Fisconline/Entratel credentials. Credentials are encrypted upon storage.

### Method
POST

### Endpoint
/api/v1/ade/credentials

### Request Body
- **codiceFiscale** (string) - Required - Max 16 characters
- **password** (string) - Required - Max 20 characters
- **pin** (string) - Required - Max 10 characters
- **spidExpiryDate** (string) - Optional - YYYY-MM-DD format

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

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **message** (string) - Confirmation message
```

--------------------------------

### Create API Key Request

Source: https://fiscoflow.cloud/docs

Payload for creating a new API key.

```json
{
  "name": "Cliente XYZ"
}
```

--------------------------------

### Risposta Classificazione Centri di Costo

Source: https://fiscoflow.cloud/docs

Risultato della classificazione dei centri di costo per una fattura.

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

--------------------------------

### ADE Login Flow

Source: https://fiscoflow.cloud/docs

Multi-step process to authenticate with the ADE portal using saved credentials.

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

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

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

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