Impostazioni

Dati azienda, aliquote IVA, listini, collaboratori, cestino.

20 endpoint Versione v1 · revisione 2026-11-02

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

GET /v1/company
Permesso richiesto settings.read

Recupera i dati azienda

L'anagrafica dell'officina e le preferenze che governano i documenti: metodo di pagamento predefinito, colore, IBAN, se i prezzi sono IVA inclusa. fiscal_fields_locked indica che partita IVA e codice fiscale non sono più modificabili perché sono già stati usati su un documento fiscale.
Risposte
200
I dati dell'azienda.
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/company \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "company_profile",
  "id": "1f8c4e73-2a95-4b06-9d31-7e5a2c8b6f40",
  "name": "Officina Rossi S.r.l.",
  "entity_type": "societa",
  "company_type": "officina",
  "tax_id": "01234567890",
  "fiscal_code": "RSSMRA80A01F205X",
  "email": "info@officinarossi.example.it",
  "phone": "+390212345678",
  "address": "Via Mecenate 12",
  "city": "Milano",
  "zip_code": "20138",
  "province": "MI",
  "fiscal_fields_locked": true,
  "primary_color": "#2563eb",
  "default_payment_method": "MP05",
  "bank_account_holder": "Officina Rossi S.r.l.",
  "line_items_including_vat": false,
  "worksheet_km_required": true,
  "waste_disposal_enabled": true,
  "waste_disposal_rate": 1.2,
  "waste_disposal_base": "articles",
  "waste_disposal_description": "Smaltimento rifiuti"
}
GET /v1/customer-field-settings
Permesso richiesto settings.read

Recupera i campi cliente

Quali campi facoltativi della scheda cliente sono visibili (data di nascita e note interne), quali campi personalizzati sono definiti (con le options dei campi list), quali campi data generano un evento in agenda (reminder_days_before) e se il compleanno dei clienti viene messo in agenda (birthday_calendar_event).
Risposte
200
La configurazione dei campi cliente.
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/customer-field-settings \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "customer_field_settings",
  "field_visibility": {
    "birthday": true,
    "comments": true
  },
  "birthday_calendar_event": true,
  "custom_fields": [
    {
      "id": "cf_4c1e7a",
      "name": "Professione",
      "type": "string",
      "visible": true,
      "order": 1,
      "reminder_days_before": null
    },
    {
      "id": "cf_9b20d3",
      "name": "Scadenza patente",
      "type": "datetime",
      "visible": true,
      "order": 2,
      "reminder_days_before": 0
    },
    {
      "id": "cf_7d14e2",
      "name": "Fonte contatto",
      "type": "list",
      "options": [
        "Passaparola",
        "Google",
        "Social",
        "Volantino"
      ],
      "visible": true,
      "order": 3,
      "reminder_days_before": null
    }
  ]
}
PUT /v1/customer-field-settings
Permesso richiesto settings.write

Imposta i campi cliente

Crea, modifica, riordina ed elimina i campi personalizzati dei clienti, aggiorna la visibilità dei campi facoltativi e l'evento di compleanno in agenda, in un'unica chiamata. custom_fields è l'elenco completo: un campo con id modifica quello esistente (i valori salvati sui clienti restano), un campo senza id ne crea uno nuovo, un campo non elencato viene eliminato. L'ordine dell'array è l'ordine di visualizzazione. Se custom_fields è assente la configurazione dei campi non cambia. Ciò che il corpo omette viene conservato, non azzerato: una chiave assente in field_visibility, un birthday_calendar_event assente e, su un campo esistente, visible o reminder_days_before assenti mantengono l'impostazione salvata. Solo data di nascita e note interne possono essere nascoste: i campi fiscali e quelli legati a listini e fatturazione elettronica sono sempre visibili. Un campo nascosto non genera eventi in agenda, qualunque sia la sua impostazione (che resta salvata e torna attiva quando il campo viene mostrato di nuovo): con field_visibility.birthday a false non vengono creati eventi di compleanno anche se birthday_calendar_event è true. Gli eventi in agenda gia' creati non vengono toccati: spegnere un evento o nascondere un campo cambia solo cosa succede al prossimo salvataggio di un cliente. Un campo list (dalla revisione 2026-10-22) è un menu a tendina: options elenca le voci nell'ordine scelto (da 1 a 20, ognuna di 1–30 caratteri) e il valore salvato sul cliente è una di esse. Su un campo già list, options assente mantiene le voci salvate (come visible); un campo che diventa list deve indicarle; su un campo di altro tipo options è rifiutato.
Risposte
200
La configurazione 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.
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/customer-field-settings \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "field_visibility": {
    "birthday": true,
    "comments": true
  },
  "birthday_calendar_event": false,
  "custom_fields": [
    {
      "id": "cf_4c1e7a",
      "name": "Professione",
      "type": "string"
    },
    {
      "name": "Scadenza patente",
      "type": "datetime",
      "reminder_days_before": 0
    },
    {
      "name": "Fonte contatto",
      "type": "list",
      "options": [
        "Passaparola",
        "Google",
        "Social",
        "Volantino"
      ]
    }
  ]
}'
Risposta
{
  "object": "customer_field_settings",
  "field_visibility": {
    "birthday": true,
    "comments": true
  },
  "birthday_calendar_event": false,
  "custom_fields": [
    {
      "id": "cf_4c1e7a",
      "name": "Professione",
      "type": "string",
      "visible": true,
      "order": 1,
      "reminder_days_before": null
    },
    {
      "id": "cf_9b20d3",
      "name": "Scadenza patente",
      "type": "datetime",
      "visible": true,
      "order": 2,
      "reminder_days_before": 0
    },
    {
      "id": "cf_7d14e2",
      "name": "Fonte contatto",
      "type": "list",
      "options": [
        "Passaparola",
        "Google",
        "Social",
        "Volantino"
      ],
      "visible": true,
      "order": 3,
      "reminder_days_before": null
    }
  ]
}
GET /v1/price-lists
Permesso richiesto settings.read

Elenca i listini

I listini configurati, applicabili ai clienti per ottenere prezzi o sconti dedicati. discount_rate è lo sconto generale (intero 1-99, null = nessuno): proposto come sconto di riga sugli articoli e sulla manodopera presi dal catalogo senza un prezzo o uno sconto dedicato nel listino. Non si applica alle righe scritte a mano, agli scontrini e ai noleggi.
Risposte
200
I listini 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/price-lists \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "price_list",
      "id": "9c5e1a83-6b24-4d70-8f39-2a7c4e1b8d56",
      "name": "Listino flotte",
      "discount_rate": 10,
      "customers_count": 12,
      "overrides_count": 3
    }
  ],
  "has_more": false,
  "url": "/v1/price-lists"
}
POST /v1/price-lists
Permesso richiesto settings.write

Crea un listino

Crea un listino prezzi.
Risposte
201
Il listino creato.
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 POST https://api.officina.it/v1/price-lists \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Listino flotte",
  "discount_rate": 10
}'
Risposta
{
  "object": "price_list",
  "id": "9c5e1a83-6b24-4d70-8f39-2a7c4e1b8d56",
  "name": "Listino flotte",
  "discount_rate": 10
}
PATCH /v1/price-lists/{id}
Permesso richiesto settings.write

Aggiorna un listino

Aggiorna nome e/o sconto generale del listino. Un campo omesso resta com'è; discount_rate: null toglie lo sconto generale. Le righe già nei documenti non cambiano.
Risposte
200
Il listino aggiornato.
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 PATCH https://api.officina.it/v1/price-lists/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "discount_rate": 15
}'
Risposta
{
  "object": "price_list",
  "id": "9c5e1a83-6b24-4d70-8f39-2a7c4e1b8d56",
  "name": "Listino flotte",
  "discount_rate": 15
}
DELETE /v1/price-lists/{id}
Permesso richiesto settings.write

Elimina un listino

Elimina il listino. I clienti che lo usavano lo perdono, insieme al suo sconto (customers_detached dice quanti); le righe già nei documenti non cambiano. Un listino con prezzi o sconti dedicati su articoli o manodopera non si elimina: 409 conflict.
Risposte
200
Il listino 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.
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/price-lists/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "price_list",
  "id": "9c5e1a83-6b24-4d70-8f39-2a7c4e1b8d56",
  "name": "Listino flotte",
  "discount_rate": 10,
  "customers_detached": 12
}
POST /v1/sezionali
Permesso richiesto settings.write

Crea un sezionale

Crea un registro di numerazione. code è il suffisso che compare sul numero del documento.
Risposte
201
Il sezionale creato.
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.
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 POST https://api.officina.it/v1/sezionali \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "A",
  "label": "Sezionale principale"
}'
Risposta
{
  "object": "sezionale",
  "id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "code": "A",
  "label": "Sezionale principale"
}
PATCH /v1/sezionali/{id}
Permesso richiesto settings.write

Aggiorna un sezionale

Aggiorna codice ed etichetta del sezionale.
Risposte
200
Il sezionale aggiornato.
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.
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/sezionali/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "A",
  "label": "Sezionale principale"
}'
Risposta
{
  "object": "sezionale",
  "id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047",
  "code": "A",
  "label": "Sezionale principale"
}
DELETE /v1/sezionali/{id}
Permesso richiesto settings.write

Elimina un sezionale

Elimina il sezionale. Non è eliminabile se è già stato usato per numerare un documento.
Risposte
200
Il sezionale 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.
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/sezionali/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "sezionale",
  "id": "c81f4a26-7d09-4e35-b6a1-2f8c5d3e9047"
}
GET /v1/team
Permesso richiesto settings.read

Elenca i collaboratori

I collaboratori dell'officina, con ruolo e stato di attivazione.
Risposte
200
I collaboratori dell'officina.
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/team \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "team_member",
      "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
      "first_name": "Luca",
      "last_name": "Bianchi",
      "email": "luca.bianchi@example.it",
      "phone": "+393337654321",
      "role": "meccanico",
      "deactivated": false,
      "is_self": false
    }
  ],
  "has_more": false,
  "url": "/v1/team"
}
GET /v1/team/{id}
Permesso richiesto settings.read

Recupera un collaboratore

Restituisce il collaboratore con i gruppi di permessi assegnati.
Risposte
200
Il collaboratore 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.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/team/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "team_member",
  "id": "4e7b1d29-5a63-40c8-9f15-2b8d6e3a1c74",
  "first_name": "Luca",
  "last_name": "Bianchi",
  "email": "luca.bianchi@example.it",
  "phone": "+393337654321",
  "role": "meccanico",
  "deactivated": false,
  "is_self": false,
  "permission_groups": [
    {
      "name": "Officina",
      "granted": true
    }
  ]
}
GET /v1/trash
Permesso richiesto trash.read

Elenca i documenti e i record eliminati

Il Cestino di Impostazioni: ogni documento o record eliminato dell'officina (fatture, scontrini, note di credito, schede lavoro, preventivi, clienti, veicoli, articoli, appuntamenti, accettazioni, spese, ordini, fornitori, depositi gomme, DDT, vendite e noleggi), dal più recente, normalizzato alle stesse colonne: tipo, numero o nome, cliente, importo, data di eliminazione e chi l'ha eliminato (dal registro attività; null per le eliminazioni più vecchie). Niente viene mai eliminato definitivamente e nessun numero viene riutilizzato: un documento fiscale numerato eliminato riporta number_unused: true. type sceglie una scheda (all, invoice, receipt, worksheet, quote, customer, vehicle, article, other), q cerca per numero, nome, targa o codice, period sceglie la finestra (c30, c60, c180, c365, all). Ogni pagina riporta counts per scheda, il period applicato e periods con il flag allowed. Lo storico dipende dal piano (window_days): 30 giorni con Base, 180 con Pro, tutto con Business e Illimitato. Senza period si applica la finestra più ampia del piano; un period oltre il piano risponde 402 plan_upgrade_required con param: /period. Serve un abbonamento attivo (402 subscription_required altrimenti). Sola lettura: il ripristino non è disponibile via API e i dettagli di un record eliminato rispondono 404 su ogni endpoint.
dalla revisione 2026-10-22

Nuovo endpoint: i documenti e i record eliminati dell'officina, con chi li ha eliminati e quando.

Risposte
200
Una pagina di record eliminati, dal più recente, con i conteggi e i periodi.
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/trash \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "deleted_record",
      "type": "invoice",
      "id": "2f6c1a84-93d7-4e1b-b0a2-7c58d9e3f614",
      "seq_number": 816,
      "label": "Tagliando 60.000 km",
      "meta": "",
      "customer_name": "Mario Rossi",
      "amount": 285.36,
      "issued": true,
      "number_unused": true,
      "numbered_at": "2026-09-30T10:12:00Z",
      "deleted_at": "2026-10-03T16:40:12Z",
      "deleted_by": "Luca Bianchi"
    },
    {
      "object": "deleted_record",
      "type": "customer",
      "id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "seq_number": null,
      "label": "Rossi Autotrasporti Srl",
      "meta": "Azienda",
      "customer_name": "",
      "amount": null,
      "issued": null,
      "number_unused": false,
      "numbered_at": "2026-02-11T09:00:00Z",
      "deleted_at": "2026-10-01T08:05:44Z",
      "deleted_by": null
    }
  ],
  "has_more": false,
  "url": "/v1/trash",
  "period": {
    "object": "trash_period",
    "key": "c30",
    "label": "Ultimi 30 giorni",
    "days": 30,
    "from": "2026-09-22",
    "to": "2026-10-22"
  },
  "periods": [
    {
      "object": "trash_period_option",
      "key": "c30",
      "label": "Ultimi 30 giorni",
      "days": 30,
      "allowed": true
    },
    {
      "object": "trash_period_option",
      "key": "c60",
      "label": "Ultimi 60 giorni",
      "days": 60,
      "allowed": false
    },
    {
      "object": "trash_period_option",
      "key": "c180",
      "label": "Ultimi 180 giorni",
      "days": 180,
      "allowed": false
    },
    {
      "object": "trash_period_option",
      "key": "c365",
      "label": "Ultimo anno",
      "days": 365,
      "allowed": false
    },
    {
      "object": "trash_period_option",
      "key": "all",
      "label": "Tutto lo storico",
      "days": -1,
      "allowed": false
    }
  ],
  "window_days": 30,
  "counts": {
    "object": "trash_counts",
    "all": 2,
    "invoice": 1,
    "receipt": 0,
    "worksheet": 0,
    "quote": 0,
    "customer": 1,
    "vehicle": 0,
    "article": 0,
    "other": 0
  }
}
PUT /v1/vat-rates
Permesso richiesto settings.write

Imposta le aliquote IVA attive

Sostituisce l'intero insieme delle aliquote attive: quelle non elencate vengono disattivate. I codici ammessi sono quelli di GET /v1/vat-rates/catalog.
Risposte
200
Le aliquote ora attive.
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/vat-rates \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "codes": [
    "22",
    "10",
    "4"
  ]
}'
Risposta
{
  "object": "vat_rates",
  "codes": [
    "22",
    "10"
  ]
}
GET /v1/vat-rates/catalog
Permesso richiesto settings.read

Catalogo delle aliquote IVA

Tutte le aliquote disponibili, con enabled a indicare quelle attive per l'officina.
Risposte
200
Il catalogo delle aliquote.
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/vat-rates/catalog \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "vat_rate_catalog_entry",
      "code": "22",
      "rate": 22,
      "description": "Aliquota ordinaria",
      "enabled": true
    },
    {
      "object": "vat_rate_catalog_entry",
      "code": "10",
      "rate": 10,
      "description": "Aliquota ridotta",
      "enabled": true
    },
    {
      "object": "vat_rate_catalog_entry",
      "code": "N2.2",
      "rate": 0,
      "description": "Non soggetta",
      "enabled": false
    }
  ],
  "has_more": false,
  "url": "/v1/vat-rates/catalog"
}
GET /v1/vehicle-field-settings
Permesso richiesto settings.read

Recupera i campi veicolo

Quali campi facoltativi della scheda veicolo sono visibili e quali campi personalizzati sono definiti, incluso quali campi data generano un evento in agenda (reminder_days_before).
Risposte
200
La configurazione dei campi veicolo.
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/vehicle-field-settings \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "vehicle_field_settings",
  "field_visibility": {
    "km": true,
    "numero_telaio": true,
    "transmission": false,
    "engine_category": true,
    "engine_power_kw": false,
    "engine_displacement_ccm": false,
    "engine_code": false,
    "vehicle_weight_kg": false,
    "registration_date": true,
    "last_inspection_date": true,
    "next_inspection_date": true
  },
  "custom_fields": [
    {
      "id": "cf_8a2d6f",
      "name": "Colore",
      "type": "string",
      "visible": true,
      "order": 1,
      "reminder_days_before": null
    },
    {
      "id": "cf_3f9b1c",
      "name": "Scadenza ATP",
      "type": "datetime",
      "visible": true,
      "order": 2,
      "reminder_days_before": 0
    },
    {
      "id": "cf_5e27a9",
      "name": "Alimentazione",
      "type": "list",
      "options": [
        "Benzina",
        "Diesel",
        "GPL/Metano",
        "Ibrida",
        "Elettrica"
      ],
      "visible": true,
      "order": 3,
      "reminder_days_before": null
    }
  ]
}
PUT /v1/vehicle-field-settings
Permesso richiesto settings.write

Imposta i campi veicolo

Crea, modifica, riordina ed elimina i campi personalizzati e aggiorna la visibilità dei campi facoltativi, in un'unica chiamata. custom_fields è l'elenco completo: un campo con id modifica quello esistente (i valori salvati sui veicoli restano), un campo senza id ne crea uno nuovo, un campo non elencato viene eliminato. L'ordine dell'array è l'ordine di visualizzazione. Se custom_fields è assente la configurazione dei campi non cambia. Ciò che il corpo omette viene conservato, non azzerato: una chiave assente in field_visibility mantiene il valore attuale, e su un campo esistente visible o reminder_days_before assenti mantengono l'impostazione salvata. Così un client che ricostruisce l'elenco con soli id, name e type non nasconde campi né spegne eventi. Un campo nascosto non genera eventi in agenda, qualunque sia il suo reminder_days_before (che resta salvato e torna attivo quando il campo viene mostrato di nuovo). Lo stesso vale per la revisione: con field_visibility.next_inspection_date a false non vengono creati eventi di revisione. Gli eventi in agenda gia' creati non vengono toccati: attivare o disattivare reminder_days_before, o nascondere un campo, cambia solo cosa succede al prossimo salvataggio di un veicolo. Un campo list (dalla revisione 2026-10-22) è un menu a tendina: options elenca le voci nell'ordine scelto (da 1 a 20, ognuna di 1–30 caratteri) e il valore salvato sul veicolo è una di esse. Su un campo già list, options assente mantiene le voci salvate (come visible); un campo che diventa list deve indicarle; su un campo di altro tipo options è rifiutato.
Risposte
200
La configurazione 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.
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/vehicle-field-settings \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "field_visibility": {
    "km": true,
    "numero_telaio": true,
    "transmission": false,
    "engine_category": true,
    "engine_power_kw": false,
    "engine_displacement_ccm": false,
    "engine_code": false,
    "vehicle_weight_kg": false,
    "registration_date": true,
    "last_inspection_date": true,
    "next_inspection_date": true
  },
  "custom_fields": [
    {
      "id": "cf_8a2d6f",
      "name": "Colore",
      "type": "string"
    },
    {
      "name": "Scadenza ATP",
      "type": "datetime",
      "reminder_days_before": 0
    },
    {
      "name": "Alimentazione",
      "type": "list",
      "options": [
        "Benzina",
        "Diesel",
        "GPL/Metano",
        "Ibrida",
        "Elettrica"
      ]
    }
  ]
}'
Risposta
{
  "object": "vehicle_field_settings",
  "field_visibility": {
    "km": true,
    "numero_telaio": true,
    "transmission": false,
    "engine_category": true,
    "engine_power_kw": false,
    "engine_displacement_ccm": false,
    "engine_code": false,
    "vehicle_weight_kg": false,
    "registration_date": true,
    "last_inspection_date": true,
    "next_inspection_date": true
  },
  "custom_fields": [
    {
      "id": "cf_8a2d6f",
      "name": "Colore",
      "type": "string",
      "visible": true,
      "order": 1,
      "reminder_days_before": null
    },
    {
      "id": "cf_3f9b1c",
      "name": "Scadenza ATP",
      "type": "datetime",
      "visible": true,
      "order": 2,
      "reminder_days_before": 0
    },
    {
      "id": "cf_5e27a9",
      "name": "Alimentazione",
      "type": "list",
      "options": [
        "Benzina",
        "Diesel",
        "GPL/Metano",
        "Ibrida",
        "Elettrica"
      ],
      "visible": true,
      "order": 3,
      "reminder_days_before": null
    }
  ]
}
POST /v1/work-categories
Permesso richiesto settings.write

Crea una categoria

Crea una categoria, usata per classificare schede lavoro, preventivi e articoli. Il nome è salvato esattamente come inviato (senza spazi iniziali e finali). I nomi sono unici per officina senza distinguere maiuscole e minuscole: se esiste già una categoria con lo stesso nome, la risposta è 200 con quella esistente invece di crearne un doppione.
dalla revisione 2026-10-03

Un nome già esistente (senza distinguere maiuscole e minuscole) restituisce 200 con la categoria esistente invece di crearne un doppione.

Risposte
200
Esisteva già una categoria con lo stesso nome: viene restituito quello.
201
La categoria creata.
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 POST https://api.officina.it/v1/work-categories \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nuovo nome"
}'
Risposta
{
  "object": "work_category",
  "id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "name": "Tagliando"
}
PATCH /v1/work-categories/{id}
Permesso richiesto settings.write

Aggiorna una categoria

Aggiorna il nome della categoria. Se un'altra categoria ha già quel nome (senza distinguere maiuscole e minuscole) la risposta è 409 conflict.
dalla revisione 2026-10-03

Rinominare con un nome già usato da un'altra categoria restituisce 409 conflict.

Risposte
200
La categoria aggiornata.
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.
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/work-categories/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nuovo nome"
}'
Risposta
{
  "object": "work_category",
  "id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "name": "Tagliando"
}
DELETE /v1/work-categories/{id}
Permesso richiesto settings.write

Elimina una categoria

Elimina la categoria. I documenti e gli articoli che la citano restano intatti.
Risposte
200
La categoria 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.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X DELETE https://api.officina.it/v1/work-categories/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "work_category",
  "id": "3a8e5c21-9d76-4f03-b418-2c6a9e7d5b40",
  "name": "Tagliando"
}