Integrations & ingestion · PG-18
Ingest everything. Replace nothing.
Under your ERP, not another ERP: one mapping model for every source system, a receipt for every load, and no rip-and-replace.
Ledgerbook ingests and standardises, and it does not replace: your estate keeps its systems of entry while the ledger becomes the governed book of record beneath them. Both paths — batch and streaming — hit the same core with the same validator, idempotency, chain-hashing and provenance, so no ingestion route can skip the rules. Practically: source systems and third-party connectors are built on a published ingestion contract; every load declares versioned mapping profiles and emits a reconciliation receipt against source control totals, and unmapped rows land in a queryable suspense queue instead of being dropped. Bank-format presets for OFX, CAMT.053, MT940 and BAI2 are Roadmap; today any format maps through the same versioned profile machinery.
Verified 2026-09-19 · ingestion contract PH-1 · bank-format presets Roadmap (PH-2)
Ingestion surfaces
Four ways in, one governed core behind all of them.
Run the full validator against an entry or a whole batch — balance, currency, account state, dimensions, equation, policy — and get structured, machine-readable errors without writing anything. The pre-commit surface ingestion adapters call first. FR-116/149 · PH-1
Submit whole entries in bulk with explicit batch semantics — all-or-nothing or per-item validated — carrying a batch idempotency key on top of per-item keys, so a retried partially-acknowledged batch can never duplicate an item. FR-140–143 · PH-1
The streaming path runs over Kafka or Redpanda, carrying CloudEvents 1.0 envelopes, and hits the same core as REST: same validator, idempotency, chain-hashing and provenance. "Reverse ETL" here means the warehouse-to-ledger direction — bulk loads through the batch endpoint under a versioned mapping profile; the ledger-to-warehouse direction is a cursor export and is named as one. Adapters transform payload shapes only — never semantics. FR-146 · PH-1 parity contract
Agent pipelines reach the same ingestion surface through MCP with identical semantics and error taxonomy, air-gap included — proposals only, with approvals reserved to policy and humans. FR-343 · PH-1 read/propose; full tool surface Roadmap
The connector contract
Source connectors are third-party surfaces, built on this contract — not built into the core. Every adapter must do five things:
- Declare itself. Source system and version are part of the adapter's identity, so every row can be traced back to the exact extract that produced it.
- Register versioned mapping profiles. Mapping from source system to accounts, dimensions and currency lives in registry data — versioned, reviewable — with an explicit unmapped_field_policy, never hidden in code.
- Emit per-row provenance. A source-row hash plus actor hints, so ingested events carry dual attribution: the connector that wrote, and the business actor from the source system.
- Honour the batch and stream contracts. Including the batch idempotency key — so a retried partially-acknowledged batch can never duplicate an item.
- Transform shapes only, never semantics. Adapters may reshape payloads; they may not change what an entry means or bypass validation.
Contract surface PH-1 · rules-engine packs and signed module registry Roadmap
A receipt for every load
Ingestion you can audit: nothing posted silently, nothing dropped silently.
Mapping registry
Mapping profiles are versioned registry data: legacy COA to ledger dimensions, group-COA mapping for consolidation, currency mapping, and each profile's idempotency-key scope. Changing a mapping is a new version, not an edit to history.
Reconciliation receipts
Every load emits a receipt comparing source control totals against posted volumes per scenario and book, with match-strategy counts (1:1, 1:N, N:1) and exceptions — so the load, not a person, carries the evidence that it balanced.
Suspense queue
Unmapped or unreconciled items land in a queryable suspense queue — reported, never silently dropped, never auto-posted. Clearing suspense is an explicit, provenanced operation.
Idempotency that does not forget
Idempotency keys are scoped to tenant, ledger, caller and key — and on money-bearing writes they never expire, so a replay can never duplicate a posting, even a year later.
Dual attribution for ingested events
Ingested events name two actors: the connector or service identity that wrote, and the business actor from the source system — with the exact row hash or stream offset as the tie-breaker.
Ordering you can rely on
Commits serialise per account partition, cross-partition batches are order-independent, and the append path assigns a strictly monotonic, gap-detectable sequence — so reconstruction never depends on timestamps.
What a governed load looks like
Validate, submit with a batch key, and read the receipt. Adaptor code never touches semantics.
# 1 · a mapping profile is versioned registry data, never code
profile erp-sap-ecc/v4:
source: "sap_ecc" # source system + version are declared
coa_map: "legacy_coa → group_dimensions"
unmapped_field_policy: "suspense"
idempotency_key_scope: "load_id"
# 2 · every load carries its batch key and declares its profile version
POST /v1/provisions { "profile": "erp-sap-ecc/v4", "batch_key": "load-2026-09-19-003" }
# 3 · the load answers with a reconciliation receipt, not a shrug
← 202 { "posted": 1042, "control_total_match": true, "strategy_counts": { "1:1": 1031, "1:N": 11 }, "suspense": 0, "receipt_id": "rcpt_9f31…" }Bank and statement formats
Named, configurable profile presets — each pre-mapping a format's date, amount-decimal and reference conventions onto registry profiles.
Roadmap (PH-2): the four presets above ship as named, configurable templates and are starting points like any other profile — under the same versioning, receipt-reconciliation and suspense-queue rules, never code. Today, any bank or statement format maps through the same versioned profile machinery; the presets remove the first day of setup, they do not gate the capability.
Your estate, one sink
The grid below is where ingestion starts — the systems you already run.
Legacy and incumbent ERPs
SAP, Oracle, Microsoft, NetSuite-class estates: extracts and third-party connectors feed mapping profiles, and consolidation rolls each entity's books into one group view — group-COA mapping, intercompany as explicit paired entries, HQ translation through posted entries.
Banks and PSPs
Statement files and payment-provider exports land via versioned profiles with bank-format presets on the Roadmap. Their control totals become reconciliation receipts; unmatched lines go to suspense.
Billing and revenue systems
Subscriptions, invoicing and revenue platforms feed entry batches with per-item and batch idempotency — replay-safe, so late-arriving adjustments can be resubmitted without duplicate postings.
Spreadsheets
The long tail still lives in files. Sheet imports run the same validator and leave the same receipts — a spreadsheet is a source system like any other, with the same suspense rules.
Agent pipelines
Agents ingest and propose over MCP with identical semantics to HTTP: proposals carry full attribution, approvals stay with policy and humans, and every load leaves a provenance trail.
Guides and connectors
Per-tool integration guides (Ledgerbook + <tool>) are hand-written against the contract above and in preparation — published only with per-tool specifics, never as renamed duplicates of this page.
Roadmap
Ingestion FAQ
What happens to my chart of accounts?
Your chart of accounts becomes data, not schema. Account identity is a tuple of dimension values — entity, cost centre, project, account code — declared in a dimension registry, with an optional hierarchy tree for reporting rollups. Mapping profiles translate each source COA onto those dimensions, and adding a dimension value never requires migrating existing postings.
Does Ledgerbook replace my ERP?
No. The ERP stays the system of entry and workflow; Ledgerbook is the downstream sink that consolidates what your estate produces into one provable book of record. There is no rip-and-replace: you keep SAP, Oracle, NetSuite, Dynamics or whatever runs the business, and ingest from them — extract files, streams and APIs included.
Do you ship SAP and NetSuite connectors?
The core ships the contract they build on: the versioned mapping registry, reconciliation receipts, the suspense queue and the batch/stream interfaces. Named source connectors — QBO, Sage, NetSuite, SAP extracts, bank and PSP statement files — are third-party surfaces built on that contract, not built into the core. Integration guides for named tools are in preparation.
Does streaming skip validation?
No. Streaming ingestion runs the same validator, invariants, idempotency, chain-hashing and provenance capture as synchronous writes — there is no fast lane that skips the rules. Ingestion adapters may transform payload shapes only, never semantics, and a load that cannot state its provenance fails closed rather than defaulting to a system actor.
Bring your messiest source system
Design partners get an ingestion walkthrough against their own extract — mapping profile, receipt and suspense queue included.