Serveur de validation MCP
Factur-X, ZUGFeRD & XRechnung

Valide une facture électronique (PDF ZUGFeRD/Factur-X ou XML XRechnung) selon la norme EN 16931 et les extensions allemandes. Renvoie des erreurs, avertissements et suggestions de correction structurés.

Schéma d'entrée

Schéma de sortie

{
  "valid":    true,
  "format":   "ZUGFeRD 2.x",
  "profile":  "EN16931",
  "container": "pdf",
  "syntax":   "CII",
  "summary":  "Keine Probleme gefunden",
  "errors":   [],
  "warnings": [],
  "notices":  [],
  "metadata": {
    "invoice_number": "RE-2026-001",
    "issue_date":     "2026-04-01",
    "seller":         "Musterfirma GmbH",
    "buyer":          "Beispiel AG",
    "total_amount":   "1190.00",
    "currency":       "EUR"
  }
}

{
  "valid":   false,
  "format":  "XRechnung 3.0",
  "profile": "XRECHNUNG",
  "summary": "1 Fehler, 1 Warnung gefunden",
  "errors": [
    {
      "severity":       "error",
      "rule_id":        "BR-DE-15",
      "field":          "BT-10",
      "message":        "Die Käuferreferenz / Leitweg-ID (BT-10) muss übermittelt werden.",
      "fix_suggestion": "Füge die Käuferreferenz / Leitweg-ID (BT-10) in 'ram:ApplicableHeaderTradeAgreement/ram:BuyerReference' ein.",
      "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
    }
  ],
  "warnings": [
    {
      "severity":       "warning",
      "rule_id":        "BR-DE-17",
      "field":          "BT-3",
      "message":        "Mit dem Element \"Invoice type code\" (BT-3) sollen ausschließlich folgende Codes aus der Codeliste UNTDID 1001 übermittelt werden: 326, 380, 384, 389 …",
      "fix_suggestion": "Bei einer Vorschussrechnung (386) ist die Warnung hinnehmbar: XRechnung empfiehlt den Code nicht, lässt ihn aber zu. Wer sie vermeiden will, nimmt 326 (Teilrechnung).",
      "xpath":          "//rsm:ExchangedDocument/ram:TypeCode"
    }
  ]
}

Champs de sortie

Extrait le document XML intégré d'un PDF ZUGFeRD/Factur-X. Renvoie le contenu XML complet sous forme de chaîne, avec le format et le profil détectés.

Entrée

Sortie

{
  "xml_content": "<?xml version='1.0' encoding='UTF-8'?>\n<rsm:CrossIndustryInvoice ...>...</rsm:CrossIndustryInvoice>",
  "format":      "ZUGFeRD 2.x",
  "profile":     "EN16931"
}

Vérifie que les données visibles par l'humain dans le PDF (numéro de facture, date, montant total) correspondent aux données machine stockées dans la pièce jointe XML. Révèle les manipulations ou erreurs de saisie.

Entrée

Sortie

{
  "consistent":    true,
  "discrepancies": []
}

{
  "consistent":    false,
  "discrepancies": [
    {
      "field":     "total_amount",
      "pdf_value": "1190.00",
      "xml_value": "1180.00",
      "message":   "Gesamtbetrag im PDF ('1190.00') unterscheidet sich von dem im XML ('1180.00')."
    }
  ]
}

Champs vérifiés & tolérances

Crée une facture électronique valide à partir de données structurées, au choix comme PDF ZUGFeRD (PDF/A-3 avec XML CII EN 16931 intégré) ou comme XML XRechnung pur (CII avec CIUS XRechnung 3.0 et Leitweg-ID pour le B2G). Plusieurs lignes, catégories de TVA S, Z, E, AE, K et G, débours sans TVA, remises et majorations, date ou période de prestation, montants déjà payés, références à des factures antérieures, pièces jointes, virement ou prélèvement SEPA. Sans état : rien n'est conservé, pièces jointes comprises. REST : POST /v1/create. Montants en centimes, date au format YYYY-MM-DD.

Entrée (extrait)

Sortie

{
  "format":     "zugferd",
  "profile":    "EN16931",
  "pdf_base64": "JVBERi0xLjc…",
  "xml":        "<?xml version=\"1.0\"…",
  "branding":   "free_footer"
}

xml est toujours joint, sauf via MCP pour une facture ZUGFeRD avec pièces jointes. extract_xml le tire alors du PDF.

Pièces jointes

Les pièces jointes figurent seulement dans le XML de la facture électronique (BT-125), pas en plus comme pièce jointe du PDF. Chaque fichier fait 5 Mo au plus, et tous ensemble 5 Mo au plus aussi, mesurés après décodage. Nous lisons le type à l'extension (.pdf, .png, .jpg, .jpeg, .csv, .xlsx, .ods) et le vérifions sur les premiers octets du fichier ; s'ils ne concordent pas, vous recevez 400. Un nom de fichier a jusqu'à 100 caractères, sans / ni \ et sans point au début ; deux noms qui ne diffèrent que par les majuscules et minuscules comptent comme identiques. description (BT-123) a 200 caractères au plus. content_base64 contient du Base64 pur ; nous retirons un préfixe data:…;base64,. Le Base64 grossit les fichiers d'un tiers : 5 Mo de pièces jointes donnent environ 7 Mo dans la requête, et la réponse les contient encore une fois dans la facture. Via MCP, envoyez donc de préférence de petites pièces jointes.

Profil d'émetteur

Ce qui manque dans la requête, nous le complétons à partir du profil d'émetteur de votre compte : tout le vendeur si seller manque (son numéro fiscal seulement si le profil n'a pas de numéro de TVA), ainsi que l'IBAN, le BIC, le titulaire du compte, les conditions de paiement, le logo et, pour un prélèvement, l'identifiant créancier. Ce que contient la requête l'emporte toujours. Vous gérez le profil dans votre compte ou via l'API : GET /v1/keys/issuer le lit, PUT /v1/keys/issuer l'enregistre, DELETE /v1/keys/issuer le supprime. Champs : name, street, zip, city, country, vat_id, tax_number, email, phone, contact_name, iban, bic, account_name, payment_terms, logo_b64, creditor_id. PUT ne modifie que les champs présents dans la requête ; une chaîne vide ou null efface un champ. PUT refuse avec 400 un numéro de TVA sans code pays, un numéro fiscal de forme incorrecte et un identifiant créancier invalide.

Erreurs

Nous répondons à une entrée invalide par 400 et { "error": "Ungültige Eingabe", "details": "…" }. Les erreurs de schéma indiquent le chemin et la raison, plusieurs séparées par des points-virgules. Les problèmes de contenu, comme un prélèvement sans référence de mandat, figurent en phrases entières dans details (en allemand), plusieurs séparées par des espaces. Une date qui n'a pas la forme YYYY-MM-DD nomme son champ, par exemple preceding_invoices[0].date (compté à partir de 0). Via MCP, les problèmes de contenu et les dates reviennent sous la forme du même objet. Les erreurs de schéma sont interceptées plus tôt par le protocole MCP lui-même : vous recevez une erreur d'outil (isError: true) avec le texte de la vérification du schéma, pas un objet avec error et details.

Afficher une facture sous forme lisible. Transforme une XRechnung (UBL ou CII), une facture CII ou un PDF Factur-X/ZUGFeRD en affichage lisible. Il repose sur la visualisation de la KoSIT (Apache 2.0), dans la version fournie avec Mustang 2.26.0. Aucune clé nécessaire ; l'affichage ne compte pas dans le quota de contrôles mais a sa propre limite journalière : 20 par adresse IP sans compte, 50 avec l'offre gratuite, 500 avec Automatiser, 2 000 avec Scaler (sinon 429). Rien n'est enregistré ni journalisé. Comme outil MCP : view_invoice.

Champs

Réponse : readable, html, format, profile, syntax, attachments (nom, type, taille, Base64), check (valide, nombre d'erreurs et d'avertissements, premiers messages) et limit. Le HTML est nettoyé : pas de script, pas de gestionnaires d'événements, pas de liens avec cible, pas d'images ni de formulaires, plus une Content Security Policy. Affichez-le tout de même uniquement dans un <iframe sandbox> sans droits, et enregistrez les pièces jointes comme fichiers au lieu de les ouvrir dans le navigateur. Si le fichier ne peut pas être affiché, readable vaut false et check en donne la raison ; un PDF sans facture électronique donne 422.

Vérifier un Leitweg-ID. Vérifie la structure, le code (Land 01 à 16, État fédéral 99) et les chiffres de contrôle (modulo 97-10) selon la spécification de format 2.0.2 de la KoSIT. Si les chiffres de contrôle sont faux ou manquent, la réponse donne l'identifiant correspondant dans corrected_id. Elle ne dit pas si l'identifiant est attribué ; il n'existe pas d'annuaire public. Sans clé, sans quota, 120 appels par minute au plus (sinon 429). Rien n'est enregistré. Outil MCP : check_leitweg_id.

Champs

Réponse (200, aussi pour un identifiant invalide) : valid, leitweg_id (forme normalisée), parts (coarse, fine, check_digits), region, expected_check_digits, corrected_id, errors et warnings (chacun code et message), notice. Faites confirmer un identifiant proposé par le donneur d'ordre avant de l'utiliser.

Contrôle par lot sur le serveur. Pour de nombreuses factures à la fois, sans que votre programme ou navigateur reste connecté tout le temps : téléverser les fichiers, lancer, récupérer les résultats plus tard. À partir de l'offre Automatiser. Les factures restent chiffrées sur notre serveur en Allemagne jusqu'au contrôle et sont supprimées juste après. Les résultats restent sept jours, puis nous les supprimons. Quand tout est terminé, un e-mail part à l'adresse du compte. Dans un compte d'entreprise, le titulaire peut désactiver cette option pour les autres accès (PATCH /v1/org/settings avec { "stapel_ablage": false }).

Appels

Chaque fichier compte dans le quota hebdomadaire. S'il est épuisé, le lot s'arrête (status: "angehalten", grund: "kontingent") ; les fichiers restants ne sont pas contrôlés et sont supprimés. Le serveur traite ces lots uniquement sur les places libres à ce moment ; les contrôles directs passent en premier.

Renvoie le résultat du contrôle sous forme de rapport de validation au format PDF/A-3b, prêt à archiver et à transmettre. Le rapport indique le résultat, chaque message avec son identifiant de règle et son champ, la date du contrôle, le format et le profil reconnus, l’empreinte SHA-256 du fichier contrôlé et le jeu de règles, c’est-à-dire les versions des outils utilisés. Chaque appel effectue un nouveau contrôle et compte dans le quota hebdomadaire comme une validation. Disponible comme outil MCP validation_report et via REST avec POST /v1/report.

Entrée

Sortie

Content-Type: application/pdf
Content-Disposition: attachment; filename="rapport-validation-facture.pdf"
X-Validation-Result: valid | invalid

Exemple

curl -X POST https://api.zugferd-validator.de/v1/report \
  -H "X-Api-Key: $ZV_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_content\": \"$(base64 -w0 rechnung.pdf)\", \"file_type\": \"pdf\", \"attach_source\": true}" \
  -o bericht.pdf