Les guides du développeur

Par où commencer

Il n'existe pas de bibliothèque à installer pour chaque langage : un appel HTTP suffit. Le bon point de départ dépend de ce que votre système utilise déjà.

• Vous voulez voir la réponse avant d'écrire du code. Un terminal suffit : commencez par Valider une facture avec curl, qui donne l'appel en une ligne, puis un script prêt pour une intégration continue.
• Votre facturation tourne sur Node.js ou en Python. Les guides Valider une facture en Node.js et Valider une facture en Python donnent un programme complet, avec ce qui est propre à chaque langage : la façon d'envoyer le fichier, de borner l'attente et de lire les refus.
• Vous voulez tester chaque modification dans votre CI. Tester vos factures dans GitLab CI et GitHub Actions donne les jobs prêts à copier, quel que soit le langage de votre projet, avec un fichier de référence qui laisse passer les échecs déjà connus et rend le pipeline rouge quand une facture empire.
• Votre application est en PHP. Le client officiel logalysm/valide-facture, installé par Composer, rend un rapport typé et une exception par refus. C'est le seul client publié, et il est écrit en PHP.
• Votre application est en Symfony et vous préférez le client HTTP du framework. Valider vos factures depuis Symfony donne le service et la commande complets, sans autre paquet que les composants de Symfony.
• Votre langage n'est pas dans la liste. Le contrat ci-dessous est le même pour tous : un envoi de fichier, une réponse JSON, et un membre type qui dit quoi faire d'un refus.

Le contrat de l'appel

Chaque exemple fait le même appel : POST https://valide-facture.fr/api/validate, authentifié par l'en-tête Authorization: Bearer suivi de votre clé API.

• Le corps est un envoi multipart/form-data, avec un seul fichier dans le champ file : un PDF Factur-X, ou un XML CII ou UBL. Le type du document est reconnu sur ses octets, jamais sur son nom ni sur le type de média annoncé.
• Le fichier pèse au plus 10 Mio. Au-delà, la réponse est un refus payload-too-large ; bien au-delà, le serveur frontal coupe l'envoi par une page HTML.
• Le service ne répond qu'une fois la facture jugée. Réglez votre client sur 35 secondes d'attente au total.
• Rangez la clé dans une variable d'environnement ou un gestionnaire de secrets, jamais dans un fichier versionné. Les exemples la lisent dans VALIDE_FACTURE_API_KEY.

Le rapport

Une réponse 200 porte toujours un rapport, et une facture non conforme n'est pas une erreur : elle a été jugée. Le membre verdict vaut CONFORME, NON_CONFORME ou NON_EVALUABLE ; le contrat garde une quatrième valeur, PROFIL_NON_SUPPORTE, qui n'est plus produite.

Chaque anomalie de findings porte sa gravité (severity), le code de la règle (code), l'explication en français (messageFr), l'endroit du fichier (location) et une piste de correction (correctionHint). Les membres versions et coverage disent quels référentiels ont été appliqués et quels contrôles ont réellement tourné. De nouvelles valeurs peuvent apparaître au fil des versions : prévoyez toujours une branche par défaut.

Les refus, et le geste qui convient

Quand le service n'a pas pu juger la facture, il répond en application/problem+json. Branchez votre traitement sur le membre type, jamais sur le seul code HTTP ni sur la phrase detail, dont la rédaction peut changer. Chaque type est une adresse qui mène à sa documentation.

Renvoyer la même requête après un refus d'envoi ou de fichier donne le même refus. Les deux 429 appellent des gestes opposés, et c'est pourquoi chaque exemple lit le type : l'un se résout en attendant quelques secondes, l'autre non.

Un troisième 429 ne vient pas de l'API : la limite de débit du serveur frontal répond par une page HTML, sans type. Testez donc l'en-tête Content-Type avant de décoder un corps d'erreur.

La documentation de l'API

La documentation de l'API décrit chaque réponse, chaque type de refus et le schéma complet du rapport, champ par champ, et permet d'essayer l'appel depuis le navigateur. Chaque code de règle qu'un rapport peut porter a sa page parmi les codes d'erreur du validateur.