87 lines
3.8 KiB
Markdown
87 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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:
|
|
|
|
1. Pin and review the new provider API/export and adapter versions.
|
|
2. Add an explicit billing-basis schema migration if the exact input version
|
|
changes; never reinterpret fields in place.
|
|
3. Run contract and golden-payload tests, then dual-run old and new adapters
|
|
against the same billing-basis IDs.
|
|
4. Reconcile record counts, amounts, currency, exception sets, and evidence
|
|
references in a non-production tenant.
|
|
5. 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.
|