{
  "openapi": "3.1.0",
  "info": {
    "title": "API Vérifier Factur-X",
    "version": "1.0.0",
    "description": "Valide une facture électronique (PDF Factur-X / ZUGFeRD, XML CII ou UBL, XRechnung, Peppol, FatturaPA, Facturae, ebInterface, KSeF, Finvoice, messages CDAR) avec les règles officielles : XSD, schématrons EN 16931, règles françaises BR-FR (FNFE-MPE), XRechnung (KoSIT), Peppol BIS 3.0… Le fichier n'est pas conservé.",
    "contact": { "email": "contact@verifier-factur-x.com", "url": "https://verifier-factur-x.com/api-factur-x/" }
  },
  "servers": [{ "url": "https://verifier-factur-x.com/api" }],
  "security": [{ "cle": [] }],
  "components": {
    "securitySchemes": { "cle": { "type": "http", "scheme": "bearer", "description": "Clé vfx_… créée sur https://verifier-factur-x.com/espace/" } },
    "schemas": {
      "Erreur": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "example": "BR-FR-10" },
          "regle": { "type": "string" },
          "identifiant": { "type": "string", "example": "BR-FR-10_BT-30" },
          "gravite": { "type": "string", "enum": ["bloquant", "avertissement", "information"] },
          "etape": { "type": "string", "enum": ["fichier", "pdf", "xsd", "profil", "norme", "france", "national"] },
          "titre": { "type": "string", "description": "Titre en français clair" },
          "message_officiel": { "type": "string", "description": "Message d'origine du composant officiel (fait foi)" },
          "explication": { "type": ["string", "null"] },
          "correction": { "type": ["string", "null"] },
          "emplacement": { "type": ["string", "null"], "example": "Vendeur › Immatriculation (BT-30)" },
          "ligne": { "type": ["integer", "null"] },
          "xpath": { "type": ["string", "null"] },
          "occurrences": { "type": "integer" },
          "bloquante_le": { "type": ["string", "null"], "format": "date" },
          "fiche": { "type": ["string", "null"], "format": "uri" }
        }
      },
      "Resultat": {
        "type": "object",
        "properties": {
          "verdict": { "type": "string", "enum": ["conforme", "reserves", "non-conforme", "pas-facture-electronique", "illisible"] },
          "resume": { "type": "string" },
          "fichier": { "type": "object", "properties": { "nom": { "type": "string" }, "taille": { "type": "integer" }, "type": { "type": "string" }, "sha256": { "type": "string" } } },
          "syntaxe": { "type": ["string", "null"], "example": "CII" },
          "profil": { "type": ["object", "null"], "properties": { "code": { "type": "string" }, "libelle": { "type": "string" }, "identifiant": { "type": ["string", "null"] }, "reforme": { "type": "string" } } },
          "regles_appliquees": { "type": ["string", "null"], "example": "FR" },
          "controles": { "type": "array", "items": { "type": "object" } },
          "erreurs": { "type": "array", "items": { "$ref": "#/components/schemas/Erreur" } },
          "facture": { "type": ["object", "null"], "description": "La facture lue : numéro, date, parties, totaux, lignes, TVA" },
          "composants": { "type": "array", "items": { "type": "string" }, "description": "Versions exactes des règles appliquées" },
          "duree_ms": { "type": "integer" },
          "date": { "type": "string", "format": "date-time" }
        }
      }
    }
  },
  "paths": {
    "/v1/valider": {
      "post": {
        "summary": "Valider une facture",
        "parameters": [
          { "name": "regles", "in": "query", "schema": { "type": "string", "enum": ["auto", "FR", "DE", "PEPPOL", "NL", "RO", "BE", "EN16931"], "default": "auto" }, "description": "Jeu de règles pour les factures EN 16931 (CII, UBL). auto = d'après l'identifiant de profil." },
          { "name": "nom", "in": "query", "schema": { "type": "string" }, "description": "Nom du fichier, repris dans le résultat." }
        ],
        "requestBody": {
          "required": true,
          "description": "Le fichier brut, 25 Mo au plus.",
          "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/xml": { "schema": { "type": "string" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }
        },
        "responses": {
          "200": { "description": "Résultat du contrôle (même pour une facture non conforme)", "headers": { "x-quota-limite": { "schema": { "type": "integer" } }, "x-quota-restant": { "schema": { "type": "integer" } }, "x-quota-offre": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resultat" } } } },
          "400": { "description": "Paramètre invalide ou corps vide" },
          "401": { "description": "Clé absente ou invalide" },
          "413": { "description": "Fichier de plus de 25 Mo" },
          "429": { "description": "Quota mensuel atteint" },
          "502": { "description": "Service de validation injoignable (l'appel n'est pas décompté)" }
        }
      }
    }
  }
}