Add peppol-bis-v3 addon (Peppol BIS Billing 3.0)

[alvarolivie]

What this adds

New addon peppol-bis-v3 at addons/peppol/bis/ that enforces the fatal-level Peppol BIS Billing 3.0 rules on top of eu-en16931-v2017. Without this, gobl.ubl can produce documents that pass EN 16931 but get rejected at a Peppol access point.

Rules enforced

• Base: PEPPOL-COMMON identifier checksums (GLN, NO, DK CVR, BE, SE, AU), plus the fatal PEPPOL-EN16931-R* and P* rules that map to GOBL document content (buyer reference, note cardinality, VATEX/tax-category coherence, allowed UNTDID document types, line-period bounds, direct-debit mandate, etc.).
• National CIUS (guarded on supplier country): fatal rules for DK, DE, GR, IS, IT, NL, NO, SE — including DE-R-018 #SKONTO# format on pay.Terms.Notes, IS-R-008/R-009/R-010 EINDAGI on org.Note{Src: "eindagi"}, GR-R-001-1 invoice-ID segment count, etc.

Rules not enforced

• Warning-level rules: not implemented as a general policy.
• Deferred to gobl.ubl (documented inline at each rule site):
  • DE-R-014, DE-R-022 — percent and attachment filenames are UBL serialization concerns the converter controls.
  • DK-R-003 — UNSPSC @listVersionID is a UBL attribute; no structured GOBL slot.
  • GR-R-001-2..-7 — segment contents (TIN, date, sequence) should be built from structured fields at emit time, not parsed back out.
• Out of scope: PEPPOL-EN16931-R001/R004/R007 (ProfileID/CustomizationID — set by gobl.ubl Context), UBL-shape concerns (R008/R043/R051), formulas already enforced by bill.Invoice.Calculate() (R040/R041/R042/R046/R120), and all UBL-CR-* warnings.

Key decisions

• Layout addons/peppol/<profile>/ so a future addons/peppol/pint/ can sit alongside bis/.
• Requires: en16931.V2017 — no duplication of EN 16931 normalization/validation.
• Identity checks key on iso-scheme-id, not regime id.Type, so they fire whether the caller used a typed identity, a key, or set the scheme directly.
• IdentityKeyFSkatt normalizer populates Scope=tax / Type / Code so gobl.ubl's existing tax-scope identity path emits the F-skatt cac:PartyTaxScheme block without converter changes (SE-R-005).

Pre-Review Checklist

• Opened this PR as a draft
• Read the CONTRIBUTING.md guide.
• Performed a self-review of my code.
• Added thorough tests with at least 90% code coverage. (addons/peppol/bis at 97.2%)
• Modified or created example GOBL documents to show my changes in use, if appropriate.
• Added links to the source of the changes in tax regimes or addons, either structured or in the comments.
• Run go generate . to ensure that the Schemas and Regime data are up to date.
• Reviewed and fixed all linter warnings.
• Been obsessive with pointer nil checks to avoid panics.
• Updated the CHANGELOG.md with an overview of my changes.
• Marked this PR as ready for review.

And if you are part of the org:

• Requested a review from Copilot and fixed or dismissed (with a reason) all the feedback raised.
• Requested a review from @samlown.

[codecov]

Codecov Report

❌ Patch coverage is 96.84647% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.56%. Comparing base (cec18ad) to head (042d8a2).

Files with missing lines	Patch %	Lines
addons/peppol/bis/is.go	88.23%	8 Missing and 8 partials ⚠️
addons/peppol/bis/de.go	96.17%	4 Missing and 4 partials ⚠️
addons/peppol/bis/org.go	95.58%	4 Missing and 2 partials ⚠️
addons/peppol/bis/bill_line.go	94.28%	1 Missing and 1 partial ⚠️
addons/peppol/bis/bis.go	97.22%	1 Missing and 1 partial ⚠️
addons/peppol/bis/se.go	97.87%	1 Missing and 1 partial ⚠️
addons/peppol/bis/tax.go	89.47%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #811      +/-   ##
==========================================
+ Coverage   93.36%   93.56%   +0.19%     
==========================================
  Files         369      384      +15     
  Lines       19882    21087    +1205     
==========================================
+ Hits        18562    19729    +1167     
- Misses        888      908      +20     
- Partials      432      450      +18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR introduces a new Peppol BIS Billing 3.0 addon (peppol-bis-v3) that layers Peppol fatal rule enforcement on top of the existing eu-en16931-v2017 addon, and wires it into the global addon registry along with examples and generated data artifacts.

Changes:

• Added addons/peppol/bis Go implementation for Peppol BIS Billing 3.0 base rules + national CIUS (DK/DE/GR/IS/IT/NL/NO/SE), including identity normalization (SE F-skatt) and extensive unit tests.
• Registered the addon in the global addon list/schema and included generated addon + rules JSON data.
• Updated/added examples (DK + DE) and documented the addition in CHANGELOG.md.

Reviewed changes

Copilot reviewed 37 out of 39 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
examples/dk/out/invoice-peppol.json	Updates DK Peppol output example to include addon + ordering reference.
examples/dk/invoice-peppol.json	Updates DK input example to use peppol-bis-v3 and include ordering code.
examples/de/out/invoice-peppol.json	Adds DE Peppol output envelope example.
examples/de/invoice-peppol.yaml	Adds DE Peppol input example (YAML).
data/schemas/tax/addon-list.json	Adds peppol-bis-v3 to addon enum list.
data/rules/peppol-bis-v3.json	Adds generated rules export for the addon.
data/addons/peppol-bis-v3.json	Adds generated addon definition export.
addons/peppol/bis/tax.go	Implements VATEX ↔ tax category coherence rule.
addons/peppol/bis/tax_test.go	Unit tests for VATEX/category coherence helper.
addons/peppol/bis/se.go	Swedish CIUS rules/helpers (VAT rate, VAT/org number checks).
addons/peppol/bis/se_test.go	Unit tests for Swedish CIUS helpers.
addons/peppol/bis/pay.go	Implements direct-debit mandate reference requirement.
addons/peppol/bis/pay_test.go	Unit tests for direct-debit mandate requirement.
addons/peppol/bis/org.go	Implements PEPPOL-COMMON identifier/inbox scheme validation helpers.
addons/peppol/bis/org_test.go	Unit tests for identifier checksum/format validators.
addons/peppol/bis/no.go	Norwegian CIUS VAT-format rule helper.
addons/peppol/bis/no_test.go	Unit tests for Norwegian VAT-format helper.
addons/peppol/bis/nl.go	Dutch CIUS rules (credit note refs, legal scheme, payment means, etc.).
addons/peppol/bis/nl_test.go	Unit tests for Dutch CIUS helpers.
addons/peppol/bis/it.go	Italian CIUS rules (tax id length, address requirements).
addons/peppol/bis/it_test.go	Unit tests for Italian CIUS helpers.
addons/peppol/bis/is.go	Icelandic CIUS rules (EINDAGI notes + payment account constraints).
addons/peppol/bis/is_test.go	Unit tests for Icelandic CIUS helpers.
addons/peppol/bis/identities.go	Defines Peppol-specific identities (GR MARK, SE F-skatt) + normalizer.
addons/peppol/bis/gr.go	Greek CIUS rules (invoice ID segments, MARK identity, inbox/VAT rules).
addons/peppol/bis/gr_test.go	Unit tests for Greek CIUS helpers.
addons/peppol/bis/dk.go	Danish CIUS rules (CVR identity, payment means subsets, etc.).
addons/peppol/bis/dk_test.go	Unit tests for Danish CIUS helpers.
addons/peppol/bis/de.go	German CIUS rules (contact requirements, #SKONTO# format, payment exclusivity).
addons/peppol/bis/de_test.go	Unit tests for German CIUS helpers.
addons/peppol/bis/bill.go	Base Peppol invoice-level rules (notes, buyer ref/PO, UNTDID type codes).
addons/peppol/bis/bill_test.go	Unit tests for base invoice-level rules.
addons/peppol/bis/bill_line.go	Base line period within invoice period checks.
addons/peppol/bis/bill_line_test.go	Unit tests for line period boundary checks.
addons/peppol/bis/bis.go	Addon registration + ruleset wiring + country guard helpers.
addons/peppol/bis/bis_test.go	Public-facing addon registration/normalizer smoke tests.
addons/peppol/bis/bis_internal_test.go	Internal helper tests (party country guard, normalizer dispatch).
addons/addons.go	Globally registers the new addon via blank import.
CHANGELOG.md	Documents the new addon and F-skatt identity key.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

partyHasContactGroup returns true when People/Telephones/Emails slices are non-empty even if they only contain nil entries. That can let DE-R-002 pass even though there is effectively no contact info (nil elements won’t be validated by org.Person/org.Telephone/org.Email rules). Consider scanning the slices for at least one non-nil entry (and/or one with required fields present) instead of relying on len(...).

Suggested change

	if len(p.People) > 0 || len(p.Telephones) > 0 || len(p.Emails) > 0 {
	return true
	}
	for _, person := range p.People {
	if person != nil {
	return true
	}
	}
	for _, telephone := range p.Telephones {
	if telephone != nil {
	return true
	}
	}
	for _, email := range p.Emails {
	if email != nil {
	return true
	}
	}

[Copilot]

partyHasContactTelephone treats any non-empty Telephones slice as satisfying DE-R-006, even if entries are nil (or otherwise empty). Since nil elements won’t be validated by org.Telephone rules, this can incorrectly pass. Consider iterating to confirm there is at least one non-nil telephone (and ideally a non-empty Number) either on the party or on a person.

Suggested change

	func partyHasContactTelephone(val any) bool {
	p, ok := val.(*org.Party)
	if !ok || p == nil {
	return true
	}
	if len(p.Telephones) > 0 {
	return true
	}
	if len(p.People) > 0 && p.People[0] != nil && len(p.People[0].Telephones) > 0 {
	return true
	func hasUsableTelephone(telephones []*org.Telephone) bool {
	for _, tel := range telephones {
	if tel != nil && strings.TrimSpace(tel.Number) != "" {
	return true
	}
	}
	return false
	}
	func partyHasContactTelephone(val any) bool {
	p, ok := val.(*org.Party)
	if !ok || p == nil {
	return true
	}
	if hasUsableTelephone(p.Telephones) {
	return true
	}
	for _, person := range p.People {
	if person != nil && hasUsableTelephone(person.Telephones) {
	return true
	}

[Copilot]

partyHasContactEmail treats any non-empty Emails slice as satisfying DE-R-007, even if entries are nil (or otherwise empty). Because nil elements won’t be validated by org.Email rules, this can incorrectly pass. Consider iterating to confirm there is at least one non-nil email (and ideally a non-empty Address) either on the party or on a person.

Suggested change

	func partyHasContactEmail(val any) bool {
	p, ok := val.(*org.Party)
	if !ok || p == nil {
	return true
	}
	if len(p.Emails) > 0 {
	return true
	}
	if len(p.People) > 0 && p.People[0] != nil && len(p.People[0].Emails) > 0 {
	return true
	func hasAnyContactEmail(emails []*org.Email) bool {
	for _, email := range emails {
	if email != nil && strings.TrimSpace(email.Address) != "" {
	return true
	}
	}
	return false
	}
	func partyHasContactEmail(val any) bool {
	p, ok := val.(*org.Party)
	if !ok || p == nil {
	return true
	}
	if hasAnyContactEmail(p.Emails) {
	return true
	}
	for _, person := range p.People {
	if person != nil && hasAnyContactEmail(person.Emails) {
	return true
	}

[Copilot]

This example uses payment.terms.detail, which is a deprecated/backwards-compat field (Terms is schema’d as notes). Consider switching to payment.terms.notes to keep the example JSON-schema-valid and avoid relying on deprecated input.