Valider et afficher XRechnung

Ironfang Finance valide les factures et avoirs XRechnung dans ses deux syntaxes, UBL 2.1 et UN/CEFACT CII, par rapport à la configuration officielle du validateur XRechnung, et les lit comme des documents. Essayez-le sans compte dans le validateur XRechnung et la visionneuse XRechnung, également en allemand.

Ce qui est contrôlé

Un document passe par ces étapes dans l'ordre. Une étape qui échoue arrête les suivantes, et le résultat indique que chacune n'a pas été atteinte plutôt que réussie.

Les règles sont la configuration officielle exécutée octet pour octet, avec les niveaux qu'elle fixe. Cette configuration abaisse certaines règles par rapport à leur propre indicateur, si bien qu'un constat porte les deux : severity, qui décide du résultat, et rule_flag, celui de la règle elle-même. Seuls les constats fatal (erreur) font échouer un document ; warning (avertissement) et information jamais.

Versions et variantes

• XRechnung 3.0.2, dans le paquet technique du 31 août 2026. Le résultat indique la version exacte dans ruleset.official_release et ruleset.technical_release.
• UBL 2.1 Invoice et CreditNote ; factures et avoirs CII, leur nature étant déterminée par le code de type.
• La variante de base (core). L'Extension et la variante CVD sont reconnues et refusées avec unsupported_variant, jamais contrôlées par rapport aux règles de base comme si elles étaient autre chose.
• XML uniquement. Un PDF, y compris ZUGFeRD et Factur-X, reçoit la réponse scope_unavailable.

Valider avec l'API

POST /finance/v2/einvoices/validate reçoit le XML comme corps de la requête. Indiquez la famille, comme le fait ce script, afin qu'un document qui ne déclare aucune famille soit tout de même contrôlé comme XRechnung et qu'un document qui en déclare une autre soit refusé avec ce qu'il déclare. Le script conserve le résultat dans result.json et dérive l'Idempotency-Key du fichier, si bien qu'une nouvelle tentative renvoie le premier résultat et n'est pas décomptée une seconde fois.

#!/usr/bin/env bash
# Validate one XRechnung with the Ironfang Finance API and keep the result.
#
#   IRONFANG_API_KEY=... ./validate-xrechnung.sh invoice.xml
#
# The result is written to 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="xr-$(sha256sum "$file" | cut -c1-40)"

curl --fail-with-body --silent --show-error \
  "$base/v2/einvoices/validate?family=xrechnung" \
  -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

Sans clé API, la même requête est anonyme : rien n'est conservé et des limites de débit plus strictes s'appliquent. Avec une clé, une validation terminée compte pour une opération de votre quota Finance, décomptée dès que le contrôle du schéma aboutit à un verdict, et le résultat est conservé 30 jours à l'adresse GET /finance/v2/einvoices/results/{id}. Le contrat complet est le document OpenAPI V2, et les différences entre V2 et V1 sont décrites dans le guide V1 et V2.

Lire un résultat

outcome vaut valid ou invalid pour une validation terminée ; tout ce qui a empêché un verdict, comme un dépassement de délai, est une réponse Problem avec outcome: indeterminate, et rien n'est décompté. coverage indique ce que le résultat établit : au niveau XML, le document XML et rien sur un PDF. Chaque constat porte son identifiant de règle inchangé, un message fixe pour son étape et un XPath dans location ; les textes officiels des règles ne sont pas repris, car ils peuvent contenir des valeurs de la facture. next_actions inclut view lorsque le document peut être ouvert dans la visionneuse.

Règles expliquées

Ces règles ont une explication relue, en anglais et en allemand, que les outils affichent à côté du constat. Chacune a été vérifiée auprès du validateur officiel avec un fichier de test qui l'enfreint.

Affichage

POST /tools/v2/invoice/view lit un document UBL ou CII dans le modèle invoice-view/2 : les parties, les lignes, la ventilation de la TVA, les totaux et les données de paiement du document, chaque valeur étant la chaîne exacte de la source, avec son chemin XML et sa ligne. Les dates CII sont lues d'après leur code de format ; une date dans un format qui ne peut pas être lu de façon sûre est conservée telle qu'écrite, avec une remarque. Un montant sans devise propre n'en a aucune : la devise du document n'est jamais supposée. Tout ce que le modèle n'affiche pas est compté dans unshown_elements, et les premiers éléments sont nommés dans des remarques, de sorte qu'une lecture partielle le signale. L'affichage ne valide jamais.

Réponses d'erreur