Invoicing Module¶

Purpose¶

Handles the financial document lifecycle: generating invoices from fulfilled sales orders, managing VAT in accordance with Polish food tax rules, tracking payment status, and issuing credit notes. KSeF (Krajowy System e-Faktur) integration is a Phase 4 concern — Phase 2 delivers basic PDF invoice generation. This module is intentionally isolated from operations so it can be deferred, replaced, or integrated with an external accounting system without affecting Production, Warehouse, or CRM.

Actors¶

Use Cases¶

INV-UC-01: Generate Invoice from Sales Order¶

Actor: Admin, Accountant Phase: 2

An invoice is generated from a confirmed and (at least partially) shipped ZS. Invoice creation is manual — user selects the ZS and clicks "Generate Invoice."

System pre-fills invoice from ZS data: - Customer data (name, NIP, address — from CRM customer record at time of invoice) - Line items (product description, quantity, unit price, discount, VAT rate per line, net value, VAT amount, gross value) - Invoice date (defaults to today; editable) - Payment due date (calculated from tenant's default payment terms; editable) - Invoice number (auto-assigned: FA-YYYY-MM-NNNNN)

User reviews, adjusts if needed, and confirms. Invoice transitions to Issued status and is immutable.

Business rules: 1. Invoice can be generated from a ZS in Confirmed status or later (Confirmed, PartiallyShipped, Shipped, Invoiced) 2. VAT rate per line is taken from the product's VAT configuration in CRM (5% / 8% / 23%) 3. Invoice is immutable once issued — corrections require a credit note (see INV-UC-03) 4. One ZS can have multiple partial invoices (e.g., for split shipments) 5. Customer data is snapshoted on the invoice — CRM customer record changes do not affect issued invoices

INV-UC-02: Track Payment Status¶

Actor: Admin, Accountant Phase: 2

Invoice payment statuses: Unpaid → PartiallyPaid → Paid | Overdue

Overdue is set automatically when due date passes and invoice is still Unpaid or PartiallyPaid.

Register payment: amount, date, payment method (bank transfer / cash / card). Partial payments allowed — system calculates remaining balance.

Overdue alert: email notification sent to Admin/Accountant when invoice becomes overdue (once per day). Dashboard widget: unpaid invoice count and total value.

Business rules: 1. Payment registration does not require a matching bank import — it is a manual entry 2. Overpayment (payment > invoice gross) is allowed; excess recorded as outstanding credit 3. When ZS status transitions to Invoiced it means at least one invoice has been generated — not that it is fully paid

INV-UC-03: Issue Credit Note (Correction Invoice)¶

Actor: Admin, Accountant Phase: 2

Credit note issued against an existing invoice: select the original invoice, enter correction reason (return | price error | quantity error | other), correct values.

Credit note: KOR-YYYY-MM-NNNNN, linked to original FA number, contains: original values, corrected values, difference.

Business rules: 1. Credit note can only be issued against an Issued or Paid invoice — not against a cancelled one 2. Credit note is immutable once issued 3. A fully corrected invoice is marked Cancelled by correction — it does not affect payment status of unrelated invoices

INV-UC-04: Export Invoice PDF¶

Actor: Admin, Accountant, Manager Phase: 2

Generate standard Polish invoice PDF from any issued invoice. Format: Polish invoice layout (FA VATM format), company logo, all mandatory fields per Polish accounting law, QR code for payment (optional, with bank account number configured in tenant settings).

INV-UC-05: Invoice List and Filters¶

Actor: Admin, Accountant, Manager Phase: 2

Invoice list with: invoice number, customer, issue date, due date, gross value, payment status, ZS reference.

Filters: status (unpaid / overdue / paid), date range, customer. Sort: issue date (default), due date, value.

Export to Excel: full invoice list for a period.

INV-UC-06: VAT Rate Configuration¶

Actor: Admin Phase: 2

Configure available VAT rates per tenant (default: 5% / 8% / 23% per Polish food regulations). Admin can add non-standard rates if needed. VAT rate is assigned per product in CRM (INV module reads it from CRM's item extension).

INV-UC-08: Proforma Invoice¶

Actor: Admin, Accountant Phase: 2

A proforma invoice is a non-binding pre-payment document issued before goods are delivered. Used for new customers or large orders where advance payment is required.

System generates a proforma from a ZS in Confirmed status. Proforma contains the same data as a regular invoice but is clearly marked as "FAKTURA PROFORMA" and auto-numbered: FP-YYYY-MM-NNNNN.

Proforma does not create a VAT obligation. When payment is received and goods are shipped, the Accountant generates a regular invoice (FA) from the same ZS.

Business rules: 1. Proforma is not a VAT document — it does not appear in VAT registers or JPK exports 2. Proforma can be issued from any ZS in Confirmed or later status 3. A ZS can have both a proforma and a regular invoice — the regular invoice supersedes the proforma 4. Proforma is immutable once issued — corrections require creating a new proforma

INV-UC-07: KSeF Integration (Phase 4 Only)¶

Actor: System (auto) + Admin Phase: 4

After issuing an invoice, system automatically submits it to KSeF (Krajowy System e-Faktur — Poland's national e-invoicing system) via the Ministry of Finance API.

On successful submission: KSeF reference number (KSeF_ID) stored on the invoice. On failure: invoice remains Issued (locally valid), retry queue processes the submission, error visible in Admin dashboard.

Phase 4 also adds: - JPK_FA export (structured XML for tax authority) - Invoice import from KSeF (for PZ-linked supplier invoices)

Business rules (Phase 4): 1. KSeF submission is mandatory from the statutory obligation date (currently planned 2026 for larger companies; mandatory date for small companies TBD per Polish law) 2. An invoice without a KSeF_ID is considered locally valid but not compliant — system flags it clearly 3. KSeF errors do not prevent invoice issuance locally — submission is async

Business Rules¶

Out of Scope¶

• Sales order management → owned by CRM module
• Payment collection (merchant account, payment gateway) → not in scope; system tracks payments registered manually
• Accounting journal entries / bookkeeping → not in scope; invoices can be exported to Excel for external accountant
• Supplier invoice management (purchase invoices) → not in scope for Phase 1–3; may be added in Phase 4 with KSeF import
• Payroll → not in scope

Open Questions¶