German fiscalization (KassenSichV / TSE) — design + Phase 0 spec

[telivity-otaip]

Context

German hotels using HAIP must comply with KassenSichV (Kassensicherungsverordnung): every transaction on an electronic recording system must be cryptographically signed by a certified TSE (Technische Sicherheitseinrichtung), with DSFinV-K export available for tax audits and receipt-issuance obligations (Belegausgabepflicht).

HAIP does not support this today. We have a tax-calculation engine (incl. a Germany/Berlin VAT profile, #91), invoice rendering, and an immutable audit log — none of which is certified fiscalization. This issue captures the design so the work can be picked up (by a contributor or the core team).

Principles

• We do not build a TSE — it must be BSI-certified. We integrate a certified provider.
• Bring-your-own-credentials, per property. A production TSS is registered to a specific taxpayer, so each German property supplies its own provider credentials via config. HAIP never owns a deployer's fiscal data or account.
• Follows the existing channel-adapter pattern (provider interface + adapter + mock server for tests).

Open questions (need domain confirmation before coding)

• Provider: default target — fiskaly SIGN DE (cloud) vs. Deutsche Fiskal vs. hardware (Epson/Swissbit)? Cloud is simplest for the reference adapter.
• Transaction trigger point: which folio event is the fiscally-recorded Kassenvorgang — charge posting, payment capture, or checkout-invoice finalization? (German tax-law judgment — must be sourced, not assumed.)
• Scope of receipts requiring signature (folio invoice only, or every payment?).

Proposed scope

Phase 0 — this issue (spec). Lock provider, trigger point, data model, DSFinV-K mapping.

Phase 1 — Core signing

• Provider client: TSS/client management, auth
• Drizzle schema: tse_transactions (signature, signature counter, TSS serial, start/finish time, process type/data), per-property TSS config
• Hook signing into the confirmed trigger point
• Receipt fields + QR code (signature, counter, serial, timestamps)
• Mock TSE server for tests (mirrors mock-bookingcom / mock-siteminder)

Phase 2 — DSFinV-K export

• Full standardized file set + index.xml, mapped from folio/payment data
• Export endpoint + tests

Phase 3 — Resilience

• TSE-offline buffering + retry (legally required), counter-gap detection, failure logging
• Feature-flag scoped to German properties only

Out of scope (cannot be delivered in code)

• Legal compliance sign-off. The certified TSE is the provider's; the overall deployment still requires a Steuerberater review and a Verfahrensdokumentation (GoBD). We provide a docs draft; production compliance is validated by the deploying hotel's tax advisor.
• Production provider accounts — each hotel's own.

How to contribute

• Build against a free sandbox account (e.g. fiskaly) — no contract, no cost, no legal exposure.
• Production credentials are always the deploying hotel's own, so contributing carries no liability.
• Comment here if you'd like to take a phase; core team will review closely.

Acceptance criteria (Phases 1–3)

• Every transaction at the confirmed trigger point is signed via the provider sandbox
• Receipts carry TSE serial, signature, counter, timestamps, QR
• Valid DSFinV-K export produced and schema-validated
• TSE-offline path buffers and reconciles without data loss
• Per-property config; non-German properties unaffected

[telivity-otaip]

Status vs what’s in the repo

This issue is not fully done. What landed under integrations is the fiskaly SIGN DE console / adapter pack, not certified German fiscalization end-to-end.

In repo today

• Demo: integrations/demos/fiskaly-sign-de/
• Provider key: fiskaly_sign_de (Wave 3 fiscal console packs)
• Docs: docs/integrations/wave3-fiscal-guest-reg.md, catalog row in docs/INTEGRATIONS.md
• Behavior: catalog toggle + property fiscal config + console handoff (logs / fake ack). No live TSE signing, no DSFinV-K export, no TSE-offline buffering.

What still belongs to this issue

• Phase 0 decisions (provider, Kassenvorgang trigger, receipt scope)
• Real FiscalProvider against a certified TSE (e.g. fiskaly SIGN DE sandbox → production)
• Receipt fields / QR, DSFinV-K, offline resilience (Phases 1–3)

Go-live requirement (by design)
HAIP does not own a production TSE. Each German property must bring their own certified-provider credentials (hotel owner / deployer signup + config on PUT /api/v1/fiscal/config). Until that exists and a real provider client is registered under fiskaly_sign_de, this pack stays wiring/demo only.

Leaving this issue open until Phase 0 is locked and a non-console path is actually implemented.