Fornitori

Fornitori, ordini e documenti di trasporto.

9 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/delivery-notes
Permesso richiesto suppliers.read

Elenca i documenti di trasporto

I DDT ricevuti dai fornitori, in sola lettura.
Risposte
200
I documenti di trasporto.
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/delivery-notes \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "delivery_note",
      "id": "9d1e6b48-5c20-4f37-a814-3b7e2d9f5a61",
      "seq_number": 77,
      "supplier_id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
      "supplier_name": "Ricambi Lombardia S.r.l.",
      "description": "Consegna filtri e olio",
      "status": "issued",
      "delivery_date": "2026-07-02",
      "total_before_tax": 128.0,
      "total_tax": 28.16,
      "total_after_tax": 156.16,
      "created_at": "2026-07-02T11:14:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/delivery-notes",
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
GET /v1/delivery-notes/status-counts
Permesso richiesto suppliers.read

Conta i DDT per stato

Il numero di documenti di trasporto in ciascuno stato, con gli stessi filtri dell'elenco.
Risposte
200
Il numero di DDT 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/delivery-notes/status-counts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "delivery_note_status_counts",
  "draft": 1,
  "issued": 64,
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
GET /v1/orders
Permesso richiesto suppliers.read

Elenca gli ordini a fornitore

Gli ordini emessi verso i fornitori, in sola lettura: creazione e modifica non sono esposte su questa API.
Risposte
200
Gli ordini a fornitore.
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/orders \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "order",
      "id": "8c14e7a2-5b30-4d96-a17f-2e9c6b4d8f05",
      "seq_number": 214,
      "supplier_id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
      "supplier_name": "Ricambi Lombardia S.r.l.",
      "supplier_invoice_reference": "2026/1184",
      "status": "received",
      "total_before_tax": 420.0,
      "total_tax": 92.4,
      "total_after_tax": 512.4,
      "payment_method": "MP05",
      "invoice_date": "2026-07-28",
      "confirmed_at": "2026-07-20T09:00:00Z",
      "received_at": "2026-07-27T11:30:00Z",
      "created_at": "2026-07-18T15:00:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/orders",
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
GET /v1/orders/status-counts
Permesso richiesto suppliers.read

Conta gli ordini per stato

Il numero di ordini in ciascuno stato, con gli stessi filtri dell'elenco.
Risposte
200
Il numero di ordini 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/orders/status-counts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "order_status_counts",
  "pending": 2,
  "delivery": 5,
  "received": 118,
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
GET /v1/suppliers
Permesso richiesto suppliers.read

Elenca i fornitori

I fornitori dell'officina. Filtra per testo con q.
Risposte
200
I fornitori dell'officina.
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/suppliers \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "supplier",
      "id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
      "name": "Ricambi Lombardia S.r.l.",
      "email": "ordini@ricambi.example.it",
      "phone": "+390212345678",
      "phone_national": "02 1234 5678",
      "address": "Via Mecenate 12",
      "city": "Milano",
      "zip_code": "20138",
      "tax_id": "01234567890",
      "comments": null,
      "bank_account_iban": "IT60X0542811101000000123456",
      "website": "https://ricambi.example.it",
      "website_display": "ricambi.example.it",
      "supplier_type": "ricambi",
      "created_at": "2025-02-11T10:00:00Z",
      "updated_at": "2026-06-03T14:20:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/suppliers"
}
POST /v1/suppliers
Permesso richiesto suppliers.write

Crea un fornitore

Crea un fornitore. Il telefono va in formato E.164 (+390212345678) e il sito con lo schema completo (https://...).
Risposte
201
Il fornitore 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.
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/suppliers \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ricambi Lombardia S.r.l.",
  "email": "ordini@ricambi.example.it",
  "phone": "+390212345678",
  "city": "Milano",
  "zip_code": "20100",
  "tax_id": "01234567890",
  "website": "https://ricambi.example.it"
}'
Risposta
{
  "object": "supplier",
  "id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "name": "Ricambi Lombardia S.r.l.",
  "email": "ordini@ricambi.example.it",
  "phone": "+390212345678",
  "phone_national": "02 1234 5678",
  "address": "Via Mecenate 12",
  "city": "Milano",
  "zip_code": "20138",
  "tax_id": "01234567890",
  "comments": null,
  "bank_account_iban": "IT60X0542811101000000123456",
  "website": "https://ricambi.example.it",
  "website_display": "ricambi.example.it",
  "supplier_type": "ricambi",
  "created_at": "2025-02-11T10:00:00Z",
  "updated_at": "2026-06-03T14:20:00Z"
}
GET /v1/suppliers/{id}
Permesso richiesto suppliers.read

Recupera un fornitore

Restituisce il fornitore con i riepiloghi collegati: ordini, articoli forniti e spese.
Risposte
200
Il fornitore 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/suppliers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "supplier",
  "id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "name": "Ricambi Lombardia S.r.l.",
  "email": "ordini@ricambi.example.it",
  "phone": "+390212345678",
  "phone_national": "02 1234 5678",
  "address": "Via Mecenate 12",
  "city": "Milano",
  "zip_code": "20138",
  "tax_id": "01234567890",
  "comments": null,
  "bank_account_iban": "IT60X0542811101000000123456",
  "website": "https://ricambi.example.it",
  "website_display": "ricambi.example.it",
  "supplier_type": "ricambi",
  "created_at": "2025-02-11T10:00:00Z",
  "updated_at": "2026-06-03T14:20:00Z"
}
PATCH /v1/suppliers/{id}
Permesso richiesto suppliers.write

Aggiorna un fornitore

Aggiorna solo i campi presenti nel corpo: gli altri restano invariati.
Risposte
200
Il fornitore 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.
500
Errore imprevisto del server. Il dettaglio finisce nei log, non nella risposta.
Richiesta
curl -X PATCH https://api.officina.it/v1/suppliers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ricambi Lombardia S.r.l.",
  "email": "ordini@ricambi.example.it",
  "phone": "+390212345678",
  "city": "Milano",
  "zip_code": "20100",
  "tax_id": "01234567890",
  "website": "https://ricambi.example.it"
}'
Risposta
{
  "object": "supplier",
  "id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "name": "Ricambi Lombardia S.r.l.",
  "email": "ordini@ricambi.example.it",
  "phone": "+390212345678",
  "phone_national": "02 1234 5678",
  "address": "Via Mecenate 12",
  "city": "Milano",
  "zip_code": "20138",
  "tax_id": "01234567890",
  "comments": null,
  "bank_account_iban": "IT60X0542811101000000123456",
  "website": "https://ricambi.example.it",
  "website_display": "ricambi.example.it",
  "supplier_type": "ricambi",
  "created_at": "2025-02-11T10:00:00Z",
  "updated_at": "2026-06-03T14:20:00Z"
}
DELETE /v1/suppliers/{id}
Permesso richiesto suppliers.write

Elimina un fornitore

Eliminazione logica del fornitore. Ordini e spese già registrati restano intatti.
Risposte
200
Il fornitore 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/suppliers/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "supplier",
  "id": "6f2b8c14-9d70-4a35-b8e2-1c5f7a3d9e60",
  "name": "Ricambi Lombardia S.r.l.",
  "email": "ordini@ricambi.example.it",
  "phone": "+390212345678",
  "phone_national": "02 1234 5678",
  "address": "Via Mecenate 12",
  "city": "Milano",
  "zip_code": "20138",
  "tax_id": "01234567890",
  "comments": null,
  "bank_account_iban": "IT60X0542811101000000123456",
  "website": "https://ricambi.example.it",
  "website_display": "ricambi.example.it",
  "supplier_type": "ricambi",
  "created_at": "2025-02-11T10:00:00Z",
  "updated_at": "2026-06-03T14:20:00Z"
}