Skip to content

feat: add general journal endpoints - #18

Merged
mwfister merged 4 commits into
masterfrom
add-general-journal-endpoints
Oct 6, 2026
Merged

mwfister merged 4 commits into
masterfrom
add-general-journal-endpoints

Conversation

@mwfister

@mwfister mwfister commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Adds the Business Central general journal endpoints to the spec and regenerates the client, so a downstream service can create and post general journals through generated models instead of raw HTTP.

The headline capability is that a whole journal — the batch, its lines, and each line's dimensions — can be created in a single request, and posted with a second one.

Endpoints

Path Verbs Generated module
/companies({company_id})/journals GET, POST api/journal_api.py
/companies({company_id})/journals({journal_id}) GET, DELETE api/journal_api.py
/companies({company_id})/journals({journal_id})/journalLines GET, POST api/journal_line_api.py
/companies({company_id})/journals({journal_id})/journalLines({journalLine_id}) PATCH, DELETE api/journal_line_api.py
/companies({company_id})/journals({journal_id})/journalLines({journalLine_id})/dimensionSetLines GET, POST api/dimension_set_line_api.py
/companies({company_id})/journals({journal_id})/Microsoft.NAV.post POST → 204 api/journal_api.py
/companies({company_id})/generalLedgerEntries GET api/general_ledger_entry_api.py

Every collection GET takes $filter, $top, $skip, $limit, $expand and $select, following the style already used by the other collection GETs. DELETE takes an If-Match header. The Microsoft.NAV.post block mirrors the existing postActionSalesInvoices one.

Creating a journal in one call

POST /journals accepts journalLines, and each line accepts dimensionSetLines — a deep insert three levels deep:

api.post_journal(
    company_id=company_id,
    content_type="application/json",
    post_journal_request=PostJournalRequest(
        code="STOCKSYNC",
        journalLines=[
            JournalLine(
                lineNumber=10000, accountType="G/L Account", accountId=debit_account,
                postingDate="2026-10-05", documentNumber="REF-1", amount=100.0,
                dimensionSetLines=[DimensionSetLine(code="AREA", valueCode="10")],
            ),
            ...
        ],
    ),
)

This works because the parent API page declares journalLines as a part with an EntityName, an EntitySetName and a SubPageLink, which is what the service requires for a nested insert. It is not covered by Microsoft's own end-to-end tests, so it was verified directly (below).

Only the journal request body changed to enable this — it already existed in components.requestBodies and was referenced by nothing. journalLines items are a direct $ref rather than an inline schema, which keeps the generator from emitting a duplicate inline model and renaming existing public ones.

DELETE on a journal completes the cycle. Posting does not remove the batch — the post action returns 204 and consumes the lines, but the batch itself is still returned by the collection afterwards. Without a delete, a caller that creates a batch per sync run accumulates empty batches indefinitely, all visible to users in the general journal.

Removing the dimensions property

dimensions was present on journalLine, generalLedgerEntry, customerPayment and timeRegistrationEntry, inherited from the published v2.0 OpenAPI definition. No such property exists on those types. The service rejects it on both read and write:

GET  ...?$expand=dimensions
400  Could not find a property named 'dimensions' on type 'Microsoft.NAV.journalLine'

POST journalLine with a `dimensions` body
400  The property 'dimensions' does not exist on type 'Microsoft.NAV.journalLine'

Confirmed for all four types against a live environment. This reverses an earlier judgement in this branch that the field should be kept so that responses still carrying it would parse — they cannot, because the service never sends it.

Dimensions are reached instead through dimensionSetLines, which is already modelled, and which survives posting: GET /generalLedgerEntries({id})/dimensionSetLines returns the dimensions of a posted entry. Nothing is lost.

This drops the now-unreferenced Dimensiontype and GeneralLedgerEntryDimensionsInner models. dimensions on company is a different, genuine navigation property (GET /companies?$expand=dimensions → 200) and is unchanged.

Source of truth

Each new path block in the spec carries a # ref: comment pointing at the Microsoft reference page it was built from:

Entity Reference What it confirms here
journal dynamics_journal the Microsoft.NAV.post bound action returns 204 with no content; templateDisplayName
journalLine dynamics_journalline postingDate is a date; dimensionSetLines is a navigation; the five properties added below; dimensions is not a property
dimensionSetLine dynamics_dimensionsetline parentType includes "Journal Line", so dimension set lines hang off a journal line
generalLedgerEntry dynamics_generalledgerentry id is a GUID and entryNumber is the integer; postingDate is a date; no externalDocumentNumber; the additional-currency amounts

Property parity

Cross-checking the three entities against the reference brought them to full property parity. Previously missing, now added to both the entity schema and the request body where one exists:

  • journalLine — journalId, taxCode, balanceAccountType, balancingAccountId, balancingAccountNumber
  • journal — templateDisplayName
  • generalLedgerEntry — entryNumber, additionalCurrencyDebitAmount, additionalCurrencyCreditAmount

The $select and $expand enums on the new GETs are extended to match. The journal, journalLine and generalLedgerEntry schemas were already present in components.schemas — only the paths were missing — so this mostly wires them up, with two corrections.

Schema corrections

Microsoft's published spec is stricter than the live API, so these follow the same loosening this repo has applied before:

  • generalLedgerEntry.id was typed as an integer. It is a uuid. The integer key is entryNumber, which the spec was missing entirely, so it is added.
  • postingDate is a plain YYYY-MM-DD string on both journalLine and generalLedgerEntry. It was declared format: date-time; with either date-time or date, pydantic parses it into a datetime/date object and to_dict() no longer returns the string the caller passed in. Typing it as a nullable string round-trips faithfully and still puts "2026-10-05" on the wire.

All new response properties are nullable: true and nothing is required, so a sparse response parses.

Incidental

model/general_ledger_setup.py and docs/GeneralLedgerSetup.md change because that model had drifted from the pinned generator — it was previously generated with a different configuration (its doc example still said openapi_client). Regenerating with 7.13.0 brings it back in line: id becomes str like every other uuid in the package, and allowPostingFrom/allowPostingTo become date, which is what the spec declares.

The README's API endpoint table is filled in for the journal, journal line and general ledger entry classes, which had not been regenerated when those paths were added.

Verification

Generator run (7.13.0, packageName=pybusinesscentral packageVersion=3.10.0) exits 0 with no errors, adds no unexpected models and renames none. mypy pybusinesscentral reports no issues in 115 source files; 145 tests pass.

Exercised against a live environment, through the generated client where noted:

  • Deep insert of a journal with nested lines → 201, lines echoed back.
  • Deep insert of a line with nested dimensionSetLines → 201, dimensions readable afterwards.
  • Three-level deep insert — a journal whose lines each carry dimensionSetLines → 201, dimensions confirmed on the line by a follow-up GET.
  • 200 lines in a single deep insert → 201 in 10.9s.
  • Microsoft.NAV.post → 204, and the resulting entries are readable by documentNumber with their dimensions intact.
  • Create → get → delete → get again returning 404, all through the generated client.
  • dimensions rejected with 400 on all four types, by both $expand and POST.

Everything created during verification was deleted afterwards.

Version bumped to 3.10.0.

🤖 Generated with Claude Code

@mwfister
mwfister force-pushed the add-general-journal-endpoints branch 2 times, most recently from a857c70 to 97b32c6 Compare September 21, 2026 13:51
Adds the Business Central general journal paths to the spec and
regenerates the client, so a downstream service can post general journal
lines through generated models instead of raw HTTP:

- GET            /companies({company_id})/journals
- GET, POST      /companies({company_id})/journals({journal_id})/journalLines
- PATCH, DELETE  .../journalLines({journalLine_id})
- GET, POST      .../journalLines({journalLine_id})/dimensionSetLines
- POST           .../journals({journal_id})/Microsoft.NAV.post
- GET            /companies({company_id})/generalLedgerEntries

Each new path block carries a "# ref:" comment pointing at the Microsoft
reference page it was built from, so the source of truth is checkable at
the point of change.

dimensionSetLines is the documented way to set a dimension on a journal
line: journalLine lists it as a navigation and dimensionSetLine's
parentType includes "Journal Line". It mirrors the blocks that already
exist for salesInvoiceLines and salesCreditMemoLines, and as there, the
field is also exposed on the journalLine request body.

Cross-checking the three entities against the reference brought them to
full property parity. Previously missing:

- journalLine: journalId, taxCode, balanceAccountType, balancingAccountId,
  balancingAccountNumber
- journal: templateDisplayName
- generalLedgerEntry: entryNumber, additionalCurrencyDebitAmount,
  additionalCurrencyCreditAmount

Three further corrections were needed for real responses to parse under
pydantic v2:

- generalLedgerEntry.id is a uuid, not an integer; the integer key is
  entryNumber.
- journalLine.postingDate and generalLedgerEntry.postingDate carry plain
  YYYY-MM-DD date strings. Declaring them as date-time made the client
  coerce them to datetime objects that no longer round-trip.
- The journalLine request body types its dimensions items as a direct
  $ref to dimensiontype rather than an inline anyOf with a null branch.
  The inline form is structurally identical to the one on the entity
  schemas, so the generator deduplicated them and renamed the existing
  GeneralLedgerEntryDimensionsInner model. A $ref emits no inline model,
  so nothing is renamed and the request body gains a properly typed
  List[Dimensiontype]. The same shape is already used by
  journal.journalLines.

dimensions is kept on journalLine and generalLedgerEntry even though the
current reference no longer lists it, so responses that still carry it
keep parsing.

Regenerating also re-types generalLedgerSetup from the pinned generator,
which had drifted from a different generation.

Bumps the package version to 3.10.0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mwfister
mwfister force-pushed the add-general-journal-endpoints branch from 97b32c6 to 85c0374 Compare September 21, 2026 13:55
mwfister and others added 3 commits October 5, 2026 17:22
Adds POST /companies({company_id})/journals and extends the journal
request body with the journalLines navigation property, so a journal
and all of its lines can be created in one request instead of one call
per line.

The journal API page exposes journalLines as a page part with a
SubPageLink on the batch id, which is what makes the nested insert
resolve the parent. Line items reference the journalLine schema
directly rather than inline, so no additional inline model is emitted.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The `dimensions` property on journalLine, generalLedgerEntry,
customerPayment and timeRegistrationEntry was inherited from the
published v2.0 OpenAPI definition, but no such property exists on those
types. The service rejects it on both read and write:

    GET  ...?$expand=dimensions
    400 Could not find a property named 'dimensions' on type
        'Microsoft.NAV.journalLine'

    POST journalLine with a `dimensions` body
    400 The property 'dimensions' does not exist on type
        'Microsoft.NAV.journalLine'

Verified against a sandbox environment for all four types. Dimensions
are reachable through the `dimensionSetLines` navigation property, which
is already modelled, so nothing is lost.

Drops the now-unreferenced Dimensiontype and
GeneralLedgerEntryDimensionsInner models. The `dimensions` property on
company is a different, genuine navigation property and is unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adds the journal entity path that was missing alongside the collection:

- GET     /companies({company_id})/journals({journal_id})
- DELETE  /companies({company_id})/journals({journal_id})

The delete is needed to complete a create-and-post cycle. Posting a
journal consumes its lines but leaves the batch itself in place, so a
caller that creates a batch per sync run has no way to clean up after
itself and the batches accumulate indefinitely, visible to users in the
general journal. Confirmed against a sandbox environment: the batch is
still returned by the collection after the post action returns 204.

The get is not required by that cycle but rounds out the entity and
gives callers a cheap way to re-read a batch by id.

Both verified end to end through the generated client: create, get,
delete, then get again returning 404.

Regenerating adds no models and renames none. Also fills in the API
endpoint table in the README, which had not been regenerated when the
journal, journal line and general ledger entry paths were added.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mwfister
mwfister requested a review from kraklo October 6, 2026 01:13
@mwfister

mwfister commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

@kraklo Don't expect you to be thorough here, it's a bit comical in size what we generated.
The gist is I'm spinning up APIs for Journalling stock. I've hooked up to our BC sandbox to validate these calls - it does apparently support deeply nested properties.
Also dropped off fake dimensions properties from this.

@kraklo kraklo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep majority a rubber stamp but the changes seem sane to me and we've got all the version number bumps and whatnot

@mwfister
mwfister merged commit 659fdb2 into master Oct 6, 2026
10 checks passed
@mwfister
mwfister deleted the add-general-journal-endpoints branch October 6, 2026 01:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants