API FiscoZone

Integra FiscoZone nelle tue applicazioni e automatizza la gestione fiscale.

Base URL

https://rest.fiscozone.it/api/v1

API RESTful con verbi HTTP standard: GET per lettura, POST per creazione, PATCH per aggiornamento, DELETE per eliminazione.

Input/output in formato JSON standard. I parametri di filtro vanno come query string normali.

Formato parametri

Per le richieste GET, i filtri sono query string standard:

GET /api/v1/invoices?year=2026&status=PAGATA&page=1&pageSize=20

Per le richieste POST e PATCH, i dati vanno nel body JSON:

POST /api/v1/invoices
Content-Type: application/json

{"clientId":"clx...","data":"2026-04-05","righe":[...]}

Formato risposta

// Successo
{"data": {...}}

// Successo con paginazione
{"data": [...], "meta": {"page": 1, "pageSize": 20, "total": 45, "totalPages": 3}}

// Errore
{"error": {"code": "NOT_FOUND", "message": "Invoice not found"}}

Autenticazione

FiscoZone usa un flusso a due passaggi: la tua API key viene scambiata per un token temporaneo JWT.

Flusso di autenticazione

Crea una API key da Impostazioni → Sviluppatori
Scambia la key per un token JWT tramite POST /api/auth/token usando l'header fz-api-key
Usa l'access_token nell'header Authorization: Bearer <token> per tutte le chiamate
Quando l'access token scade, usa il refresh_token per ottenerne uno nuovo senza rimandare la API key

1. Ottenere un token

POST/api/auth/tokennessuno

Scambia una API key per un token JWT temporaneo (durata: 1 ora). La API key viene inviata una sola volta in questa chiamata tramite l'header dedicato fz-api-key.

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/auth/token \
  -H "fz-api-key: fz_la_tua_api_key"

Esempio risposta

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scopes": ["invoices:read", "invoices:write", "clients:read"]
}

2. Usare il token

Includi il token in tutte le richieste successive:

# Richiesta GET senza parametri:
curl https://rest.fiscozone.it/api/v1/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Richiesta GET con filtri:
curl "https://rest.fiscozone.it/api/v1/invoices?year=2026&status=PAGATA" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Richiesta POST (creazione):
curl -X POST https://rest.fiscozone.it/api/v1/invoices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"clientId":"clx...","data":"2026-04-05","righe":[...]}'

# Richiesta PATCH (aggiornamento):
curl -X PATCH https://rest.fiscozone.it/api/v1/invoices/clx123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"pagata":true,"dataPagamento":"2026-04-05"}'

3. Refresh del token

Quando l'access token scade (errore 401), usa il refresh token per ottenerne uno nuovo senza rimandare la API key:

POST/api/auth/tokennessuno

Rinnova la coppia access + refresh token. Il refresh token e valido per 7 giorni dopo la scadenza dell'access token.

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

Esempio risposta

{
  "access_token": "eyJ...nuovo...",
  "refresh_token": "eyJ...nuovo...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Sicurezza: L'access token scade dopo 1 ora. Il refresh token e valido per 7 giorni. Dopo la scadenza del refresh token, dovrai riautenticarti con la API key. La key transita solo nell'header fz-api-key, mai nell'URL o nel body. Non conservare la API key nel codice client - usala solo lato server.

Scopes

Ogni API key ha un set di scopes che determinano quali endpoint sono accessibili.

Scope	Descrizione	Accesso
invoices:read	Fatture	Lettura fatture, note di credito, proforma
invoices:write	Fatture	Creazione, modifica, eliminazione, invio SDI
quotes:read	Preventivi	Lettura preventivi
quotes:write	Preventivi	Creazione, modifica, conversione in fattura
clients:read	Clienti	Anagrafica e report clienti
clients:write	Clienti	Creazione, modifica, eliminazione
taxes:read	Fiscale	Calcolo tasse, scadenze, F24
f24:read	F24	Download documenti F24
expenses:read	Spese	Lettura spese e categorie
expenses:write	Spese	Creazione, modifica, eliminazione
contracts:read	Contratti	Lettura contratti e firme
contracts:write	Contratti	Creazione e invio per firma
projects:read	Progetti	Lettura progetti, task e timesheet
projects:write	Progetti	Creazione e gestione progetti, task e timesheet
calendar:read	Calendario	Lettura impostazioni, tipi evento, prenotazioni e disponibilita
calendar:write	Calendario	Creazione e gestione prenotazioni, tipi evento e disponibilita
pos:read	Pagamenti	Lettura link di pagamento
pos:write	Pagamenti	Creazione link di pagamento
notifications:read	Notifiche	Lettura notifiche
documents:read	Documenti	Lettura documenti
documents:write	Documenti	Upload documenti
communications:read	Comunicazioni	Lettura thread e messaggi
communications:write	Comunicazioni	Invio messaggi
profile:read	Profilo	Dati account e attivita
commercialista:read	Commercialista	Clienti assegnati
commercialista:write	Commercialista	Gestione operazioni clienti

Fatturazione

Gestisci fatture, proforma e note di credito.

GET/api/v1/invoicesinvoices:read

Elenco fatture con filtri opzionali.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
status	string	No	BOZZA \| EMESSA \| INVIATA \| CONSEGNATA \| PAGATA
tipoDocumento	string	No	FATTURA \| PROFORMA \| NOTA_CREDITO
year	number	No	Anno di riferimento
search	string	No	Ricerca per numero o cliente
page	number	No	Pagina (default: 1)
pageSize	number	No	Risultati per pagina (default: 20, max: 100)

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/invoices?year=2026" \
  -H "Authorization: Bearer <token>"

Esempio risposta

{
  "result": {
    "data": {
      "items": [
        {
          "id": "clx...",
          "numero": "1/2026",
          "data": "2026-01-15",
          "status": "PAGATA",
          "tipoDocumento": "FATTURA",
          "totale": 1220.00,
          "imponibile": 1000.00,
          "client": { "denominazione": "Acme Srl" }
        }
      ],
      "total": 15,
      "page": 1,
      "pageSize": 20,
      "totalPages": 1
    }
  }
}

GET/api/v1/invoices/:idinvoices:read

Dettaglio completo di una fattura con righe e tracking SDI.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
id	string	Si	ID della fattura

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/invoices/clx123abc" \
  -H "Authorization: Bearer <token>"

POST/api/v1/invoicesinvoices:write

Crea una nuova fattura o proforma.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
tipoDocumento	string	Si	FATTURA \| PROFORMA
clientId	string	Si	ID del cliente
data	string	Si	Data emissione (ISO format)
righe	array	Si	Array di righe fattura
status	string	No	BOZZA \| EMESSA (default: BOZZA)
scadenza	string	No	Data scadenza pagamento
note	string	No	Note aggiuntive
applicaRivalsa	boolean	No	Applica rivalsa INPS 4%
applicaBollo	boolean	No	Applica bollo (auto-calcolato)

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/invoices \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoDocumento": "FATTURA",
    "clientId": "clx...",
    "data": "2026-04-05",
    "status": "BOZZA",
    "righe": [{
      "descrizione": "Consulenza web",
      "quantita": 10,
      "prezzoUnitario": 50,
      "tipoIva": "ESENTE",
      "naturaEsenzione": "N2.2"
    }]
  }'

Esempio risposta

{
  "result": {
    "data": {
      "id": "clx...",
      "numero": "5/2026",
      "status": "BOZZA",
      "totale": 500.00
    }
  }
}

PATCH/api/v1/invoices/:idinvoices:write

Aggiorna una fattura (stato pagamento, note).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
id	string	Si	ID della fattura
pagata	boolean	No	Segna come pagata
dataPagamento	string	No	Data pagamento (ISO)
note	string	No	Note

DELETE/api/v1/invoices/:idinvoices:write

Elimina una fattura (solo BOZZA o EMESSA).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
id	string	Si	ID della fattura

POST/api/v1/invoices/:id/send-sdiinvoices:write

Invia una fattura allo SDI (fatturazione elettronica).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
invoiceId	string	Si	ID della fattura da inviare

GET/api/v1/invoices/statsinvoices:read

Statistiche fatturato dell'anno: totale, non pagato, conteggi.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
year	number	No	Anno (default: corrente)

Clienti

Gestisci l'anagrafica clienti.

GET/api/v1/clientsclients:read

Elenco clienti con ricerca.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
search	string	No	Ricerca per nome, P.IVA, CF
page	number	No	Pagina (default: 1)
pageSize	number	No	Risultati per pagina (default: 20)

POST/api/v1/clientsclients:write

Crea un nuovo cliente.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
denominazione	string	Si	Nome o ragione sociale
partitaIva	string	No	Partita IVA
codiceFiscale	string	No	Codice fiscale
indirizzo	string	No	Indirizzo
cap	string	No	CAP
comune	string	No	Comune
provincia	string	No	Provincia (2 lettere)
pec	string	No	PEC
codiceSdi	string	No	Codice SDI (7 caratteri)
email	string	No	Email
telefono	string	No	Telefono

GET/api/v1/clients/:id/reportclients:read

Report finanziario dettagliato per un cliente specifico.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
clientId	string	Si	ID del cliente
anno	number	No	Anno di riferimento

Preventivi

Crea e gestisci preventivi.

GET/api/v1/quotesquotes:read

Elenco preventivi.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
status	string	No	BOZZA \| INVIATO \| ACCETTATO \| RIFIUTATO \| SCADUTO
page	number	No	Pagina

POST/api/v1/quotesquotes:write

Crea un nuovo preventivo.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
clientId	string	Si	ID del cliente
data	string	Si	Data (ISO)
righe	array	Si	Righe del preventivo
validitaGiorni	number	No	Giorni di validita (default: 30)

Spese

Registra e gestisci le spese dell'attivita.

GET/api/v1/expensesexpenses:read

Elenco spese con filtri.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
anno	number	No	Anno
categoriaSpesaId	string	No	Filtra per categoria
pagata	boolean	No	Filtra per stato pagamento
search	string	No	Ricerca

POST/api/v1/expensesexpenses:write

Registra una nuova spesa.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
fornitore	string	Si	Nome fornitore
descrizione	string	Si	Descrizione
importoLordo	number	Si	Importo lordo (IVA inclusa)
data	string	Si	Data (ISO)
aliquotaIva	number	No	Aliquota IVA %
categoriaSpesaId	string	No	ID categoria
isAsset	boolean	No	Segna come cespite
pagata	boolean	No	Gia pagata

GET/api/v1/expenses/categoriesexpenses:read

Lista delle categorie di spesa disponibili.

Tasse

Calcolo previsionale tasse e scadenze fiscali. Richiede piano PRO.

GET/api/v1/taxes/calculatetaxes:read

Calcolo previsionale completo: imposta sostitutiva, INPS, acconti, saldi.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
anno	number	No	Anno (default: corrente)
fatturatoManuale	number	No	Override fatturato per simulazione

Esempio risposta

{
  "result": {
    "data": {
      "fatturatoAnno": 45000.00,
      "coefficienteRedditivita": 0.67,
      "redditoImponibile": 28150.00,
      "aliquotaImposta": 0.05,
      "impostaSostitutiva": 1407.50,
      "contributiInps": 7200.00,
      "totaleImposte": 8607.50,
      "nettoStimato": 36392.50,
      "saldoImposta": 1407.50,
      "saldoInps": 3600.00
    }
  }
}

GET/api/v1/taxes/deadlinestaxes:read

Scadenze fiscali con importi e stato pagamento.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
anno	number	No	Anno

GET/api/v1/taxes/f24f24:read

Elenco modelli F24 generati.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
anno	number	No	Anno

Contratti

Gestisci contratti digitali con firma elettronica.

GET/api/v1/contractscontracts:read

Elenco contratti.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
status	string	No	BOZZA \| FINALIZZATO \| INVIATO \| FIRMATO \| SCADUTO
tipo	string	No	LETTERA_INCARICO \| CONTRATTO_SERVIZI \| NDA \| ...
clientId	string	No	Filtra per cliente

POST/api/v1/contractscontracts:write

Crea un nuovo contratto.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
tipo	string	Si	Tipo di contratto
titolo	string	Si	Titolo
clientId	string	No	ID cliente
contenuto	string	No	Contenuto HTML
templateId	string	No	ID template da usare

Progetti

Gestisci progetti con Kanban board, task e timesheet. Richiede piano PRO.

GET/api/v1/projectsprojects:read

Elenco progetti con filtri.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
status	string	No	PLANNING \| IN_PROGRESS \| ON_HOLD \| COMPLETED \| ARCHIVED
clientId	string	No	Filtra per cliente
search	string	No	Cerca per nome
page	number	No	Pagina (default: 1)
pageSize	number	No	Risultati per pagina (default: 12)

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/projects?status=IN_PROGRESS" \
  -H "Authorization: Bearer <token>"

POST/api/v1/projectsprojects:write

Crea un nuovo progetto con colonne Kanban predefinite.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Si	Nome progetto
clientId	string	No	ID cliente
billingType	string	No	HOURLY \| DAILY \| FIXED (default: HOURLY)
rate	number	No	Tariffa oraria/giornaliera
budget	number	No	Budget totale
startDate	string	No	Data inizio (ISO)
endDate	string	No	Data fine (ISO)
color	string	No	Colore hex (default: #6366f1)
tags	string[]	No	Tag per categorizzazione

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sito web Acme", "clientId": "clx...", "billingType": "HOURLY", "rate": 50}'

GET/api/v1/projects/:idprojects:read

Dettaglio progetto completo con colonne Kanban, task e etichette.

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/projects/clx123" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/projects/:idprojects:write

Aggiorna un progetto (nome, stato, tariffa, budget, ecc.).

DELETE/api/v1/projects/:idprojects:write

Elimina un progetto e tutti i dati associati.

Task

GET/api/v1/projects/:id/tasksprojects:read

Elenco task del progetto con colonne e checklist.

POST/api/v1/projects/:id/tasksprojects:write

Crea un nuovo task in una colonna.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
title	string	Si	Titolo del task
columnId	string	Si	ID della colonna Kanban
priority	string	No	LOW \| MEDIUM \| HIGH \| URGENT
dueDate	string	No	Scadenza (ISO)
estimatedHours	number	No	Ore stimate

GET/api/v1/projects/:id/tasks/:taskIdprojects:read

Dettaglio task con checklist e time entries.

PATCH/api/v1/projects/:id/tasks/:taskIdprojects:write

Aggiorna task (titolo, priorita, colonna, completamento, ecc.).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
title	string	No	Titolo
columnId	string	No	Sposta in altra colonna
completed	boolean	No	Segna come completato
priority	string	No	LOW \| MEDIUM \| HIGH \| URGENT

DELETE/api/v1/projects/:id/tasks/:taskIdprojects:write

Elimina un task.

Timesheet

GET/api/v1/projects/:id/timesheetprojects:read

Registrazioni di tempo del progetto.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
dateFrom	string	No	Data inizio (ISO)
dateTo	string	No	Data fine (ISO)
billable	boolean	No	Solo fatturabili
invoiced	boolean	No	Solo fatturate
taskId	string	No	Filtra per task

POST/api/v1/projects/:id/timesheetprojects:write

Registra una nuova entry di tempo.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
date	string	Si	Data (ISO)
hours	number	Si	Ore lavorate
taskId	string	No	ID task associato
description	string	No	Descrizione attivita
billable	boolean	No	Fatturabile (default: true)

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/projects/clx123/timesheet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-04-05", "hours": 3.5, "description": "Sviluppo frontend"}'

Calendario

Gestisci prenotazioni, tipi evento, disponibilita e impostazioni calendario. Richiede piano PRO.

Impostazioni

GET/api/v1/calendar/settingscalendar:read

Legge le impostazioni del calendario, incluse le regole di disponibilita settimanale e gli override.

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/calendar/settings" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/calendar/settingscalendar:write

Aggiorna le impostazioni del calendario.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
displayName	string	No	Nome visualizzato nella pagina pubblica
bio	string	No	Biografia breve
timezone	string	No	Fuso orario (es. Europe/Rome)
isActive	boolean	No	Pagina pubblica attiva
minimumNotice	number	No	Preavviso minimo in minuti
bookingWindowDays	number	No	Finestra prenotazione in giorni
bufferBefore	number	No	Buffer prima (minuti)
bufferAfter	number	No	Buffer dopo (minuti)
requireConfirmation	boolean	No	Richiedi conferma manuale
brandColor	string	No	Colore brand hex (es. #2563eb)
googleSyncEnabled	boolean	No	Sincronizzazione Google Calendar

Esempio richiesta

curl -X PATCH https://rest.fiscozone.it/api/v1/calendar/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"minimumNotice": 60, "bufferAfter": 15}'

Tipi Evento

GET/api/v1/calendar/event-typescalendar:read

Elenco tipi di evento prenotabili con conteggio prenotazioni.

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/calendar/event-types" \
  -H "Authorization: Bearer <token>"

POST/api/v1/calendar/event-typescalendar:write

Crea un nuovo tipo di evento prenotabile.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
title	string	Si	Titolo evento
slug	string	Si	Slug URL-friendly (univoco)
duration	number	No	Durata in minuti (default: 30)
description	string	No	Descrizione
color	string	No	Colore hex (default: #2563eb)
locationType	string	No	GOOGLE_MEET \| CUSTOM_URL \| IN_PERSON \| PHONE
customLocationUrl	string	No	URL meeting (se CUSTOM_URL)
isGroup	boolean	No	Evento di gruppo (default: false)
maxAttendees	number	No	Partecipanti massimi (default: 1)
requiresPayment	boolean	No	Richiedi pagamento (default: false)
priceInCents	number	No	Prezzo in centesimi
currency	string	No	Valuta (default: EUR)
googleCalendarId	string	No	Calendario Google di destinazione

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/calendar/event-types \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Consulenza fiscale", "slug": "consulenza-fiscale", "duration": 30, "locationType": "GOOGLE_MEET"}'

GET/api/v1/calendar/event-types/:idcalendar:read

Dettaglio tipo evento con conteggio prenotazioni.

PATCH/api/v1/calendar/event-types/:idcalendar:write

Aggiorna un tipo evento (titolo, durata, prezzo, stato, ecc.).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
title	string	No	Titolo
duration	number	No	Durata in minuti
isActive	boolean	No	Attivo/disattivato
requiresPayment	boolean	No	Richiedi pagamento
priceInCents	number	No	Prezzo in centesimi
locationType	string	No	GOOGLE_MEET \| CUSTOM_URL \| IN_PERSON \| PHONE

DELETE/api/v1/calendar/event-types/:idcalendar:write

Elimina un tipo evento. Se ha prenotazioni attive, viene disattivato.

Prenotazioni

GET/api/v1/calendar/bookingscalendar:read

Elenco prenotazioni con filtri e paginazione.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
status	string	No	PENDING \| CONFIRMED \| CANCELLED \| COMPLETED \| NO_SHOW
eventTypeId	string	No	Filtra per tipo evento
search	string	No	Cerca per nome o email ospite
page	number	No	Pagina (default: 1)
pageSize	number	No	Risultati per pagina (default: 20, max: 50)

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/calendar/bookings?status=CONFIRMED&page=1" \
  -H "Authorization: Bearer <token>"

Esempio risposta

{
  "data": [{
    "id": "clx...",
    "status": "CONFIRMED",
    "startTime": "2026-04-10T09:00:00.000Z",
    "endTime": "2026-04-10T09:30:00.000Z",
    "attendeeName": "Mario Rossi",
    "attendeeEmail": "mario@example.com",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "paymentStatus": "NOT_REQUIRED",
    "eventType": {
      "id": "clx...",
      "title": "Consulenza fiscale",
      "duration": 30,
      "color": "#2563eb"
    }
  }],
  "meta": { "page": 1, "pageSize": 20, "total": 5, "totalPages": 1 }
}

GET/api/v1/calendar/bookings/:idcalendar:read

Dettaglio prenotazione con tipo evento e promemoria.

POST/api/v1/calendar/bookings/:id/cancelcalendar:write

Cancella una prenotazione confermata o in attesa. Rimuove evento da Google Calendar.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
reason	string	No	Motivo cancellazione (opzionale)

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/calendar/bookings/clx123/cancel \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Imprevisto"}'

Disponibilita

GET/api/v1/calendar/availabilitycalendar:read

Regole di disponibilita settimanale (7 giorni, Domenica=0).

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/calendar/availability" \
  -H "Authorization: Bearer <token>"

Esempio risposta

{
  "data": [
    { "dayOfWeek": 0, "startTime": "09:00", "endTime": "18:00", "isEnabled": false },
    { "dayOfWeek": 1, "startTime": "09:00", "endTime": "18:00", "isEnabled": true },
    ...
  ]
}

PATCH/api/v1/calendar/availabilitycalendar:write

Aggiorna tutte le regole di disponibilita settimanale. Richiede un array di 7 elementi.

Esempio richiesta

curl -X PATCH https://rest.fiscozone.it/api/v1/calendar/availability \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[
    {"dayOfWeek": 0, "startTime": "09:00", "endTime": "18:00", "isEnabled": false},
    {"dayOfWeek": 1, "startTime": "09:00", "endTime": "18:00", "isEnabled": true},
    {"dayOfWeek": 2, "startTime": "09:00", "endTime": "18:00", "isEnabled": true},
    {"dayOfWeek": 3, "startTime": "09:00", "endTime": "18:00", "isEnabled": true},
    {"dayOfWeek": 4, "startTime": "09:00", "endTime": "18:00", "isEnabled": true},
    {"dayOfWeek": 5, "startTime": "09:00", "endTime": "13:00", "isEnabled": true},
    {"dayOfWeek": 6, "startTime": "09:00", "endTime": "18:00", "isEnabled": false}
  ]'

Override Disponibilita

GET/api/v1/calendar/overridescalendar:read

Lista override disponibilita (ferie, orari speciali).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
from	string	No	Data inizio filtro (YYYY-MM-DD)
to	string	No	Data fine filtro (YYYY-MM-DD)

POST/api/v1/calendar/overridescalendar:write

Crea un override per una data specifica.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
date	string	Si	Data (YYYY-MM-DD)
isUnavailable	boolean	No	Giorno non disponibile (default: true)
startTime	string	No	Orario inizio personalizzato (HH:mm)
endTime	string	No	Orario fine personalizzato (HH:mm)
label	string	No	Etichetta (es. Ferie, Mezza giornata)

PATCH/api/v1/calendar/overrides/:idcalendar:write

Aggiorna un override.

DELETE/api/v1/calendar/overrides/:idcalendar:write

Elimina un override.

Gestione Prenotazioni Avanzata

POST/api/v1/calendar/bookingscalendar:write

Crea una prenotazione manuale (host-initiated).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
eventTypeId	string	Si	ID tipo evento
startTime	string	Si	Data/ora inizio (ISO 8601)
attendeeName	string	Si	Nome ospite
attendeeEmail	string	Si	Email ospite
attendeePhone	string	No	Telefono
hostNotes	string	No	Note interne (solo per l'host)

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/calendar/bookings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"eventTypeId": "clx...", "startTime": "2026-04-10T09:00:00Z", "attendeeName": "Mario Rossi", "attendeeEmail": "mario@example.com"}'

PATCH/api/v1/calendar/bookings/:idcalendar:write

Aggiorna dati prenotazione (note, info ospite).

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
attendeeName	string	No	Nome ospite
attendeeEmail	string	No	Email
attendeePhone	string	No	Telefono
attendeeNotes	string	No	Note dall'ospite
hostNotes	string	No	Note interne

POST/api/v1/calendar/bookings/:id/confirmcalendar:write

Conferma una prenotazione in attesa.

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/calendar/bookings/clx123/confirm \
  -H "Authorization: Bearer <token>"

POST/api/v1/calendar/bookings/:id/meetingcalendar:write

Gestisci il link meeting: crea Google Meet, imposta link custom, o rimuovi.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
action	string	Si	create_meet \| set_custom \| remove
customUrl	string	No	URL personalizzato (richiesto se action=set_custom)

Esempio richiesta

curl -X POST https://rest.fiscozone.it/api/v1/calendar/bookings/clx123/meeting \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action": "create_meet"}'

Partecipanti

GET/api/v1/calendar/bookings/:id/attendeescalendar:read

Lista partecipanti aggiuntivi di una prenotazione.

POST/api/v1/calendar/bookings/:id/attendeescalendar:write

Aggiungi un partecipante. Invia email di invito automaticamente.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
name	string	Si	Nome
email	string	Si	Email
phone	string	No	Telefono

DELETE/api/v1/calendar/bookings/:id/attendees/:attendeeIdcalendar:write

Rimuovi un partecipante dalla prenotazione.

Statistiche

GET/api/v1/calendar/statscalendar:read

Statistiche prenotazioni per mese: totali, confermate, cancellate, ricavi.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
month	number	No	Mese (1-12, default: mese corrente)
year	number	No	Anno (default: anno corrente)

Esempio richiesta

curl "https://rest.fiscozone.it/api/v1/calendar/stats?month=4&year=2026" \
  -H "Authorization: Bearer <token>"

Esempio risposta

{
  "data": {
    "total": 24,
    "confirmed": 18,
    "cancelled": 4,
    "noShow": 2,
    "completionRate": 75,
    "revenueInCents": 45000
  }
}

Prodotti

Catalogo prodotti e servizi.

GET/api/v1/productsinvoices:read

Elenco prodotti.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
search	string	No	Ricerca per nome

POST/api/v1/productsinvoices:write

Crea un nuovo prodotto.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
nome	string	Si	Nome prodotto
prezzoUnitario	number	Si	Prezzo unitario
unitaMisura	string	No	Unita di misura
codiceArticolo	string	No	Codice articolo
aliquotaIva	number	No	Aliquota IVA %

Cespiti

Beni strumentali e ammortamento.

GET/api/v1/assetsexpenses:read

Elenco cespiti con stato ammortamento.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
completati	boolean	No	Filtra cespiti completati/attivi

POST/api/v1/assets/depreciationexpenses:read

Calcola ammortamento per un anno specifico.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
anno	number	Si	Anno di calcolo

POS / Pagamenti

Link di pagamento online tramite Stripe.

GET/api/v1/paymentspos:read

Elenco link di pagamento.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
status	string	No	PENDING \| PAID \| EXPIRED \| CANCELED

POST/api/v1/paymentspos:write

Crea un nuovo link di pagamento.

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
invoiceIds	string[]	Si	ID delle fatture da includere
customerEmail	string	No	Email del cliente
descrizione	string	No	Descrizione

Profilo

Informazioni account e attivita.

GET/api/v1/profileprofile:read

Dati account: email, nome, cognome.

GET/api/v1/profile/businessprofile:read

Dati attivita: P.IVA, regime fiscale, coefficiente, cassa previdenziale.

GET/api/v1/profile/subscriptionprofile:read

Piano di abbonamento attivo e stato.

Errori

Le API restituiscono errori nel formato tRPC standard.

{
  "error": {
    "message": "Fattura non trovata",
    "code": -32004,
    "data": {
      "code": "NOT_FOUND",
      "httpStatus": 404
    }
  }
}

Codice	HTTP	Descrizione
UNAUTHORIZED	401	Token mancante, scaduto o invalido
FORBIDDEN	403	Scope insufficienti per questa operazione
NOT_FOUND	404	Risorsa non trovata
BAD_REQUEST	400	Parametri di input non validi
CONFLICT	409	Conflitto (es. slug duplicato)
TOO_MANY_REQUESTS	429	Limite richieste superato
INTERNAL_SERVER_ERROR	500	Errore interno del server

Rate Limits

Per garantire la stabilita del servizio, le API sono soggette a limiti di frequenza.

Piano	Limite
PRO	100 richieste / minuto
COMPLETE	200 richieste / minuto

Best practices

Usa la paginazione per elenchi grandi (parametri page e pageSize)
Implementa retry con backoff esponenziale per errori 429 e 5xx
Cachea l'access token - non richiederne uno nuovo ad ogni chiamata
Quando ricevi un errore 401, usa il refresh token per rinnovare
Conserva il refresh token in modo sicuro - e valido per 7 giorni
Non conservare la API key nel codice client o repository pubblici