API Report per gestionale officina

GET /v1/dealership-report/{widget}

Permesso richiesto reports.read

Recupera un widget concessionaria

Come GET /v1/report/{widget}, ma per le statistiche della concessionaria. Stessa busta di risposta.

Risposte

200: I dati del widget concessionaria.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
404: La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl https://api.officina.it/v1/dealership-report/{widget} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"

Risposta

{
  "object": "report_widget",
  "widget": "stock_aging",
  "preset": "year",
  "from": "2026-01-01",
  "to": "2026-12-31",
  "data": [
    {
      "label": "0-30 giorni",
      "value": 4
    },
    {
      "label": "31-90 giorni",
      "value": 7
    }
  ]
}

GET /v1/report/{widget}

Permesso richiesto reports.read

Recupera un widget di report

Deprecato dalla revisione 2026-10-19: usa GET /v1/reports/{widget} (Report v2). Dichiarando la revisione 2026-10-19 o successive risponde 410 endpoint_retired. Restituisce i dati di un singolo widget delle statistiche officina. Il nome del widget va nel percorso; l'intervallo si sceglie con preset oppure con from / to. La risposta è una busta uniforme: widget ripete il widget richiesto, preset, from e to riportano l'intervallo effettivamente applicato e data contiene il risultato, la cui forma dipende dal widget.

Risposte

200: I dati del widget richiesto.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
404: La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
422: Un campo della richiesta manca o non è valido: «param» indica quale.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl https://api.officina.it/v1/report/{widget} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"

Risposta

{
  "object": "report_widget",
  "widget": "revenue_by_month",
  "preset": "year",
  "from": "2026-01-01",
  "to": "2026-12-31",
  "data": [
    {
      "label": "2026-06",
      "value": 12480.5
    },
    {
      "label": "2026-07",
      "value": 15230.0
    }
  ]
}

GET /v1/reports/fiscal

Permesso richiesto reports.read

Recupera il profilo fiscale e i periodi IVA

Il profilo fiscale che decide la scheda Fiscale del report: state vale profile (profilo incompleto), forfettario (niente IVA) o full. Solo con full arrivano i periodi di liquidazione (dal più recente) e default_period, l'ultimo periodo chiuso, quello del prossimo F24. Richiede anche prices.read.

dalla revisione 2026-10-19

Nuovo endpoint: profilo fiscale e periodi di liquidazione IVA del report Fiscale.

Risposte

200: Il profilo fiscale.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl https://api.officina.it/v1/reports/fiscal \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"

GET /v1/reports/fiscal/export.zip

Permesso richiesto reports.read

Scarica l'export per il commercialista

Lo stesso zip che scarica il gestionale: i CSV del periodo (separati da ;, UTF-8 con BOM) con documenti emessi, fatture ricevute e pagamenti. files sceglie quali (predefinito: tutti).

dalla revisione 2026-10-19

Nuovo endpoint: zip con i CSV del periodo IVA (documenti emessi, fatture ricevute, pagamenti).

Risposte

200: Il file zip.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
422: Un campo della richiesta manca o non è valido: «param» indica quale.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl https://api.officina.it/v1/reports/fiscal/export.zip \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"

PUT /v1/reports/fiscal/profile

Permesso richiesto reports.write

Salva il profilo fiscale

Salva il profilo con le stesse regole del gestionale e risponde come GET /v1/reports/fiscal. Un profilo incompleto non si salva: manca fiscal_regime, o vat_settlement_period per un regime diverso dal forfettario (422 parameter_missing). Se l'officina ha la fatturazione elettronica configurata, il regime resta quello delle sue impostazioni. Richiede anche settings_company.read.

dalla revisione 2026-10-19

Nuovo endpoint: salva regime fiscale, periodicità IVA e metodo dell'acconto.

Risposte

200: Salvato: il profilo e i suoi periodi.
400: Corpo della richiesta non leggibile o JSON non valido.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
422: Un campo della richiesta manca o non è valido: «param» indica quale.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl -X PUT https://api.officina.it/v1/reports/fiscal/profile \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "fiscal_regime": "RF01",
  "vat_settlement_period": "quarterly",
  "vat_advance_method": "storico"
}'

GET /v1/reports/fiscal/{widget}

Permesso richiesto reports.read

Recupera una card del report Fiscale

Una card della scheda Fiscale per un periodo di liquidazione (period, da GET /v1/reports/fiscal). kpis e iva portano la stessa liquidazione (VATSummary). Nascosta (visible: false) finché il profilo non è completo e per il forfettario. Richiede anche prices.read.

dalla revisione 2026-10-19

Nuovo endpoint: liquidazione IVA, aliquote, storico, acconto, scadenze ed export del periodo.

Risposte

200: La card richiesta.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
404: La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl https://api.officina.it/v1/reports/fiscal/{widget} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"

Risposta

{
  "object": "report_fiscal_widget",
  "widget": "kpis",
  "period": {
    "key": "2026-Q3",
    "label": "3° trimestre 2026",
    "from": "2026-07-01",
    "to": "2026-09-30",
    "current": false,
    "due_date": "2026-11-16",
    "due_code": "6033"
  },
  "visible": true,
  "data": {
    "debit": 4820.4,
    "credit": 1210.1,
    "balance": 3610.3,
    "interest": 36.1,
    "to_pay": 3646.4,
    "status": "due",
    "quarterly": true,
    "sales_documents": 61,
    "purchase_documents": 18,
    "split_payment": 0,
    "due_date": "2026-11-16",
    "due_code": "6033",
    "days_until_due": 28
  }
}

GET /v1/reports/{widget}

Permesso richiesto reports.read

Recupera una card del report

Restituisce i dati di una card del report, gli stessi che mostra la pagina Report del gestionale (schede Officina ed Economico). Ogni card è una richiesta a sé. L'intervallo si sceglie con preset oppure from / to (senza parametri: ultimi 12 mesi); grain sceglie settimane o mesi nei grafici (predefinito: settimane fino a 62 giorni, mesi oltre). Una card che per l'officina o il periodo non ha niente da mostrare risponde con visible: false e data: null: va nascosta. Gli importi sono in euro, IVA esclusa salvo dove il campo dice altrimenti; un campo null indica un valore non significativo (nessun periodo precedente, sotto la soglia minima, permesso mancante). Permessi: le card con importi richiedono anche prices.read; quote-funnel richiede quotes.read, top-customers-fatturato anche customers.read, le card dei tempi settings_company.read. In receivables i nomi dei debitori compaiono solo con customers.read (debtors_shown).

dalla revisione 2026-10-19

Nuovo endpoint: le card del report Officina ed Economico, con gli stessi dati della pagina Report del gestionale. Sostituisce GET /v1/report/{widget}.

Risposte

200: La card richiesta, visibile o nascosta.
401: Chiave API mancante, non valida, revocata o scaduta.
402: Il piano non include l'accesso API, oppure non è attivo un abbonamento.
403: La chiave non ha il permesso richiesto per questa operazione.
404: La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
422: Un campo della richiesta manca o non è valido: «param» indica quale.
500: Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.

Richiesta

curl https://api.officina.it/v1/reports/{widget} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"

Risposta

{
  "object": "report_widget",
  "widget": "economico-kpis",
  "tab": "economico",
  "preset": "rel365",
  "from": "2025-10-19",
  "to": "2026-10-19",
  "grain": "month",
  "visible": true,
  "data": {
    "ever_issued": true,
    "fatturato": {
      "total": 48210.5,
      "previous_total": 41890,
      "delta_percent": 15.1,
      "documents": 212
    },
    "incassato": {
      "total": 51340.2,
      "payments": 240,
      "last_year_total": 47100,
      "last_year_payments": 221,
      "delta_percent": 9
    },
    "margine": {
      "state": "shown",
      "value": 19210.5,
      "percent_of_fatturato": 39.8
    },
    "receivables": {
      "total": 6420,
      "invoices": 14,
      "overdue": 2110
    }
  }
}