z77 / module-debtor
Z77 Debtor Module | receivables: debtor profile per contact, payment terms, payment targets, dunning levels, invoices and credit notes through InvoicingService, the accounting port (ADR-040, plan §6).
Requires
- php: >=8.4
- z77/kernel: ^1.0
- z77/module-contact: ^1.0
- z77/module-mandator: ^1.0
- z77/module-vat: ^1.0
- z77/persistence-doctrine: ^1.0
Requires (Dev)
None
Suggests
- z77/module-financial: Books the receivables of this module; without it debtor runs against an external bookkeeping and its account settings are not checked.
- z77/module-mailing: Sends booked documents by e-mail through the outbox (the result list of the booking print, «Alle per E-Mail senden»); without it the result list offers download and ZIP only.
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 05:01:02 UTC
README
Receivables for z77 business modules (ADR-040, plan §6): invoices and credit notes with the Swiss
QR-bill, the Faktura-Journal that posts them to the books in one step, open items, payments
(by hand or from the bank's camt.054 credit advices), dunning runs with fee documents, and the
document mails. The debtor is a role of a contact (z77/module-contact); the books are reached
only through an accounting port, so an installation may keep them elsewhere.
Part of the z77 framework monorepo
(packages/module-debtor). Not yet a split target or on Packagist — projects consume it through
a path repository until it is.
Requirements
- PHP ≥ 8.4, MariaDB (Doctrine, ADR-039)
z77/kernel,z77/persistence-doctrinez77/module-contact— the party; its address, language and e-mail are what a document snapshotsz77/module-vat— tax codes, rates by service date, the per-code summaryz77/module-mandator— the letterhead, the VAT liability and the five debtor accounts (receivable, discount, loss, rounding, dunning fee)
Suggested, optional:
z77/module-financial— the booksLedgerAccountingGatewayposts into, the account checks, the year-close checks and the subledger reconciliation. Without it, nameNullAccountingGatewayunderaccountingGateway(books kept elsewhere).z77/module-mailing— documents and dunning notices by e-mail through the outbox. Without it the screens offer PDF and ZIP only.
Enabling it in a project
- Require the package (
composer require z77/module-debtor, or the monorepo'spathrepository).composer install/updateadds the navigation entries ofdata/framework/routing/navigation.d/module-debtor.json(ADR-050) and seeds the payment terms («30 Tage netto», «10 Tage 2 %, 30 Tage netto») and the dunning levels («Zahlungserinnerung», «1. Mahnung», «2. Mahnung») once underdata/framework/debtor/. - Register the namespace in the project's
composer.jsonautoload.psr-4— this module plus those of its requires (vat, contact, mandator):"Z77\\Module\\Debtor\\": ["override/z77/module/debtor/src/"]— an unregistered package is installed but not a module, andz77-dbdoes not see its migrations (Switch the modules on). - Apply the migrations (
res/migrations, namespaceZ77\Module\Debtor\Migrations):php vendor/bin/z77-db migrate.data/archive/debtor/must be writable by the web server — the issued PDFs are archived there (on a release server: the shareddata). - Set the five debtor accounts on the mandator (Stammdaten › Firma › Mandant; KMU start values 1100 / 3800 / 3805 / 3809 / 6950). Stammdaten › Auftragswesen › Debitoren shows whether they are postable.
- Create at least one payment target with the company's IBAN and / or QR-IBAN (Stammdaten › Auftragswesen › Zahlungsziele) — deliberately not seeded: an IBAN cannot be guessed.
- Override
src/App/Config/debtorConfig.inc.phponly as a whole file (a project override replaces the module config, BOOT-CONFIG-001); customise the PDF layouts by copyingres/view/templates/pdf/*.tpl.phpunderoverride/(CE principle — never editvendor/).
Backend screens
Fragments in Ui\ (ADR-018), mounted by thin hosts in z77/module-backend
(Ui/Controllers/Finance/*), URL group finance.
| Menu | URL | What it does |
|---|---|---|
| Auftragswesen › Rechnungen | /backend/finance/invoice/list |
tabs «In Fakturierung» · «Fakturiert» · «Verbucht» · «Gutschriften» · «Ersetzt» · «Gelöscht»; in «Verbucht» the payment facts «Bezahlt am» (carrying the payment state: empty = offen, a date = bezahlt, «· Teil» = teilbezahlt, «gutgeschrieben»), «Zahlbetrag» and «Zahlziel»; «+ Rechnung»; «Fakturieren …» for the ticked drafts → the result list (PDF, «Alle als ein PDF», ZIP, «Alle per E-Mail senden …»); one mask per document (draft editor, correction of an issued invoice, read-only once posted, payment form, credit note) |
| Auftragswesen › Faktura-Journal | /backend/finance/invoice-journal/list |
the issued, not yet posted documents; «Journal drucken», «Journal verbuchen …» (always the whole journal); tab «Verbuchte Journale» |
| Auftragswesen › Debitoren | /backend/finance/debtor/list |
open items: «Offen» · «Überfällig» · «Alle», OP-Total, «Zahlung» per row; the columns «Bezahlt am» (searchable as a date range, sortable) and «Zahlziel» |
| Auftragswesen › Zahlungseingänge | /backend/finance/bank-import/list |
camt.054 upload (XML or a ZIP of them), tabs «Offen» / «Erledigt», per message «Zuordnen» / «Ignorieren» / «Verbuchen»; «Bankabgleich …» (camt.053 collective credit, ADR-061 C3b); every imported camt.054 is kept unaltered under data/archive/debtor/bank/ (Services\BankMessageArchive) |
| Auftragswesen › Mahnungen | /backend/finance/dunning/list |
the due list as of a day, «Mahnlauf starten», the runs; per notice «PDF öffnen» / «Per E-Mail senden …» |
| Stammdaten › Auftragswesen › Debitoren | /backend/finance/debtor-profile/list |
the debtor profile of a contact: payment terms, price mode, subject label, dunning block, active; the account settings |
| Stammdaten › Auftragswesen › Zahlungskonditionen | /backend/finance/payment-terms/list |
due days, up to two discount tiers, the printed text per language, «Standard» |
| Stammdaten › Auftragswesen › Zahlungsziele | /backend/finance/payment-target/list |
the company's bank accounts: IBAN / QR-IBAN, ledger account, payee |
| Stammdaten › Auftragswesen › Mahnstufen | /backend/finance/dunning-level/list |
level, days after due, days after the last notice, fee, notice text |
Every list and the important windows carry their help (ADR-048, *.help.tpl.php). Two
base-knowledge helps for the backend assistant (ADR-055) describe the workflows across screens:
res/view/templates/Backend/Guide/invoiceWorkflow.help.tpl.php («Ablauf: Rechnung →
Faktura-Journal → Verbuchen → Zahlung → Mahnung», including corrections) and
Backend/Guide/bankImport.help.tpl.php («Zahlungseingänge einlesen»).
The workflow
- Draft (
invoicing) — no number, nothing posted, a watermarked preview;InvoicingService::invoice()/reinvoice()/discard(). - «Fakturieren» (
issued) —InvoicingService::issue(): the gapless numberYYMMnnnn(one series for every kind, by the month of the invoice date), the payment part, a content stamp («ID»), the PDF rendered once and archived (Pdf\InvoiceArchive). Nothing is posted. - Faktura-Journal — while issued, a manual invoice is corrected by a new version (same number)
or a replacement (new number), or deleted with a reason; an invoice from an order only through
the order. «Journal verbuchen» (
JournalPostingService::post()) posts the whole journal in one unit of work →final, immutable; a correction is then a credit note. - Payment —
PaymentService(payment, discount, loss; correctable while the fiscal year is open);BankImportServicereads camt.054, matches by QR reference or the message, books on «Verbuchen»;BankEntryLinkServicelinks a camt.054 entry to its camt.053 collective credit (module-financial'sbank_link; at the import or by the jobdebtor-bank-link) — nothing booked. - Dunning —
DunningService::dueList()/run(): a notice per invoice at the next active level, a fee as a document of its own kind (no VAT), the notice PDF with a QR-bill over open + fee.
The open amount is derived (gross − posted credit notes − allocations); there is no open-item
table. When, how much and through which payment target a document was paid is one read model,
Repositories\PaymentFacts (one aggregate over the allocations of kind payment), shared by the
lists «Debitoren» and «Rechnungen › Verbucht» (DEBTOR-PAID-001).
Extension points
Config key (debtorConfig) |
What plugs in |
|---|---|
accountingGateway |
LedgerAccountingGateway (default, module-financial) or NullAccountingGateway |
invoicePostedListeners (any module) |
called inside «Journal verbuchen» with the posted ids (module-order moves its orders to «Gebucht») |
openWorkChecks |
period-close (drafts / issued documents / unbooked bank credits block a year close), ledger-report, vat-return |
subledgerReconciliations |
ReceivablesReconciliation — open items against the receivable account at the year close |
contactRoles |
the role «Debitor» in the contact editor |
dashboard |
DebtorDashboard — overdue invoices, due notices, unbooked bank credits, drafts, the unposted (or blocked) journal, no payment target with an IBAN |
bankEntryOwners |
DebtorBankEntryOwner — financial's bank check asks which posting belongs to which linked camt.054 entry |
bankMovementClaims |
CollectiveCreditBankClaim — debtor claims the QR collective credit on a payment target's bank account: it is linked through «Bankabgleich …» and cannot be set «Privat» |
mailAttachments, documentMails |
invoice-pdf, dunning-pdf; the mail kinds «Rechnung», «Rechnung (ersetzt eine frühere)», «Gutschrift», «Mahnung» (texts editable under Service › E-Mail › Beleg-Mails) |
A source that is its own draft (module-order) uses InvoicingService::preview(),
invoiceAndIssue(), classify() / revise() / flagReissue() / delete(…, fromSource: true)
and the read port Services\PaymentStates; debtor names no source module.
Not built yet
- «Alle per E-Mail senden» for a whole dunning run — notices are mailed one by one (⋮ per notice).
- Dunning notice PDFs are not stored — rendered on request; invoices and credit notes are archived.
- Payments out — supplier invoices live in
z77/module-creditor, not in this package. - VAT return from the posted documents (
vat-returncheck is registered, asked by nobody yet). - Foreign-currency documents — currency and rate columns exist, amounts are base currency only.
- A cross-message list of unbooked bank credits — the screen is per camt.054 message.
- Prepayment invoices (a payment before the invoice) and the PDF in the DMS.
Tests
tests/module-debtor.php — the harness against MariaDB (throwaway schema; migrations through
z77-db with a clean diff, the services, the screens through host doubles, the helps). It prints
its check count; --from=BM / --from=FJ run a late section from a saved checkpoint.
Documentation
- Topic doc:
docs/topics/debtor.md - Faktura-Journal: ADR-054
- Plan:
order-debtor-financial-bauplan.md§6