Fatture

Fatture, note di credito, pagamenti ed emissione.

20 endpoint Versione v1 · revisione 2026-10-31

Gli endpoint sono relativi a https://api.officina.it e richiedono l'header Authorization: Bearer con la chiave API e X-API-Version: 2026-10-31. L'header della revisione è obbligatorio: differenza fra v1 e revisione; le novità di ogni revisione sono nell'elenco delle revisioni.

GET /v1/credit-notes
Permesso richiesto invoices.read

Elenca le note di credito

Le note di credito emesse, dalla più recente. Stessa paginazione a cursore dell'elenco fatture.
Risposte
200
Una pagina di note di credito.
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.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
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/credit-notes \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "credit_note",
      "id": "9e5a3d78-1b46-4c02-8f93-7a2d5e1c8b40",
      "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
      "seq_number": 12,
      "title": "Storno parziale tagliando",
      "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
      "sezionale_code": "A",
      "customer_name": "Mario Rossi",
      "vehicle_name": "Fiat Panda",
      "vehicle_license": "AB123CD",
      "sdi_status": "delivered",
      "total_before_tax": 74.0,
      "total_tax": 16.28,
      "total_after_tax": 90.28,
      "created_at": "2026-07-18T09:00:00Z",
      "updated_at": "2026-07-18T09:00:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/credit-notes"
}
POST /v1/credit-notes
Permesso richiesto invoices.write

Crea una nota di credito

Storna una fattura emessa: passa invoice_id e righe e totali vengono ripresi dalla fattura di origine. È il modo corretto di annullare una fattura già emessa, che non è eliminabile.
Risposte
201
La nota di credito creata.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
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 POST https://api.officina.it/v1/credit-notes \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "title": "Storno parziale tagliando"
}'
Risposta
{
  "object": "credit_note",
  "id": "9e5a3d78-1b46-4c02-8f93-7a2d5e1c8b40",
  "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "seq_number": 12,
  "title": "Storno parziale tagliando",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "customer_name": "Mario Rossi",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "sdi_status": "delivered",
  "total_before_tax": 74.0,
  "total_tax": 16.28,
  "total_after_tax": 90.28,
  "created_at": "2026-07-18T09:00:00Z",
  "updated_at": "2026-07-18T09:00:00Z"
}
GET /v1/credit-notes/by-number/{year}/{number}
Permesso richiesto invoices.read

Recupera la nota di credito dal numero

Restituisce la nota di credito con il numero number dell'anno year (anno della nota di credito): lo stesso numero mostrato nell'app, per esempio 12/2026. Le fatture, le note di credito e gli scontrini sono numerati per sezionale: indica sezionale_id (l'id del sezionale, oppure default per la numerazione senza sezionale) per cercare in una sola serie; senza, la ricerca copre tutte le serie. Risponde come il recupero per id. Se il numero corrisponde a più documenti — numeri ripetuti nello storico — restituisce 409 ambiguous_number con gli id in candidates.
dalla revisione 2026-10-04

Nuovo: recupera la nota di credito dal numero e dall'anno.

Risposte
200
La nota di credito, con la stessa risposta del recupero per id.
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.
409
Il numero corrisponde a più documenti: scegli quello giusto tra i `candidates` e recuperalo per id.
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/credit-notes/by-number/{year}/{number} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "credit_note",
  "id": "9e5a3d78-1b46-4c02-8f93-7a2d5e1c8b40",
  "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "seq_number": 12,
  "title": "Storno parziale tagliando",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "customer_name": "Mario Rossi",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "sdi_status": "delivered",
  "total_before_tax": 74.0,
  "total_tax": 16.28,
  "total_after_tax": 90.28,
  "created_at": "2026-07-18T09:00:00Z",
  "updated_at": "2026-07-18T09:00:00Z"
}
GET /v1/credit-notes/{id}
Permesso richiesto invoices.read

Recupera una nota di credito

Restituisce la nota di credito e il riferimento alla fattura stornata (invoice_id).
Risposte
200
La nota di credito 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.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/credit-notes/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "credit_note",
  "id": "9e5a3d78-1b46-4c02-8f93-7a2d5e1c8b40",
  "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "seq_number": 12,
  "title": "Storno parziale tagliando",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "customer_name": "Mario Rossi",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "sdi_status": "delivered",
  "total_before_tax": 74.0,
  "total_tax": 16.28,
  "total_after_tax": 90.28,
  "created_at": "2026-07-18T09:00:00Z",
  "updated_at": "2026-07-18T09:00:00Z"
}
PATCH /v1/credit-notes/{id}
Permesso richiesto invoices.write

Aggiorna una nota di credito

Aggiorna i campi descrittivi. Gli importi derivano dalla fattura di origine e non si modificano da qui.
dalla revisione 2026-10-22

If-Match obbligatorio da questa revisione: senza l'header la richiesta è rifiutata con 428 precondition_required (If-Match: * scrive comunque). Con una version superata risponde 409.

Risposte
200
La nota di credito aggiornata.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
409
Il documento è stato salvato nel frattempo (la `version` di `If-Match` è superata): ricaricalo e riprova. Nulla è stato salvato.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
422
Un campo della richiesta manca o non è valido: «param» indica quale.
428
Manca l'header `If-Match` (obbligatorio dalla revisione 2026-10-22).
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PATCH https://api.officina.it/v1/credit-notes/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Storno tagliando — corretto"
}'
Risposta
{
  "object": "credit_note",
  "id": "9e5a3d78-1b46-4c02-8f93-7a2d5e1c8b40",
  "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "seq_number": 12,
  "title": "Storno parziale tagliando",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "customer_name": "Mario Rossi",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "sdi_status": "delivered",
  "total_before_tax": 74.0,
  "total_tax": 16.28,
  "total_after_tax": 90.28,
  "created_at": "2026-07-18T09:00:00Z",
  "updated_at": "2026-07-18T09:00:00Z"
}
DELETE /v1/credit-notes/{id}
Permesso richiesto invoices.write

Elimina una nota di credito

Eliminazione logica della nota di credito. Una nota di credito la cui controparte elettronica è già stata trasmessa allo SdI non è eliminabile: la richiesta risponde 409. Il documento è ormai un record fiscale e va gestito dal gestionale web.
Risposte
200
La nota di credito eliminata.
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.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X DELETE https://api.officina.it/v1/credit-notes/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "credit_note",
  "id": "9e5a3d78-1b46-4c02-8f93-7a2d5e1c8b40",
  "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "seq_number": 12,
  "title": "Storno parziale tagliando",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "customer_name": "Mario Rossi",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "sdi_status": "delivered",
  "total_before_tax": 74.0,
  "total_tax": 16.28,
  "total_after_tax": 90.28,
  "created_at": "2026-07-18T09:00:00Z",
  "updated_at": "2026-07-18T09:00:00Z",
  "deleted_at": "2026-07-20T11:04:00Z"
}
GET /v1/invoices
Permesso richiesto invoices.read

Elenca le fatture

Le fatture dell'officina, dalla più recente. Filtra per stato con status (draft o issued), per cliente con customer_id e per periodo con from / to. La paginazione usa un cursore opaco: passa next_starting_after invariato in starting_after.
dalla revisione 2026-10-03

Nuovo campo work_category_names: le categorie della scheda lavoro collegata, in ordine.

Risposte
200
Una pagina di fatture.
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.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
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/invoices \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
      "work_category_name": "Tagliando",
      "work_category_names": [
        "Tagliando",
        "Freni"
      ],
      "status": "issued",
      "seq_number": 214,
      "title": "Tagliando 60.000 km",
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "customer_name": "Mario Rossi",
      "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
      "vehicle_name": "Fiat Panda",
      "vehicle_license": "AB123CD",
      "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
      "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
      "sezionale_code": "A",
      "payment_method": "bonifico",
      "payment_due_at": "2026-08-15T00:00:00Z",
      "total_before_tax": 233.9,
      "total_tax": 51.46,
      "total_after_tax": 285.36,
      "total_payments": 150.0,
      "outstanding_payments": 135.36,
      "sdi_status": "delivered",
      "issued_at": "2026-07-16T10:30:00Z",
      "created_at": "2026-07-16T10:12:00Z",
      "updated_at": "2026-07-16T10:30:00Z"
    }
  ],
  "has_more": true,
  "next_starting_after": "eyJvIjoyMH0",
  "url": "/v1/invoices",
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
POST /v1/invoices
Permesso richiesto invoices.write

Crea una fattura

La fattura nasce sempre da una scheda lavoro: passa worksheet_id e righe, totali e anagrafiche vengono copiati da lì. Non esiste un flusso «fattura vuota + aggiungi righe» su questa API. La fattura creata è in stato draft e non ha ancora numero: il numero viene assegnato da POST /v1/invoices/{id}/issue.
Risposte
201
La fattura creata, in bozza.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
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 POST https://api.officina.it/v1/invoices \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "payment_method": "bank_transfer",
  "payment_due_at": "2026-06-30T00:00:00Z"
}'
Risposta
{
  "object": "invoice",
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "work_category_name": "Tagliando",
  "work_category_names": [
    "Tagliando",
    "Freni"
  ],
  "status": "draft",
  "seq_number": 214,
  "title": "Tagliando 60.000 km",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "payment_method": "bonifico",
  "payment_due_at": "2026-08-15T00:00:00Z",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 150.0,
  "outstanding_payments": 135.36,
  "sdi_status": "delivered",
  "issued_at": "2026-07-16T10:30:00Z",
  "created_at": "2026-07-16T10:12:00Z",
  "updated_at": "2026-07-16T10:30:00Z"
}
GET /v1/invoices/by-number/{year}/{number}
Permesso richiesto invoices.read

Recupera la fattura dal numero

Restituisce la fattura con il numero number dell'anno year (anno di emissione): lo stesso numero mostrato nell'app, per esempio 12/2026. Le fatture, le note di credito e gli scontrini sono numerati per sezionale: indica sezionale_id (l'id del sezionale, oppure default per la numerazione senza sezionale) per cercare in una sola serie; senza, la ricerca copre tutte le serie. Risponde come il recupero per id. Se il numero corrisponde a più documenti — numeri ripetuti nello storico — restituisce 409 ambiguous_number con gli id in candidates.
dalla revisione 2026-10-04

Nuovo: recupera la fattura dal numero e dall'anno.

Risposte
200
La fattura, con la stessa risposta del recupero per id.
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.
409
Il numero corrisponde a più documenti: scegli quello giusto tra i `candidates` e recuperalo per id.
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/invoices/by-number/{year}/{number} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "invoice",
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "work_category_name": "Tagliando",
  "work_category_names": [
    "Tagliando",
    "Freni"
  ],
  "status": "issued",
  "seq_number": 214,
  "title": "Tagliando 60.000 km",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "payment_method": "bonifico",
  "payment_due_at": "2026-08-15T00:00:00Z",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 150.0,
  "outstanding_payments": 135.36,
  "sdi_status": "delivered",
  "issued_at": "2026-07-16T10:30:00Z",
  "created_at": "2026-07-16T10:12:00Z",
  "updated_at": "2026-07-16T10:30:00Z",
  "line_items": [
    {
      "object": "invoice_line_item",
      "id": "7c0f6c4e-9b1a-4c2e-9a5d-2f3b1e8a4d10",
      "description": "Olio motore 5W30",
      "quantity": 4,
      "unit_type": "pz",
      "unit_price": 18.5,
      "vat_code": "22",
      "tax_rate": 22,
      "total_before_tax": 74.0,
      "total_tax": 16.28,
      "total_after_tax": 90.28
    }
  ]
}
GET /v1/invoices/payment-counts
Permesso richiesto invoices.read

Conta le fatture per stato di incasso

Quante fatture risultano da incassare (pending) e quante saldate (settled), con gli stessi filtri dell'elenco.
Risposte
200
Il numero di fatture per stato di incasso.
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/invoices/payment-counts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "invoice_payment_counts",
  "pending": 7,
  "settled": 132,
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
GET /v1/invoices/{id}
Permesso richiesto invoices.read

Recupera una fattura

Restituisce la fattura con le righe (line_items) e i totali. Il campo sdi_status riporta lo stato della trasmissione elettronica in sola lettura: l'invio allo SdI non è esposto su questa API.
dalla revisione 2026-10-03

Nuovo campo work_category_names: le categorie della scheda lavoro collegata, in ordine.

Risposte
200
La fattura 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.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/invoices/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "invoice",
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "work_category_name": "Tagliando",
  "work_category_names": [
    "Tagliando",
    "Freni"
  ],
  "status": "issued",
  "seq_number": 214,
  "title": "Tagliando 60.000 km",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "payment_method": "bonifico",
  "payment_due_at": "2026-08-15T00:00:00Z",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 150.0,
  "outstanding_payments": 135.36,
  "sdi_status": "delivered",
  "issued_at": "2026-07-16T10:30:00Z",
  "created_at": "2026-07-16T10:12:00Z",
  "updated_at": "2026-07-16T10:30:00Z",
  "line_items": [
    {
      "object": "invoice_line_item",
      "id": "7c0f6c4e-9b1a-4c2e-9a5d-2f3b1e8a4d10",
      "description": "Olio motore 5W30",
      "quantity": 4,
      "unit_type": "pz",
      "unit_price": 18.5,
      "vat_code": "22",
      "tax_rate": 22,
      "total_before_tax": 74.0,
      "total_tax": 16.28,
      "total_after_tax": 90.28
    }
  ]
}
PATCH /v1/invoices/{id}
Permesso richiesto invoices.write

Aggiorna una fattura

Aggiorna solo i campi presenti nel corpo: gli altri restano invariati, e null svuota il campo. Una fattura già emessa accetta solo modifiche che non incidono sui valori fiscali.
dalla revisione 2026-10-22

If-Match obbligatorio da questa revisione: senza l'header la richiesta è rifiutata con 428 precondition_required (If-Match: * scrive comunque). Con una version superata risponde 409.

Risposte
200
La fattura aggiornata.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
409
Il documento è stato salvato nel frattempo (la `version` di `If-Match` è superata): ricaricalo e riprova. Nulla è stato salvato.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
422
Un campo della richiesta manca o non è valido: «param» indica quale.
428
Manca l'header `If-Match` (obbligatorio dalla revisione 2026-10-22).
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PATCH https://api.officina.it/v1/invoices/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Tagliando completo",
  "comments": null,
  "payment_method": "card",
  "payment_due_at": "2026-07-15T00:00:00Z"
}'
Risposta
{
  "object": "invoice",
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "work_category_name": "Tagliando",
  "work_category_names": [
    "Tagliando",
    "Freni"
  ],
  "status": "issued",
  "seq_number": 214,
  "title": "Tagliando 60.000 km",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "payment_method": "bonifico",
  "payment_due_at": "2026-08-15T00:00:00Z",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 150.0,
  "outstanding_payments": 135.36,
  "sdi_status": "delivered",
  "issued_at": "2026-07-16T10:30:00Z",
  "created_at": "2026-07-16T10:12:00Z",
  "updated_at": "2026-07-16T10:30:00Z",
  "line_items": [
    {
      "object": "invoice_line_item",
      "id": "7c0f6c4e-9b1a-4c2e-9a5d-2f3b1e8a4d10",
      "description": "Olio motore 5W30",
      "quantity": 4,
      "unit_type": "pz",
      "unit_price": 18.5,
      "vat_code": "22",
      "tax_rate": 22,
      "total_before_tax": 74.0,
      "total_tax": 16.28,
      "total_after_tax": 90.28
    }
  ]
}
DELETE /v1/invoices/{id}
Permesso richiesto invoices.write

Elimina una fattura

Eliminazione logica della fattura. Una fattura la cui controparte elettronica è già stata trasmessa allo SdI non è eliminabile: la richiesta risponde 409. In quel caso il documento va stornato con una nota di credito (POST /v1/credit-notes), non eliminato.
Risposte
200
La fattura eliminata.
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.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X DELETE https://api.officina.it/v1/invoices/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "invoice",
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "work_category_name": "Tagliando",
  "work_category_names": [
    "Tagliando",
    "Freni"
  ],
  "status": "issued",
  "seq_number": 214,
  "title": "Tagliando 60.000 km",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "payment_method": "bonifico",
  "payment_due_at": "2026-08-15T00:00:00Z",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 150.0,
  "outstanding_payments": 135.36,
  "sdi_status": "delivered",
  "issued_at": "2026-07-16T10:30:00Z",
  "created_at": "2026-07-16T10:12:00Z",
  "updated_at": "2026-07-16T10:30:00Z",
  "deleted_at": "2026-07-20T11:04:00Z"
}
POST /v1/invoices/{id}/convert-to-scontrino
Permesso richiesto invoices.write

Converti in scontrino

Trasforma la fattura in uno scontrino, mantenendo righe e totali. Attenzione: la risposta è lo scontrino creato, non la fattura — l'oggetto restituito ha object: receipt.
Risposte
201
Lo scontrino generato dalla fattura.
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 -X POST https://api.officina.it/v1/invoices/{id}/convert-to-scontrino \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "receipt",
  "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
  "seq_number": 58,
  "status": "draft",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "created_at": "2026-07-17T08:00:00Z"
}
POST /v1/invoices/{id}/issue
Permesso richiesto invoices.write

Emetti una fattura

Porta la fattura da draft a issued, assegnandole il numero progressivo del sezionale e valorizzando issued_at. È il punto in cui la fattura diventa un documento fiscale: da qui in poi non è più eliminabile. L'emissione non trasmette allo SdI — la trasmissione non è esposta su questa API. Se indicata, issued_at deve cadere tra oggi e 12 giorni fa (fattura immediata, giorni di calendario Europe/Rome), altrimenti 422 su /issued_at.
Risposte
200
La fattura emessa, con numero e data.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
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 POST https://api.officina.it/v1/invoices/{id}/issue \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "issued_at": "2026-05-29T12:00:00Z"
}'
Risposta
{
  "object": "invoice",
  "id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
  "work_category_name": "Tagliando",
  "work_category_names": [
    "Tagliando",
    "Freni"
  ],
  "status": "issued",
  "seq_number": 214,
  "title": "Tagliando 60.000 km",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "sezionale_id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "sezionale_code": "A",
  "payment_method": "bonifico",
  "payment_due_at": "2026-08-15T00:00:00Z",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 150.0,
  "outstanding_payments": 135.36,
  "sdi_status": "delivered",
  "issued_at": "2026-07-16T10:30:00Z",
  "created_at": "2026-07-16T10:12:00Z",
  "updated_at": "2026-07-16T10:30:00Z",
  "line_items": [
    {
      "object": "invoice_line_item",
      "id": "7c0f6c4e-9b1a-4c2e-9a5d-2f3b1e8a4d10",
      "description": "Olio motore 5W30",
      "quantity": 4,
      "unit_type": "pz",
      "unit_price": 18.5,
      "vat_code": "22",
      "tax_rate": 22,
      "total_before_tax": 74.0,
      "total_tax": 16.28,
      "total_after_tax": 90.28
    }
  ]
}
GET /v1/invoices/{id}/payments
Permesso richiesto invoices.read

Elenca i pagamenti della fattura

Gli incassi registrati sulla fattura. Il residuo è outstanding_payments sulla fattura stessa.
Risposte
200
I pagamenti della fattura.
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/invoices/{id}/payments \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "id": "d47c0b58-3e91-42a6-8f05-1b9d6a3e2c74",
      "amount": 150.0,
      "payment_method": "MP05",
      "payment_date": "2026-07-16",
      "created_at": "2026-07-16T10:30:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/invoices/4412e7b9-0c35-4a18-92d7-5b6ea1f38c04/payments"
}
POST /v1/invoices/{id}/payments
Permesso richiesto invoices.write

Registra un pagamento

Registra un incasso sulla fattura. Qui payment_method è un codice ministeriale (MP01 contanti, MP05 bonifico, MP08 carta), a differenza del campo omonimo sulla fattura che è un'etichetta libera. L'importo può essere parziale.
Risposte
201
Il pagamento registrato.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
415
Il Content-Type deve essere application/json e Accept deve accettare JSON.
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 POST https://api.officina.it/v1/invoices/{id}/payments \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 150.0,
  "payment_method": "MP01",
  "payment_date": "2026-07-16"
}'
Risposta
{
  "object": "payment",
  "id": "d47c0b58-3e91-42a6-8f05-1b9d6a3e2c74",
  "amount": 150.0,
  "payment_method": "MP05",
  "payment_date": "2026-07-16",
  "created_at": "2026-07-16T10:30:00Z"
}
DELETE /v1/invoices/{id}/payments/{paymentID}
Permesso richiesto invoices.write

Elimina un pagamento

Rimuove l'incasso e riporta il residuo della fattura al valore precedente.
Risposte
200
Il pagamento eliminato.
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 -X DELETE https://api.officina.it/v1/invoices/{id}/payments/{paymentID} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "payment",
  "id": "d47c0b58-3e91-42a6-8f05-1b9d6a3e2c74",
  "amount": 150.0,
  "payment_method": "MP05",
  "payment_date": "2026-07-16",
  "created_at": "2026-07-16T10:30:00Z"
}
POST /v1/invoices/{id}/unissue
Permesso richiesto invoices.write

Annulla l'emissione di una fattura

Riporta in draft una fattura emessa: azzera seq_number e issued_at e il numero torna libero, quindi la prossima fattura emessa nello stesso sezionale e anno lo riprende. Possibile solo per l'ultima fattura emessa del suo sezionale nel suo anno (anche un anno passato), senza nota di credito e senza fattura elettronica inviata (una bozza mai inviata viene eliminata insieme, i dati SDI restano sul cliente); altrimenti 409. I pagamenti registrati restano collegati. Nessun corpo.
Risposte
200
La fattura tornata in bozza, senza numero né data.
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.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X POST https://api.officina.it/v1/invoices/{id}/unissue \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
GET /v1/sezionali
Permesso richiesto settings.read

Elenca i sezionali

I registri di numerazione configurati dall'officina, da usare per valorizzare sezionale_id. È una voce di Impostazioni, quindi richiede il permesso settings.read.
Risposte
200
I sezionali configurati.
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/sezionali \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "sezionale",
      "id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
      "code": "A",
      "label": "Sezionale principale"
    },
    {
      "object": "sezionale",
      "id": "5a9c2e71-4b83-40df-9126-7e3d1f6a8c25",
      "code": "B",
      "label": "Corrispettivi"
    }
  ],
  "has_more": false,
  "url": "/v1/sezionali"
}