quints 0.18.0__tar.gz → 0.19.0__tar.gz

{quints-0.18.0 → quints-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quints
-Version: 0.18.0
+Version: 0.19.0
 Summary: Swiss VAT & accounting toolkit for plain-text (beancount) books: MWST reports and quarterly settlement, Bezugsteuer helpers, BAZG daily FX rates, QR-bill invoicing, KMU statutory statements, and statement importers (UBS MT940, Yapeal, Wise, Stripe) that draft into a staging area
 License: GPL-2.0-only
 License-File: LICENSE

{quints-0.18.0 → quints-0.19.0}/examples/AGENTS.md

@@ -15,6 +15,14 @@ This project is a git repository; `quints init` committed the pristine
 scaffold. Work in reviewable steps: `git diff` before moving drafts into
 `books/`, commit once `quints check` passes — the history is the audit trail.
 
+## Confidential data
+
+These are the company's books: its customers, suppliers, bank balances and
+their documents, some of them personal data. Whatever you read here goes to
+your model provider. Read what the task needs, never open `.env` or `.wise/`,
+and never send the books to a service the company hasn't approved. Keep the
+git remote private.
+
 ## Layout
 
 - `main.bean` — options, plugins, includes; the entry point every tool loads.

{quints-0.18.0 → quints-0.19.0}/examples/accounts.bean

@@ -11,6 +11,10 @@
   kmu: "1170"  ; Input VAT
 2026-01-01 open Liabilities:CH:GmbH:Payable:Trade
   kmu: "2000"  ; Trade payables
+2026-01-01 open Liabilities:CH:GmbH:Advances:Domestic
+  kmu: "2030"  ; Advances received
+2026-01-01 open Liabilities:CH:GmbH:Advances:Export
+  kmu: "2030"  ; Advances received
 ; Fixed assets: `quints close depreciation --year <year>` prints the
 ; year's write-down from the metadata below, and `quints close check`
 ; verifies it was booked. Rates are the ESTV Merkblatt A/1995 maxima

{quints-0.18.0 → quints-0.19.0}/examples/quints.toml

@@ -36,6 +36,8 @@ reduced_marker = ":Reduced"           # 2.6 % rate class → Ziffer 313
 lodging_marker = ":Lodging"           # 3.8 % Beherbergung → Ziffer 343
 income_domestic = "Income:CH:GmbH:Consulting:External:Domestic"
 income_export = "Income:CH:GmbH:Consulting:External:Export"
+advances_domestic = "Liabilities:CH:GmbH:Advances:Domestic"  # pro forma payments, until invoiced
+advances_export = "Liabilities:CH:GmbH:Advances:Export"
 fx_gain = "Income:CH:GmbH:FX:CurrencyGain"
 fx_loss = "Expenses:CH:GmbH:FX:CurrencyLoss"
 rounding_income = "Income:CH:GmbH:Rounding"

{quints-0.18.0 → quints-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quints"
-version = "0.18.0"
+version = "0.19.0"
 description = "Swiss VAT & accounting toolkit for plain-text (beancount) books: MWST reports and quarterly settlement, Bezugsteuer helpers, BAZG daily FX rates, QR-bill invoicing, KMU statutory statements, and statement importers (UBS MT940, Yapeal, Wise, Stripe) that draft into a staging area"
 readme = "README.md"
 requires-python = ">=3.10"

{quints-0.18.0 → quints-0.19.0}/src/quints/cli.py

@@ -245,23 +245,15 @@ def _problems(violations: list[ledger.Violation], *, err: bool = False) -> None:
         console.print(ui.violations_table(violations, "Problems in the books"))
 
 
-def _vat_chf(file: Path, totals: Totals, inv: Invoice) -> Decimal | None:
-    """An invoice's VAT in CHF at its issue date, for the ledger draft — None
-    when it is CHF already or the books hold no rate (the draft says so)."""
-    from beancount.core.amount import Amount
-
-    if inv.currency == "CHF" or not totals.vat_amount:
+def _chf_rate(file: Path, inv: Invoice) -> Decimal | None:
+    """CHF per unit of a foreign invoice's currency on its issue date, for the
+    ledger draft's VAT — None when it is CHF already, a pro forma (owed at the
+    day received), or the books hold no rate (the draft says so)."""
+    if inv.currency == "CHF" or inv.proforma:
         return None
     entries, _ = ledger.load_entries(file)  # its errors were listed by the cross-check
-    try:
-        chf = ledger.to_chf(
-            Amount(totals.vat_amount, inv.currency),
-            inv.issue_date,
-            bc_prices.build_price_map(entries),
-        )
-    except ledger.RateUnavailable:
-        return None
-    return ledger.rappen(chf)
+    _, rate = ledger.rate(bc_prices.build_price_map(entries), inv.currency, inv.issue_date)
+    return rate
 
 
 def _require_ledger(file: Path) -> None:
@@ -844,10 +836,9 @@ def invoice(
     # an invoice from before registration (or after it ended) carries no VAT.
     registered = cfg.liable_on(inv.issue_date)
     if out is None:
-        # File the PDF the way beancount documents are filed: under the income
-        # account's folder, date-prefixed, next to the ledger's other evidence.
-        account = cfg.income_export if inv.kind == "export" else cfg.income_domestic
-        out = m.document_path(inv, account)
+        # File the PDF the way beancount documents are filed: under the folder
+        # of the account it books against, date-prefixed, next to the evidence.
+        out = m.document_path(inv, dr.filing_account(inv, cfg))
     path, totals, payload = r.render(inv, iss, out, vat_registered=registered)
     ref = ref_mod.payment_reference(inv, iss.account(inv.currency))
 
@@ -859,7 +850,9 @@ def invoice(
     if verify and file.exists():
         cc = v.cross_check(file, inv, totals)
         if not cc.found:
-            ledger_draft = dr.build_draft(inv, totals, vat_chf=_vat_chf(file, totals, inv))
+            ledger_draft = dr.build_draft(
+                inv, totals, chf_rate=_chf_rate(file, inv), received=cc.received
+            )
         if not as_json:
             _print_cross_check(cc, inv, ledger_draft)
     elif verify and not as_json:
@@ -892,6 +885,7 @@ def _invoice_payload(
     return {
         "number": inv.number,
         "kind": inv.kind,
+        "proforma": inv.proforma,
         "currency": inv.currency,
         "issue_date": inv.issue_date,
         "customer": inv.resolved_customer.name,
@@ -918,8 +912,9 @@ def _print_rendered(
     """What was written: the PDF, its reference, VAT status and QR payload."""
     from .invoice import model as m
 
+    kind = f"pro forma {inv.kind}" if inv.proforma else inv.kind
     ui.console.print(
-        f"[ok]Wrote[/] {path}  ·  {inv.kind}  ·  {inv.currency} {m.money(totals.grand_total)}"
+        f"[ok]Wrote[/] {path}  ·  {kind}  ·  {inv.currency} {m.money(totals.amount_due)}"
     )
     ui.console.print(f"[muted]ref {ref.kind} {ref.formatted}[/]")
     if not registered:
@@ -938,7 +933,18 @@ def _print_cross_check(cc: CrossCheck, inv: Invoice, ledger_draft: str | None) -
     from .invoice import model as m
 
     _problems(cc.violations)
-    if not cc.found:
+    for problem in cc.advance_problems:
+        ui.console.print(
+            f"[err]{problem}[/] — fix the invoice's `advances` or the receipt booking."
+        )
+    if not cc.found and inv.proforma:
+        ui.console.print(
+            f"[warn]No payment booked for pro forma {inv.number} yet[/] — when it arrives, "
+            f"book it with these legs into books/<year>.bean:\n"
+        )
+        print(ledger_draft)
+        print()
+    elif not cc.found:
         ui.console.print(
             f"[warn]No ledger txn for {inv.number}[/] — paste this draft "
             f"into books/{inv.issue_date.year}.bean:\n"
@@ -948,9 +954,16 @@ def _print_cross_check(cc: CrossCheck, inv: Invoice, ledger_draft: str | None) -
     elif cc.ok:
         if cc.ledger_total is None:  # unreachable: found implies totals are set
             raise ValueError(f"cross-check for {inv.number} lost its ledger total")
-        ui.console.print(
-            f"[ok]Ledger match[/] ({cc.date}): {inv.currency} {m.money(cc.ledger_total)}"
-        )
+        if inv.proforma and cc.invoice_total is not None and cc.ledger_total < cc.invoice_total:
+            ui.console.print(
+                f"[ok]Advance received[/] ({cc.date}): {inv.currency} "
+                f"{m.money(cc.ledger_total)} of {m.money(cc.invoice_total)}"
+            )
+        else:
+            what = "Advance received" if inv.proforma else "Ledger match"
+            ui.console.print(
+                f"[ok]{what}[/] ({cc.date}): {inv.currency} {m.money(cc.ledger_total)}"
+            )
         if not cc.date_ok:
             ui.console.print(f"[warn]booking date {cc.date} ≠ invoice date {inv.issue_date}[/]")
     else:
@@ -1546,9 +1559,29 @@ def statements(
     lang = lang or config_mod.get().report_language
     bilanz_report = kmu_mod.compute_bilanz(file, balance_date, date_from=date_from)
     erfolg_report = kmu_mod.compute_erfolg(file, date_from, balance_date)
+    # The prior year's figures sit next to this year's (Art. 958d Abs. 2 OR).
+    # An extended first year (`--from`) and a year with empty books before it
+    # have none.
+    # shortcut: the prior year is a calendar year, so after an extended first
+    # year its column covers only that year's calendar part; add --prior-from if asked.
+    prior = None
+    if from_ is None:
+        prior_bilanz = kmu_mod.compute_bilanz(
+            file, f"{year - 1}-12-31", date_from=f"{year - 1}-01-01"
+        )
+        prior_erfolg = kmu_mod.compute_erfolg(file, f"{year - 1}-01-01", f"{year - 1}-12-31")
+        if prior_bilanz.total_assets or prior_erfolg.result:
+            prior = (prior_bilanz, prior_erfolg)
     out = out or Path(f"statements-{year}-{lang}.pdf")
-    path = report_pdf.render_pdf(bilanz_report, erfolg_report, lang, out)
+    path = report_pdf.render_pdf(bilanz_report, erfolg_report, lang, out, prior=prior)
     typer.secho(f"Wrote {path}", fg="green")
+    if prior is None and from_ is None:
+        typer.secho(
+            f"No figures for {year - 1} in the books, so the statements have no "
+            "prior-year column (Art. 958d Abs. 2 OR). If the company existed then, "
+            f"date the opening balances {year - 1}-12-31 instead of {year}-01-01.",
+            fg="yellow",
+        )
     if bilanz_report.violations:
         typer.secho("The statements list these problems in the books at the top:", fg="yellow")
         _problems(bilanz_report.violations)

{quints-0.18.0 → quints-0.19.0}/src/quints/config.py

@@ -243,6 +243,12 @@ class Config:
     rounding_income: str = "Income:CH:GmbH:Rounding"
     income_domestic: str = "Income:CH:GmbH:Consulting:External:Domestic"
     income_export: str = "Income:CH:GmbH:Consulting:External:Export"
+    # Customer advances (KMU 2030 Erhaltene Anzahlungen): a payment against a
+    # pro forma, held until the invoice credits it. The return counts it as
+    # turnover on receipt (Art. 40 Abs. 1 Bst. c MWSTG), so `mwst` routes these
+    # like the income account they mirror — the export one carries the marker.
+    advances_domestic: str = "Liabilities:CH:GmbH:Advances:Domestic"
+    advances_export: str = "Liabilities:CH:GmbH:Advances:Export"
     # Saldosteuersatz method only. The difference between the statutory VAT
     # invoiced and the SSS owed lands in `saldo_difference` at settlement;
     # Bezugsteuer is a cost, not a deduction, so it lands in
@@ -320,6 +326,19 @@ class Config:
         """Whether the entity is VAT-registered on ``day``."""
         return self.phase_at(day) is not None
 
+    @property
+    def advances(self) -> tuple[str, str]:
+        """The customer-advance accounts: held at the CHF received, turnover to `mwst`."""
+        return (self.advances_domestic, self.advances_export)
+
+    def advances_for(self, kind: str) -> str:
+        """The advances account of an invoice `kind` (domestic or export)."""
+        return self.advances_export if kind == "export" else self.advances_domestic
+
+    def mirrored_income(self, account: str) -> str:
+        """The income account an advances account stands in for until invoiced."""
+        return self.income_export if account == self.advances_export else self.income_domestic
+
     def for_period(self, d0: Date, d1: Date) -> tuple[Config, Date, Date]:
         """The config one return is computed under, and the liable stretch of it.
 
@@ -445,6 +464,8 @@ _ACCOUNT_KEYS = (
     "rounding_income",
     "income_domestic",
     "income_export",
+    "advances_domestic",
+    "advances_export",
     "saldo_difference",
     "bezugsteuer_expense",
 )

{quints-0.18.0 → quints-0.19.0}/src/quints/fx.py

@@ -78,6 +78,8 @@ def compute(
             root = p.account.split(":", 1)[0]
             if cfg.entity_marker not in p.account or root not in ("Assets", "Liabilities"):
                 continue
+            if p.account in cfg.advances:
+                continue  # settled by the supply, not in money: stays at the rate received
             if p.units is None or p.units.currency == "CHF":
                 continue
             inventories.setdefault(p.account, Inventory()).add_position(p)

{quints-0.18.0 → quints-0.19.0}/src/quints/init.py

@@ -201,6 +201,8 @@ def _cfg(answers: Answers) -> config.Config:
         rounding_income=_sub(base.rounding_income, c),
         income_domestic=_sub(base.income_domestic, c),
         income_export=_sub(base.income_export, c),
+        advances_domestic=_sub(base.advances_domestic, c),
+        advances_export=_sub(base.advances_export, c),
         saldo_difference=_sub(base.saldo_difference, c),
         bezugsteuer_expense=_sub(base.bezugsteuer_expense, c),
         saldo=tuple(config.SaldoRate(Decimal(spec) / 100) for spec in sorted(answers.saldo_rates)),
@@ -241,6 +243,8 @@ def _backbone(answers: Answers) -> list[_Account]:
         _Account(cfg.receivable, "1100"),
         _Account(cfg.input_vat, "1170", (oc,)),
         _Account(cfg.payable, "2000"),
+        _Account(cfg.advances_domestic, "2030"),
+        _Account(cfg.advances_export, "2030"),
         _Account(
             _sub(_FIXED_ASSETS, c),
             "1510",
@@ -816,6 +820,8 @@ def _quints_toml(answers: Answers) -> str:
         *_marker_lines(cfg),
         f'income_domestic = "{cfg.income_domestic}"',
         f'income_export = "{cfg.income_export}"',
+        f'advances_domestic = "{cfg.advances_domestic}"  # pro forma payments, until invoiced',
+        f'advances_export = "{cfg.advances_export}"',
         *_saldo_account_lines(answers, cfg),
         f'fx_gain = "{cfg.fx_gain}"',
         f'fx_loss = "{cfg.fx_loss}"',
@@ -1145,6 +1151,14 @@ This project is a git repository; `quints init` committed the pristine
 scaffold. Work in reviewable steps: `git diff` before moving drafts into
 `books/`, commit once `quints check` passes — the history is the audit trail.
 
+## Confidential data
+
+These are the company's books: its customers, suppliers, bank balances and
+their documents, some of them personal data. Whatever you read here goes to
+your model provider. Read what the task needs, never open `.env` or `.wise/`,
+and never send the books to a service the company hasn't approved. Keep the
+git remote private.
+
 ## Layout
 
 - `main.bean` — options, plugins, includes; the entry point every tool loads.

quints-0.19.0/src/quints/invoice/draft.py

@@ -0,0 +1,151 @@
+"""Ready-to-paste Beancount draft for an invoice with no ledger entry yet."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from decimal import Decimal
+
+from .. import config, ledger
+from .model import Invoice, Totals, document_path, vat_included
+from .verify import Received
+
+
+def _quoted(value: str) -> str:
+    """A beancount string literal — free text from the customer must not be
+    able to break the draft out of its quotes."""
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def filing_account(inv: Invoice, cfg: config.Config) -> str:
+    """The account the invoice books against, and its PDF is filed under: the
+    income account — or, for a pro forma, the customer advances it becomes."""
+    if inv.proforma:
+        return cfg.advances_for(inv.kind)
+    return cfg.income_export if inv.kind == "export" else cfg.income_domestic
+
+
+def _vat_leg(vat: Decimal, ccy: str, chf_rate: Decimal | None, todo: str = "") -> str:
+    """The OutputVAT amount: CHF as the return is, priced ``@@`` in `ccy`."""
+    if ccy == "CHF":
+        return f"{-vat:>10.2f} {ccy}"
+    if chf_rate is not None:
+        return f"{-ledger.rappen(vat * chf_rate):>10.2f} CHF @@ {vat:.2f} {ccy}"
+    return f"{-vat:>10.2f} {ccy}  ; TODO in CHF{todo}: quints vat convert"
+
+
+def _lines(header: str, meta: list[str], legs: list[tuple[str, str, str]]) -> str:
+    width = max(len(a) for a, _, _ in legs) + 4
+    out = [header, *meta]
+    for account, amount, posting_meta in legs:
+        out.append(f"    {account:<{width}}{amount}")
+        if posting_meta:
+            out.append(f"      {posting_meta}")
+    return "\n".join(out)
+
+
+def receipt_draft(inv: Invoice, totals: Totals, cfg: config.Config | None = None) -> str:
+    """The booking for a pro forma's payment, when it arrives.
+
+    Not income yet: the advance is a liability until the invoice credits it.
+    The return declares it on receipt all the same — with its VAT when
+    domestic (Art. 40 Abs. 1 Bst. c MWSTG), so the VAT is split out of the
+    gross received the way the invoice will credit it back (`vat_included`).
+    """
+    cfg = cfg or config.get()
+    ccy = inv.currency
+    gross = totals.amount_due
+    vat = vat_included(gross, totals.vat_rate)
+    doc = document_path(inv, filing_account(inv, cfg))
+    legs = [(filing_account(inv, cfg), f"{-(gross - vat):>10.2f} {ccy}", "")]
+    if vat:
+        legs.append((cfg.output_vat, _vat_leg(vat, ccy, None, " at the day received"), ""))
+    header = (
+        f"{inv.issue_date} * {_quoted(inv.resolved_customer.name)} "
+        f"{_quoted(f'Advance on pro forma {inv.number}')} ^{inv.number}"
+        "  ; TODO the day it was received"
+    )
+    meta = [
+        f"    proforma: {_quoted(inv.number)}",
+        f"    document: {_quoted(doc.name)}  ; TODO file the PDF under {doc.parent}/",
+        f"    ; TODO the bank leg: {gross:.2f} {ccy} into the account it was paid to.",
+    ]
+    if vat:
+        meta.append(
+            "    ; A different amount arrived? Split that: VAT = amount × rate / (100 + rate)."
+        )
+    return _lines(header, meta, legs)
+
+
+def build_draft(
+    inv: Invoice,
+    totals: Totals,
+    cfg: config.Config | None = None,
+    chf_rate: Decimal | None = None,
+    received: Mapping[str, Received] | None = None,
+) -> str:
+    """A balanced receivable booking matching what `verify.cross_check` expects.
+
+    VAT is owed in CHF, so on a foreign-currency invoice the OutputVAT leg is
+    CHF at ``chf_rate`` (the issue date's), priced ``@@`` at the invoice's
+    VAT. Without a rate it stays in the invoice currency, marked to convert.
+
+    Credited advances are released as their receipts booked them
+    (``received``, from `verify.cross_check`): the VAT they declared is not
+    owed again, and a foreign advance leaves at the CHF it came in at — the
+    income it becomes is valued at that too, so the advances account clears
+    in CHF as well as in units. A pro forma missing from ``received`` is
+    released as the invoice credits it.
+    """
+    cfg = cfg or config.get()
+    if inv.proforma:
+        return receipt_draft(inv, totals, cfg)
+    customer = inv.resolved_customer
+    ccy = inv.currency
+    income = filing_account(inv, cfg)
+    advances = cfg.advances_for(inv.kind)
+    narration = f"{inv.supply.text(inv.locale)} invoiced"
+    doc = document_path(inv, income)  # same name the rendered PDF is filed under
+
+    vat = totals.vat_amount
+    rest = totals.subtotal  # the income not advanced, valued at the issue date
+    slices: list[tuple[str, str, str]] = []
+    released: list[tuple[str, str, str]] = []
+    for number in dict.fromkeys(a.proforma for a in inv.advances):
+        r = (received or {}).get(number) or _as_credited(inv, number, totals.vat_rate)
+        vat -= r.vat
+        # Posting metadata, not a second ^link: receivables trust a lone invoice link.
+        tag = f"proforma: {_quoted(number)}"
+        if ccy != "CHF" and r.net_chf is not None:
+            rest -= r.net
+            slices.append((income, f"{-r.net:>10.2f} {ccy} @@ {r.net_chf:.2f} CHF", ""))
+            released.append((advances, f"{r.net:>10.2f} {ccy} @@ {r.net_chf:.2f} CHF", tag))
+        elif ccy != "CHF":
+            todo = "  ; TODO @@ the CHF it was received at"
+            released.append((advances, f"{r.net:>10.2f} {ccy}{todo}", tag))
+        else:
+            released.append((advances, f"{r.net:>10.2f} {ccy}", tag))
+
+    legs = [*([(income, f"{-rest:>10.2f} {ccy}", "")] if rest else []), *slices]
+    if totals.amount_due:
+        legs.append((cfg.receivable, f"{totals.amount_due:>10.2f} {ccy}", ""))
+    legs += released
+    if vat:
+        legs.append((cfg.output_vat, _vat_leg(vat, ccy, chf_rate), ""))
+    if totals.rounding:
+        legs.append((cfg.rounding_income, f"{-totals.rounding:>10.2f} {ccy}", ""))
+
+    meta = [f"    invoice: {_quoted(inv.number)}"]
+    if inv.customer_reference:
+        # The payer quotes their own reference, not ours, when they ask about
+        # this invoice — so the ledger can be searched by it too.
+        meta.append(f"    customer_reference: {_quoted(inv.customer_reference)}")
+    meta.append(f"    document: {_quoted(doc.name)}  ; TODO file the PDF under {doc.parent}/")
+    header = f"{inv.issue_date} * {_quoted(customer.name)} {_quoted(narration)} ^{inv.number}"
+    return _lines(header, meta, legs)
+
+
+def _as_credited(inv: Invoice, number: str, rate: Decimal) -> Received:
+    """An advance not (yet) in the books, split the way its receipt would be."""
+    gross = sum((a.amount for a in inv.advances if a.proforma == number), Decimal("0"))
+    vat = vat_included(gross, rate)
+    return Received(net=gross - vat, vat=vat, net_chf=None)

{quints-0.18.0 → quints-0.19.0}/src/quints/invoice/labels.py

@@ -6,9 +6,11 @@ these keys, so a new language is accepted the moment it is defined here — no
 other file to touch; the matching CLDR locale, e.g. `es_ES`, gives Babel the
 number/date formatting for free).
 
-The legally load-bearing strings — `terms`, `export_note`, `reverse_charge` —
+The legally load-bearing strings — `terms`, `export_note`, `reverse_charge`,
+`proforma_note`, `advance_vat` —
 should be reviewed by a native/legal speaker before an entry ships.
-`terms` MUST keep the literal `{days}` placeholder (`render` calls `.format`)."""
+`terms` MUST keep the literal `{days}` placeholder, `advance` its `{number}`
+and `{date}`, and `advance_vat` its `{vat}` (`render` calls `.format`)."""
 
 LABELS = {
     "de": {
@@ -34,6 +36,15 @@ LABELS = {
         "export_note": "Nicht der schweizerischen MWST unterliegend: Ort der "
         "Leistung im Ausland (Art. 8 Abs. 1 MWSTG).",
         "reverse_charge": "Reverse Charge — die Steuer ist vom Leistungsempfänger abzurechnen.",
+        "proforma": "Proforma-Rechnung",
+        "proforma_no": "Proforma-Nr.",
+        "proforma_date": "Datum",
+        "amount_due": "Zahlbar",
+        "invoice_total": "Rechnungstotal",
+        "advance": "Anzahlung {number} vom {date}",
+        "advance_vat": "inkl. MWST {vat}",
+        "proforma_note": "Zahlungsaufforderung für eine Anzahlung. Die Rechnung folgt mit "
+        "der Leistung und rechnet diese Zahlung samt der darin enthaltenen MWST an.",
     },
     "en": {
         "invoice": "Invoice",
@@ -58,6 +69,15 @@ LABELS = {
         "export_note": "Not subject to Swiss VAT: place of supply abroad "
         "(Art. 8 para. 1 Swiss VAT Act).",
         "reverse_charge": "Reverse charge — VAT to be accounted for by the recipient.",
+        "proforma": "Pro forma invoice",
+        "proforma_no": "Pro forma no.",
+        "proforma_date": "Date",
+        "amount_due": "Amount due",
+        "invoice_total": "Invoice total",
+        "advance": "Advance {number} received {date}",
+        "advance_vat": "incl. VAT {vat}",
+        "proforma_note": "Request for an advance payment. The invoice follows with the "
+        "supply and credits this payment, including the VAT it contains.",
     },
     "es": {
         "invoice": "Factura",
@@ -83,6 +103,15 @@ LABELS = {
         "extranjero (art. 8 apdo. 1 de la Ley suiza del IVA).",
         "reverse_charge": "Inversión del sujeto pasivo — el IVA debe ser "
         "liquidado por el destinatario.",
+        "proforma": "Factura proforma",
+        "proforma_no": "N.º de proforma",
+        "proforma_date": "Fecha",
+        "amount_due": "Importe a pagar",
+        "invoice_total": "Total factura",
+        "advance": "Anticipo {number} recibido el {date}",
+        "advance_vat": "IVA incl. {vat}",
+        "proforma_note": "Solicitud de pago anticipado. La factura se emitirá con la "
+        "prestación y descontará este pago, incluido el IVA que contiene.",
     },
 }
 

{quints-0.18.0 → quints-0.19.0}/src/quints/invoice/model.py

@@ -279,6 +279,22 @@ class LineItem(BaseModel):
         return (self.quantity * self.unit_price).quantize(Decimal("0.01"), ROUND_HALF_UP)
 
 
+class Advance(BaseModel):
+    """A payment received against a pro forma, credited on the final invoice."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    proforma: str = Field(min_length=1, description="The pro forma's number, e.g. PF2026001.")
+    received: date = Field(description="The day the payment arrived.")
+    amount: Decimal = Field(
+        gt=0,
+        description=(
+            "What was received, in the invoice currency, VAT included — the "
+            "amount the advance was booked at."
+        ),
+    )
+
+
 class VatBlock(BaseModel):
     rate: Decimal | None = Field(
         default=None,
@@ -336,6 +352,23 @@ class Invoice(BaseModel):
         ),
     )
     notes: list[str] = Field(default_factory=list)
+    proforma: bool = Field(
+        default=False,
+        description=(
+            "A pro forma: a request for an advance payment, not the invoice. It "
+            "is titled and marked as such, carries no Swico billing information "
+            "(the payer's software would book it as an invoice), and is booked "
+            "only when paid, as a customer advance. Give it its own number "
+            "series (PF2026001)."
+        ),
+    )
+    advances: list[Advance] = Field(
+        default_factory=list,
+        description=(
+            "Payments received against pro formas, credited on this invoice: it "
+            "shows VAT on the full supply, subtracts them, and asks for the rest."
+        ),
+    )
     round_5: bool | None = None  # None → 0.05 rounding iff currency is CHF
     terms_days: int | None = 30  # None → no payment-terms line
     # Export only. None → reverse charge expected (EU B2B default); requires the
@@ -369,6 +402,14 @@ class Invoice(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _proforma_has_no_advances(self) -> Invoice:
+        if self.proforma and self.advances:
+            raise ValueError(
+                "a pro forma cannot credit advances — list them on the invoice that follows it"
+            )
+        return self
+
     @model_validator(mode="before")
     @classmethod
     def _reject_legacy_language(cls, data: Any) -> Any:
@@ -611,6 +652,10 @@ class Totals(BaseModel):
     unrounded: Decimal
     rounding: Decimal
     grand_total: Decimal
+    # Advances received against pro formas, VAT included: their VAT was
+    # declared when received (see `draft.build_draft`).
+    advances: Decimal = Decimal("0")
+    amount_due: Decimal  # grand_total − advances: what the payment part asks for
     # Whether the issuer was VAT-registered on the issue date. When not, the
     # invoice must not mention the tax at all (Art. 27 Abs. 1 MWSTG).
     vat_registered: bool = True
@@ -696,6 +741,11 @@ def load_invoice(path: Path, customers: CustomerRegistry | None = None) -> Invoi
 # ── computation ───────────────────────────────────────────────────────────────
 
 
+def vat_included(gross: Decimal, rate: Decimal) -> Decimal:
+    """The VAT within a gross amount at `rate` per cent (8.1 → 81 of 1081)."""
+    return (gross * rate / (100 + rate)).quantize(Decimal("0.01"), ROUND_HALF_UP)
+
+
 def compute(inv: Invoice, vat_registered: bool = True) -> Totals:
     """The invoice's figures. ``vat_registered`` is the issuer's status on the
     issue date: a business that is not registered charges no VAT."""
@@ -708,6 +758,12 @@ def compute(inv: Invoice, vat_registered: bool = True) -> Totals:
         vat = (subtotal * rate / 100).quantize(Decimal("0.01"), ROUND_HALF_UP)
     unrounded = subtotal + vat
     grand = round_step(unrounded, Decimal("0.05") if inv.rounds_to_5 else Decimal("0"))
+    advances = sum((a.amount for a in inv.advances), Decimal("0"))
+    if advances > grand:
+        raise ValueError(
+            f"invoice {inv.number}: advances of {advances} exceed its total of {grand} "
+            f"{inv.currency} — refund the difference or issue a credit note"
+        )
     return Totals(
         subtotal=subtotal,
         vat_rate=rate,
@@ -715,5 +771,7 @@ def compute(inv: Invoice, vat_registered: bool = True) -> Totals:
         unrounded=unrounded,
         rounding=grand - unrounded,
         grand_total=grand,
+        advances=advances,
+        amount_due=grand - advances,
         vat_registered=vat_registered,
     )

{quints-0.18.0 → quints-0.19.0}/src/quints/invoice/qr.py

@@ -31,6 +31,14 @@ def _structured(name: str, lines: Sequence[str], country: str) -> dict[str, str
             f"like '8000 Zürich' (got {lines})"
         )
     street_lines = [ln for i, ln in enumerate(lines) if i != postal_idx]
+    if len(street_lines) > 1:
+        # Structured addresses carry one street line; c/o or Postfach can't follow.
+        warnings.warn(
+            f"{name}: the QR-bill's structured address takes one street line, so "
+            f"{street_lines[1:]} is left off the payment part (the invoice still "
+            f"prints it) — put the line the post delivers to first",
+            stacklevel=3,
+        )
     if street_lines:
         m = re.match(r"^(.*?)[\s,]+(\d+\w*)$", street_lines[0])  # split trailing house no
         street, house = (m.group(1), m.group(2)) if m else (street_lines[0], "")
@@ -54,14 +62,18 @@ def build_bill(inv: Invoice, issuer: Issuer, account: BankAccount, totals: Total
     # statement, so it carries the invoice number; the structured billing
     # information is for the payer's software and carries everything else.
     message = inv.number
-    billing = swico.billing_information(inv, issuer, totals, message) or ""
+    # A pro forma carries none: its /10/ invoice number, date and VAT rate are
+    # what the payer's software books an invoice — and input tax — from.
+    billing = "" if inv.proforma else swico.billing_information(inv, issuer, totals, message) or ""
+    creditor = _structured(issuer.name, issuer.address, issuer.country)
+    debtor = _structured(customer.name, customer.address, customer.country)
     with warnings.catch_warnings():
         warnings.simplefilter("ignore")
         bill = QRBill(
             account=ref_mod.creditor_iban(account, payment_ref.kind, currency),
-            creditor=_structured(issuer.name, issuer.address, issuer.country),
-            debtor=_structured(customer.name, customer.address, customer.country),
-            amount=f"{totals.grand_total:.2f}",
+            creditor=creditor,
+            debtor=debtor,
+            amount=f"{totals.amount_due:.2f}",
             currency=currency,
             reference_number=payment_ref.value,
             additional_information=message,