Prima nota

Movimenti di cassa e conti finanziari.

5 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/cashbook-entries
Permesso richiesto cashbook.read

Elenca i movimenti di cassa

I movimenti di prima nota, incassi e pagamenti insieme. Filtra per conto con financial_account_id e per periodo con from / to. Ogni riga porta running_balance, il saldo progressivo dopo quel movimento, e i riferimenti al documento che lo ha generato (fattura, scontrino, scheda lavoro o spesa).
Risposte
200
I movimenti di prima nota.
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/cashbook-entries \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "cashbook_entry",
      "id": "2f8b6d31-7a05-4c94-8e26-1d5f3a9c7b40",
      "payment_type": "incasso",
      "amount": 285.36,
      "payment_date": "2026-07-17",
      "financial_account_id": "d61c8b04-3f97-4a25-8e70-9b2d5f1a6c38",
      "financial_account_name": "Cassa",
      "customer_name": "Mario Rossi",
      "supplier_name": null,
      "invoice_id": "4412e7b9-0c35-4a18-92d7-5b6ea1f38c04",
      "invoice_seq_number": 214,
      "invoice_issued_at": "2026-07-16T10:30:00Z",
      "running_balance": 4821.9
    }
  ],
  "has_more": false,
  "url": "/v1/cashbook-entries",
  "date_filter": {
    "object": "date_filter",
    "preset": "year",
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}
GET /v1/financial-accounts
Permesso richiesto cashbook.read

Elenca i conti

I conti configurati (cassa, banca), da usare per valorizzare financial_account_id sui pagamenti.
Risposte
200
I conti configurati.
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/financial-accounts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "list",
  "data": [
    {
      "object": "financial_account",
      "id": "d61c8b04-3f97-4a25-8e70-9b2d5f1a6c38",
      "type": "cassa",
      "name": "Cassa"
    },
    {
      "object": "financial_account",
      "id": "7e3c9a25-1b68-4f40-9d72-5a8e2c6b3f19",
      "type": "banca",
      "name": "Banca Intesa"
    }
  ],
  "has_more": false,
  "url": "/v1/financial-accounts"
}
POST /v1/financial-accounts
Permesso richiesto cashbook.write

Crea un conto

Crea un conto finanziario. type distingue cassa e banca.
Risposte
201
Il conto 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/financial-accounts \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Banca Intesa",
  "type": "banca"
}'
Risposta
{
  "object": "financial_account",
  "name": "Banca Intesa",
  "type": "banca"
}
PATCH /v1/financial-accounts/{id}
Permesso richiesto cashbook.write

Aggiorna un conto

Aggiorna il nome del conto.
Risposte
200
Il conto 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.
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/financial-accounts/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nuovo nome"
}'
Risposta
{
  "object": "financial_account",
  "id": "7e3c9a25-1b68-4f40-9d72-5a8e2c6b3f19"
}
DELETE /v1/financial-accounts/{id}
Permesso richiesto cashbook.write

Elimina un conto

Elimina il conto. I movimenti già registrati su di esso restano intatti.
Risposte
200
Il conto 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/financial-accounts/{id} \
  -H "Authorization: Bearer ofk_live_LA_TUA_CHIAVE" \
  -H "X-API-Version: 2026-07-20"
Risposta
{
  "object": "financial_account",
  "id": "7e3c9a25-1b68-4f40-9d72-5a8e2c6b3f19"
}