Clienti

Anagrafiche, documenti allegati e storico.

8 endpoint Versione v1 · revisione 2026-07-20

Gli endpoint sono relativi a https://api.officina.it e richiedono l'header Authorization: Bearer con la chiave API e X-API-Version: 2026-07-20. L'header della revisione è obbligatorio: differenza fra v1 e revisione.

GET /v1/customers

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.
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-07-20"
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

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.
Risposte
201
Cliente creato.
400
Corpo della richiesta non leggibile o JSON non valido.
401
Chiave API mancante, non valida, revocata o scaduta.
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-07-20" \
  -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/{id}

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.
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-07-20"
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}

Aggiorna un cliente

Aggiorna solo i campi presenti nel corpo della richiesta: quelli omessi restano invariati. Per svuotare un campo inviagli esplicitamente `null`.
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.
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 PATCH https://api.officina.it/v1/customers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -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": "+393331234567",
  "city": "Milano",
  "created_at": "2026-08-03T14:32:11Z"
}
DELETE /v1/customers/{id}

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.
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-07-20"
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

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.
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-07-20" \
  -F "file=@/percorso/documento.pdf"
Risposta
{
  "object": "customer_document",
  "id": "3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14",
  "file_name": "libretto.pdf",
  "content_type": "application/pdf",
  "size": 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}

Elimina un documento

Rimuove il file allegato alla scheda del cliente.
Risposte
200
Documento eliminato.
401
Chiave API mancante, non valida, revocata o scaduta.
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-07-20"
Risposta
{
  "object": "customer_document",
  "id": "3b91ee0c-19b4-4f0a-9c2e-7d51a0c88e14",
  "file_name": "libretto.pdf",
  "content_type": "application/pdf",
  "size": 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

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.
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-07-20"