z77 / module-creditor
Z77 Creditor Module | the supplier as a role of a contact (creditor profile with several IBANs and posting defaults); the supplier's PDF invoice in a creditor journal (upload, lines, duplicate check), later posted into module-financial with the payment date (creditor-module-bauplan).
Requires
- php: >=8.4
- z77/kernel: ^1.0
- z77/module-contact: ^1.0
- z77/module-dms: ^1.0
- z77/module-financial: ^1.0
- z77/module-mandator: ^1.0
- z77/module-receipt: ^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:03:02 UTC
README
Payables for z77 business modules. A creditor is a contact (z77/module-contact) with a
creditor profile: the supplier's UID, several IBANs (an IBAN may be shared by several
creditors — a billing or collection company) and the defaults a new invoice line of that
supplier starts with (expense account, VAT code or «ohne MWST», «Bezahlt mit»). The role
«Kreditor» is switched on in the contact editor; the master data are edited under
Stammdaten › Finanzen › Kreditoren.
The supplier's PDF invoice is uploaded into the Kreditorenjournal (Finanzen): stored unaltered in the DMS, read once only (SHA-256), checked and split into lines in a window with the PDF beside the fields; a suspected duplicate (same creditor + invoice number, or same IBAN + reference) is created and blocked until the owner decides. The owner sets «bezahlt am» (per invoice or for ticked rows) and posts the paid invoices with «Journal verbuchen …» up to a cut-off on the payment date — the direct variant: ONE entry per invoice, expense (+ input VAT) to the payment method's account, dated with the payment date (cash principle, ADR-059). A posted invoice is immutable; its PDF is kept 10 years in the DMS.
Every received PDF is recognised (stage 2): the text layer of a Swiss QR-bill (pdftotext) gives
IBAN, amount, reference, message, the creditor and — with a Swico S1 line — number and dates; the
creditor is matched by one of its IBANs, else by its UID (a shared IBAN is never guessed — the row
lists the candidates); an unknown one becomes a proposal. Only EMPTY fields are filled; the row
shows the source (Text / KI / von Hand). The recognition runs ONLY in the job creditor-intake
(CLI), never in a web request: an upload is stored «Erkennung ausstehend» and queues the job, which
reads the PDF back from the DMS (ModuleDrive::read()); «Jetzt erkennen» re-runs it. An opt-in AI step (z77/kibot's client, creditorAi in
config/client/kibot.inc.php, default off) reads what the text layer cannot. creditorAi.enabled
RELEASES it for the installation; within that the owner switches it on and off with the switch
«KI-Erkennung» beside «PDF hochladen» (stored in data/framework/creditor/ai_switch.json, never
set = on) — the AI runs only when both say yes. Learning per creditor: when the owner saves
an invoice with its creditor (or takes a proposed creditor over), the creditor learns from that
invoice's text what stays the same — a foreign VAT number, its domain, the sender line — and the
label printed before number, dates and amount; its next invoice without a known IBAN or Swiss UID
is recognised by them and read at those labels. The AI reads along for the first invoices; once
PHP and the AI agreed twice, PHP reads that creditor's invoices alone. Besides the upload,
the job creditor-intake reads an intake folder on the server (data/framework/creditor/intake)
every minute, deletes a file once the DMS holds its verified copy and keeps a refused one in
failed/ for the tab «Nicht eingelesen».
Source of the design: docs/03-development/creditor-module-bauplan.md, owner answers §11 of
2026-11-15. Part of the z77 framework monorepo
(packages/module-creditor). Not yet a split target or on Packagist.
Requirements
- PHP ≥ 8.4, MariaDB (Doctrine, ADR-039)
z77/kernel(the sharedZ77\Shared\Payment\Iban/QrReference/ScorReference),z77/persistence-doctrinez77/module-contact— the party and the role registryz77/module-financial— the chart, the ledger (LedgerService::post()),GrossEntryBuilder, the open-work registry of the period closez77/module-receipt— the payment methods («Bezahlt mit», their usage count through the registrypaymentMethodUsage), the field rules, the retention rulez77/module-vat,z77/module-mandator— tax codes, the UID check, the VAT liabilityz77/module-dms— holds the supplier PDFs (partition «Kreditorenrechnungen»)
Enabling it in a project
-
In the PROJECT's
composer.json: requirez77/module-creditor(with apathrepository for every z77 package in its dependency graph) and register its namespace — and the namespaces of the modules it requires — inautoload.psr-4:"Z77\\Module\\Creditor\\": ["override/z77/module/creditor/src/"]
config/vendor/moduleManager.inc.phpis GENERATED by the installer from the project's psr-4 — never edit it by hand (business-suite-setup.md§2,create-module.md). -
composer update(the installer buildsmoduleManagerand merges the navigation seed), thenphp vendor/bin/z77-db migrate(tablescreditor_profile,creditor_iban— migrationVersion20261115100000;creditor_intake,creditor_invoice,creditor_invoice_line,creditor_journal_posting— migrationVersion20261115120000). -
In the backend: create the payment methods first (Stammdaten › Finanzen › Zahlungsarten), then switch on «Kreditor» on a contact and fill UID, IBANs and defaults (or leave the defaults empty — the first saved invoice with an account sets what is still missing). Upload PDFs under Finanzen › Kreditorenjournal. The largest PDF is
creditorConfig['intake']['maxBytes'](20 MiB); PHP'supload_max_filesize/post_max_sizemust allow it. -
Open the fiscal year (Finanzen) — «Journal verbuchen …» posts into it.
creditorConfig['postingVariant']isdirect(the only variant built; another value is refused). -
Recognition and the intake folder (stage 2):
pdftotextfor the CLI PHP of the host (poppler;creditorConfig['tools']['pdftotext'],auto= from PATH — without it every row is completed by hand; the web PHP needs noproc_open()). The cron runner must run (vendor/bin/z77-run, jobs.md) — without it uploads stay «Erkennung ausstehend»; migrationVersion20261115140000addscreditor_invoice.recognition_pending_at;Version20261116100000addscreditor_learnedandcreditor_invoice_text(learning per creditor). The jobcreditor-intake(scheduleevery:1m) CREATES the foldercreditorConfig['intake']['folder'](defaultdata/framework/creditor/intake, i.e.shared/data/…in the release layout) with.work/andfailed/on its first run — so does opening the tab «Nicht eingelesen». The AI step:creditorAi.enabledinconfig/client/kibot.inc.php(default off; putAiInvoiceReader::PRIVACY_NOTEinto the privacy notes first) releases it — only then the journal shows the switch «KI-Erkennung», with which the owner turns it on and off at runtime. -
Payments from the bank statement (ADR-061 stage C1, optional): switch «Kontoauszug einlesen» on for a bank account (Stammdaten › Finanzen › Bankkonten) and read its camt.053 (Finanzen › Bankkonto). Migration
Version20261117110000addscreditor_profile.bank_text(«Banktext»); the link tablebank_linkis module-financial's (Version20261117100000). The jobcreditor-intakelinks invoices by their QR / RF reference; the journal's «Zahlungen suchen …» proposes the rest.creditorConfig['bankMatch']holds the days a movement is looked for around an invoice. From the date «Abgleich ab» on a bank account (stage C4) the account is bank-driven: «Bezahlt am» of an invoice paid through it comes only from the bank, not from the keyboard (no creditor migration). -
The line text per creditor (2026-11-17): migration
Version20261117170000addscreditor_profile.default_line_text(«Kontierungstext», the standard line text) andlast_line_text(the last saved one). Nothing to configure.
Backend screen
| Menu | URL | What it does |
|---|---|---|
| Finanzen › Kreditorenjournal | /backend/finance/creditor-journal/list |
«Journal verbuchen …» (action cell, the posting window with the cut-off); «PDF hochladen» in the toolbar (several, drag and drop) and beside it the switch «KI-Erkennung» (only where the AI is released); tabs «Im Journal» · «Gesperrt» · «Verbuchte Journale» · «Nicht eingelesen» (refused folder files: «Erneut versuchen» / «Entfernen»); «Bezahlt am …» for ticked rows; the column «Erkannt»; the invoice window with the PDF, the recognition's notes, head, «Bezahlt am» and lines; «Kein Doppel — übernehmen», «Kreditor übernehmen …», «Löschen …» / «Verwerfen …» |
| Stammdaten › Finanzen › Kreditoren | /backend/finance/creditor-profile/list |
the creditors: search by name, UID, IBAN; the window for UID, defaults and IBANs, and what the creditor learned from its invoices with «Gelerntes vergessen»; invoice count; «Aktiv» |
| Kontakte › Kontakt › Rollen | (module-contact's dialog) | the switch «Kreditor»: on = empty profile, off = delete it (refused while invoices name it — deactivate instead) |
Fragments in Ui\ (ADR-018), mounted by z77/module-backend. The lists and the windows carry
their help (ADR-048); Backend/Guide/creditorWorkflow.help is the KI-Assistent's overview.
Pieces
CreditorProfile/CreditorIban(Doctrine) — the profile per contact and its IBANs.Services\CreditorProfileService—open(),update()with optimistic locking and the IBAN sync,setActive(),delete(); the defaults stamp.Validators\CreditorProfileValidator— UID, defaults (through module-receipt'sReceiptFields), IBAN rows.Roles\CreditorContactRole— the role «Kreditor» in the contact editor.CreditorIntake/CreditorInvoice/CreditorInvoiceLine/CreditorJournalPosting(Doctrine) — the file that came in, the supplier invoice with its lines, the posting protocol (1c).Services\CreditorIntakeService::receive()— the one intake path: sniff, SHA-256, DMS store, the invoice with one line on the creditor's defaults.Services\CreditorInvoiceService—update()(head + lines, «bezahlt am», defaults, VAT forcing for a mandator not liable to VAT, duplicate check, defaults once),markPaid()(bulk),release(),delete()(unposted: completely, the hash freed; a discarded duplicate keeps it),adoptCreditor().Posting\CreditorPostingStrategy/DirectPosting/CreditorPostingVariant— how an invoice reaches the ledger; the variant per installation, snapshotted on the invoice (ADR-059).Services\CreditorJournalPostingService— «Journal verbuchen»:preview()/post()up to a cut-off on the payment date, all or nothing, the protocol;Services\CreditorRetention— the 10-year deadline of a posted PDF.Close\UnpostedCreditorInvoicesCheck— the open-work answer (period close, VAT return, report).Services\CreditorPaymentMethodUsage— the invoices' share of the payment methods' usage count.Recognition\*—TextLayerRecognizer(pdftotext →SwissQrBillText),Ai\AiInvoiceReader(opt-in),InvoiceFacts(one step's values);Services\CreditorRecognitionService— read, match, thenCreditorInvoiceService::applyRecognition()(only empty fields, the duplicate check).Services\CreditorBankMatchService/CreditorBankMatch— finds an invoice's bank movement (reference first, then amount and days around the invoice) and links it through module-financial'sBankLinkService;Services\CreditorBankEntryOwner(registrybankEntryOwners) tells financial's bank check which posting belongs to which invoice.Services\CreditorIntakeFolder+Jobs\CreditorIntakeJob— the intake folder and its jobcreditor-intake.Services\CreditorLearningService+Recognition\SenderFeatures/LearnedLabels/OwnParty(CreditorLearned,CreditorInvoiceText) — learning per creditor: the text the job read is kept, the creditor learns its sender features and value labels when the owner settles an invoice, matching by them after IBAN and UID, the AI left out once PHP and the AI agreed.
Not built yet
- The collective-account variant (2000 payables) — the strategy is the place; the invoice carries the columns.
Foreign currency is built: the invoice window has «Währung», «Betrag in Währung», «Betrag CHF» and
«Kurs». With «Betrag CHF» empty the server computes the amount on save (original × rate, to the
Rappen); a typed rate is stored (exchange_rate) and goes when an amount changes or the bank brings
the amount. Posting is CHF only; the currencies come from receiptConfig['foreignCurrencies'].
Documentation
Topic doc: docs/topics/creditor.md
— the single source of truth for this module. Harness: tests/module-creditor.php.