z77 / module-receipt
Z77 Receipt Module | receipt templates as master data, the receipt journal a phone captures into (photo, amount, text, optional template), the owner's correction and «Journal verbuchen» into module-financial (gateway-app-kanal-bauplan T4, ADR-054 pattern).
Requires
- php: >=8.4
- z77/kernel: ^1.0
- z77/module-dms: ^1.0
- z77/module-financial: ^1.0
- z77/module-mandator: ^1.0
- z77/module-vat: ^1.0
- z77/persistence-doctrine: ^1.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 05:01:53 UTC
README
The receipt journal for z77 business modules: a phone captures a receipt — photo, gross amount, text, optionally a template (what was bought: debit account and VAT code) and a payment method («Bezahlt mit»: the credit account) — into a JOURNAL; the ledger sees nothing yet. In the backend the owner reviews, corrects, splits a mixed-VAT receipt and posts every receipt up to a cut-off date in one go («Journal verbuchen»): one generated journal entry per receipt, all or nothing — the flow of debtor's Faktura-Journal (ADR-054).
Source of the design: docs/03-development/gateway-app-kanal-bauplan.md, owner decisions
E1–E16 and T2 / T4 of 2026-11-12.
Part of the z77 framework monorepo
(packages/module-receipt). Not yet a split target or on Packagist.
Requirements
- PHP ≥ 8.4, MariaDB (Doctrine, ADR-039)
z77/kernel,z77/persistence-doctrinez77/module-financial— accounts,GrossEntryBuilder(the VAT split of a gross amount),LedgerService::post()z77/module-vat,z77/module-mandator— tax codes, the VAT accountsz77/module-dms— the photo is stored in the document drive («Belege//»)z77/module-api(installed by the project) — the phone's gateway and the app shell/app; this package only DECLARES its API targets and app screen inreceiptConfig, module-api finds them.
Enabling it in a project
-
Register the module in the project
composer.json'sautoload.psr-4:"Z77\\Module\\Receipt\\": ["override/z77/module/receipt/src/"]
-
composer update, thenphp vendor/bin/z77-db migrate(tablesreceipt,receipt_journal_posting). -
In the backend: create the receipt templates and payment methods (not seeded — the accounts depend on the chart), then give an app user the function «Belege erfassen» (Stammdaten › System › App-Benutzer; the linked backend person needs at least the role EDITOR).
Backend screens
| Menu | URL | What it does |
|---|---|---|
| Finanzen › Belegjournal | /backend/finance/receipt-journal/list |
the captured receipts with photo; correct, split («Aufteilen …»), delete; «Journal verbuchen …» up to a cut-off; tab «Verbuchte Journale» |
| (same screen, bank stage C5) | tool «Zahlungen suchen …» (only while a bank account reads statements) proposes the bank movement of each unlinked receipt; in the receipt window «Zahlung suchen …» / «Zuordnung lösen» | |
| Stammdaten › Finanzen › Belegvorlagen | /backend/finance/receipt-template/list |
the tiles on the phone: name, icon, debit account, VAT code, order, active |
| Stammdaten › Finanzen › Zahlungsarten | /backend/finance/payment-method/list |
«Bezahlt mit»: name, credit account, order, active |
Fragments in Ui\ (ADR-018), mounted by z77/module-backend. Every list and window carries its
help (ADR-048); a base-knowledge help for the backend assistant, «Belege erfassen: App,
Belegjournal, Vorlagen, Zahlungsarten», lives in
res/view/templates/Backend/Guide/receiptCapture.help.tpl.php.
Phone (via z77/module-api)
Three targets on the gateway, scope receipt.capture, a paired device only (a bearer key gets
403): GET receipt-templates, GET payment-methods (no account and no VAT code on the wire) and
POST receipts (multipart: photo + amount, date, text, template, payment_method;
the request's Idempotency-Key makes a resend harmless). The app screen
(res/view/templates/App/receipt.tpl.php, res/assets/js/app/receipt.js) shows the templates as
tiles, scales the photo on the phone to a JPEG and queues offline.
Pieces
ReceiptTemplate/PaymentMethod(file-based,data/framework/receipt/) — referenced bycode, deactivated never deleted; written throughReceiptTemplateService/PaymentMethodService.Receipt/ReceiptJournalPosting(Doctrine) — the journal row and the protocol of one «Journal verbuchen».Services\ReceiptCaptureService::capture()— the one capture path, no session needed; the photo is sniffed (JPEG, PNG, PDF, ≤ 10 MiB) and stored through the DMS's module partition.Services\ReceiptJournalService— correction, split and deletion with optimistic locking.Services\ReceiptJournalPostingService—preview($cutOff)andpost($cutOff, $seen), all or nothing.Services\ReceiptPostingBuilder— one receipt as a generated entry; the lines come from module-financial'sGrossEntryBuilder(the same VAT split as the one-line entry).Services\ReceiptRetention— after posting, the photo gets the legal deadline in the DMS: end of the fiscal year of the receipt date + 10 years (OR 958f); until then it cannot be purged.Services\ReceiptBankMatchService/ReceiptBankMatch(ADR-061 stage C5) — finds the bank movement of a receipt (amount, bank account, the days around the receipt date fromreceiptConfig['bankMatch']) and links it through module-financial'sBankLinkService; while linked, amount and «Haben» are the bank's. There is no reference on a slip, so every link is the office's act.Services\ReceiptBankEntryOwner(registrybankEntryOwners) tells financial's bank check which posting belongs to which receipt.receiptConfig['foreignCurrencies']is the one list of foreign currencies (used by module-creditor).Close\UnpostedReceiptsCheck— a receipt still in the journal blocks the year close (and the future VAT return) of its date; the reports show a notice.
Not built yet
- Correcting a POSTED receipt through the ledger as its source (
amend()/retract()/reverse()). - «Journal drucken» (the journal as PDF), zoom / rotate of the photo, a dashboard entry («n Belege im Belegjournal»).
- The receipts of one device or app user; a link from a journal entry to its receipt photo.
- The mandator's VAT liability is not applied to receipts (RECEIPT-VAT-001) — a non-liable company sets «ohne MWST».
- The Drive does not show a photo's retention deadline beforehand — only when a purge is refused.
- The VAT return does not exist yet;
UnpostedReceiptsCheckalready answers its open-work scope.
Out of scope: supplier invoices as PDF (with creditor and invoice number) go to the creditor
journal of z77/module-creditor, not here — this journal is for receipts captured
by phone and already paid. module-creditor reuses PaymentMethod and ReceiptFields.
Documentation
Topic doc: docs/topics/receipt.md
— the single source of truth for this module. Harness: tests/module-receipt.php.