Veicoli

Veicoli, marche e documenti allegati.

14 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/manufacturers
Permesso richiesto vehicles.read

Elenca le marche attive

Le marche selezionate dall'officina, da usare per popolare manufacturer_id in fase di creazione o modifica di un veicolo. L'elenco è breve e non paginato: has_more è sempre false.
Risposte
200
Le marche attive dell'officina.
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/manufacturers \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "manufacturer",
      "id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
      "name": "Fiat"
    },
    {
      "object": "manufacturer",
      "id": "9a4c2e70-6b18-4d3f-a5c9-1e8b7d0f2a46",
      "name": "Volkswagen"
    }
  ],
  "has_more": false,
  "next_starting_after": null,
  "url": "/v1/manufacturers"
}
PUT /v1/manufacturers
Permesso richiesto settings.write

Imposta le marche attive

Sostituisce l'intero insieme delle marche attive dell'officina: le marche non elencate vengono disattivate. new_names crea al volo le marche non presenti a catalogo. Almeno una marca deve restare attiva. Richiede il permesso settings.write.
Risposte
200
Le marche ora attive.
401
Chiave API mancante, non valida, revocata o scaduta.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PUT https://api.officina.it/v1/manufacturers \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
    "9a4c2e70-6b18-4d3f-a5c9-1e8b7d0f2a46"
  ],
  "new_names": [
    "Ligier"
  ]
}'
Risposta
{
  "object": "manufacturers",
  "ids": [
    "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
    "9a4c2e70-6b18-4d3f-a5c9-1e8b7d0f2a46"
  ]
}
GET /v1/manufacturers/catalog
Permesso richiesto settings.read

Catalogo completo delle marche

Tutte le marche disponibili, con selected a indicare quelle attive per l'officina e vehicle_count a indicare quanti veicoli le usano. È la vista dietro Impostazioni -> Marche veicolo, quindi richiede il permesso settings.read.
Risposte
200
Il catalogo completo delle marche.
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/manufacturers/catalog \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "manufacturer_catalog_entry",
      "id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
      "name": "Fiat",
      "selected": true,
      "vehicle_count": 128
    },
    {
      "object": "manufacturer_catalog_entry",
      "id": "9a4c2e70-6b18-4d3f-a5c9-1e8b7d0f2a46",
      "name": "Volkswagen",
      "selected": true,
      "vehicle_count": 41
    },
    {
      "object": "manufacturer_catalog_entry",
      "id": "2f6d8b31-7c05-4a92-9e4d-3b1a6c8f5d20",
      "name": "Zastava",
      "selected": false,
      "vehicle_count": 0
    }
  ],
  "has_more": false,
  "next_starting_after": null,
  "url": "/v1/manufacturers/catalog"
}
GET /v1/vehicles
Permesso richiesto vehicles.read

Elenca i veicoli

Restituisce i veicoli dell'officina, dal più recente. Filtra per testo con q (modello o targa) e per proprietario con customer_id. La paginazione usa un cursore opaco: passa next_starting_after invariato in starting_after per la pagina successiva e usa has_more per sapere se fermarti.
Risposte
200
Una pagina di veicoli.
401
Chiave API mancante, non valida, revocata o scaduta.
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/vehicles \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "vehicle",
      "id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
      "license": "AB123CD",
      "manufacturer_id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
      "manufacturer_name": "Fiat",
      "model": "Panda",
      "variant": "1.2 Lounge",
      "vin": "ZFA31200003456789",
      "transmission": "manuale",
      "engine_power_kw": 51,
      "engine_displacement_ccm": 1242,
      "engine_category": "Euro 6",
      "registered_at": "2019-06-12T00:00:00Z",
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "customer_name": "Mario Rossi",
      "km": 84210,
      "km_registered_at": "2026-07-14T09:12:00Z",
      "last_inspection_at": "2025-06-01T00:00:00Z",
      "next_inspection_at": "2027-06-01T00:00:00Z",
      "is_rental": false,
      "created_at": "2024-03-02T10:14:33Z",
      "updated_at": "2026-07-14T09:12:00Z"
    }
  ],
  "has_more": true,
  "next_starting_after": "eyJvIjoyMH0",
  "url": "/v1/vehicles"
}
POST /v1/vehicles
Permesso richiesto vehicles.write

Crea un veicolo

Crea un veicolo. Sono obbligatori manufacturer_id e model; la marca deve essere fra quelle attive per l'officina (vedi GET /v1/manufacturers). Collega il veicolo a un cliente con customer_id: può restare vuoto e venire assegnato in seguito.
Risposte
201
Il veicolo creato.
400
Corpo della richiesta non leggibile o JSON non valido.
401
Chiave API mancante, non valida, revocata o scaduta.
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/vehicles \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "manufacturer_id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
  "model": "Panda",
  "license": "AB123CD",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "km": 84210.5
}'
Risposta
{
  "object": "vehicle",
  "id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
  "license": "AB123CD",
  "manufacturer_id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
  "manufacturer_name": "Fiat",
  "model": "Panda",
  "variant": "1.2 Lounge",
  "vin": "ZFA31200003456789",
  "transmission": "manuale",
  "engine_power_kw": 51,
  "engine_displacement_ccm": 1242,
  "engine_category": "Euro 6",
  "registered_at": "2019-06-12T00:00:00Z",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "km": 84210,
  "km_registered_at": "2026-07-14T09:12:00Z",
  "last_inspection_at": "2025-06-01T00:00:00Z",
  "next_inspection_at": "2027-06-01T00:00:00Z",
  "is_rental": false,
  "created_at": "2024-03-02T10:14:33Z",
  "updated_at": "2026-07-14T09:12:00Z"
}
GET /v1/vehicles/{id}
Permesso richiesto vehicles.read

Recupera un veicolo

Restituisce un singolo veicolo. Rispetto all'elenco include anche i documenti allegati, i campi personalizzati risolti (custom_field_values) e il primo appuntamento in agenda (next_appointment).
Risposte
200
Il veicolo richiesto.
401
Chiave API mancante, non valida, revocata o scaduta.
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/vehicles/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "vehicle",
  "id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
  "license": "AB123CD",
  "manufacturer_id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
  "manufacturer_name": "Fiat",
  "model": "Panda",
  "variant": "1.2 Lounge",
  "vin": "ZFA31200003456789",
  "transmission": "manuale",
  "engine_power_kw": 51,
  "engine_displacement_ccm": 1242,
  "engine_category": "Euro 6",
  "registered_at": "2019-06-12T00:00:00Z",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "km": 84210,
  "km_registered_at": "2026-07-14T09:12:00Z",
  "last_inspection_at": "2025-06-01T00:00:00Z",
  "next_inspection_at": "2027-06-01T00:00:00Z",
  "is_rental": false,
  "created_at": "2024-03-02T10:14:33Z",
  "updated_at": "2026-07-14T09:12:00Z",
  "next_appointment": null,
  "comments": "Cliente chiede sempre olio Selenia.",
  "documents": [
    {
      "object": "vehicle_document",
      "id": "e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64",
      "name": "libretto.pdf",
      "content_type": "application/pdf",
      "file_size_bytes": 148213,
      "url": "/v1/vehicles/7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47/documents/e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64/download",
      "created_at": "2026-07-14T09:20:11Z"
    }
  ]
}
PATCH /v1/vehicles/{id}
Permesso richiesto vehicles.write

Aggiorna un veicolo

Aggiorna solo i campi presenti nel corpo della richiesta: i campi omessi restano invariati. Per svuotare un campo passalo esplicitamente a null.
Risposte
200
Il veicolo aggiornato.
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.
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 PATCH https://api.officina.it/v1/vehicles/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "license": "EF456GH",
  "km": 90100,
  "customer_id": null
}'
Risposta
{
  "object": "vehicle",
  "id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
  "license": "AB123CD",
  "manufacturer_id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
  "manufacturer_name": "Fiat",
  "model": "Panda",
  "variant": "1.2 Lounge",
  "vin": "ZFA31200003456789",
  "transmission": "manuale",
  "engine_power_kw": 51,
  "engine_displacement_ccm": 1242,
  "engine_category": "Euro 6",
  "registered_at": "2019-06-12T00:00:00Z",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "km": 84210,
  "km_registered_at": "2026-07-14T09:12:00Z",
  "last_inspection_at": "2025-06-01T00:00:00Z",
  "next_inspection_at": "2027-06-01T00:00:00Z",
  "is_rental": false,
  "created_at": "2024-03-02T10:14:33Z",
  "updated_at": "2026-07-14T09:12:00Z",
  "next_appointment": null,
  "comments": "Cliente chiede sempre olio Selenia.",
  "documents": [
    {
      "object": "vehicle_document",
      "id": "e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64",
      "name": "libretto.pdf",
      "content_type": "application/pdf",
      "file_size_bytes": 148213,
      "url": "/v1/vehicles/7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47/documents/e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64/download",
      "created_at": "2026-07-14T09:20:11Z"
    }
  ]
}
DELETE /v1/vehicles/{id}
Permesso richiesto vehicles.write

Elimina un veicolo

Eliminazione logica: il veicolo sparisce dagli elenchi ma i documenti già emessi che lo citano restano intatti.
Risposte
200
Il veicolo 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/vehicles/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "vehicle",
  "id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
  "license": "AB123CD",
  "manufacturer_id": "c3d9e8f1-4a72-4b60-8e15-9d2f7c4a6b83",
  "manufacturer_name": "Fiat",
  "model": "Panda",
  "variant": "1.2 Lounge",
  "vin": "ZFA31200003456789",
  "transmission": "manuale",
  "engine_power_kw": 51,
  "engine_displacement_ccm": 1242,
  "engine_category": "Euro 6",
  "registered_at": "2019-06-12T00:00:00Z",
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "km": 84210,
  "km_registered_at": "2026-07-14T09:12:00Z",
  "last_inspection_at": "2025-06-01T00:00:00Z",
  "next_inspection_at": "2027-06-01T00:00:00Z",
  "is_rental": false,
  "created_at": "2024-03-02T10:14:33Z",
  "updated_at": "2026-07-14T09:12:00Z",
  "deleted_at": "2026-07-20T11:04:00Z"
}
GET /v1/vehicles/{id}/checkins
Permesso richiesto checkins.read

Storico accettazioni del veicolo

Le accettazioni registrate per il veicolo, dalla più recente. Richiede il permesso checkins.read.
Risposte
200
Le accettazioni del veicolo.
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/vehicles/{id}/checkins \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "checkin",
      "id": "1c7a9e04-5f83-4b26-8d10-6e2b4a9c7f31",
      "status": "convertita",
      "vehicle_id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "created_at": "2026-05-17T16:44:00Z"
    }
  ],
  "has_more": false,
  "next_starting_after": null,
  "url": "/v1/vehicles/7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47/checkins"
}
POST /v1/vehicles/{id}/documents
Permesso richiesto vehicles.write

Allega un documento al veicolo

Carica un file fra i Documenti Allegati del veicolo. La richiesta e' multipart/form-data con il file nel campo file, non JSON.
Risposte
201
Il documento allegato.
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/vehicles/{id}/documents \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -F "file=@/percorso/documento.pdf"
Risposta
{
  "object": "vehicle_document",
  "id": "e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64",
  "name": "libretto.pdf",
  "content_type": "application/pdf",
  "description": "Carta di circolazione",
  "file_size_bytes": 148213,
  "url": "/v1/vehicles/7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47/documents/e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64/download",
  "created_at": "2026-07-14T09:20:11Z"
}
DELETE /v1/vehicles/{id}/documents/{documentID}
Permesso richiesto vehicles.write

Elimina un documento del veicolo

Rimuove definitivamente il file allegato.
Risposte
200
Il documento 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/vehicles/{id}/documents/{documentID} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "vehicle_document",
  "id": "e2a4b6c8-1d3f-4059-b7e8-2c9a5d1f3b64",
  "name": "libretto.pdf",
  "content_type": "application/pdf",
  "file_size_bytes": 148213,
  "created_at": "2026-07-14T09:20:11Z"
}
GET /v1/vehicles/{id}/documents/{documentID}/download
Permesso richiesto vehicles.read

Scarica un documento del veicolo

Restituisce il contenuto del file, non JSON. È il percorso indicato dal campo url di ogni documento.
Risposte
200
The file bytes.
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/vehicles/{id}/documents/{documentID}/download \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
GET /v1/vehicles/{id}/quotes
Permesso richiesto quotes.read

Storico preventivi del veicolo

I preventivi collegati al veicolo, dal più recente. Richiede il permesso quotes.read.
Risposte
200
I preventivi del veicolo.
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/vehicles/{id}/quotes \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "quote",
      "id": "8d3f5b92-2a71-4c08-9e6b-1f4a7d0c3e85",
      "seq_number": 87,
      "status": "accettato",
      "vehicle_id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "total_after_tax": 310.0,
      "created_at": "2026-04-02T11:05:00Z"
    }
  ],
  "has_more": false,
  "next_starting_after": null,
  "url": "/v1/vehicles/7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47/quotes"
}
GET /v1/vehicles/{id}/worksheets
Permesso richiesto worksheets.read

Storico schede lavoro del veicolo

Le schede lavoro del veicolo, dalla più recente. Restituisce schede lavoro, quindi richiede il permesso worksheets.read e non vehicles.read.
Risposte
200
Le schede lavoro del veicolo.
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/vehicles/{id}/worksheets \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "worksheet",
      "id": "5e8c1a37-9d24-4f60-b3a8-7c2e9f1d4b05",
      "seq_number": 412,
      "status": "completata",
      "vehicle_id": "7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47",
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "customer_name": "Mario Rossi",
      "total_after_tax": 285.4,
      "created_at": "2026-05-18T08:30:00Z"
    }
  ],
  "has_more": false,
  "next_starting_after": null,
  "url": "/v1/vehicles/7b1f4a92-3c8d-4e15-9a20-5f6c8d3e1b47/worksheets"
}