Magazzino

Articoli, listino manodopera e movimenti.

7 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/articles
Permesso richiesto articles.read

Cerca nel magazzino e nel listino

Il catalogo dietro «Cerca da magazzino». Contiene sia i ricambi (kind: item) sia le voci di manodopera (kind: work). Ogni parola di q deve comparire nel nome, nel codice o nelle note. Filtra per tipo con kind. Passa customer_id per ottenere il sale_price già scontato secondo il listino di quel cliente.
Risposte
200
Gli articoli che soddisfano la ricerca.
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/articles \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "article",
      "id": "f18c4b62-9d07-4e53-a294-6b1f8d3c5e70",
      "code": "FO-2231",
      "name": "Filtro olio",
      "kind": "item",
      "unit_type": "pz",
      "stock": 12,
      "sale_price": 14.9,
      "vat_code": "22",
      "unit_discount_rate": 0
    },
    {
      "object": "article",
      "id": "2c9e5a71-4b38-40df-9126-7e3d1f6a8c25",
      "code": null,
      "name": "Manodopera meccanica",
      "kind": "work",
      "unit_type": "h",
      "stock": 0,
      "sale_price": 40.0,
      "vat_code": "22",
      "unit_discount_rate": 0
    }
  ],
  "has_more": false,
  "url": "/v1/articles"
}
POST /v1/articles
Permesso richiesto articles.write

Crea un articolo

Crea un ricambio o una voce di manodopera. unit_type deve essere coerente con il tipo: kg, L, kit, pz per il magazzino; gg, h, lav, min per la manodopera. vat_code deve essere una delle aliquote attive dell'azienda (vedi GET /v1/vat-rates).
Risposte
201
L'articolo creato.
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 -X POST https://api.officina.it/v1/articles \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Filtro olio",
  "code": "FO-2231",
  "unit_type": "pz",
  "stock": 12,
  "purchase_price": 6.4,
  "sale_price": 14.9,
  "vat_code": "22",
  "supplier_id": null
}'
Risposta
{
  "object": "article",
  "id": "f18c4b62-9d07-4e53-a294-6b1f8d3c5e70",
  "code": "FO-2231",
  "name": "Filtro olio",
  "kind": "item",
  "unit_type": "pz",
  "stock": 12,
  "sale_price": 14.9,
  "vat_code": "22",
  "unit_discount_rate": 0,
  "minimum_stock": 4,
  "purchase_price": 6.4,
  "location": "Scaffale A2",
  "comments": "Compatibile con motori 1.2 FIRE",
  "supplier_id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "supplier_name": "Ricambi Lombardia S.r.l."
}
GET /v1/articles/{id}
Permesso richiesto articles.read

Recupera un articolo

Restituisce l'articolo con i campi di dettaglio che l'elenco omette: soglia di riordino, prezzo di acquisto, posizione, note e fornitore.
Risposte
200
L'articolo 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/articles/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "article",
  "id": "f18c4b62-9d07-4e53-a294-6b1f8d3c5e70",
  "code": "FO-2231",
  "name": "Filtro olio",
  "kind": "item",
  "unit_type": "pz",
  "stock": 12,
  "sale_price": 14.9,
  "vat_code": "22",
  "unit_discount_rate": 0,
  "minimum_stock": 4,
  "purchase_price": 6.4,
  "location": "Scaffale A2",
  "comments": "Compatibile con motori 1.2 FIRE",
  "supplier_id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "supplier_name": "Ricambi Lombardia S.r.l."
}
PATCH /v1/articles/{id}
Permesso richiesto articles.write

Aggiorna un articolo

Il corpo è lo stesso della creazione: va inviato l'oggetto completo, non solo i campi da cambiare. I campi omessi vengono azzerati, non lasciati invariati.
Risposte
200
L'articolo aggiornato.
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 PATCH https://api.officina.it/v1/articles/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Filtro olio",
  "code": "FO-2231",
  "unit_type": "pz",
  "stock": 12,
  "purchase_price": 6.4,
  "sale_price": 14.9,
  "vat_code": "22",
  "supplier_id": null
}'
Risposta
{
  "object": "article",
  "id": "f18c4b62-9d07-4e53-a294-6b1f8d3c5e70",
  "code": "FO-2231",
  "name": "Filtro olio",
  "kind": "item",
  "unit_type": "pz",
  "stock": 12,
  "sale_price": 14.9,
  "vat_code": "22",
  "unit_discount_rate": 0,
  "minimum_stock": 4,
  "purchase_price": 6.4,
  "location": "Scaffale A2",
  "comments": "Compatibile con motori 1.2 FIRE",
  "supplier_id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "supplier_name": "Ricambi Lombardia S.r.l."
}
DELETE /v1/articles/{id}
Permesso richiesto articles.write

Elimina un articolo

Eliminazione logica: l'articolo sparisce dal catalogo. Le righe dei documenti che lo citano restano intatte.
Risposte
200
L'articolo 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/articles/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "article",
  "id": "f18c4b62-9d07-4e53-a294-6b1f8d3c5e70",
  "code": "FO-2231",
  "name": "Filtro olio",
  "kind": "item",
  "unit_type": "pz",
  "stock": 12,
  "sale_price": 14.9,
  "vat_code": "22",
  "unit_discount_rate": 0,
  "minimum_stock": 4,
  "purchase_price": 6.4,
  "location": "Scaffale A2",
  "comments": "Compatibile con motori 1.2 FIRE",
  "supplier_id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "supplier_name": "Ricambi Lombardia S.r.l."
}
GET /v1/articles/{id}/movements
Permesso richiesto articles.read

Movimenti di un articolo

Lo storico di carico e scarico dell'articolo. quantity è positiva per i carichi e negativa per gli scarichi; source indica il documento che ha generato il movimento e source_id lo identifica.
Risposte
200
I movimenti dell'articolo.
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/articles/{id}/movements \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "article_movement",
      "id": "8b4d2f06-1c73-4a95-b028-5e7f3a1d9c64",
      "quantity": -4,
      "source": "worksheet",
      "source_id": "a5d21e64-8f37-4b90-ae12-3c7d6b048f95",
      "seq_number": 412,
      "document_date": "2026-07-15",
      "customer_name": "Mario Rossi",
      "vehicle_name": "Fiat Panda",
      "total": 74.0,
      "created_at": "2026-07-15T08:31:00Z"
    },
    {
      "object": "article_movement",
      "id": "3f7a9c25-6d81-4e40-9b53-2a8c1f4d7e06",
      "quantity": 20,
      "source": "delivery_note",
      "source_id": "9d1e6b48-5c20-4f37-a814-3b7e2d9f5a61",
      "seq_number": 77,
      "document_date": "2026-07-02",
      "customer_name": null,
      "vehicle_name": null,
      "total": 128.0,
      "created_at": "2026-07-02T11:14:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/articles/f18c4b62-9d07-4e53-a294-6b1f8d3c5e70/movements"
}
GET /v1/vat-rates
Permesso richiesto settings.read

Elenca le aliquote IVA

Le aliquote attive dell'azienda, da usare per valorizzare vat_code sugli articoli e sulle righe dei documenti. È una voce di Impostazioni, quindi richiede il permesso settings.read.
Risposte
200
Le aliquote IVA attive.
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/vat-rates \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "vat_rate",
      "code": "22",
      "rate": 22,
      "description": "Aliquota ordinaria"
    },
    {
      "object": "vat_rate",
      "code": "10",
      "rate": 10,
      "description": "Aliquota ridotta"
    },
    {
      "object": "vat_rate",
      "code": "N2.2",
      "rate": 0,
      "description": "Non soggetta"
    }
  ],
  "has_more": false,
  "url": "/v1/vat-rates"
}