Valider, comprendre, corriger

Ironfang Finance vérifie les factures électroniques structurées, qu'il s'agisse de Factur-X / ZUGFeRD, de Peppol ou de XRechnung, selon les règles exactes publiées pour leur format, et signale chaque constat avec l'identifiant d'origine de sa règle. Essayez-le dans le navigateur sans compte, ou lancez les mêmes contrôles depuis votre propre code.

Vous découvrez les formats de facture électronique et leurs règles ? Explorez l'espace d'apprentissage de la facturation électronique pour les bases, des parcours guidés et les validateurs gratuits.

Choisir votre format

Chaque format est vérifié de la même façon : le document passe ses étapes dans l'ordre, chaque résultat nomme le jeu de règles utilisé, et une défaillance du service n'est jamais présentée comme une facture non valide. Ce que vous soumettez, et ce que couvrent les contrôles, dépend du format.

L'API valide Peppol via V1 ou V2, et XRechnung et ZUGFeRD / Factur-X via V2 ; le guide V1 et V2 indique quelle version sert quoi et en quoi leurs résultats diffèrent.

Essayer dans le navigateur

Chaque validateur gratuit fonctionne dans le navigateur sans compte. Les documents et résultats anonymes ne sont pas conservés.

1. Ouvrez le validateur de votre format, puis essayez son exemple ou importez votre propre document.
2. Lisez le verdict et chaque étape. Une défaillance du service n'est pas une facture non valide.
3. Suivez l'explication d'une règle quand elle existe, corrigez votre document source et validez-le à nouveau.

Ouvrir le validateur PeppolVoir un exemple de facture complet

Autres formats : XRechnung ou ZUGFeRD / Factur-X, chacun aussi en allemand. Le validateur Peppol télécharge aussi le résultat en JSON et sous forme de rapport lisible, que vous pouvez imprimer ou enregistrer en PDF.

L'exemple de facture XML Peppol parcourt un exemple valide champ par champ, rapproche ses totaux et montre une copie défectueuse avec ses deux constats et la correction. Pour lire une facture plutôt que la vérifier, la visionneuse de factures XML gratuite ouvre une facture ou un avoir UBL sous forme de document lisible, et la visionneuse XRechnung fait de même pour XRechnung en UBL ou CII.

Valider depuis votre code

Ce démarrage rapide valide l'exemple de facture Peppol BIS Billing 3 publié via la version 2 de l'API Finance et conserve le résultat. Il vous faut bash, curl et sha256sum, ainsi qu'un compte Ironfang gratuit.

1. Créer une clé API avec sa portée

Dans le portail (en anglais), ouvrez Developers, API keys et créez une clé avec la portée Validate and generate e-invoices, finance:einvoices:write. Le secret n'est affiché qu'une fois. Conservez-le dans la variable d'environnement IRONFANG_API_KEY, jamais dans un script ni dans un dépôt. Pas encore de compte ? Créez-en un gratuitement.

2. Télécharger l'exemple de facture

L'exemple de facture est une facture Peppol BIS Billing 3 complète et fictive en UBL, celle que propose le validateur Peppol :

curl --fail --silent --show-error --output invoice.xml https://ironfang.uk/samples/peppol-bis-billing-3-invoice-v1.xml

3. La valider

Enregistrez ce script sous validate-peppol.sh et lancez bash validate-peppol.sh invoice.xml. Il nomme la famille, si bien qu'un document qui en déclare une autre est refusé au lieu d'être vérifié comme autre chose, et il dérive l'Idempotency-Key du fichier, si bien qu'une nouvelle tentative renvoie le premier résultat et n'est pas facturée une seconde fois.

#!/usr/bin/env bash
# Validate one Peppol BIS Billing 3 invoice with the Ironfang Finance API
# (V2) and keep the result.
#
#   IRONFANG_API_KEY=... ./validate-peppol.sh invoice.xml
#
# The result is written to result.json. A completed validation exits 0 and
# prints its outcome, valid or invalid. A request or service problem exits
# non-zero and leaves the Problem in result.json. A retry with the same file
# sends the same Idempotency-Key, so it returns the first result and is not
# charged again.
set -euo pipefail
file="$1"
base="${IRONFANG_FINANCE_API:-https://api.ironfang.uk/finance}"
key="peppol-$(sha256sum "$file" | cut -c1-40)"

curl --fail-with-body --silent --show-error \
  "$base/v2/einvoices/validate?family=peppol-bis-billing-3" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: $key" \
  --data-binary "@$file" \
  --output result.json

grep -o '"outcome":"[a-z]*"' result.json | head -n 1

4. Lire la réponse

Le script affiche "outcome":"valid" et conserve le résultat complet dans result.json. En version abrégée, sans les moteurs ni les durées :

{
  "schema": "ironfang/finance/einvoice/validation-result/v2",
  "operation_id": "01929a8e-0000-7000-8000-000000000000",
  "status": "completed",
  "outcome": "valid",
  "input": {
    "media_type": "application/xml",
    "document_type": "invoice"
  },
  "ruleset": {
    "requested": "latest",
    "id": "fwrs_pub_invoice_2026_5",
    "family": "peppol-bis-billing-3",
    "selection_method": "latest",
    "official_release": "2026.5 (May 2026 release, aka BIS Billing 3.0.21)"
  },
  "coverage": {"scope": "xml", "checked": ["input", "xml", "xsd", "en16931", "peppol"], "not_checked": []},
  "layers": [
    {"layer": "input", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "xml", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "xsd", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "en16931", "status": "passed", "fatal": 0, "warning": 0, "information": 0},
    {"layer": "peppol", "status": "passed", "fatal": 0, "warning": 0, "information": 0}
  ],
  "counts": {"by_severity": {"fatal": 0, "warning": 0, "information": 0}},
  "findings": [],
  "usage": {"charged": true, "credits": 1}
}

ruleset nomme la version exacte qui a vérifié le document, layers rend compte de chaque contrôle dans l'ordre et usage indique la validation décomptée de votre quota. Un résultat obtenu avec un compte est conservé 30 jours à l'adresse GET /finance/v2/einvoices/results/{id}, où l'id est son operation_id.

Valide, non valide ou aucun verdict

• Valide : HTTP 200, status completed, outcome valid. Des avertissements peuvent encore figurer ; ils ne font jamais échouer un document.
• Non valide : HTTP 200, status completed, outcome invalid. Chaque entrée de findings indique l'id de sa règle, son étape, sa gravité et son emplacement, et counts.by_severity.fatal est supérieur à zéro. Corrigez le document source et validez à nouveau ; la référence des règles explique les règles courantes.
• Aucun verdict : tout autre statut est un Problem (application/problem+json) avec un code. Le script se termine avec un code de sortie non nul et le conserve dans result.json. Un 4xx concerne la requête ou le compte, par exemple la clé, la taille, la famille ou le type de document : corrigez-le avant de réessayer, ou, pour un 429, attendez la levée de la limite. validator_unavailable, validation_timeout et internal_error portent outcome indeterminate : rien n'a été établi, rien n'est facturé, et la même requête peut être relancée.

Et ensuite

XRechnung et ZUGFeRD / Factur-X utilisent la même route avec leur propre famille : la section API du guide XRechnung et la section API du guide Factur-X / ZUGFeRD ont chacune un script testé, celui de ZUGFeRD pour les PDF comme pour le XML. Le contrat OpenAPI V2 décrit chaque paramètre et chaque champ, et la référence de l'API ci-dessous liste les portées et les endpoints.

Résultats et règles

Un résultat rend compte de chaque étape dans l'ordre. Une condition préalable non remplie laisse les étapes suivantes non exécutées plutôt que réussies. Seuls les constats fatals font échouer un document ; les avertissements restent visibles même quand le verdict est valide. Les règles officielles décident de la validité, et la validation ne répare jamais votre XML.

La référence des règles de validation explique 142 règles, une page chacune : ce qui a échoué, les causes probables, la correction, et un exemple avant et après tiré de documents passés par le même moteur que le validateur. Cherchez une règle par son code, par un terme métier comme BT-106 ou par un élément XML. Les règles sans explication gardent le constat et l'identifiant du moteur ; les constats du validateur renvoient à une explication chaque fois qu'il en existe une.

Quelques points de départ :

• BR-01: L'identifiant de spécification est absent

  Les documents Invoice et CreditNote doivent comporter un élément CustomizationID non vide qui identifie leur spécification.

• BR-CO-10: Les montants des lignes ne correspondent pas au total

  Le total des lignes au niveau du document doit être égal à la somme des montants nets des lignes individuelles.

• BR-CO-13: Le total hors TVA n'est pas cohérent

  Le total hors TVA part du total des lignes, soustrait les remises au niveau du document et ajoute les frais au niveau du document.

• BR-S-08: La base imposable au taux normal ne correspond pas au document

  Pour chaque taux normal, la base imposable de la ventilation doit correspondre aux montants des lignes au taux normal, plus les frais et moins les remises au niveau du document à ce taux.

• PEPPOL-EN16931-R004: Vérifier l'identifiant de spécification Billing

  Cette règle contrôle le préfixe de l'identifiant Peppol Billing et rejette une suite de deux deux-points dans l'identifiant.

• PEPPOL-EN16931-R020: Ajouter l'adresse électronique du vendeur

  L'élément Party du vendeur doit contenir un EndpointID. Cette règle vérifie sa présence ; d'autres règles vérifient son schéma et sa valeur.

• PEPPOL-EN16931-R120: Le montant net de la ligne ne correspond pas à la quantité et au prix

  Chaque montant net de ligne doit être égal à la quantité multipliée par le prix net divisé par la quantité de base du prix, plus les frais de la ligne, moins les remises de la ligne, à 0.02 près.

• FW-XML-001: Le XML n'a pas pu être lu en toute sécurité

  Le document contient du XML mal formé, un encodage non pris en charge ou une construction XML interdite. Aucune étape de validation ultérieure ne peut s'exécuter tant que ce n'est pas corrigé.

Au-delà d'une validation

Une fois la validation lancée depuis votre code, ces fonctions s'appuient dessus.

Génération

La génération crée du Peppol BIS Billing 3 UBL, une facture ou un avoir, à partir de JSON structuré au format generation-input/v1. Elle ne crée pas de documents XRechnung ni ZUGFeRD / Factur-X. Les octets finaux exacts doivent passer le validateur de production choisi avant d'être renvoyés, encodés en base64 avec leur SHA-256 ; en cas d'échec, aucune facture n'est renvoyée, et Ironfang Finance ne contourne jamais une règle pour faire passer une facture. Le playground JSON de factures permet de l'essayer dans le navigateur, et le guide de la génération présente le schéma et quatre démarrages rapides exécutables. Générer via un compte nécessite une offre payante.

Tâches et lots

Les endpoints de tâches et de lots acceptent une validation ou une génération avec une clé d'écriture Ironfang Finance, renvoient un identifiant de tâche à interroger et conservent le jeu de règles choisi d'une tentative à l'autre. Les clés de lecture récupèrent les métadonnées et les résultats terminés. L'annulation conserve le travail déjà terminé. Une validation terminée est valide ou non valide ; les défaillances du service restent sans verdict (indeterminate) et ne sont pas facturées. Les tâches durables utilisent les mêmes moteurs, ne transmettent pas de factures et n'ajoutent aucune certification juridique.

Webhooks et livraison

Les comptes peuvent configurer des webhooks d'événements signés et la livraison d'artefacts vers un stockage compatible S3 comme destinations distinctes. Chaque destination a son propre historique de nouvelles tentatives ; un échec de livraison ne change pas un verdict et ne facture pas une autre validation. Vérifiez les signatures des webhooks et dédupliquez les identifiants d'événements côté récepteur.

La qualification S3 couvre SeaweedFS 4.46 dans la configuration testée ; les autres fournisseurs demandent leurs propres vérifications. Les PDF et les ZIP de rapports signés ne sont pas exportés automatiquement. La livraison vers votre endpoint ou votre bucket ne prouve ni l'acceptation par le destinataire, ni l'intégration en comptabilité, ni le paiement, et n'envoie pas la facture sur Peppol.

Résultats enregistrés et confidentialité

Les documents et résultats anonymes sont traités de façon transitoire. Avec un compte ou une clé API, le JSON du résultat et les constats sont conservés 30 jours, et vous pouvez les supprimer plus tôt. La validation synchrone ne conserve pas le document importé. Les tâches API durables conservent l'entrée chiffrée jusqu'à leur achèvement, leur annulation ou leur nettoyage à l'expiration de 24 heures. Les sauvegardes suivent leur propre politique de conservation. Le XML généré avec authentification est conservé avec son résultat pendant 30 jours. Les copies téléchargées restent sous votre contrôle.

Après suppression ou expiration, un petit enregistrement de l'opération conserve les empreintes, le jeu de règles, l'issue, les horodatages et les métadonnées d'utilisation jusqu'à l'effacement de l'organisation. Cela empêche une ancienne tentative d'être exécutée ou facturée à nouveau : réutiliser son Idempotency-Key renvoie 410 result_gone ; ne demandez donc une nouvelle validation avec une nouvelle Idempotency-Key que si c'est bien votre intention. Les rapports signés transforment un résultat conservé en preuve vérifiable.

Chaîne de validation Peppol

Comment un document Peppol BIS Billing 3 est vérifié. UBL est la syntaxe du document XML, EN 16931 définit la sémantique de base d'une facture électronique, et Peppol BIS Billing y ajoute ses règles d'usage. Ironfang Finance envoie les octets XML fournis à son service Java auto-hébergé, où PHIVE exécute les artefacts de validation enregistrés, publiés en amont, en utilisant Saxon pour leurs contrôles XSLT. XRechnung et ZUGFeRD / Factur-X passent par leurs propres étapes, décrites dans leurs guides.

1. XML bien formé : le document doit pouvoir être analysé sans risque. Un XML mal formé se distingue d'un échec de règle métier.
2. Schéma UBL : l'Invoice ou la CreditNote doit avoir la structure et les types de données que définit son schéma UBL.
3. EN 16931 : les artefacts publiés en amont vérifient les règles sémantiques et de calcul applicables.
4. Peppol : les artefacts BIS Billing publiés en amont vérifient les règles de profil et d'usage applicables.
5. Défaillances du service : les délais dépassés, les validateurs indisponibles et les erreurs internes restent sans verdict. Ils n'établissent pas si la facture est valide.

Quelles versions ont vérifié mon document ?

Chaque résultat nomme son jeu de règles et son moteur exacts. Le registre des jeux de règles en direct liste les VESID, les types de document, les versions des spécifications, les sommes de contrôle et les dates du cycle de vie. Les validateurs plus récents fournissent aussi un objet d'exécution avec les versions du validateur, de PHIVE, de phive-rules, de phive-rules-peppol et de Saxon, le nom VES amont et le statut de dépréciation.

Les métadonnées d'exécution sont une observation vérifiée à l'instant observed_at, pas une garantie de disponibilité en direct. Les validateurs conservés plus anciens peuvent les omettre. Les versions des bibliothèques et les versions des spécifications sont des identités distinctes ; une date de validité amont n'est incluse que si PHIVE en fournit une. Le libellé de cycle de vie sendable du registre sélectionne la version active pour latest ; il ne signifie pas qu'Ironfang Finance peut envoyer une facture.

Les normes, jeux de règles et bibliothèques open source derrière chaque contrôle, avec leurs licences et l'endroit où leur code source est publié, sont listés dans Licences et remerciements.

Référence de l'API

Envoyez la clé API de la plateforme comme jeton Bearer. Validez avec POST /finance/v2/einvoices/validate, pour tous les formats, ou POST /finance/v1/einvoices/validate, pour Peppol. La validation, la génération et la suppression nécessitent finance:einvoices:write ; la lecture des résultats nécessite finance:einvoices:read ; la lecture authentifiée des jeux de règles nécessite finance:einvoices:rulesets:read. V1 liste ses résultats sous /finance/v1/einvoices/results et en lit ou supprime un par identifiant d'opération ; V2 liste ensemble les résultats V1 et V2, comme l'explique le guide V1 et V2. Le serveur MCP Ironfang propose 3 outils Ironfang Finance. Référence uniquement : ce que signifie une règle de validation et comment la corriger, et quels jeux de règles le validateur exécute. La validation et la génération de documents, les résultats et les tâches passent uniquement par REST ; l'API Ironfang Finance accepte une clé API de la plateforme et n'a pas encore de délégation OAuth.

Contrat OpenAPI V2 - Contrat OpenAPI V1 - Clés API et exemples d'intégration - Politique de confidentialité

Exécuter dans PostmanVoir la collection

La collection est générée à partir du contrat OpenAPI et commence par trois requêtes qui ne demandent aucun identifiant : lister les jeux de règles, valider un exemple de facture et en générer une à partir de JSON. Vous pouvez aussi la télécharger. Conservez les clés API dans un environnement privé ou un coffre-fort, et choisissez les fichiers de factures que vous comptez envoyer.

SDK et offres

SDK, CLI et GitHub Action

Les SDK de validation Python et TypeScript, une CLI Python et la GitHub Action officielle sont publiés publiquement en v0.2.0. Ils couvrent la validation d'Invoice et de CreditNote selon un jeu de règles choisi via V1, et via V2 Peppol BIS Billing 3, XRechnung et ZUGFeRD / Factur-X en XML ou en PDF hybride, avec les tâches, lots et livraisons de V2, et des issues distinctes pour les documents valides, les documents non valides et les défaillances du service. Les instructions d'installation et la référence publique épinglée de l'Action se trouvent dans le guide d'intégration (en anglais). Installez TypeScript depuis npm ou téléchargez la version Python depuis GitHub.

Offres gratuite et payantes

Les comptes gratuits incluent 250 validations par mois civil UTC, sans carte bancaire. La génération authentifiée nécessite un abonnement payant Build, Pro ou Platform. Les offres payantes partagent un seul quota entre validation et génération, qui suit la période d'abonnement mensuelle. Comparez les prix et quotas actuels.

Les offres payantes s'adressent aux entreprises du Royaume-Uni et de l'UE, y compris les entrepreneurs individuels. Le numéro de TVA britannique est facultatif. Le paiement automatique dans l'UE exige un numéro de TVA vérifié et des informations d'entreprise concordantes ; les entreprises sans numéro de TVA, ou dont les informations vérifiées doivent être examinées, doivent être approuvées avant le paiement. Saisissez les informations de votre entreprise, demandez l'examen et choisissez une offre dans le portail de facturation (en anglais).

Une validation terminée compte même si elle trouve des erreurs dans la facture ; une génération réussie compte une fois. Le travail en cours réserve du quota. Les téléchargements et les relances idempotentes n'ajoutent aucune utilisation. Les requêtes mal formées et les défaillances du service ne consomment pas de quota. Le plafond bloque les nouvelles opérations du compte jusqu'à ce que de la capacité se libère, que votre période se renouvelle ou que vous passiez à une offre supérieure ; aucun dépassement n'est facturé automatiquement.

Les validateurs anonymes et le playground JSON restent gratuits, avec des limites de requêtes et de débit. L'usage anonyme n'a ni historique enregistré ni quota de compte. Les abonnements, les moyens de paiement et l'historique de facturation d'Ironfang Finance sont distincts de ceux d'Ironfang Render et d'Ironfang Audit.

Limites des requêtes

Le XML et le JSON de génération sont limités à 5 Mio, et une validation XML dispose d'un délai de 10 secondes. Un PDF hybride a ses propres limites, plus élevées, et un délai plus long, décrits dans le guide Factur-X / ZUGFeRD. Un résultat renvoie au plus 1 000 constats en ligne : examinez le nombre de constats et les indicateurs de troncature, car une liste raccourcie n'est pas un audit complet. Les limites de débit renvoient HTTP 429 ; respectez Retry-After lorsqu'il est fourni. Les contrats OpenAPI précisent les limites des entrées et des champs.

Ce qu'un résultat valide n'établit pas

• Il ne transmet pas la facture sur le réseau Peppol.
• Il ne fait pas d'Ironfang un point d'accès Peppol (Access Point).
• Il n'enregistre pas de participant Peppol et ne prouve pas son enregistrement.
• Il ne certifie pas la conformité juridique ou fiscale.
• Il ne garantit pas qu'un destinataire acceptera, comptabilisera ou paiera la facture.

Un résultat valide signifie que ces octets ont passé le jeu de règles pris en charge sélectionné. Les exigences du destinataire, le contexte métier et les questions juridiques ou fiscales demandent un examen distinct.