API-Referenz

Clés publiques de vérification des packs

Les clés publiques Ed25519 au format JWKS, actives et révoquées. Elles permettent de vérifier un pack de preuve hors ligne, sans nous appeler. Une clé révoquée n'est jamais retirée d'ici : elle vit aussi longtemps que les packs qu'elle a signés, sans quoi ce qu'elle a scellé deviendrait invérifiable.

Convertir entre les formats du socle

Deux cibles, et rien d'autre. `to=cii` extrait le XML d'un conteneur Factur-X ; `to=facturx` attache un XML CII au PDF lisible que vous fournissez dans `visual`. **Le XML n'est jamais relu ni resérialisé** : il est rattaché octet pour octet, et le conteneur produit est relu après coup pour le vérifier. Si le XML relu ne correspond pas, rien n'est rendu — nous préférons un refus à un document dont nous ne pouvons pas garantir le contenu. Deux refus assumés. **Depuis ou vers l'UBL** : la correspondance sémantique champ par champ entre les deux vocabulaires n'existe pas vérifiée, et l'approximer produirait des factures syntaxiquement valides et sémantiquement fausses. **Sans `visual`** : un Factur-X est un PDF qu'un humain lit et un XML qu'une machine lit, et la réglementation exige qu'ils disent la même chose. Nous ne mettons pas votre facture en page à votre place.

Vérifier et compléter les données de tiers

Confronte les tiers de la facture aux référentiels publics : numéro de TVA intracommunautaire auprès de VIES, immatriculation et adresse auprès des annuaires d'entreprises et de la base adresse nationale. **Tout enrichissement est sourcé.** Chaque valeur ajoutée porte son référentiel, l'horodatage de l'interrogation et la valeur précédente : un enrichissement qu'on ne peut pas retracer ne vaut pas mieux qu'une saisie. Les référentiels publics tombent. Une interrogation qui échoue n'est pas convertie en absence de donnée : le champ sort avec son drapeau, et le reste du traitement continue.

Sceller un pack de preuve

Valide le document et scelle le tout — verdict, jeu de règles, empreintes des artefacts, horodatage — dans un pack signé en Ed25519. Le pack est autoportant : il contient de quoi rejouer le raisonnement sans nous interroger. **La facture elle-même n'est pas dans le pack**, seulement son empreinte. Le document n'est pas conservé, ici pas plus qu'ailleurs. `pinned` vaut vrai par défaut sur cet endpoint, à l'inverse de la validation : un pack de preuve rendu contre des Schematron non épinglés ne prouverait pas grand-chose.

Vérifier un sceau

Confronte un pack à la clé publique qui l'a signé et dit s'il est intact. Gratuit et sans clé : la vérification ne nous transmet aucun document et ne demande aucune confiance, donc elle ne se paye pas. Les clés publiques, actives et révoquées, sont publiées en JWKS sur `/.well-known/evidence-jwks.json` : un destinataire peut vérifier un pack sans nous appeler du tout. Une clé révoquée reste publiée aussi longtemps que les packs qu'elle a signés — la retirer rendrait invérifiable ce qu'elle a scellé.

Relire un pack scellé

Rend un pack déjà scellé, tel qu'il a été signé. Ce que nous conservons est le pack, jamais la facture qui l'a produit.

Corriger les anomalies structurelles

Corrige ce qui se corrige sans rien inventer, revalide le résultat et rend le document modifié avec le détail de chaque écriture : code de règle, XPath, valeur avant, valeur après. Toute correction est réversible et tracée. **Un champ financier n'est jamais écrit.** Montants, taux et bases de TVA, IBAN et coordonnées de paiement sont refusés à l'écriture même demandés explicitement : la valeur calculée sort en `suggested_value` et le constat en `blocked`. C'est une règle produit, pas une limite technique — écrire un montant à la place de l'émetteur engagerait sa facture. Une donnée que seul l'émetteur possède ne s'invente pas davantage : le constat sort en `needs_input` avec son emplacement. Pour la fournir, reprenez le diagnostic sur `/v1/fix-with-input` avec le `flow_id` rendu ici.

Reprendre une correction avec les valeurs de l'émetteur

Reprend un diagnostic `/v1/fix` en y ajoutant les valeurs que seul l'émetteur possède. Le service rejoue les corrections automatiques sur le document d'origine, applique les valeurs autorisées, puis revalide. Trois verrous, cumulatifs. Le code doit figurer dans le verdict initial avec `resolution: "input"` ; il doit appartenir à la liste blanche d'emplacements que le serveur sait écrire sans ambiguïté — aujourd'hui `BR-02` (BT-1, numéro de facture) et `PEPPOL-EN16931-R001` (BT-23, processus métier sous forme d'URN), tout autre code recevant `input_not_supported` plutôt qu'une écriture approximative ; et l'emplacement visé repasse par la politique des champs financiers. **Rien du document n'est conservé entre les deux appels.** Le `flow_id` ne retient que l'empreinte : renvoyez le fichier d'origine octet pour octet. Un autre fichier reçoit 409, un flux expiré 410. `inputs` est une partie multipart JSON : un tableau de `{"code","value"}`, vingt au maximum.

Lister les juridictions suivies

Les pays suivis, avec pour chacun son modele reglementaire, les formats de son socle, son calendrier d'obligations date, et ce que Factlint applique reellement a une facture de ce pays. `coverage` vaut `national` quand un socle national scelle est en vigueur, `core-en16931` quand seule la base europeenne l'est, `none` quand aucun jeu scelle ne couvre le pays. Il est deduit des manifestes, jamais declare : rien ici ne peut annoncer une couverture que les empreintes ne portent pas. Le calendrier est date et source. `verified_on` dit quand la fiche a ete recoupee pour la derniere fois — une donnee reglementaire sans date de verification ne vaut rien. `Accept-Language: en` rend les libelles en anglais, avec repli sur le francais.

Detailler une juridiction

La fiche d'un pays par son code ISO 3166-1 alpha-2 (`FR`, `DE`, `BE`…), avec son calendrier, ses sources datees et le jeu de regles scelle qui lui est applique. Un code inconnu rend 404 : le catalogue ne suit pas tous les pays, et se taire vaut mieux que rendre une fiche vide qui se lirait comme une absence d'obligation.

Enchaîner le pipeline en un appel

Orchestre les étapes du pipeline sur un même document : identification, validation, correction, enrichissement, conversion, scellement. Le corps JSON déclare les étapes voulues et leurs options ; chacune reçoit la sortie de la précédente. **Une étape qui échoue arrête la suite** et la réponse dit laquelle et pourquoi. Les étapes déjà exécutées gardent leur résultat : un appel interrompu reste lisible, il ne rend pas une réponse vide. Le décompte porte sur le document distinct, pas sur le nombre d'étapes : un pipeline de cinq étapes coûte le même document qu'un `/v1/fix` seul.

Lister les jeux de règles

Le catalogue des jeux de règles publiés, avec pour chacun son état, sa période d'effet et sa date de conservation. Un jeu scellé est immuable et reste exécutable pendant la durée d'archivage fiscal : c'est ce qui permet de rejouer dans dix ans un verdict rendu aujourd'hui. Un jeu en préparation apparaît ici avec `sealed: false`. Ses empreintes ne sont pas calculées et aucun verdict rendu contre lui n'est rejouable.

Détailler un jeu de règles

Le manifeste d'un jeu : ses artefacts, leurs versions, leurs licences et leurs empreintes SHA-256. C'est ce qu'il faut pour vérifier soi-même qu'un verdict a été rendu contre ce qu'on annonce. Les artefacts eux-mêmes ne sont pas redistribués — certaines licences ne le permettent pas. Le manifeste et les empreintes suffisent à les identifier et à les récupérer à la source.

Valider une facture

Rend le verdict d'un document contre un jeu de règles, sans rien écrire et sans rien conserver. Gratuit, sans clé, sans compte et sans limite de volume. **Le verdict n'est pas un code HTTP.** Un document non conforme renvoie 200 et un `status` métier : `passed`, `needs_input` (une donnée obligatoire manque, que seul l'émetteur possède), `blocked` (incohérence sur un champ financier — la valeur correcte est suggérée, jamais écrite) ou `not_evaluated` (le contrôle n'a pas pu avoir lieu ; mieux vaut une absence de verdict qu'un faux verdict, et ce cas n'est jamais décompté). Deux champs disent ce que la réponse ne prouve pas. `engine.pinned` à false signale un verdict exact mais non rejouable, rendu contre des Schematron embarqués plutôt que contre les artefacts épinglés. `national_rules.applied` à false signale un socle national non appliqué — sur un document UBL par exemple, les règles françaises BR-FR n'étant publiées qu'en syntaxe CII. Accepte un Factur-X ou ZUGFeRD (PDF/A-3), un CII ou un UBL 2.1, jusqu'à 10 Mo. Le document est traité en mémoire et n'est jamais écrit sur disque.