Skip to content

Partner invoice upload flow

When an authorised partner (today: optician on Marmot, supplier = LPL) uploads a PDF invoice for a Saleor fulfillment, the request goes through 3 explicit phases, each backed by a separate "brick". The orchestrator (process_partner_invoice.py) wires them together and decides which persistence path to take based on the check result.

                ┌─────────────────────────────────────────┐
                │  Controller : POST .../invoice         │
                │  admin_order.py                         │
                └────────────────────┬────────────────────┘
                                     ↓
                  ┌──────────────────────────────────────┐
                  │  ORCHESTRATOR                        │
                  │  process_partner_invoice_upload      │
                  └──────────────────────────────────────┘
                                     │
        ┌────────────────────────────┼────────────────────────────┐
        ↓                            ↓                            ↓

  ┌─────────────────┐       ┌─────────────────┐         ┌──────────────────┐
  │ BRICK 1         │       │ BRICK 2         │         │ BRICK 3          │
  │ Parse +         │  →    │ Automated       │   →     │ Persist          │
  │ optician-facing │       │ checks          │         │ (success / fail) │
  │ validation      │       │ (silent, ops)   │         │                  │
  └─────────────────┘       └─────────────────┘         └──────────────────┘
   raises ValueError         returns list[str]            writes Saleor
   on user-fixable           on rule failures              metadata
   problem                                                 → drives UI badge

Brick 1 — Parse + opticien-facing validation

Module : partner_invoice_upload.py

Purpose : turn the raw PDF into a structured ParsedPartnerInvoice and reject inputs the optician can fix themselves (wrong file, wrong commande, etc.).

Country-agnostic : the parser dispatch + the validation rules apply to every country that uses this flow. The country adapter is used only to resolve the buyer's name via resolve_user_name_from_user_id.

Dispatch : parser selection is driven by warehouse.slug through PARSER_REGISTRY. Adding a new supplier means registering a new parser function in that mapping (and nothing else in this brick).

Failure mode : ValueError → the controller surfaces it as a 400 with the error message. The optician sees the error in the dashboard and retries with a fixed file.

Brick 2 — Automated checks (silent, ops-facing)

Modules : - shop aggregator : glasses_invoice_post_upload_checks.py - country-specific stub : fr/.../glasses_invoice_post_upload_checks.py

Purpose : run rules that should not block the upload from the optician's perspective but should prevent the system from creating an InsuranceDocument on suspicious data.

Reached via : the shop aggregator delegates to shop_adapter.run_country_specific_invoice_automated_checks, which routes to the appropriate country's check module. The base adapter ships a no-op default (return []), so a country opts in by overriding the method.

Failure mode : returns a list[str] of human-readable error messages. Empty list → success branch. Non-empty → failure branch (see Brick 3). No exception is raised — the optician's UI flow never stops here.

Adding a new check rule : append to the country-specific module's run_*_invoice_automated_checks function. The specific rules are documented in the source, intentionally not duplicated here — they evolve per business need.

Brick 3 — Persistence

Module : process_partner_invoice.py (_persist_successful_upload / _persist_failed_upload)

The orchestrator branches based on the aggregated check errors :

Success path (no errors)

  • Calls shop_adapter.create_insurance_document_from_parsed_partner_invoice, which delegates to the country's claim engine to create a real InsuranceDocument with care acts.
  • Writes invoice-document-id + invoice-file-name on the Saleor fulfillment metadata.
  • Posts a success Saleor order note.

Failure path (≥ 1 error)

  • Calls the shop-level store_failed_partner_invoice_pdf, which uploads the rejected PDF as a generic Document (with the country-specific DocumentType from shop_adapter.get_lab_invoice_document_type) — it stays out of the claim engine.
  • Writes failed-invoice-document-id + failed-invoice-file-name on the fulfillment metadata.
  • Posts a failure Saleor order note listing every error.
  • Pings ops on Slack so a human can review the PDF.

The two metadata key sets are mutually exclusive : the presence of invoice-document-id is the "checks passed" signal, the presence of failed-invoice-document-id is the "checks failed" signal. No separate flag needed.

How the frontend uses the metadata

The Marmot optician dashboard reads the fulfillment metadata to render the téléTT status :

Metadata key present Badge Meaning
invoice-document-id 📡 Prêt pour télétransmission Care acts created, ready for the claim engine.
failed-invoice-document-id 🛑 En attente de validation de la facture Rejected PDF stored, ops needs to review.
neither (no badge) No invoice uploaded yet.