CashBook

List cashbook entries

Returns a paginated, filtered, ordered window of cashbook entries for the authenticated user's company.

The response envelope extends the standard ListEnvelope with two cashbook-specific fields:

  • opening_balance — the running-balance anchor at the start of the from window. Zero when no from is set (the running balance simply accumulates from zero on the first row).
  • total_items — the full filtered count, so clients can render "n of N" without a follow-up request.

Page rows carry running_balance already computed in order_direction from opening_balance. Do not re-sort client-side without recomputing.

get/v1/cashbook-entries

Request

  • Base URL: https://api.officina.it
  • URL: https://api.officina.it/v1/cashbook-entries
  • Auth: HTTP bearer

Query parameters

tab'tutto' | 'entrate' | 'uscite'

Row-type filter. tutto (default) returns both income and expense; entrate returns income only; uscite returns expense only. The Italian tokens mirror the web app's URL params so deep-links transfer 1:1.

financial_account_idstring

Filter to a single financial account (UUID).

preset'rel30' | 'rel90' | 'rel365' | 'year' | 'Q1' | 'Q2' | 'Q3' | 'Q4' | 'month' | 'custom' | 'all'

Date filter preset. Relative presets (rel30/rel90/rel365) are resolved server-side from "now" and ignore from/to. Absolute presets (year, Q1-Q4, month, custom) require both from and to. all returns everything (no time bound). Unknown values are rejected with 422.

Omitting from/to/preset gives the default window, the last 12 months. This tier is stateless: a selection applies to the request that carries it and is never stored, so the same request always covers the same range. The effective range is echoed back in date_filter.

fromstring date

Inclusive lower bound on payment_date (YYYY-MM-DD). When set, opening_balance in the response carries the running total of all earlier matching rows; the page itself starts from zero offset within the window.

tostring date

Inclusive upper bound on payment_date (YYYY-MM-DD).

qstring

Substring match on the counterparty name (customer_name for income rows, supplier_name for expense rows).

limitinteger

Page size. Default 20, max 100. Out-of-range values clamp silently — never error.

starting_afterstring

Opaque cursor from a prior response's next-page link. Pass verbatim. Omit on the first page.

order_direction'asc' | 'desc'

Sort by payment_date. desc (default) lists newest-first; asc lists oldest-first. Invalid values are rejected with 422 — silent clamping would silently flip the running balance.

Response

Page of cashbook entries.

object'list' required

Polymorphic discriminator.

has_moreboolean required

True if more results exist beyond this page. Use this for the "load more" UI — data.length alone is unreliable because a full page may still be the last page.

next_starting_afterstring

Opaque cursor for the next page. Present (and non-empty) when has_more is true; omitted otherwise. Pass the value verbatim as ?starting_after= on the follow-up request. Clients MUST NOT parse it — today it encodes an offset, tomorrow it may encode a (created_at, id) tuple without a wire-visible change.

urlstring required

The request path that produced this list.

opening_balancenumber double required

Running-balance anchor at the start of the from window. Zero when from is unset.

total_itemsinteger required

Full filtered count, ignoring pagination.

Changes

No recorded changes to this operation across all 1 revision of this API.