Reading accounting data

📘
Conventions
In the examples, $API_URL stands for the api_url of the connected license and $ACCESS_TOKEN for a valid access token. See Quickstart.

This guide shows the typical sequence of calls used to read data from a Horus Office folder.

1. Find the folder

curl -X POST "$API_URL/folders.list" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{ "Mode": 0, "Filter": { "VatNumber": "BE0000000097", "IsVatLiable": true } }'

Keep the folder Id: it is the FolderId used by nearly every other endpoint.

2. Load the reference data

Reference data changes rarely. Load it once and cache it per folder:

Data	Endpoint
Fiscal years and closure dates	`fiscal-years.list`
Daybooks (journals)	`daybooks.list`
Chart of accounts	`accounts.list`
Customers, suppliers, beneficiaries	`companies.list`
Vehicles	`vehicles.list`
Analytics (if `WithAnalytics`)	`cost-schemas.list`, `cost-sections.list`

3. Read entries and ledgers

Periods are expressed by month and year (StartMonth, StartYear, EndMonth, EndYear).

Book entries of a daybook

book-entries.list returns the entries of one daybook over a period:

{
  "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
  "DaybookId": "87f48c7e-54d1-48d2-aed7-447e6003bc67",
  "StartMonth": 1, "StartYear": 2024,
  "EndMonth": 12, "EndYear": 2024,
  "Filter": { "ConfirmedOnly": true }
}

Use book-entries.info to get the full detail of one entry.

Account histories (general ledger)

account-histories.list returns every entry line of the folder over a period, across all daybooks. Useful filters include:

Filter	Usage
`AccountSearchKeys`	Restrict to accounts starting with the given keys, e.g. `["6", "7"]` for P&L accounts.
`DaybookIds` / `ExcludedDaybookIds`	Include or exclude specific daybooks.
`CompanyId`	Lines of one customer or supplier.
`NotMatchedOnly`	Only lines that are not matched yet.
`ConfirmedOnly`	Only entries confirmed by the accountant.
`IncludeCompanyDetail`, `IncludeMatchDetail`, `IncludeVatDetail`, `IncludeCostDetail`	Enrich each line with additional details.

Account balance (trial balance)

account-balance.list returns the debit/credit state of each account over a period. Use AccountSearchKeys to narrow it down and IncludeUnusedAccounts to include accounts without movement.

Outstanding items

Need	Endpoint
Open items of customers	`customers.outstanding`
Open items of suppliers	`suppliers.outstanding`
Open sales invoices and their linked payments	`invoices.sales.outstanding.list` / `.info`

See Outstanding items & matching.

Confirmed vs. unconfirmed data

By default, lists include unconfirmed entries, i.e. entries not yet validated by the accountant. For reporting based on validated figures, set ConfirmedOnly: true.

Incremental synchronisation

To keep a local copy in sync without reloading everything, use the ModifiedAfter filter, available on companies.list, book-entries.list and account-histories.list among others:

Run a full load once and record the time at which you started it.
On the next run, pass that time as ModifiedAfter and only process what changed.
Store the new start time for the following run.

{
  "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
  "StartMonth": 1, "StartYear": 2024,
  "EndMonth": 12, "EndYear": 2024,
  "Filter": { "ModifiedAfter": "2024-06-01T00:00:00+00:00" }
}

🚧
Updated entries get a new Id
When an invoice or an operation is updated, a new book entry is generated. When synchronising entries, do not rely on the Id alone to detect changes; also reconcile on business identifiers such as the daybook and the entry number.

Reduce round trips

Use sideloading with Include to fetch related companies, daybooks or folders together with entries.
Enable gzip compression for large ledgers.