# API e integrazioni di officina.it

> Documentazione delle API REST JSON di officina.it: collega il gestionale ad altri programmi e leggi o aggiorna clienti, veicoli, schede lavoro, preventivi, fatture e altro.

Pagina HTML canonica: https://officina.it/api

Ultimo aggiornamento: 2026-08-10

- **Host API:** `https://api.officina.it`
- **Versione maggiore:** `v1` (nel percorso)
- **Revisione corrente:** `2026-07-20` (header `X-API-Version`, obbligatorio)
- **Endpoint documentati:** 161
- **Autenticazione:** chiave API bearer (`Authorization: Bearer ofk_live_…`), creata in Impostazioni › Accesso API
- **Piani:** richiede un piano Business o Illimitato (la prova gratuita non include l'accesso API)
- **Specifica OpenAPI 3.1:** https://api.officina.it/openapi.yaml

## Come iniziare: genera una chiave API

1. Crea una chiave in **Impostazioni › Accesso API** e assegna solo i permessi necessari. La chiave viene mostrata una sola volta.
2. Verifica con `GET /v1/whoami` (header `Authorization` + `X-API-Version`).
3. Leggi e scrivi le risorse; le liste sono paginate con un cursore opaco in `starting_after`.

```bash
curl https://api.officina.it/v1/whoami \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
```

## Permessi

Ogni chiave ha permessi per area, distinti fra lettura e scrittura. La scrittura include sempre la lettura. Senza il permesso richiesto la risposta è `403 insufficient_scope`.

- **Clienti** (`customers.read` / `customers.write`): Anagrafiche clienti e relativi documenti
- **Veicoli** (`vehicles.read` / `vehicles.write`): Veicoli, marche e documenti allegati
- **Schede lavoro** (`worksheets.read` / `worksheets.write`): Schede lavoro, righe, pagamenti e documenti
- **Preventivi** (`quotes.read` / `quotes.write`): Preventivi e relative righe
- **Fatture** (`invoices.read` / `invoices.write`): Fatture, note di credito e pagamenti
- **Scontrini** (`receipts.read` / `receipts.write`): Scontrini e relativi pagamenti
- **Accettazioni** (`checkins.read` / `checkins.write`): Accettazioni e documenti allegati
- **Agenda** (`calendar.read` / `calendar.write`): Calendari e appuntamenti
- **Magazzino** (`articles.read` / `articles.write`): Articoli, movimenti e pneumatici in deposito
- **Fornitori** (`suppliers.read` / `suppliers.write`): Fornitori, ordini e documenti di trasporto
- **Spese** (`expenses.read` / `expenses.write`): Spese, pagamenti e categorie
- **Prima nota** (`cashbook.read` / `cashbook.write`): Movimenti di cassa e conti finanziari
- **Impostazioni** (`settings.read` / `settings.write`): Dati azienda, aliquote IVA, listini, collaboratori
- **Report** (`reports.read` / `reports.write`): Statistiche, contatori e report concessionaria

## Risorse documentate

Pagine di riferimento HTML (endpoint, esempi curl e risposte). Non esiste uno specchio markdown per ogni risorsa: l'indice è questa pagina e l'OpenAPI.

- [Clienti](https://officina.it/api/clienti): Anagrafiche, documenti allegati e storico. (8 endpoint)
- [Veicoli](https://officina.it/api/veicoli): Veicoli, marche e documenti allegati. (14 endpoint)
- [Schede lavoro](https://officina.it/api/schede-lavoro): Schede, righe, pagamenti e stati di lavorazione. (16 endpoint)
- [Preventivi](https://officina.it/api/preventivi): Preventivi, righe e conversione in scheda lavoro. (9 endpoint)
- [Fatture](https://officina.it/api/fatture): Fatture, note di credito, pagamenti ed emissione. (17 endpoint)
- [Scontrini](https://officina.it/api/scontrini): Scontrini e relativi pagamenti. (9 endpoint)
- [Accettazioni](https://officina.it/api/accettazioni): Accettazioni, conversioni e documenti. (13 endpoint)
- [Agenda](https://officina.it/api/agenda): Calendari e appuntamenti. (9 endpoint)
- [Magazzino](https://officina.it/api/magazzino): Articoli, listino manodopera e movimenti. (7 endpoint)
- [Deposito gomme](https://officina.it/api/deposito-gomme): Pneumatici in deposito e passaggi di stato. (7 endpoint)
- [Fornitori](https://officina.it/api/fornitori): Fornitori, ordini e documenti di trasporto. (9 endpoint)
- [Spese](https://officina.it/api/spese): Spese, pagamenti e categorie. (10 endpoint)
- [Prima nota](https://officina.it/api/prima-nota): Movimenti di cassa e conti finanziari. (5 endpoint)
- [Impostazioni](https://officina.it/api/impostazioni): Dati azienda, aliquote IVA, listini, collaboratori. (17 endpoint)
- [Fatturazione elettronica](https://officina.it/api/fatturazione-elettronica): Fatture elettroniche emesse e ricevute, in sola lettura. (4 endpoint)
- [Concessionaria](https://officina.it/api/concessionaria): Stock veicoli, vendite e report. (4 endpoint)
- [Report](https://officina.it/api/report): Statistiche e contatori della tua officina. (2 endpoint)
- [Autenticazione](https://officina.it/api/autenticazione): Verifica della chiave e dei permessi. (1 endpoint)

## Date e orari

Date e timestamp usano RFC 3339 in UTC (es. `2026-06-12T09:30:00Z`).

Le date scritte dal client devono cadere fra il **1° gennaio 1900** e il **31 dicembre 2100**: fuori da questo intervallo la risposta è `422 parameter_invalid` con `param` sul campo. È lo stesso intervallo accettato dai selettori di data del gestionale, così un record creato via API resta modificabile anche dall'interfaccia web. I timestamp generati dal server (`created_at`, `updated_at`) non hanno questo vincolo.

## Errori

Gli errori usano sempre la stessa struttura: `code` stabile, `message`, `trace_id`.

| Codice | Quando |
| --- | --- |
| `api_key_invalid` | Chiave assente o sconosciuta |
| `api_key_revoked` | Chiave revocata |
| `api_key_expired` | Chiave scaduta |
| `insufficient_scope` | Permesso mancante |
| `plan_upgrade_required` | Piano senza accesso API |
| `parameter_invalid` | Campo non valido |
| `not_found` | Risorsa assente o di un'altra officina |
| `api_version_missing` | Manca l'header `X-API-Version` |

## Versionamento

- **`/v1/…` nel percorso:** versione maggiore. Cambia solo per breaking change (nuovo `/v2`, la `/v1` resta).
- **`X-API-Version` (data):** revisione retrocompatibile. Dichiarandola, l'integrazione conserva il comportamento di quella data.
- L'header di revisione è **obbligatorio** su ogni richiesta.

Documentazione HTML: https://officina.it/api
Skill per agenti AI: https://officina.it/api/skill.md
OpenAPI: https://api.officina.it/openapi.yaml