Scontrini

Scontrini e relativi pagamenti.

9 endpoint Versione v1 · revisione 2026-07-20

Gli endpoint sono relativi a https://api.officina.it e richiedono l'header Authorization: Bearer con la chiave API e X-API-Version: 2026-07-20. L'header della revisione è obbligatorio: differenza fra v1 e revisione.

GET /v1/receipts
Permesso richiesto receipts.read

Elenca gli scontrini

Gli scontrini dell'officina, dal più recente. Filtra per cliente con q e per periodo con from / to. A differenza degli altri elenchi questo non è paginato: restituisce tutti gli scontrini del periodo e has_more è sempre false.
Risposte
200
Una pagina di scontrini.
401
Chiave API mancante, non valida, revocata o scaduta.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/receipts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "receipt",
      "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
      "type": "issued",
      "status": "sale",
      "seq_number": 58,
      "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": "B",
      "payment_method": "MP01",
      "total_before_tax": 233.9,
      "total_tax": 51.46,
      "total_after_tax": 285.36,
      "total_payments": 285.36,
      "outstanding_payments": 0,
      "electronic_receipts_enabled": false,
      "e_receipt_status": null,
      "issued_at": "2026-07-17T08:20:00Z",
      "voided_at": null,
      "created_at": "2026-07-17T08:00:00Z",
      "updated_at": "2026-07-17T08:20:00Z"
    }
  ],
  "has_more": true,
  "next_starting_after": "eyJvIjoyMH0",
  "url": "/v1/receipts",
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
POST /v1/receipts
Permesso richiesto receipts.write

Crea uno scontrino

Lo scontrino nasce sempre da una scheda lavoro: passa worksheet_id e righe, totali e anagrafiche vengono copiati da lì. Una scheda lavoro può generare un solo scontrino: se ne esiste già uno la richiesta risponde 409.
Risposte
201
Lo scontrino creato, in bozza.
400
Corpo della richiesta non leggibile o JSON non valido.
401
Chiave API mancante, non valida, revocata o scaduta.
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/receipts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "worksheet_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
  "payment_method": "MP01"
}'
Risposta
{
  "object": "receipt",
  "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
  "type": "draft",
  "status": "sale",
  "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": "B",
  "payment_method": "MP01",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 285.36,
  "outstanding_payments": 0,
  "electronic_receipts_enabled": false,
  "e_receipt_status": null,
  "voided_at": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:20:00Z",
  "seq_number": null,
  "issued_at": null
}
GET /v1/receipts/{id}
Permesso richiesto receipts.read

Recupera uno scontrino

Restituisce lo scontrino con le righe (line_items) e i totali. Il campo type è derivato e vale draft, issued o voided.
Risposte
200
Lo scontrino richiesto.
401
Chiave API mancante, non valida, revocata o scaduta.
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/receipts/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "receipt",
  "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
  "type": "issued",
  "status": "sale",
  "seq_number": 58,
  "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": "B",
  "payment_method": "MP01",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 285.36,
  "outstanding_payments": 0,
  "electronic_receipts_enabled": false,
  "e_receipt_status": null,
  "issued_at": "2026-07-17T08:20:00Z",
  "voided_at": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:20:00Z",
  "line_items": [
    {
      "object": "receipt_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_price": 74.0
    }
  ]
}
PATCH /v1/receipts/{id}
Permesso richiesto receipts.write

Aggiorna uno scontrino

Modifica i campi descrittivi di uno scontrino ancora in bozza. Aggiorna solo i campi presenti nel corpo: gli altri restano invariati.
Risposte
200
Lo scontrino aggiornato.
401
Chiave API mancante, non valida, revocata o scaduta.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
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 PATCH https://api.officina.it/v1/receipts/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Scontrino tagliando",
  "payment_method": "MP08"
}'
Risposta
{
  "object": "receipt",
  "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
  "type": "draft",
  "status": "sale",
  "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": "B",
  "payment_method": "MP01",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 285.36,
  "outstanding_payments": 0,
  "electronic_receipts_enabled": false,
  "e_receipt_status": null,
  "voided_at": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:20:00Z",
  "seq_number": null,
  "issued_at": null,
  "line_items": [
    {
      "object": "receipt_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_price": 74.0
    }
  ]
}
DELETE /v1/receipts/{id}
Permesso richiesto receipts.write

Elimina uno scontrino

Eliminazione logica, possibile finché lo scontrino è in bozza. Uno scontrino già emesso va prima annullato dal gestionale web: l'annullamento non è esposto su questa API.
Risposte
200
Lo scontrino eliminato.
401
Chiave API mancante, non valida, revocata o scaduta.
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/receipts/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "receipt",
  "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
  "type": "draft",
  "status": "sale",
  "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": "B",
  "payment_method": "MP01",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 285.36,
  "outstanding_payments": 0,
  "electronic_receipts_enabled": false,
  "e_receipt_status": null,
  "voided_at": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:20:00Z",
  "seq_number": null,
  "issued_at": null,
  "deleted_at": "2026-07-20T11:04:00Z"
}
POST /v1/receipts/{id}/issue
Permesso richiesto receipts.write

Emetti uno scontrino

Assegna il numero progressivo e valorizza issued_at. Vale solo per la numerazione cartacea: se l'officina ha i corrispettivi elettronici attivi (electronic_receipts_enabled) la richiesta risponde 409, perché in quel caso l'emissione passa dal registratore telematico e non da questa API.
Risposte
200
Lo scontrino emesso, con numero e data.
401
Chiave API mancante, non valida, revocata o scaduta.
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/receipts/{id}/issue \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 150.0,
  "payment_method": "MP01",
  "payment_date": "2026-07-16"
}'
Risposta
{
  "object": "receipt",
  "id": "3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19",
  "type": "issued",
  "status": "sale",
  "seq_number": 58,
  "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": "B",
  "payment_method": "MP01",
  "total_before_tax": 233.9,
  "total_tax": 51.46,
  "total_after_tax": 285.36,
  "total_payments": 285.36,
  "outstanding_payments": 0,
  "electronic_receipts_enabled": false,
  "e_receipt_status": null,
  "issued_at": "2026-07-17T08:20:00Z",
  "voided_at": null,
  "created_at": "2026-07-17T08:00:00Z",
  "updated_at": "2026-07-17T08:20:00Z",
  "line_items": [
    {
      "object": "receipt_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_price": 74.0
    }
  ]
}
GET /v1/receipts/{id}/payments
Permesso richiesto receipts.read

Elenca i pagamenti dello scontrino

Gli incassi registrati sullo scontrino. Il residuo è outstanding_payments sullo scontrino stesso.
Risposte
200
I pagamenti dello scontrino.
401
Chiave API mancante, non valida, revocata o scaduta.
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/receipts/{id}/payments \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "id": "d47c0b58-3e91-42a6-8f05-1b9d6a3e2c74",
      "amount": 285.36,
      "payment_method": "MP01",
      "payment_date": "2026-07-17",
      "created_at": "2026-07-17T08:20:00Z"
    }
  ],
  "has_more": false,
  "next_starting_after": null,
  "url": "/v1/receipts/3d7f1b95-6c28-4a04-9e51-8b2f7a3c6d19/payments"
}
POST /v1/receipts/{id}/payments
Permesso richiesto receipts.write

Registra un pagamento

Registra un incasso sullo scontrino. payment_method usa i codici ministeriali (MP01 contanti, MP05 bonifico, MP08 carta); se omesso vale quello dello scontrino. 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.
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/receipts/{id}/payments \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -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": 285.36,
  "payment_method": "MP01",
  "payment_date": "2026-07-17",
  "created_at": "2026-07-17T08:20:00Z"
}
DELETE /v1/receipts/{id}/payments/{paymentID}
Permesso richiesto receipts.write

Elimina un pagamento

Rimuove l'incasso e riporta il residuo dello scontrino al valore precedente.
Risposte
200
Il pagamento eliminato.
401
Chiave API mancante, non valida, revocata o scaduta.
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/receipts/{id}/payments/{paymentID} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "payment",
  "id": "d47c0b58-3e91-42a6-8f05-1b9d6a3e2c74",
  "amount": 285.36,
  "payment_method": "MP01",
  "payment_date": "2026-07-17",
  "created_at": "2026-07-17T08:20:00Z"
}