Tutorial: design accounting automation that fails closed

This is a sanitised tutorial from Ko Kitchen accounting operations. It covers the system design behind a difficult rule: never create a financial record from uncertain source data. The system reconciles daily SumUp activity with Lexware documents, but the pattern applies to any irreversible API write.

Why the direct-posting design fails

Sales, refunds, payouts, and accounting records live in different systems. Reading payment data and immediately creating a voucher assumes the current response is complete, the calculated total is correct, no matching voucher exists, and a POST response tells the whole truth. Those assumptions are unsafe for financial data.

The alternative is a two-stage system. Inventory establishes what can safely be posted. Workers execute only that persisted plan. A new source response cannot silently alter the write plan halfway through a retry.

Use one business day as the unit of work

A month driver invokes inventory for exactly one business date. The inventory workflow combines the approved control source, SumUp evidence, and a same-day Lexware scan. It persists the day state, the transaction rows needed to justify the day, an immutable batch manifest, and a run log. Posting is allowed only when that persisted result is complete and marked ready.

Screenshot: day-state lifecycle

Add a redrawn state diagram here: INVENTORY → READY → POSTING → VERIFIED, with INVENTORY or POSTING able to move to BLOCKED and BLOCKED returning to INVENTORY only after review. Do not expose dates, totals, source IDs, or table names.

Make the plan immutable

The batch manifest is a boundary between discovery and execution. It records the proposed cash and card documents before the workers call Lexware. If the system is restarted, workers recover the stored plan instead of reconstructing it from whatever the payment API returns later. This makes a rerun explainable.

The day worker handles repeatable cash and card legs. A separate exception worker handles online invoices and credit notes. The split keeps ordinary daily aggregation small while allowing exceptional documents to carry their own identifiers and recovery rules.

Use a marker-aware write protocol

For each planned document, the worker runs this sequence serially: look up the exact planned voucher number; check for an unexpected same-day collision; recover a stored accounting-document ID if an earlier attempt succeeded; create only when no safe recovery path exists; read the result back; then verify the marker and expected fields before marking the item complete.

Read-back verification solves the uncertain-timeout problem. A client can time out even when the server accepted the POST. Retrying another POST is dangerous. The next run must be able to discover and verify the already-created document instead.

Screenshot: write recovery path

Add a sanitised workflow screenshot here. Show: Exact Lookup → Collision Check → Recover Stored ID? → Create Only If Needed → Read Back → Verify Marker. Use generic example values only.

A blocked day is a safety feature

Missing or contradictory evidence, payout mismatch, unexpected transaction shape, multiple voucher candidates, an unverified POST outcome, or a record without the expected marker all block the day. Blocking preserves the reason and evidence for review. It is better than guessing, posting a plausible voucher, and leaving an accountant to find the error later.

Terminal days are safe on re-run. The worker can re-enter a completed state, read the existing record, verify it, and stop without posting another voucher. That is the difference between a retry and repeating a financial write.

Test the failure paths first

Exercise a missing evidence case, a payout mismatch, a duplicate candidate, a timeout after an accepted POST, and a rerun of a verified day. In every case, the expected result is either a recoverable verified record or a blocked state with a named reason. A fast happy path alone does not prove accounting safety.

Publication boundary

Do not publish customer data, transaction records, payout identifiers, document IDs, credentials, database or table IDs, raw workflow exports, execution logs, or unapproved financial totals.