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 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. 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. 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. 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.