Documentation API externe V1

Convertir un document de facture

Convertir des données structurées

Interroger le statut de tâche

Téléversez un document de facture PDF, DOCX ou TXT et démarrez la conversion asynchrone. Renvoie un task_id pour le polling. Les PDF hybrides ZUGFeRD/Factur-X exigent une source PDF ; pour les sources DOCX/TXT, demandez des résultats XML. Requête: multipart/form-data; file (binary, requis) — document source de facture PDF, DOCX ou TXT ; les anciens fichiers DOC/RTF, images et autres fichiers sont refusés; format (string, requis) — format de sortie cible ; voir la matrice des formats ci-dessous; profile (string, optionnel, recommandé pour les intégrations déterministes) — profil de conformité explicite. Les valeurs par défaut dépendent du format ; les valeurs autorisées incluent XRECHNUNG, PEPPOL, EN16931 et les profils ZUGFeRD/Factur-X pris en charge; jurisdiction (string, optionnel) — contexte de juridiction ISO 3166-1 alpha-2 explicite utilisé pour les contrôles de validation/conseil ; ne remplace pas le profil; transaction_scope (string, optionnel) — contexte de périmètre transactionnel explicite, par exemple B2G ; appliqué à la tâche mise en file; delivery_channel (string, optionnel) — PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF ou UNKNOWN ; appliqué à la tâche mise en file; client_reference ou external_invoice_id (string, optionnel) — référence facture/job côté client renvoyée dans les uploads acceptés et les réponses de statut; source_system (string, optionnel) — libellé ERP ou système de facturation amont renvoyé dans les uploads acceptés et les réponses de statut; use_seller_master_data (boolean, optionnel) — si omis, la valeur par défaut du profil du tenant s’applique ; false ignore les données de base vendeur enregistrées pour cette requête, true fournit/utilise les données de base vendeur; seller_master_data (chaîne d’objet JSON, optionnel) — données vendeur utilisées uniquement lorsque use_seller_master_data=true ; prend en charge les champs société, adresse, fiscalité, contact et paiement (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note) ; chaque valeur du profil remplace la valeur extraite correspondante, les champs absents du profil restent inchangés et les différences créent des avertissements non bloquants. Réponse: 202 Accepted.

Téléversez un PDF porteur avec des données de facture CSV, JSON, XML, XLSX ou TXT et démarrez une conversion asynchrone depuis données structurées. Les parties data_file sont la seule source sémantique ; le PDF ne complète pas les champs de facture manquants. Pour ZUGFeRD/Factur-X, il sert de PDF porteur ; pour les sorties orientées XML, il est conservé comme artefact PDF soumis. Utilisez une requête de conversion par facture ; répétez data_file uniquement pour des exports ERP fractionnés décrivant la même facture. Requête: multipart/form-data; pdf_file (binary, requis) — PDF porteur utilisé pour l’intégration ZUGFeRD/Factur-X et conservé pour les sorties orientées XML; data_file (binary, requis, répétable) — données de facture CSV, JSON, XML, XLSX ou TXT utilisées comme seule source sémantique ; .xls, les PDF et les images sont refusés comme data_file ; répéter pour les exports header/lines fractionnés de la même facture ; les alias data_files et data_files[] sont acceptés; taille totale des données structurées — maximum 2 MB sur toutes les parties data_file; format (string, requis) — format de sortie cible ; prend en charge XRECHNUNG, ZUGFERD, EN16931, UBL et CII; profile (string, optionnel, recommandé pour les intégrations déterministes) — profil de conformité explicite. Valeur par défaut selon le format; jurisdiction (string, optionnel) — contexte de juridiction ISO 3166-1 alpha-2 explicite utilisé pour les contrôles de validation/conseil ; ne remplace pas le profil; transaction_scope (string, optionnel) — contexte de périmètre transactionnel explicite, par exemple B2G ; appliqué à la tâche mise en file; delivery_channel (string, optionnel) — PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF ou UNKNOWN ; appliqué à la tâche mise en file; client_reference ou external_invoice_id (string, optionnel) — référence facture/job côté client renvoyée dans les uploads acceptés et les réponses de statut; source_system (string, optionnel) — libellé ERP ou système de facturation amont renvoyé dans les uploads acceptés et les réponses de statut; use_seller_master_data (boolean, optionnel) — si omis, la valeur par défaut du profil du tenant s’applique ; false ignore les données de base vendeur enregistrées pour cette requête, true fournit/utilise les données de base vendeur; seller_master_data (chaîne d’objet JSON, optionnel) — données vendeur utilisées uniquement lorsque use_seller_master_data=true ; prend en charge les champs société, adresse, fiscalité, contact et paiement (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note) ; chaque valeur du profil remplace la valeur extraite correspondante, les champs absents du profil restent inchangés et les différences créent des avertissements non bloquants. Réponse: 202 Accepted.

Interrogez le statut actuel d’une tâche de conversion. Renvoie pending, processing, completed ou failed. Les tâches terminées incluent des diagnostics result_artifacts pour indiquer quels artefacts XML/PDF sont disponibles, mis en cache et prouvés par validation. Les payloads des tâches terminées peuvent inclure des entrées additives _processing_warnings et _validation_warnings avec des ID de règle SOURCE_CONTEXT_* lorsque les preuves source étaient indisponibles, douteuses ou tronquées ; traitez-les comme des signaux de revue, pas comme des échecs. En cas d’échec, la réponse inclut un champ error avec le motif. Requête: aucun (GET); task_id (path, requis) — UUID renvoyé par l’endpoint de conversion; include_validation_report_html (query, optionnel) — true ou false (false par défaut) ; avec true, la réponse de statut inclut le rapport de validation HTML assaini de l’artefact strict actuel lorsqu’il est disponible. Réponse: 200 OK.

Téléchargez le fichier généré (XML ou PDF). La syntaxe du résultat correspond au format initial de la tâche : XRECHNUNG/EN16931/UBL renvoient du XML UBL, CII/ZUGFERD renvoient du XML CII, et ZUGFERD + download=pdf renvoie un PDF/A-3 hybride. Pour d’autres formats, download=pdf peut renvoyer un PDF rendu. Les téléchargements répétés peuvent être servis depuis des artefacts générés en cache lorsque la preuve de validation est encore actuelle. Pendant le traitement, cet endpoint renvoie 202 TASK_NOT_READY ; les problèmes de validation bloquants renvoient 422 VALIDATION_FAILED, les dépendances temporairement indisponibles renvoient 503, et les échecs d’invariant d’artefact renvoient 500, toujours sans corps de fichier. Requête: aucun (GET); task_id (path, requis) — UUID renvoyé par l’endpoint de conversion; download (query, requis) — xml ou pdf. Réponse: 200 OK.

Download the validation report tied to the current validated result artifact. The report is available only after strict conversion has produced a cached artifact with current validation proof, and returns 404 when no report is bound to the delivered artifact. Requête: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Réponse: 200 OK.

When seller master data is enabled, every supplied profile value replaces the corresponding extracted seller or payment value. Fields absent from the profile remain unchanged. Source differences are non-blocking review warnings.

Rattrapage de documentation ; aucun changement de comportement à l’exécution. Le catalogue d’erreurs documente désormais des codes d’erreur d’exécution auparavant non documentés, dont API_CREDIT_SERVICE_UNAVAILABLE, TASK_NOT_FOUND, INVALID_CLIENT_METADATA, INVALID_SELLER_MASTER_DATA, PROFILE_MISMATCH, ZUGFERD_SOURCE_PDF_REQUIRED, VALIDATION_REPORT_NOT_FOUND, VALIDATION_REPORT_FAILED, INVALID_QUERY_PARAMETER et METHOD_NOT_ALLOWED. Les clients qui analysent les réponses d’erreur via le champ code lisible par machine n’ont rien à changer ; les clients qui s’appuient sur une liste fixe de codes doivent ajouter les valeurs nouvellement documentées. Dates du changelog corrigées : la prise en charge des sources DOCX/TXT a été livrée le 2026-06-30 et non le 2026-07-06.

Les payloads des tâches terminées peuvent inclure des entrées additives _processing_warnings et _validation_warnings avec des ID de règle SOURCE_CONTEXT_* lorsque les preuves source étaient indisponibles, douteuses ou tronquées avant l’extraction. Traitez les entrées SOURCE_CONTEXT_* comme des signaux de revue pour la gestion des exceptions côté client ; les téléchargements d’artefacts stricts restent régis par la preuve de validation et les contrôles d’artefact.

Les échecs de prérequis stricts ZUGFeRD (champs obligatoires manquants pour la génération hybride) échouent désormais en 422 VALIDATION_FAILED avec les ID de règle bloquants au lieu d’un 503 réessayable ; orientez-les vers un flux de correction des données, pas vers une boucle de réessai. Pour les formats XML uniquement (XRECHNUNG, EN16931, UBL, CII), le rendu PDF est désormais un artefact de commodité en best effort : download=xml reste la référence disponible sur les tâches terminées, tandis que download=pdf peut être indisponible si le rendu a échoué après l’émission du XML. Les conversions avec des conflits de source bloquants non résolus échouent désormais en 422 VALIDATION_FAILED avec des entrées blocking_source_conflict au lieu d’émettre un artefact.

POST /api/v1/invoices:convert accepte désormais les documents sources de facture PDF, DOCX et TXT dans le champ file. Les anciens fichiers DOC, RTF, images et autres sources non prises en charge sont refusés avant le démarrage de la conversion. Les téléchargements PDF hybrides ZUGFeRD/Factur-X exigent toujours une source PDF ; utilisez les téléchargements XML pour les conversions depuis DOCX/TXT. Ajout de l’option include_validation_report_html=true sur GET /api/v1/tasks/{task_id} pour inclure en ligne le rapport de validation HTML assaini lorsqu’il est disponible. Les uploads de conversion acceptent désormais les champs optionnels use_seller_master_data et seller_master_data sur les deux endpoints, afin que les tenants approuvés puissent activer des données de base vendeur enregistrées ou limitées à la requête.

Ajout de GET /api/v1/tasks/{task_id}/validation-report?download=html|xml pour récupérer le rapport de validation lié à la preuve de l’artefact de résultat strict actuel. Les réponses du rapport de validation exposent les headers ID de tâche, SHA-256 de l’artefact, ID de preuve de validation, ID de preuve du rapport, type de contenu du rapport et ID de corrélation.

L’accès External API est maintenant documenté comme accès approuvé et non comme création de clé non contrôlée. Clarification qu’aucun SLA formel, crédit de service ou pénalité contractuelle ne s’applique sauf accord dans un order form. format est désormais requis sur les deux endpoints de conversion ; les valeurs manquantes renvoient 400 FORMAT_REQUIRED et les valeurs non prises en charge 422 INVALID_FORMAT. download est désormais requis sur les requêtes task-result ; les valeurs manquantes renvoient 400 DOWNLOAD_FORMAT_REQUIRED et les valeurs non prises en charge 400 INVALID_DOWNLOAD_FORMAT. Les uploads de conversion acceptent maintenant client_reference/external_invoice_id et source_system pour le rapprochement côté client. Les réponses de conversion acceptée et de statut de tâche incluent maintenant status_url, primary_result_format, primary_result_url et les champs de rapprochement fournis.

La conversion structurée accepte désormais tous les formats de sortie publics : XRECHNUNG, ZUGFeRD, EN16931, UBL et CII. La conversion structurée accepte maintenant des parties data_file répétables ainsi que les alias data_files et data_files[] pour les exports ERP scindés. Les bundles structurés multi-fichiers doivent décrire exactement une facture et échouent rapidement si les ID de facture du bundle sont contradictoires ou manquants. Clarification que plusieurs documents de facture doivent être soumis comme tâches de conversion séparées, chacune avec sa propre clé d’idempotence.

Ajout de POST /api/v1/invoices:convert-structured pour la conversion de données structurées avec PDF porteur et CSV/JSON/XML/XLSX/TXT sur les formats de sortie pris en charge. Documentation du fait que les données structurées sont la seule source sémantique sur cet endpoint ; le PDF sert à l’intégration hybride. Artefacts OpenAPI et Postman mis à jour pour la conversion structurée.

Crédits API externes prépayés ajoutés pour les tenants non Enterprise. 402 INSUFFICIENT_API_CREDITS documenté pour les tenants approuvés sans facturation Enterprise par order form ni crédits prépayés. Confirmation que les relectures idempotentes ne consomment pas de crédits API supplémentaires. Clarification que le routage de modèle External API V1 est géré côté serveur, tandis que le profil et le contexte de livraison restent contrôlés par l’appelant.

Les téléchargements task-result respectent désormais le format pour les sorties CII et ZUGFERD. Réutilisation d’artefacts de résultat en cache ajoutée pour les téléchargements XML/PDF répétés d’une même tâche. Quotas de polling alignés sur les buckets de rate-limit pondérés par endpoint.

Réponses d’erreur API plus claires et cohérentes ajoutées sur tous les endpoints. Options de conversion étendues et comportement de téléchargement XML/PDF documenté pour les résultats de tâche. Sécurité des réessais améliorée avec des exigences d’idempotence et une validation plus strictes. Artefacts OpenAPI/Postman mis à jour pour correspondre au comportement actuel de l’API.