Clienti

Anagrafiche, documenti allegati e storico.

9 endpoint Versione v1 · revisione 2026-10-31

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

GET /v1/customers
Permesso richiesto customers.read

Elenca i clienti

Restituisce i clienti della tua officina, dal più recente. Cerca per nome con ?q=. Impagina con ?limit= e ?starting_after=. Il cursore è opaco: non interpretarlo, rimandalo così com'è. Usa has_more per sapere se c'è un'altra pagina, non la lunghezza di data: l'ultima pagina può essere piena.
Risposte
200
Una pagina di clienti.
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.
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/customers \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "customer",
      "id": "8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1",
      "customer_type": "private",
      "full_name": "Mario Rossi",
      "email": "mario.rossi@example.com",
      "phone": "+393331234567",
      "city": "Milano"
    }
  ],
  "has_more": true,
  "next_starting_after": "eyJvIjoyMH0",
  "url": "/v1/customers"
}
POST /v1/customers
Permesso richiesto customers.write

Crea un cliente

Crea un cliente nella tua officina. L'azienda e l'autore sono sempre ricavati dalla chiave API: non puoi impostarli dal corpo della richiesta. Obbligatorio: customer_type. Tutto il resto è facoltativo. I riferimenti ad altre risorse (per esempio price_list_id) devono appartenere alla tua officina, altrimenti ricevi 422 parameter_invalid con l'indicazione del campo. custom_fields contiene i valori dei campi personalizzati, con chiave l'id definito in GET /v1/customer-field-settings. Come dal gestionale, vengono creati in agenda l'evento del compleanno (se birthday è impostato e l'officina lo tiene attivo) e un evento per ogni campo data personalizzato che lo prevede. tax_id è controllato come nel gestionale, in tutte le revisioni: per un cliente italiano (tutti i clienti creati via API) serve una partita IVA di 11 cifre con cifra di controllo corretta. Il numero è salvato senza prefisso IT, spazi o punti. Se non è valido ricevi 422 parameter_invalid con param: "/tax_id".
Risposte
201
Cliente creato.
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.
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/customers \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_type": "private",
  "full_name": "Mario Rossi",
  "phone": "+39 333 1234567",
  "email": "mario.rossi@example.com"
}'
Risposta
{
  "object": "customer",
  "id": "8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1",
  "customer_type": "private",
  "full_name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "phone": "+393331234567",
  "city": "Milano",
  "created_at": "2026-08-03T14:32:11Z"
}
GET /v1/customers/by-number/{year}/{number}
Permesso richiesto customers.read

Recupera un cliente per numero e anno

Returns the same detail response as GET /v1/customers/{id}, scoped to the authenticated company. The number is unique within the creation year. Deleted records and records from other companies return 404. Available on existing supported API revisions; no new revision is required.
Risposte
200
Customer found, with the same body as retrieval by id.
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
Multiple records match; the error contains candidate ids.
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/customers/by-number/{year}/{number} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
GET /v1/customers/{id}
Permesso richiesto customers.read

Recupera un cliente

Restituisce un singolo cliente della tua officina. Un id sconosciuto, di un'altra officina o di un cliente eliminato restituisce sempre 404: mai 403, mai 200 con il record eliminato.
Risposte
200
Cliente trovato.
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.
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/customers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "customer",
  "id": "8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1",
  "customer_type": "private",
  "full_name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "phone": "+393331234567",
  "city": "Milano",
  "created_at": "2026-08-03T14:32:11Z"
}
PATCH /v1/customers/{id}
Permesso richiesto customers.write

Aggiorna un cliente

Header If-Match (obbligatorio dalla revisione 2026-10-22) con il campo version letto nel cliente: se è stato salvato nel frattempo la modifica è rifiutata con 409 e nulla viene salvato. Aggiorna solo i campi presenti nel corpo della richiesta: quelli omessi restano invariati. Per svuotare un campo inviagli esplicitamente null. custom_fields sostituisce l'intero oggetto dei valori personalizzati (i campi nascosti conservano il loro valore se la chiave non è inviata). Gli eventi in agenda generati dal cliente seguono le date: se cambi la data di nascita o una data personalizzata l'evento si sposta, se la svuoti l'evento viene rimosso. tax_id è controllato come nel gestionale, in tutte le revisioni, solo quando cambiano tax_id o customer_type. Per un cliente italiano serve una partita IVA valida (11 cifre, cifra di controllo); per un'azienda, un ente o una PA di un altro paese UE il numero IVA del paese, con formato e cifre di controllo verificati (AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK; per la Grecia il prefisso è EL). Il numero è salvato senza prefisso paese, spazi o punti. Se non è valido ricevi 422 parameter_invalid con param: "/tax_id".
dalla revisione 2026-10-22

If-Match obbligatorio da questa revisione: senza l'header la richiesta è rifiutata con 428 precondition_required (If-Match: * scrive comunque). Con una version superata risponde 409.

Risposte
200
Cliente aggiornato. Restituisce la scheda completa.
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.
404
La risorsa non esiste, è stata eliminata o non appartiene alla tua officina.
409
L'operazione è in conflitto con lo stato attuale della risorsa.
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.
428
Manca l'header `If-Match` (obbligatorio dalla revisione 2026-10-22).
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PATCH https://api.officina.it/v1/customers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -H "Content-Type: application/json" \
  -d '{
  "full_name": "Mario Rossi",
  "phone": null,
  "email": "mario.rossi@example.com"
}'
Risposta
{
  "object": "customer",
  "id": "8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1",
  "customer_type": "private",
  "full_name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "phone": null,
  "city": "Milano",
  "created_at": "2026-08-03T14:32:11Z"
}
DELETE /v1/customers/{id}
Permesso richiesto customers.write

Elimina un cliente

Eliminazione logica: il cliente sparisce dagli elenchi ma i documenti già emessi restano validi e collegati.
Risposte
200
Cliente eliminato. Il campo «deleted_at» viene valorizzato.
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/customers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "customer",
  "id": "8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1",
  "customer_type": "private",
  "full_name": "Mario Rossi",
  "email": "mario.rossi@example.com",
  "phone": "+393331234567",
  "city": "Milano",
  "created_at": "2026-08-03T14:32:11Z"
}
POST /v1/customers/{id}/documents
Permesso richiesto customers.write

Carica un documento

Allega un file alla scheda del cliente. La richiesta è multipart/form-data.
Risposte
201
Il documento salvato («url» è la rotta di download).
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.
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/customers/{id}/documents \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31" \
  -F "file=@/percorso/documento.pdf"
Risposta
{
  "object": "customer_document",
  "id": "3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14",
  "name": "libretto.pdf",
  "content_type": "application/pdf",
  "file_size_bytes": 184320,
  "url": "/v1/customers/8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1/documents/3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14/download",
  "created_at": "2026-08-03T14:41:02Z"
}
DELETE /v1/customers/{id}/documents/{documentID}
Permesso richiesto customers.write

Elimina un documento

Rimuove il file allegato alla scheda del cliente.
Risposte
200
Documento 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.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X DELETE https://api.officina.it/v1/customers/{id}/documents/{documentID} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"
Risposta
{
  "object": "customer_document",
  "id": "3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14",
  "name": "libretto.pdf",
  "content_type": "application/pdf",
  "file_size_bytes": 184320,
  "url": "/v1/customers/8f173fd2-6fa4-46e5-a8e3-23dfff31a0a1/documents/3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14/download",
  "created_at": "2026-08-03T14:41:02Z"
}
GET /v1/customers/{id}/documents/{documentID}/download
Permesso richiesto customers.read

Scarica un documento

Restituisce un link temporaneo per scaricare il file allegato.
Risposte
200
Il contenuto del file.
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/customers/{id}/documents/{documentID}/download \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-10-31"