---
name: officina-api
description: Integrate with the officina.it public REST API (customers, vehicles, worksheets, invoices, quotes, calendar). Use when building or debugging an integration against api.officina.it.
---

# officina.it Public API

- **Host:** `https://api.officina.it`
- **Human docs (Italian):** https://officina.it/api
- **Overview (markdown, Italian):** https://officina.it/api.md
- **OpenAPI 3.1 (source of truth for fields/paths):** https://api.officina.it/openapi.yaml
- **Major version in path:** `/v1/`
- **Revision header (required on every request):** `X-API-Version: 2026-07-20`
- **Auth:** `Authorization: Bearer ofk_live_…` (non-prod test keys use `ofk_test_`). Create keys in the app under Settings › API access (Impostazioni › Accesso API). The secret is shown once at creation.
- **Plan:** Business or Illimitato only. Free trial → `402 plan_upgrade_required`.

## Hard rules

1. Always send `X-API-Version`. Missing → `400 api_version_missing`.
2. Do not invent endpoints, fields, or error codes. Prefer OpenAPI over guesswork.
3. Scopes are `resource.read` / `resource.write`; write implies read. Missing scope → `403 insufficient_scope`.
4. List endpoints use opaque cursor pagination: pass `next_starting_after` back as `starting_after` unchanged.
5. Errors: stable `code`, human `message`, `trace_id` for support.
6. This public tier has no PDF export, no outbound SMS/WhatsApp/email send, no account/billing routes.
7. Dates are RFC 3339 UTC. Client-supplied dates must be between 1900-01-01 and 2100-12-31 — outside that window is `422 parameter_invalid` with `param` naming the field. Server-stamped timestamps are unbounded.

## Scopes

Grant these keys on the API key (product UI may show Italian labels):

- `customers.read` / `customers.write`
- `vehicles.read` / `vehicles.write`
- `worksheets.read` / `worksheets.write`
- `quotes.read` / `quotes.write`
- `invoices.read` / `invoices.write`
- `receipts.read` / `receipts.write`
- `checkins.read` / `checkins.write`
- `calendar.read` / `calendar.write`
- `articles.read` / `articles.write`
- `suppliers.read` / `suppliers.write`
- `expenses.read` / `expenses.write`
- `cashbook.read` / `cashbook.write`
- `settings.read` / `settings.write`
- `reports.read` / `reports.write`

## Quickstart

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

## Resource docs (HTML, Italian)

- https://officina.it/api/clienti — Clienti
- https://officina.it/api/veicoli — Veicoli
- https://officina.it/api/schede-lavoro — Schede lavoro
- https://officina.it/api/preventivi — Preventivi
- https://officina.it/api/fatture — Fatture
- https://officina.it/api/scontrini — Scontrini
- https://officina.it/api/accettazioni — Accettazioni
- https://officina.it/api/agenda — Agenda
- https://officina.it/api/magazzino — Magazzino
- https://officina.it/api/deposito-gomme — Deposito gomme
- https://officina.it/api/fornitori — Fornitori
- https://officina.it/api/spese — Spese
- https://officina.it/api/prima-nota — Prima nota
- https://officina.it/api/impostazioni — Impostazioni
- https://officina.it/api/fatturazione-elettronica — Fatturazione elettronica
- https://officina.it/api/concessionaria — Concessionaria
- https://officina.it/api/report — Report
- https://officina.it/api/autenticazione — Autenticazione