> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Journals

> The company's accounting journals: categories, numbering formats, defaults.

A journal is the register a document is booked and **numbered** in. Its `category`
says which documents it takes (`sales_invoice`, `sales_credit`,
`purchases_invoice`, `purchases_credit`, `incoming_sales`, `incoming_purchases`); a
few historical incoming journals read as `incoming`, read-only.

## Numbering

Every document of the journal gets a number drawn from a counter, rendered
according to `numbering_format`: `{code}<sep><period><sep>{seq:N}`, where `<sep>`
is `-` or `/`, and `N` (2–8) is the width of the counter — invoice 119 renders as
`0119` with `{seq:4}`. Default: `{code}-{year4}-{seq:5}`.

`<period>` combines one or more of these tokens, computed from the issue date:

| Token               | Represents                                 | Example *(2026-01-15, fiscal year starting in July)* |
| ------------------- | ------------------------------------------ | ---------------------------------------------------- |
| `{year4}`           | Year                                       | `2026`                                               |
| `{year2}`           | Year, 2 digits                             | `26`                                                 |
| `{month}`           | Month, 2 digits                            | `01`                                                 |
| `{fys4}` / `{fye4}` | Start / end of the current **fiscal year** | `2025` / `2026`                                      |
| `{fys2}` / `{fye2}` | Same, 2 digits                             | `25` / `26`                                          |
| `{fy4}`             | Both fiscal-year years, joined by a dash   | `2025-2026`                                          |
| `{fy2}`             | Same, 2 digits, concatenated               | `2526`                                               |

The `fy*` tokens only differ from `{year4}`/`{year2}` when `sequence_scope` is
`fiscal-year` and the fiscal year does not start in January; otherwise they render
the same value.

`sequence_scope` (`never`, `monthly`, `calendar-year`, `fiscal-year`) says when the
counter resets.

The `code` prefixes that number: it is unique within the company, case-insensitive
(`409 duplicate_journal_code`).

`code`, `category` and `sequence_scope` are **fixed at creation**
(`422 field_not_editable` afterwards): changing them would break the continuity of
the numbers already handed out. For another code or category, create a journal.

## Default journal

Each category has a default journal, the one `POST /documents` books a document in
when it names none. It must stay usable:

* `is_default: true` promotes a journal and demotes the previous default of the
  same category;
* a journal cannot be created or updated into being both default and inactive at
  once, and the last default of a category cannot be demoted with `is_default: false`
  (`422 default_journal_required`) — promote another journal instead. The rule
  looks at the final state: promoting an inactive journal passes if the same
  request reactivates it.

## On documents

`documents.journal_id` is the journal the document is booked in, `null` when it has
none (many received documents). A document imported as `purchase`/`sale` is booked
in the default incoming journal at creation.