MCP Factur-X : générer et valider des factures électroniques¶
Connexion avec authentification immédiate : utilisez https://facturx.orvel.dev/mcp/account. Dans Claude Code :
Ouvrez /mcp, choisissez facturx-account, puis Authenticate. Connectez-vous et approuvez la demande dans le navigateur. L'adresse /mcp reste disponible pour la démo publique et les intégrations existantes. Un changement d'adresse nécessite une nouvelle autorisation ; le quota reste identique.
Valider votre facture et obtenir un essai gratuit
Créez des PDF Factur-X, du XML CII ou UBL 2.1, contrôlez les règles EN 16931 et extrayez les données depuis votre assistant.
Tester la validation maintenant¶
Sans inscription, clé API ni carte. Vérifiez une facture synthétique avec le moteur XSD et EN 16931 de production, puis testez la même facture sans nom d’acheteur pour voir l’erreur.
Sans JavaScript : résultat valide · résultat incorrect.
Depuis votre assistant¶
Connectez https://facturx.orvel.dev/mcp sans clé et demandez :
Appelle view_invoice_demo avec sample="invalid". Explique le nom d’acheteur manquant avec explain_finding pour BR-07, puis compare avec sample="valid".
L’appel {} valide désormais le bon exemple. Le sélecteur sample propose valid (par défaut), invalid ou downloads. Sur Glama : Try in Browser, connexion sans authentification, outil de démo puis Execute.
Le résultat indique les erreurs, contrôles exécutés, version du moteur, date de validation et état du cache. Cache de 24 heures maximum par version et exemple ; un résultat en cache n’est pas un nouveau calcul. Seul le XML CII est vérifié, sans PDF ni registre. Aucun document personnel ou URL accepté. Limites partagées : 120 requêtes/minute et deux calculs hors cache/minute. Une indisponibilité renvoie une erreur.
Télécharger le PDF d’exemple Rapports publiés
Pour les liens PDF/CII/UBL, utilisez {"sample":"downloads"} ou /v1/demo?sample=downloads. Pour vos factures : essai gratuit vérifié, 10 opérations sur 14 jours, ou pack à 10 EUR, 100 opérations sans expiration, sans abonnement.
Contrôler votre propre facture, sans clé¶
validate_invoice fonctionne sur https://facturx.orvel.dev/mcp sans authentification : joignez un PDF Factur-X, un CII ou un UBL et demandez à votre assistant de le contrôler et d'expliquer chaque anomalie. Fichiers jusqu'à 5 Mo, capacité quotidienne partagée. Générer, incorporer et extraire nécessitent un forfait.
Contrôler une facture dans le navigateur
Pour vos propres documents, les configurations ci-dessous utilisent /mcp/account afin de demander la connexion dès le départ. Gardez /mcp pour la démo sans compte. Si vous changez d’adresse, authentifiez à nouveau le client.
Cursor¶
Dans .cursor/mcp.json :
VS Code¶
Dans .vscode/mcp.json :
Claude Code¶
Un client web doit prendre en charge les connecteurs MCP personnalisés. La démo fonctionne sans clé. Pour vos documents, choisissez Authenticate, connectez-vous avec e-mail/mot de passe, Google ou votre compte Orvel, puis approuvez la connexion. L'essai ou le forfait lié conserve son quota et sa date d'expiration. Les configurations détaillées sont dans le guide anglais.
Traiter vos documents¶
- Obtenez un essai gratuit : 10 opérations sur 14 jours, compte Orvel vérifié, sans carte. Une attribution par compte/e-mail, 100 places, 30 tentatives de traitement maximum. Registres exclus. Le pack à 10 EUR offre ensuite 100 opérations sans expiration.
- Ouvrez votre espace Factur-X. Un achat effectué depuis cet espace est lié au compte après confirmation du paiement. Un ancien achat peut être lié une fois avec sa clé existante.
- Connectez le même serveur par OAuth et approuvez la connexion. Les clients qui utilisent une clé peuvent toujours envoyer
Authorization: Bearer <votre-clé>. - Utilisez
get_invoice_example, remplacez les données d'exemple, puis appelezgenerate_invoiceavec la sortiefacturx-pdf,cii-xmlouubl-xml.
Dans Cursor, ajoutez "headers":{"Authorization":"Bearer VOTRE_CLE_API"} à l'entrée facturx. Ne publiez jamais la clé dans Git ou une conversation publique.
| Outil | Accès |
|---|---|
view_invoice_demo |
Validation de deux exemples CII (sample: valid ou invalid), ou téléchargements (sample: "downloads") ; {} valide l’exemple correct ; sans clé |
get_invoice_example, explain_finding, draft_credit_note |
Aides sans clé ; aucun fichier produit |
generate_invoice, embed_xml, validate_invoice, extract_invoice |
Clé requise ; un document par appel réussi |
check_party, check_invoice_parties |
Une partie ou le vendeur et l'acheteur ensemble ; sans quota documentaire ; registres sur Pro et Scale |
REST et MCP partagent le quota. Consultez GET /v1/usage. Les anciennes clés Free gardent leur quota mensuel ; les anciennes clés d'essai gardent leur expiration et leur quota total. Les essais anonymes renouvelables restent fermés ; l'essai avec compte vérifié possède un quota fixe distinct. Un rapport de validation terminé compte comme une opération, même si la facture contient des erreurs.
Comprendre le résultat¶
status distingue les contrôles réussis, un échec et une validation incomplète. issues regroupe les problèmes avec le champ concerné et une correction indicative ; findings conserve les constats techniques d'origine. Un json_pointer désigne le JSON d'entrée Orvel, pas un emplacement XML. Les exemples de correction ne remplacent pas vos données réelles. coverage indique les contrôles effectués et leurs limites : aucune garantie de conformité PDF/A complète, de vérification des registres ou d'acceptation par une plateforme destinataire.
En cas de difficulté¶
401: connectez votre clé par OAuth, configurez un en-tête bearer, ou utilisez la démo sans clé.402: quota atteint ; changez de forfait.503: le contrôle d'usage est indisponible ; réessayez plus tard.plan_excluded: la vérification des parties nécessite Pro ou Scale.- Erreur de règle : appelez
explain_finding, corrigez les champs indiqués puis réessayez.
Vérifier les deux parties avant génération¶
Appelez check_invoice_parties avec seller et buyer, chacun contenant au moins siren, siret ou vat. Les rôles découlent du nom des arguments ; aucune ligne de facture n'est nécessaire. Le paramètre facultatif requester_vat s'applique aux deux recherches.
Le statut global est invoice_ready seulement si les deux vérifications sont positives, not_ready si l'une échoue de façon certaine, sinon inconclusive. Consultez toujours parties.seller et parties.buyer : les preuves disponibles sont conservées dans la réponse même si l'autre registre ne répond pas. Deux recherches au maximum sont effectuées avec votre clé ; les restrictions et quotas d'EU Verify restent applicables à chacune.
Le parcours reste sans stockage : exemple, vérification des parties, génération, puis sauvegarde et transmission du fichier par votre propre système. Pour corriger un document, modifiez les données et régénérez-le ; pour un avoir intégral ou partiel, utilisez draft_credit_note. Les documents reçus peuvent être extraits, validés et leurs erreurs expliquées.
Le serveur ne conserve aucun dossier de facture à modifier ou supprimer. Votre application assure le stockage, la transmission et la suppression ; le serveur n'est pas un point d'accès Peppol.
Avoirs intégraux et partiels¶
get_invoice_example accepte {"document_type":"credit_note"} pour obtenir un exemple d'avoir. Remplacez les parties, dates, numéro, lignes et preceding_invoices par les données réelles avant génération.
Pour créditer une facture existante, transmettez son objet d'entrée original à draft_credit_note. Omettez credit_lines pour un avoir intégral. Pour créditer deux unités de la deuxième ligne, ajoutez :
line_index désigne la position dans le tableau original invoice.lines, à partir de 1, et non son champ id. Les positions doivent être distinctes, la liste non vide et les quantités positives, sans dépasser celles d'origine. Les lignes non sélectionnées sont exclues. Prix, unités et taux de TVA sont conservés. En mode sélection, les anciens totaux, acomptes, arrondis et statut payé sont effacés pour recalcul à la génération.
Les remises/frais au niveau du document et les quantités réduites sur des lignes avec remises/frais ou montants nets surchargés nécessitent une répartition explicite. Ces cas sont refusés : préparez alors le corps de l'avoir et appelez generate_invoice. Une ligne sélectionnée en totalité conserve ses ajustements. Aucun remboursement bancaire n'est effectué. Votre système doit suivre les avoirs antérieurs pour éviter de créditer plusieurs fois les mêmes montants.
Authentification des annuaires¶
Le serveur accepte Authorization: Bearer VOTRE_CLE ou X-API-Key: VOTRE_CLE.
Les deux utilisent la même clé, les mêmes contrôles de forfait et le même quota.
Utilisez un seul en-tête. Ne placez jamais la clé dans une URL ou un argument d'outil.
Dans Smithery, le réglage facultatif apiKey transmet la clé via X-API-Key, sans préfixe
Bearer. Laissez-le vide pour les exemples publics. Dans l'annuaire Claude, l'en-tête
authorization doit contenir Bearer VOTRE_CLE. La soumission à un annuaire ne garantit pas
sa disponibilité : avant approbation, utilisez un connecteur personnalisé ou les configurations
ci-dessus. Glama et les autres clients peuvent utiliser l'un ou l'autre des en-têtes.
La découverte et la démonstration fixe restent accessibles sans clé ; OAuth permet de connecter votre clé existante sans changer son forfait ni son quota.
Connexion OAuth¶
Connectez votre client à https://facturx.orvel.dev/mcp. Connectez-vous à votre compte, vérifiez le domaine de retour de l'application, puis choisissez Approve connection. Si vous êtes déjà connecté à Factur-X, la page d'approbation s'affiche directement. Le démarrage de l'essai est une action séparée : une connexion MCP ne crée ni crédits supplémentaires ni abonnement.
Le flux utilise un code d'autorisation avec PKCE SHA-256. Les jetons d'accès durent 15 minutes ; les jetons de renouvellement sont remplacés à chaque utilisation et la connexion expire au plus tard après 30 jours. Pour révoquer l'accès, utilisez la révocation de votre client ou révoquez la clé API d'origine. Les en-têtes API restent disponibles. Les jetons OAuth sont réservés au point d'accès MCP.