Scriboby Causa Prima
Following system theme

#Jurisdictions & Format Selection

Phase 1 scope. Scribo currently emits invoices for Germany (DE) and the United States (US) only. Any other sender jurisdiction — resolved via sender.country_code, the sender.tax_id prefix, or an explicit jurisdiction override — is rejected with unsupported_jurisdiction. France, Spain, Belgium and the rest of the EU are Phase 2 and not yet wired.

Scribo picks the document format from a deterministic priority chain. The caller — whether the LLM via the MCP server or skill, or your own API client — should generally let the chain do its work and only set jurisdiction or format_override when the user explicitly asks for a specific format.

#Priority chain

Scribo resolves the format by walking these in order. Top-first match wins.

  1. format_override in the request body — explicit user override (with one exception: a leitweg_id will pin XRechnung; format_override: "xrechnung_cii" picks the CII syntax for that leitweg invoice, while non-XRechnung overrides lose to the B2G mandate).
  2. recipient.leitweg_id present — auto-selects xrechnung_ubl (German federal B2G). UBL is the default XRechnung syntax — every Peppol AccessPoint speaks it, and KoSIT + the federal procurement portals accept it. Force xrechnung_cii via format_override if you specifically need the CII syntax.
  3. jurisdiction in the request body — explicit user override for the country resolution step.
  4. sender.country_code — the issuer's jurisdiction (e-invoicing flows are regulated by the issuer's country, not the buyer's).
  5. sender.tax_id prefix — first two letters of the tax ID, when sender.country_code is missing.
  6. recipient.country_code — fallback to the recipient's country.
  7. recipient.tax_id prefix — final fallback.

If none of these resolve to a supported jurisdiction, Scribo returns 400 with error.code == "unsupported_jurisdiction".

#Per-country defaults

Country Default format Supported alternatives
DE Germany zugferd_comfort (B2B) / xrechnung_ubl (B2G, when leitweg_id set) zugferd_basic, xrechnung_cii
US United States plain_pdf —

Anything else (FR / ES / BE / NL / LU / AT / IT / MX / BR / …) is Phase 2 — the resolver still walks the priority chain, but the pipeline rejects the request with unsupported_jurisdiction before any document is generated. Call GET /api/v1/jurisdictions for the live list.

#Format reference

Format Profile When you want it
zugferd_comfort EN 16931 CII embedded in PDF/A-3 German B2B; humans see PDF, machines parse XML.
zugferd_basic Subset of EN 16931 CII in PDF/A-3 German B2B where recipient accepts the smaller profile.
xrechnung_ubl German XRechnung in UBL syntax — default for B2G Automatic when leitweg_id is set. Broadest Peppol compatibility.
xrechnung_cii German XRechnung in CII syntax German B2G where the recipient procurement portal specifically requires CII (rare — most accept either). Force via format_override.
plain_pdf Non-structured PDF (no embedded XML) US, or any jurisdiction without a structured mandate. Renders payment instructions (IBAN or US account + ABA routing, holder, bank) when payment_means is supplied.

Phase 2 formats (factur_x, facturae, peppol_bis_ubl) are wired through the GOBL builder but not yet exposed at the public boundary; passing them in format_override returns a Zod validation error.

#Mandatory fields by format

All formats need everything in the base CreateInvoiceInput. Format-specific extras:

  • xrechnung_ubl / xrechnung_cii —
    • Payment means: payment_means with an IBAN (+ holder, optional BIC) is required by BR-DE-1 (German B2G mandates electronic payment instructions); a US account_number + routing_number cannot satisfy it.
    • Sender contact: sender.contact_name and sender.contact_phone are required downstream by BR-DE-5/6.
    • All-O rejection: invoices where every line is tax_category_code = O are rejected (BR-DE-14 — the outside-scope tax breakdown has no rate); use AE/G or a non-XRechnung format.
    • Leitweg-ID (optional): when present it auto-selects xrechnung_ubl (BT-10 buyer reference) and acts as the buyer routing ID for federal procurement portals; XRechnung B2B between two German companies without a Leitweg-ID is also valid and is accepted.
  • zugferd_* — recipient address must be parseable (street, postcode, city). Invopop's validator rejects PO-box-only addresses.
  • Line items with tax_category_code = E (exempt) — tax_exemption_code (VATEX-EU-* / VATEX-{ISO2}-*) is required per EN 16931 BR-E-10 + GOBL TAX-COMBO-06. Pick the code that matches the legal basis (VATEX-EU-132 for Art. 132 health/education exemptions, VATEX-EU-79-C for the small-business exemption under § 19 UStG, etc.). AE / K / G / O have well-known VATEX codes and Scribo applies them automatically when not supplied.

If a mandatory field is missing the response includes validator_summary.errors with [{ path, rule, message }]. Surface these to the user verbatim and ask for the missing field. See troubleshooting.

#See also