Search by

z77 / module-creditor

z77

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).

dev-main / 1.0.x-dev 2026-11-20 04:55 UTC

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 shared Z77\Shared\Payment\Iban / QrReference / ScorReference), z77/persistence-doctrine
  • z77/module-contact — the party and the role registry
  • z77/module-financial — the chart, the ledger (LedgerService::post()), GrossEntryBuilder, the open-work registry of the period close
  • z77/module-receipt — the payment methods («Bezahlt mit», their usage count through the registry paymentMethodUsage), the field rules, the retention rule
  • z77/module-vat, z77/module-mandator — tax codes, the UID check, the VAT liability
  • z77/module-dms — holds the supplier PDFs (partition «Kreditorenrechnungen»)

Enabling it in a project

  1. In the PROJECT's composer.json: require z77/module-creditor (with a path repository for every z77 package in its dependency graph) and register its namespace — and the namespaces of the modules it requires — in autoload.psr-4:

    "Z77\\Module\\Creditor\\": ["override/z77/module/creditor/src/"]

    config/vendor/moduleManager.inc.php is GENERATED by the installer from the project's psr-4 — never edit it by hand (business-suite-setup.md §2, create-module.md).

  2. composer update (the installer builds moduleManager and merges the navigation seed), then php vendor/bin/z77-db migrate (tables creditor_profile, creditor_iban — migration Version20261115100000; creditor_intake, creditor_invoice, creditor_invoice_line, creditor_journal_posting — migration Version20261115120000).

  3. 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's upload_max_filesize / post_max_size must allow it.

  4. Open the fiscal year (Finanzen) — «Journal verbuchen …» posts into it. creditorConfig['postingVariant'] is direct (the only variant built; another value is refused).

  5. Recognition and the intake folder (stage 2): pdftotext for 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 no proc_open()). The cron runner must run (vendor/bin/z77-run, jobs.md) — without it uploads stay «Erkennung ausstehend»; migration Version20261115140000 adds creditor_invoice.recognition_pending_at; Version20261116100000 adds creditor_learned and creditor_invoice_text (learning per creditor). The job creditor-intake (schedule every:1m) CREATES the folder creditorConfig['intake']['folder'] (default data/framework/creditor/intake, i.e. shared/data/… in the release layout) with .work/ and failed/ on its first run — so does opening the tab «Nicht eingelesen». The AI step: creditorAi.enabled in config/client/kibot.inc.php (default off; put AiInvoiceReader::PRIVACY_NOTE into 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.

  6. 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 Version20261117110000 adds creditor_profile.bank_text («Banktext»); the link table bank_link is module-financial's (Version20261117100000). The job creditor-intake links 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).

  7. The line text per creditor (2026-11-17): migration Version20261117170000 adds creditor_profile.default_line_text («Kontierungstext», the standard line text) and last_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's ReceiptFields), 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, then CreditorInvoiceService::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's BankLinkService; Services\CreditorBankEntryOwner (registry bankEntryOwners) tells financial's bank check which posting belongs to which invoice.
  • Services\CreditorIntakeFolder + Jobs\CreditorIntakeJob — the intake folder and its job creditor-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.

License

MIT — see LICENSE. Author: Peter Ruepp, z77.ch.