Deposito gomme

Pneumatici in deposito e passaggi di stato.

8 endpoint Versione v1 · revisione 2026-11-02

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

GET /v1/tyresets
Permesso richiesto articles.read

Elenca i treni in deposito

I treni di gomme custoditi per i clienti. Filtra per stato con status e per testo con q. Il deposito gomme rientra nel permesso articles, non ne ha uno proprio: una chiave con articles.read vede sia il magazzino sia il deposito.
Risposte
200
I treni in deposito.
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.
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/tyresets \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "tyre_set",
      "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
      "seq_number": 63,
      "status": "deposited",
      "description": "Michelin Primacy 195/65 R15",
      "quantity": 4,
      "rim_type": "lega",
      "season_type": "estive",
      "condition": "buono",
      "residual_mm": 6,
      "location": "Scaffale B3",
      "comments": null,
      "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
      "customer_name": "Mario Rossi",
      "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
      "vehicle_name": "Fiat Panda",
      "vehicle_license": "AB123CD",
      "deposited_at": "2026-04-10T09:00:00Z",
      "mounted_at": null,
      "collected_at": null,
      "disposed_at": null,
      "inventory_check_at": null,
      "created_at": "2026-04-10T09:00:00Z",
      "updated_at": "2026-04-10T09:00:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/tyresets"
}
POST /v1/tyresets
Permesso richiesto articles.write

Registra un treno in deposito

Prende in custodia un treno di gomme per un cliente. Servono customer_id, vehicle_id, description e rim_type.
Risposte
201
Il treno registrato.
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.
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/tyresets \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "residual_mm": 6,
  "location": "Scaffale B3"
}'
Risposta
{
  "object": "tyre_set",
  "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
  "seq_number": 63,
  "status": "deposited",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "condition": "buono",
  "residual_mm": 6,
  "location": "Scaffale B3",
  "comments": null,
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "deposited_at": "2026-04-10T09:00:00Z",
  "mounted_at": null,
  "collected_at": null,
  "disposed_at": null,
  "inventory_check_at": null,
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}
GET /v1/tyresets/by-number/{year}/{number}
Permesso richiesto articles.read

Recupera il deposito gomme dal numero

Restituisce il deposito gomme con il numero number dell'anno year (anno del deposito): lo stesso numero mostrato nell'app, per esempio 12/2026. Risponde come il recupero per id. Se il numero corrisponde a più documenti — numeri ripetuti nello storico — restituisce 409 ambiguous_number con gli id in candidates.
dalla revisione 2026-10-04

Nuovo: recupera il deposito gomme dal numero e dall'anno.

Risposte
200
Il deposito gomme, con la stessa risposta del recupero per 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
Il numero corrisponde a più documenti: scegli quello giusto tra i `candidates` e recuperalo per id.
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/tyresets/by-number/{year}/{number} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "tyre_set",
  "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
  "seq_number": 63,
  "status": "deposited",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "condition": "buono",
  "residual_mm": 6,
  "location": "Scaffale B3",
  "comments": null,
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "deposited_at": "2026-04-10T09:00:00Z",
  "mounted_at": null,
  "collected_at": null,
  "disposed_at": null,
  "inventory_check_at": null,
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}
GET /v1/tyresets/status-counts
Permesso richiesto articles.read

Conta i treni per stato

Il numero di treni in ciascuno stato, con gli stessi filtri dell'elenco.
Risposte
200
Il numero di treni per stato.
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.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl https://api.officina.it/v1/tyresets/status-counts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "tyre_set_status_counts",
  "deposited": 18,
  "mounted": 4,
  "collected": 61,
  "disposed": 3,
  "locations": [
    "Scaffale B3",
    "Magazzino esterno"
  ]
}
GET /v1/tyresets/{id}
Permesso richiesto articles.read

Recupera un treno in deposito

Restituisce il treno con le date dei passaggi di stato: deposited_at, mounted_at, collected_at, disposed_at.
Risposte
200
Il treno richiesto.
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/tyresets/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "tyre_set",
  "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
  "seq_number": 63,
  "status": "deposited",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "condition": "buono",
  "residual_mm": 6,
  "location": "Scaffale B3",
  "comments": null,
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "deposited_at": "2026-04-10T09:00:00Z",
  "mounted_at": null,
  "collected_at": null,
  "disposed_at": null,
  "inventory_check_at": null,
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}
PATCH /v1/tyresets/{id}
Permesso richiesto articles.write

Aggiorna un treno in deposito

Il corpo è lo stesso della creazione: va inviato l'oggetto completo, non solo i campi da cambiare.
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
Il treno aggiornato.
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
Il documento è stato salvato nel frattempo (la `version` di `If-Match` è superata): ricaricalo e riprova. Nulla è stato salvato.
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/tyresets/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "residual_mm": 6,
  "location": "Scaffale B3"
}'
Risposta
{
  "object": "tyre_set",
  "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
  "seq_number": 63,
  "status": "deposited",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "condition": "buono",
  "residual_mm": 6,
  "location": "Scaffale B3",
  "comments": null,
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "deposited_at": "2026-04-10T09:00:00Z",
  "mounted_at": null,
  "collected_at": null,
  "disposed_at": null,
  "inventory_check_at": null,
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}
DELETE /v1/tyresets/{id}
Permesso richiesto articles.write

Elimina un treno dal deposito

Eliminazione logica del treno in deposito.
Risposte
200
Il treno 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/tyresets/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02"
Risposta
{
  "object": "tyre_set",
  "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
  "seq_number": 63,
  "status": "deposited",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "condition": "buono",
  "residual_mm": 6,
  "location": "Scaffale B3",
  "comments": null,
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "deposited_at": "2026-04-10T09:00:00Z",
  "mounted_at": null,
  "collected_at": null,
  "disposed_at": null,
  "inventory_check_at": null,
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}
POST /v1/tyresets/{id}/transitions
Permesso richiesto articles.write

Cambia stato al treno

Registra un passaggio di stato (montato, ritirato, smaltito) e valorizza la data corrispondente. È l'unico modo di cambiare status: non impostarlo via PATCH, perché non aggiornerebbe le date.
Risposte
200
Il treno dopo il passaggio di stato.
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.
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/tyresets/{id}/transitions \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-11-02" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "ritirato"
}'
Risposta
{
  "object": "tyre_set",
  "id": "47e2c9b1-8d50-4f36-a127-6c3b9e5d2a84",
  "seq_number": 63,
  "status": "mounted",
  "description": "Michelin Primacy 195/65 R15",
  "quantity": 4,
  "rim_type": "lega",
  "season_type": "estive",
  "condition": "buono",
  "residual_mm": 6,
  "location": "Scaffale B3",
  "comments": null,
  "customer_id": "4c911f08-7713-4e83-bdf6-a0692a1b43fd",
  "customer_name": "Mario Rossi",
  "vehicle_id": "8821f0ac-5d2b-41e7-9a10-6c3f2b7d4e55",
  "vehicle_name": "Fiat Panda",
  "vehicle_license": "AB123CD",
  "deposited_at": "2026-04-10T09:00:00Z",
  "mounted_at": "2026-08-04T09:00:00Z",
  "collected_at": null,
  "disposed_at": null,
  "inventory_check_at": null,
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}