Repository navigation
feat: add general journal endpoints - #18
Merged
Merged
Conversation
mwfister
force-pushed
the
add-general-journal-endpoints
branch
2 times, most recently
from
September 21, 2026 13:51
a857c70 to
97b32c6
Compare
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
force-pushed
the
add-general-journal-endpoints
branch
from
September 21, 2026 13:55
97b32c6 to
85c0374
Compare
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>
Contributor
Author
|
@kraklo Don't expect you to be thorough here, it's a bit comical in size what we generated. |
kraklo
approved these changes
Oct 6, 2026
kraklo
left a comment
Contributor
There was a problem hiding this comment.
Yep majority a rubber stamp but the changes seem sane to me and we've got all the version number bumps and whatnot
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
/companies({company_id})/journalsapi/journal_api.py/companies({company_id})/journals({journal_id})api/journal_api.py/companies({company_id})/journals({journal_id})/journalLinesapi/journal_line_api.py/companies({company_id})/journals({journal_id})/journalLines({journalLine_id})api/journal_line_api.py/companies({company_id})/journals({journal_id})/journalLines({journalLine_id})/dimensionSetLinesapi/dimension_set_line_api.py/companies({company_id})/journals({journal_id})/Microsoft.NAV.postapi/journal_api.py/companies({company_id})/generalLedgerEntriesapi/general_ledger_entry_api.pyEvery collection GET takes
$filter,$top,$skip,$limit,$expandand$select, following the style already used by the other collection GETs. DELETE takes anIf-Matchheader. TheMicrosoft.NAV.postblock mirrors the existingpostActionSalesInvoicesone.Creating a journal in one call
POST /journalsacceptsjournalLines, and each line acceptsdimensionSetLines— a deep insert three levels deep:This works because the parent API page declares
journalLinesas a part with anEntityName, anEntitySetNameand aSubPageLink, 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
journalrequest body changed to enable this — it already existed incomponents.requestBodiesand was referenced by nothing.journalLinesitems are a direct$refrather than an inline schema, which keeps the generator from emitting a duplicate inline model and renaming existing public ones.DELETEon 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
dimensionspropertydimensionswas present onjournalLine,generalLedgerEntry,customerPaymentandtimeRegistrationEntry, inherited from the published v2.0 OpenAPI definition. No such property exists on those types. The service rejects it on both read and write: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})/dimensionSetLinesreturns the dimensions of a posted entry. Nothing is lost.This drops the now-unreferenced
DimensiontypeandGeneralLedgerEntryDimensionsInnermodels.dimensionsoncompanyis 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:journalMicrosoft.NAV.postbound action returns 204 with no content;templateDisplayNamejournalLinepostingDateis adate;dimensionSetLinesis a navigation; the five properties added below;dimensionsis not a propertydimensionSetLineparentTypeincludes"Journal Line", so dimension set lines hang off a journal linegeneralLedgerEntryidis a GUID andentryNumberis the integer;postingDateis adate; noexternalDocumentNumber; the additional-currency amountsProperty 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,balancingAccountNumberjournal—templateDisplayNamegeneralLedgerEntry—entryNumber,additionalCurrencyDebitAmount,additionalCurrencyCreditAmountThe
$selectand$expandenums on the new GETs are extended to match. Thejournal,journalLineandgeneralLedgerEntryschemas were already present incomponents.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.idwas typed as an integer. It is a uuid. The integer key isentryNumber, which the spec was missing entirely, so it is added.postingDateis a plainYYYY-MM-DDstring on bothjournalLineandgeneralLedgerEntry. It was declaredformat: date-time; with eitherdate-timeordate, pydantic parses it into adatetime/dateobject andto_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: trueand nothing isrequired, so a sparse response parses.Incidental
model/general_ledger_setup.pyanddocs/GeneralLedgerSetup.mdchange because that model had drifted from the pinned generator — it was previously generated with a different configuration (its doc example still saidopenapi_client). Regenerating with 7.13.0 brings it back in line:idbecomesstrlike every other uuid in the package, andallowPostingFrom/allowPostingTobecomedate, 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 pybusinesscentralreports no issues in 115 source files; 145 tests pass.Exercised against a live environment, through the generated client where noted:
dimensionSetLines→ 201, dimensions readable afterwards.dimensionSetLines→ 201, dimensions confirmed on the line by a follow-up GET.Microsoft.NAV.post→ 204, and the resulting entries are readable bydocumentNumberwith their dimensions intact.dimensionsrejected with 400 on all four types, by both$expandand POST.Everything created during verification was deleted afterwards.
Version bumped to 3.10.0.
🤖 Generated with Claude Code