Pour les développeurs · GitHub Action et CLI

Sur GitHub dès maintenant ; bientôt sur GitHub Marketplace

Contrôle Peppol UBL : une GitHub Action gratuite pour vos factures électroniques

Name: Peppol UBL check
Author: Kalmwerk

Vérifiez les factures UBL / Peppol BIS Billing 3.0 que votre logiciel génère, à chaque push et pull request. En cas d’erreur, le job échoue et le résumé indique pour chacune l’identifiant de la règle, la ligne et la correction, avant qu’un point d’accès ne rejette la facture.

153 règles EN 16931, Peppol et XRechnung
Hors ligne, sans clé API
Licence MIT
Les mêmes règles que le validateur en ligne

Mise en place Voir sur GitHub Télécharger la v1.0.1 (.zip, 243 Ko)

Utilisez kalmwerk/peppol-ubl-check@v1 dans n’importe quel workflow, ou gardez une copie téléchargée dans votre dépôt. Dernière version sur GitHub

Aussi en:English Nederlands

Mise en place en deux étapes

Ajoutez un seul fichier de workflow. Rien à installer, pas de clé API.

1
Ajoutez le workflow
Enregistrez-le sous .github/workflows/peppol-ubl-check.yml et faites pointer files vers vos factures ou fichiers de test. Sans files, chaque fichier *.xml du dépôt est vérifié ; les fichiers XML qui ne sont pas des factures, comme un pom.xml, sont ignorés.
Enregistrer sous .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
Poussez
Le job échoue dès qu’une facture contient des erreurs. Le résumé du job liste chaque erreur avec la règle, la ligne et la correction, et les pull requests les affichent à côté du code.

Vous préférez une copie dans votre dépôt ?

Téléchargez le zip et décompressez-le dans .github/actions/, depuis la racine de votre dépôt :

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

Utilisez ensuite le chemin local dans le workflow :

Enregistrer sous .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"

Seuls action.yml et dist/ s’exécutent. Les factures de test du zip restent dans .github/, un dossier que le motif files par défaut ignore.

Téléchargement

peppol-ubl-check-1.0.1.zip

Version: 1.0.1
Taille: 243 Ko
Licence: MIT
Fonctionne sur: Tout runner GitHub, hébergé ou auto-hébergé ; Node.js 20+ pour la CLI
Contenu: Le code source complet : action.yml et dist/ (ce qui s’exécute : l’Action et la CLI, un fichier chacune), plus src/, les tests avec des factures d’exemple, les workflows CI, les exemples, le README, le changelog et les licences

Somme de contrôle SHA-256

db81eaa58507884dfaba61b26876d655b7e8f2c655d37e93a83de5d32e0abcd0

Vérifiez le zip avant de le committer :

Linux / macOS

sha256sum -c peppol-ubl-check-1.0.1.zip.sha256
# macOS
shasum -a 256 -c peppol-ubl-check-1.0.1.zip.sha256

Windows (PowerShell)

Get-FileHash peppol-ubl-check-1.0.1.zip -Algorithm SHA256

Fichier de contrôle (.sha256)

Sur GitHub

github.com/kalmwerk/peppol-ubl-check

Ce qu’affiche le résumé du job

Pour l’une de nos factures d’exemple volontairement erronées (une erreur de calcul de TVA), le résumé affiche notamment ceci. L’Action écrit en anglais ; chaque identifiant de règle renvoie à l’explication en français.

❌ invoices/2026-0918.xml

Règle	Ligne	Le problème	La correction
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.

…et 2 lignes de plus, sous un tableau récapitulatif avec une ligne par facture.

Ce qu’elle vérifie

101 règles métier EN 16931 : champs obligatoires, catégories et exonérations de TVA, calculs des lignes, des totaux et du récapitulatif TVA, listes de codes.
28 règles Peppol BIS Billing 3.0 : identifiants de spécification, référence acheteur, identifiants d’endpoint et numéros belges 0208, types de documents autorisés.
13 règles XRechnung, pour les fichiers qui déclarent XRechnung (ou avec profile: xrechnung).
11 contrôles supplémentaires : XML bien formé avec la ligne exacte, chiffres de contrôle des numéros de TVA et des numéros d’entreprise belges, IBAN, date d’échéance.

Ce qu’elle ne vérifie pas

L’intégralité des règles Schematron officielles : les 153 règles en sont une version partielle.
La validation par schéma XSD (ordre des éléments, éléments inconnus).
Le PDF/A et les PDF Factur-X / ZUGFeRD : elle ne lit que des fichiers XML.
Si l’acheteur peut recevoir des factures via Peppol : il faut pour cela une recherche sur le réseau.
Un contrôle réussi est un bon signal, pas une garantie : votre point d’accès valide encore chaque facture.

Entrées (inputs)

Toutes facultatives. Les valeurs par défaut conviennent à un dépôt qui contient des factures ou des fichiers de test.

Entrée	Par défaut	Rôle
files	*/.xml	Fichiers de factures, en motifs glob depuis la racine du dépôt, un par ligne ou séparés par des virgules. Un dossier signifie tous ses fichiers `*.xml` ; `!motif` exclut des fichiers.
ignore	–	Motifs glob à exclure, p. ex. `test/fixtures/broken/**`.
profile	peppol	`peppol` : règles Peppol et EN 16931 sur chaque fichier UBL. `auto` : choisit d’après le `CustomizationID` de chaque fichier. `en16931` ou `xrechnung` : toujours ces règles.
fail-on	error	`error` fait échouer le job en cas d’erreur, `warning` aussi en cas d’avertissement, `never` se contente de signaler.
non-invoice	skip	XML qui n’est pas une facture : `skip` l’ignore, `fail` le compte comme une erreur.
if-no-files-found	error	Aucune facture trouvée : `error` fait échouer le job, `warn` avertit seulement, `ignore` ne dit rien.
json-file	–	Écrit aussi le rapport complet en JSON à ce chemin.
summary	true	Affiche les résultats dans le résumé du job.
annotations	true	Annote chaque erreur sur son fichier et sa ligne (50 au maximum).

Sorties (outputs)

Pour les étapes suivantes du workflow :

result: passed ou failed
checked: nombre de factures vérifiées
failed: factures avec des constats au niveau de fail-on ou au-dessus
errors: nombre d’erreurs sur toutes les factures
warnings: nombre d’avertissements sur toutes les factures
skipped: fichiers ignorés qui ne sont pas des factures
json-file: chemin du rapport JSON

Ligne de commande (CLI)

Le zip contient le même contrôle sous forme d’outil en ligne de commande, pour votre machine ou une autre CI (GitLab, Jenkins, Azure DevOps), avec Node.js 20 ou plus récent :

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

Code de sortie 0 : pas d’erreur ; 1 : erreurs ; 2 : mauvaise utilisation ou aucune facture trouvée. --help liste toutes les options.

Un paquet npm, pour que npx peppol-ubl-check fonctionne sans téléchargement, est prévu.

Rien ne quitte votre runner. L’Action n’établit aucune connexion réseau : pas de compte, de clé API, d’analytics ni de télémétrie. Elle lit les fichiers que vous indiquez et écrit le résumé, les annotations et, si vous le souhaitez, le rapport JSON. Le seul code tiers qu’elle contient est le lecteur XML saxes.

Questions

Est-ce vraiment gratuit ?

Oui. L’Action est sous licence MIT : vous pouvez l’utiliser dans des dépôts privés et commerciaux, la modifier et la redistribuer. Il n’y a ni version payante ni limite d’utilisation, puisque rien ne tourne chez nous.

Mes factures sont-elles envoyées quelque part ?

Non. Les règles sont intégrées à l’Action et s’exécutent dans votre runner. Les factures contiennent souvent des noms, adresses et coordonnées bancaires de clients ; elles restent où elles sont.

Quelle différence avec le validateur en ligne ?

Les mêmes règles et les mêmes corrections. Le site ajoute un rapport visuel d’une facture (en-tête, parties, lignes, récapitulatif TVA, avec les lignes en erreur surlignées) et lit les PDF Factur-X et ZUGFeRD. L’Action sert à vérifier automatiquement beaucoup de fichiers, à chaque modification.

Un contrôle réussi garantit-il que Peppol acceptera la facture ?

C’est un bon signal, pas une garantie. Les 153 règles couvrent les erreurs de calcul, de TVA et d’identifiants qui font le plus souvent rejeter une facture, mais elles sont une version partielle des règles Schematron officielles, sans validation par schéma XSD. Votre point d’accès valide chaque facture avec l’ensemble complet avant l’envoi.

Où la trouver sur GitHub ?

Sur github.com/kalmwerk/peppol-ubl-check, avec ses versions publiées et son changelog. Utilisez kalmwerk/peppol-ubl-check@v1, qui pointe toujours vers la dernière version 1.x ; le téléchargement reste disponible pour les dépôts qui n’autorisent que des actions locales. Le référencement sur GitHub Marketplace arrive bientôt.

Puis-je l’utiliser en dehors de GitHub ?

Oui. dist/cli.js, dans le zip, fonctionne partout avec Node.js 20 ou plus récent, renvoie un code d’erreur en cas d’erreur et peut écrire le même rapport JSON. Il s’intègre à GitLab CI, Jenkins, Azure DevOps ou un hook pre-commit.

Quels fichiers vérifie-t-elle ?

Les factures et notes de crédit UBL 2.1 (Peppol BIS Billing 3.0, XRechnung UBL, EN 16931 simple) et le XML UN/CEFACT CII. Les fichiers XML qui ne sont pas des factures sont ignorés, sauf si vous définissez non-invoice: fail.