External accounting adapter boundary

Decision date: 2026-08-11

Decision

DATEV Unternehmen online (DUO) is the default and authoritative external GoBD bookkeeping and document-retention system. fin-hub remains the source of a reporting-only billing basis; it is not a bookkeeping system and does not issue invoices or handle payments.

Qonto is the first complementary candidate when a needed function is not provided conveniently by DUO. In particular, Qonto may provide the customer invoice draft/delivery workflow and the managed transfer of bank data, documents, and structured invoice data to DUO. Selecting Qonto for one of these capabilities does not make it the bookkeeping authority.

Other GoBD-capable systems remain possible through the same adapter contract. No provider is selected implicitly because another provider lacks a feature. The caller must request a capability and explicitly select a non-default adapter.

Data and authority flow

fin-hub billing-basis v0.1
        |
        | side-effect-free, version-pinned adapter
        v
provider draft / exception report
        |
        | authorized external workflow and legal/tax completion
        v
DATEV Unternehmen online (bookkeeping and document authority)

The preferred operational route is Qonto's managed DATEV integration when the invoice workflow already occurs in Qonto and it preserves all required fields. A direct DATEV integration is the fallback for non-Qonto sources or missing Qonto capabilities. Provider activation, credentials, tax configuration, customer master data, invoice numbering, delivery, and retention validation are deliberately outside the current adapter.

Contract

fin_hub.accounting defines:

a manifest with stable adapter ID, semantic adapter version, provider role, exact input schema version, and declared capabilities;
a side-effect-free prepare operation producing an incomplete provider draft with the source billing-basis ID as its idempotency reference;
an explicit schema-migration graph. An adapter rejects an unsupported source schema, including a new major version, unless a reviewed migration is registered;
capability checks that fail closed. The registry never silently falls back from DATEV to Qonto or another provider.

Provider payloads retain the billing-basis reference, client/engagement reference, service period, currency, amount, price reference, and source evidence IDs where supported. They explicitly mark legal and tax completion as required and contain no invoice number, issue date, or payment state.

Change and migration controls

Before a provider or adapter upgrade is promoted:

Pin and review the new provider API/export and adapter versions.
Add an explicit billing-basis schema migration if the exact input version changes; never reinterpret fields in place.
Run contract and golden-payload tests, then dual-run old and new adapters against the same billing-basis IDs.
Reconcile record counts, amounts, currency, exception sets, and evidence references in a non-production tenant.
Obtain bookkeeping/tax-owner acceptance before cutover, retain the prior adapter for rollback, and record the cutover decision.

Custody and retention

fin-hub retains reporting inputs, derivations, corrections, allocations, and export provenance according to its financial-evidence policy.
DATEV/Steuerbüro owns bookkeeping records, document retention, tax treatment, legal invoice completion, and correction/cancellation procedures.
Qonto owns bank records and any Qonto-created invoice/document workflow; its DATEV transfer must be monitored and reconciled rather than treated as proof of successful bookkeeping.
Secrets and provider credentials are never stored in billing-basis artifacts, workplans, logs, or adapter configuration committed to Git.

3.8 KiB Raw Permalink Blame History