Come iniziare: genera una chiave API
Tre passaggi. Richiede un piano Business o Illimitato.
Crea una chiave
Dal gestionale, in Impostazioni › Accesso API, seleziona «Nuova chiave API» e assegna i soli permessi necessari. La chiave viene mostrata una sola volta al momento della creazione: conservala in un luogo sicuro.
Verifica che funzioni
Ogni richiesta deve riportare la chiave nell'header Authorization e la revisione dell'API.
# chi sono, cosa può fare questa chiave curl https://api.officina.it/v1/whoami \ -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \ -H "X-API-Version: 2026-07-20"
Leggi e scrivi i tuoi dati
Le liste sono paginate tramite un cursore opaco: va restituito invariato in starting_after per ottenere la pagina successiva.
curl "https://api.officina.it/v1/customers?limit=50" \ -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \ -H "X-API-Version: 2026-07-20" { "object": "list", "data": [ … ], "has_more": true, "next_starting_after": "eyJvIjoyMH0" }
Permessi
A ogni chiave sono associati permessi per area, distinti fra lettura e scrittura. Il permesso di scrittura comprende sempre quello di lettura. Una chiamata priva del permesso richiesto risponde 403 insufficient_scope.
| Area | Permesso | Cosa comprende |
|---|---|---|
| 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
Le aree del gestionale disponibili via API, con la stessa denominazione utilizzata nell'applicazione.
Clienti
Anagrafiche, documenti allegati e storico.
Veicoli
Veicoli, marche e documenti allegati.
Schede lavoro
Schede, righe, pagamenti e stati di lavorazione.
Preventivi
Preventivi, righe e conversione in scheda lavoro.
Fatture
Fatture, note di credito, pagamenti ed emissione.
Scontrini
Scontrini e relativi pagamenti.
Accettazioni
Accettazioni, conversioni e documenti.
Agenda
Calendari e appuntamenti.
Magazzino
Articoli, listino manodopera e movimenti.
Deposito gomme
Pneumatici in deposito e passaggi di stato.
Fornitori
Fornitori, ordini e documenti di trasporto.
Spese
Spese, pagamenti e categorie.
Prima nota
Movimenti di cassa e conti finanziari.
Impostazioni
Dati azienda, aliquote IVA, listini, collaboratori.
Fatturazione elettronica
Fatture elettroniche emesse e ricevute, in sola lettura.
Concessionaria
Stock veicoli, vendite e report.
Report
Statistiche e contatori della tua officina.
Autenticazione
Verifica della chiave e dei permessi.
Date e orari
Date e timestamp adottano il formato RFC 3339 in UTC, ad esempio 2026-06-12T09:30:00Z.
Le date scritte dal client devono cadere fra il 1° gennaio 1900 e il 31 dicembre 2100. Un anno esterno a tale intervallo costituisce pressoché sempre un refuso di digitazione (2025 digitato «0025») e viene rifiutato con 422 parameter_invalid, dove param indica il campo interessato. È il medesimo intervallo accettato dai selettori di data del gestionale: un record creato via API resta pertanto modificabile anche dall'interfaccia web. I timestamp generati dal server (created_at, updated_at) non sono soggetti a tale vincolo.
{
"error": {
"status": 422,
"code": "parameter_invalid",
"param": "/registered_at",
"message": "La data deve essere compresa tra il 1° gennaio 1900 e il 31 dicembre 2100."
}
}
Errori
Gli errori adottano sempre la stessa struttura: un code stabile su cui il client può discriminare e un trace_id da riportare all'assistenza.
{
"error": {
"type": "https://api.officina.it/errors/insufficient_scope",
"status": 403,
"code": "insufficient_scope",
"message": "Questa chiave API non ha il permesso «invoices.write».",
"trace_id": "21fef3bbb28da12cff21e19cadf9c99d"
}
}
| Codice | Quando |
|---|---|
| api_key_invalid | Chiave assente o sconosciuta. |
| api_key_revoked | La chiave è stata revocata dal gestionale. |
| api_key_expired | La chiave ha superato la data di scadenza. |
| insufficient_scope | La chiave non ha il permesso richiesto. |
| plan_upgrade_required | Il piano non include l'accesso API. |
| parameter_invalid | Un campo della richiesta non è valido. param indica quale. |
| not_found | La risorsa non esiste o non appartiene alla tua officina. |
Versionamento
L'API adotta due livelli di versionamento con finalità distinte: il percorso identifica la versione maggiore del contratto, l'header ne identifica la revisione.
| Elemento | Significato | Criterio di aggiornamento |
|---|---|---|
| /v1/ | Versione maggiore, indicata nel percorso della richiesta. | Viene incrementata esclusivamente in caso di modifiche non retrocompatibili: rimozione o ridenominazione di un campo, variazione della semantica di un endpoint. In tale evenienza viene pubblicato un nuovo percorso /v2 e /v1 resta operativo. |
| X-API-Version | Revisione datata all'interno della versione maggiore. | Viene aggiornata a ogni estensione retrocompatibile: nuovi endpoint, nuovi campi nelle risposte. Dichiarando una revisione, l'integrazione conserva il comportamento previsto a quella data anche in seguito all'evoluzione dell'API. |
Specifica OpenAPI
Il contratto completo in formato OpenAPI 3.1, con tutti gli endpoint, i campi e gli errori, utilizzabile con qualsiasi generatore di client.
Per agenti AI
Se usi Claude, Cursor, Codex o un altro agente di coding, incolla il prompt qui sotto (in inglese, più affidabile con gli agenti): scarica da solo le istruzioni e l'OpenAPI. Non serve installare nulla in locale.