Voor ontwikkelaars · GitHub Action en CLI

Nu op GitHub; Marketplace-vermelding volgt binnenkort

Peppol UBL-check: een gratis GitHub Action voor uw e-facturen

Name: Peppol UBL check
Author: Kalmwerk

Controleer de UBL- en Peppol BIS Billing 3.0-facturen die uw software aanmaakt, bij elke push en pull request. Bij een fout faalt de job, en de samenvatting geeft per fout de regel-ID, het lijnnummer en de oplossing, nog voor een accesspoint de factuur weigert.

153 EN 16931-, Peppol- en XRechnung-regels
Werkt offline, geen API-sleutel
MIT-licentie
Dezelfde regels als de online validator

Instellen Bekijk op GitHub Download v1.0.1 (.zip, 243 KB)

Gebruik kalmwerk/peppol-ubl-check@v1 in elke workflow, of bewaar een gedownloade kopie in uw repository. Nieuwste release op GitHub

Ook in het:English Français

In twee stappen ingesteld

Voeg één workflowbestand toe. Niets te installeren, geen API-sleutel.

1
Voeg de workflow toe
Bewaar dit als .github/workflows/peppol-ubl-check.yml en laat files naar uw facturen of testbestanden wijzen. Zonder files wordt elk *.xml-bestand in de repository gecontroleerd; XML-bestanden die geen factuur zijn, zoals een pom.xml, worden overgeslagen.
Bewaar als .github/workflows/peppol-ubl-check.yml
```
name: Peppol UBL check

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  invoices:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: kalmwerk/peppol-ubl-check@v1
        with:
          files: "invoices/**/*.xml"
```
2
Push
De job faalt zodra een factuur fouten bevat. De samenvatting van de job toont elke fout met de regel-ID, het lijnnummer en de oplossing, en in pull requests verschijnen ze naast de code.

Liever een kopie in uw repository?

Download de zip en pak hem uit in .github/actions/, vanuit de hoofdmap van uw repository:

mkdir -p .github/actions
unzip peppol-ubl-check-1.0.1.zip -d .github/actions/
git add .github/actions/peppol-ubl-check

Gebruik daarna het lokale pad in de workflow:

Bewaar als .github/workflows/peppol-ubl-check.yml

name: Peppol UBL check

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  invoices:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: ./.github/actions/peppol-ubl-check
        with:
          files: "invoices/**/*.xml"

Alleen action.yml en dist/ draaien. De testfacturen uit de zip blijven in .github/, en die map slaat het standaardpatroon van files over.

Wat de samenvatting van de job toont

Voor een van onze bewust foute voorbeeldfacturen (een btw-rekenfout) toont de samenvatting onder meer dit. De Action schrijft in het Engels; elke regel-ID linkt naar de uitleg in het Nederlands.

❌ invoices/2026-0918.xml

Regel	Lijn	Wat er mis is	Oplossing
BR-CO-14	88	VAT total does not match breakdown. VAT breakdown adds up to 403.04, but the VAT total is 422.64.	Make cac:TaxTotal/cbc:TaxAmount equal to the sum of all cac:TaxSubtotal/cbc:TaxAmount values.
BR-CO-17	91	VAT amount does not match rate. 1960.00 × 21% = 411.60, but the VAT amount is 392.00.	Calculate VAT per category on the taxable total (not per line) and round once to 2 decimals.
PEPPOL-EN16931-R120	140	Line net amount calculation error. Line 2: 8 × 95 = 760.00, but the line amount is 712.50.	Recalculate cbc:LineExtensionAmount = quantity × price / base quantity + charges − allowances, rounded to 2 decimals.

…en nog 2 rijen, onder een overzichtstabel met één rij per factuur.

Wat ze controleert

101 EN 16931-bedrijfsregels: verplichte velden, btw-categorieën en vrijstellingen, berekeningen van lijnen, totalen en btw-overzicht, codelijsten.
28 Peppol BIS Billing 3.0-regels: specificatie-ID's, kopersreferentie, endpoint-ID's en Belgische 0208-nummers, toegelaten documenttypes.
13 XRechnung-regels, voor bestanden die XRechnung aangeven (of met profile: xrechnung).
11 extra controles: geldige XML met de exacte lijn, controlecijfers van btw-nummers en Belgische ondernemingsnummers, IBAN, vervaldatum.

Wat ze niet controleert

De officiële Schematron-regels volledig: de 153 regels zijn een gedeeltelijke versie.
XSD-schemavalidatie (volgorde van elementen, onbekende elementen).
PDF/A en Factur-X- of ZUGFeRD-pdf's: ze leest alleen XML-bestanden.
Of de koper facturen kan ontvangen via Peppol: daarvoor is een opzoeking in het netwerk nodig.
Een geslaagde controle is een sterk signaal, geen garantie: uw accesspoint valideert elke factuur nog eens.

Inputs

Allemaal optioneel. De standaardwaarden passen bij een repository met facturen of testbestanden.

Input	Standaard	Wat het doet
files	*/.xml	Factuurbestanden als globpatronen vanaf de hoofdmap, één per regel of gescheiden door komma's. Een map betekent elk `*.xml`-bestand erin; `!patroon` sluit bestanden uit.
ignore	–	Globpatronen om over te slaan, bv. `test/fixtures/broken/**`.
profile	peppol	`peppol`: Peppol- en EN 16931-regels op elk UBL-bestand. `auto`: kiest per bestand op basis van de `CustomizationID`. `en16931` of `xrechnung`: altijd die regels.
fail-on	error	`error` laat de job falen bij fouten, `warning` ook bij waarschuwingen, `never` rapporteert alleen.
non-invoice	skip	XML die geen factuur is: `skip` slaat hem over, `fail` telt hem als fout.
if-no-files-found	error	Geen factuur gevonden: `error` laat de job falen, `warn` waarschuwt alleen, `ignore` zegt niets.
json-file	–	Schrijft ook het volledige rapport als JSON naar dit pad.
summary	true	Zet de resultaten in de samenvatting van de job.
annotations	true	Toont elke fout als annotatie bij het bestand en de lijn (max. 50).

Outputs

Voor latere stappen in de workflow:

result: passed of failed
checked: aantal gecontroleerde facturen
failed: facturen met bevindingen vanaf het niveau van fail-on
errors: aantal fouten over alle facturen
warnings: aantal waarschuwingen over alle facturen
skipped: overgeslagen bestanden die geen factuur zijn
json-file: pad van het JSON-rapport

Opdrachtregel (CLI)

In de zip zit dezelfde controle als opdrachtregeltool, voor uw eigen computer of een andere CI (GitLab, Jenkins, Azure DevOps), met Node.js 20 of nieuwer:

node .github/actions/peppol-ubl-check/dist/cli.js "invoices/**/*.xml"
node .github/actions/peppol-ubl-check/dist/cli.js --json build/invoices > peppol-report.json

Exitcode 0: geen fouten; 1: fouten; 2: verkeerd gebruik of geen facturen gevonden. --help toont alle opties.

Een npm-pakket, zodat npx peppol-ubl-check werkt zonder download, staat gepland.

Niets verlaat uw runner. De Action maakt geen enkele netwerkverbinding: geen account, API-sleutel, analytics of telemetrie. Ze leest de bestanden die u aanwijst en schrijft de samenvatting, de annotaties en eventueel het JSON-rapport. De enige code van derden erin is de XML-lezer saxes.

Vragen

Is het echt gratis?

Ja. De Action heeft een MIT-licentie: u mag ze gebruiken in private en commerciële repositories, aanpassen en verspreiden. Er is geen betalende versie en geen gebruikslimiet, want er draait niets bij ons.

Worden mijn facturen ergens naartoe gestuurd?

Nee. De regels zitten in de Action zelf en draaien in uw runner. Facturen bevatten vaak namen, adressen en bankgegevens van klanten; die blijven waar ze zijn.

Wat is het verschil met de online validator?

Dezelfde regels en dezelfde oplossingen. De website geeft daarnaast een visueel rapport van één factuur (kop, partijen, lijnen, btw-overzicht, met de foute lijnen gemarkeerd) en leest Factur-X- en ZUGFeRD-pdf's. De Action is er om automatisch veel bestanden te controleren, bij elke wijziging.

Betekent een geslaagde controle dat Peppol de factuur aanvaardt?

Het is een sterk signaal, geen garantie. De 153 regels dekken de reken-, btw- en identificatiefouten waardoor facturen het vaakst geweigerd worden, maar ze zijn een gedeeltelijke versie van de officiële Schematron-regels, zonder XSD-schemavalidatie. Uw accesspoint valideert elke factuur tegen de volledige set voor ze vertrekt.

Waar staat ze op GitHub?

Op github.com/kalmwerk/peppol-ubl-check, met de releases en de changelog. Gebruik kalmwerk/peppol-ubl-check@v1; dat wijst altijd naar de nieuwste 1.x-release. De download blijft beschikbaar voor repositories die alleen lokale actions toelaten. Een vermelding in GitHub Marketplace volgt binnenkort.

Kan ik ze ook buiten GitHub gebruiken?

Ja. dist/cli.js uit de zip draait overal met Node.js 20 of nieuwer, eindigt met een foutcode bij fouten en kan hetzelfde JSON-rapport schrijven. Dat past in GitLab CI, Jenkins, Azure DevOps of een pre-commit hook.

Welke bestanden controleert ze?

UBL 2.1-facturen en -creditnota's (Peppol BIS Billing 3.0, XRechnung UBL, gewone EN 16931) en UN/CEFACT CII-XML. XML-bestanden die geen factuur zijn, worden overgeslagen, tenzij u non-invoice: fail instelt.