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. Le XML de facture intégré est ignoré par défaut ; définissez use_embedded_xml=true uniquement si votre intégration l’accepte comme source d’extraction principale. 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, comparé sans tenir compte de la casse. Chaque format a un ensemble fermé de valeurs acceptées et une seule valeur par défaut : XRECHNUNG → [XRECHNUNG] (par défaut XRECHNUNG) ; EN16931 → [EN16931] (par défaut EN16931) ; UBL → [XRECHNUNG, PEPPOL, EN16931] (par défaut EN16931) ; CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (par défaut EN16931) ; ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (par défaut ZUGFERD_EN16931). ZUGFERD, FACTURX, FACTUR-X et FACTUR_X sont des alias de ZUGFERD_EN16931 ; ZUGFERD-XRECHNUNG est un alias de ZUGFERD_XRECHNUNG. Une valeur hors de l’ensemble accepté renvoie 422 OUTPUT_PROFILE_CONFLICT ; un nom de profil non reconnu renvoie 422 INVALID_PROFILE avec details.allowed_profiles; 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; email_input (texte libre, optionnel, sources PDF uniquement) — instructions client dans n’importe quelle langue, jusqu’à 10 000 caractères, transmises sans marqueurs de bloc e-mail ; toutes les étapes d’extraction et de correction IA les reçoivent séparément du texte source de la facture ; incompatible avec use_embedded_xml=true, intégré à l’identité de requête utilisée pour l’idempotence et non pris en charge par invoices:convert-structured ; la validation de facture standard reste appliquée; 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 ; electronic_address et electronic_address_scheme doivent être fournis ensemble ou tous deux omis; use_embedded_xml (boolean, optionnel, false par défaut) — le XML Factur-X, ZUGFeRD ou XRechnung intégré est ignoré sauf si la valeur est explicitement true ; utilisez cette option uniquement si l’intégration accepte le XML intégré comme source d’extraction principale. 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, comparé sans tenir compte de la casse. Chaque format a un ensemble fermé de valeurs acceptées et une seule valeur par défaut : XRECHNUNG → [XRECHNUNG] (par défaut XRECHNUNG) ; EN16931 → [EN16931] (par défaut EN16931) ; UBL → [XRECHNUNG, PEPPOL, EN16931] (par défaut EN16931) ; CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (par défaut EN16931) ; ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (par défaut ZUGFERD_EN16931). Une valeur hors de l’ensemble accepté renvoie 422 OUTPUT_PROFILE_CONFLICT ; un nom de profil non reconnu renvoie 422 INVALID_PROFILE avec details.allowed_profiles; 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 ; electronic_address et electronic_address_scheme doivent être fournis ensemble ou tous deux omis. Réponse: 202 Accepted.

Interrogez le statut actuel d’une tâche de conversion. Renvoie pending (acceptée et en file, pas encore démarrée), processing, completed ou failed. Rate limit 10/min et 120/hour, ce qui constitue la contrainte déterminante pour le polling : attendez environ 20 secondes après le 202 accepté avant le premier appel, puis espacez les appels (20s, 30s, 45s, 60s, puis 60s ensuite) et arrêtez sur 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 ; sur une tâche terminée, download=xml est l’artefact attendu comme disponible, pas un artefact garanti. 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 un 202 portant l’enveloppe d’erreur standard ({"code":"TASK_NOT_READY","message":"Strict conversion is still processing. No validated artifact is available yet.","correlation_id":"<uuid>"}) ; les problèmes de validation bloquants renvoient 422 VALIDATION_FAILED, les dépendances temporairement indisponibles renvoient 503, les échecs de conversion terminaux renvoient 500 TASK_FAILED avec la raison dans details.code, et les échecs d’invariant d’artefact renvoient 500 INTERNAL_ARTIFACT_INVARIANT_FAILED, toujours sans corps de fichier. Les téléchargements réussis portent X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status et X-Validator-Bundle-Id ; X-Task-Id n’est pas défini sur cet endpoint. Rate limit 10/min et environ 134/hour. 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.

Téléchargez le rapport de l’artefact de résultat validé actuel. Le rapport est disponible seulement après le stockage d’un artefact avec une preuve à jour ; sinon, l’endpoint renvoie 202 ou 404. Les headers de réponse identifient l’artefact et la preuve du rapport. X-Artifact-Sha256 désigne l’artefact de résultat, pas le fichier du rapport. Rate limit : 10/min et 120/heure. Requête: aucun (GET); task_id (chemin, requis) — UUID renvoyé par un endpoint de conversion; download (query, optionnel) — html ou xml. Réponse: 200 OK.

seller_master_data traite désormais electronic_address et electronic_address_scheme comme une paire facultative. Fournissez les deux champs ou omettez-les tous les deux ; une paire incomplète renvoie 400 INVALID_SELLER_MASTER_DATA.

Correction de la documentation tarifaire : 1 000 crédits prépayés coûtent 400 EUR (0,40 EUR par crédit). Les forfaits de 100, 200 et 500 crédits restent à 50, 100 et 250 EUR. Les prix appliqués et les achats existants ne changent pas.

La conversion de documents ignore désormais le XML de facture intégré par défaut. Définissez use_embedded_xml=true uniquement si l’intégration accepte explicitement le XML intégré comme source d’extraction principale. L’import e-mail ignore toujours le XML de facture intégré. La modification de use_embedded_xml modifie le hash d’idempotence de la requête ; utilisez un nouvel Idempotency-Key lorsque vous modifiez cette option.

Lorsque les données maître vendeur remplissent un champ, les drapeaux d’extraction restants restent visibles mais ne bloquent plus l’import e-mail strict ni l’API externe. Acheteur, lignes, taxe, livraison, échéance, escompte, motif de virement, champs de profil non renseignés et valeurs invalides restent bloquants.

Enterprise est devenu disponible en achat direct à 50 EUR/mois ou 420 EUR/an. Enterprise comprend 100 conversions E-mail/API partagées par mois ; les conversions supplémentaires utilisent des crédits prépayés à 0,40–0,50 EUR. Les clés API ne demandent plus d’approbation manuelle.

Publication du catalogue d’erreurs actuel et des règles de réessai par code. Un statut 500 n’est pas automatiquement réessayable ; consultez code, details.code et details.retryable. Documentation des deux formes de details pour 402 INSUFFICIENT_API_CREDITS et des parcours de reprise différents pour les erreurs 409 d’idempotence. Publication des headers de preuve du rapport, de la conservation de 24 heures, des timeouts de tâche et des rate limits par endpoint. Publication de la table fermée format/profil et correction des indications de téléchargement, METHOD_NOT_ALLOWED et PROFILE_MISMATCH.

La conversion API rejette maintenant une source confirmée avec plusieurs factures par l’erreur terminale MULTIPLE_INVOICES_IN_DOCUMENT. Scindez les fichiers multi-factures confirmés. Un signal incertain renvoie plutôt 422 VALIDATION_FAILED pour examen.

Les données de référence vendeur activées remplacent maintenant les valeurs vendeur ou paiement extraites correspondantes. Les champs absents du profil laissent les valeurs extraites inchangées ; les écarts restent des avertissements non bloquants.

Remplacé par 2026-07-26 : les données de référence vendeur remplacent maintenant les valeurs extraites correspondantes au lieu de combler seulement les valeurs absentes.

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.

Les données de facture envoyées sont maintenant la source de données de la sortie ZUGFeRD hybride ; le nettoyage déterministe et la normalisation fiscale restent actifs. Les tâches échouent en cas d’arrêt de progression ou à la limite de 15 minutes, et non après un timeout fixe de cinq minutes.

Un échec de stockage du suivi d’usage ne bloque plus une réponse validée prête et ne facture pas de crédit en plus ; les événements sont mis en file pour rapprochement.

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.

Les artefacts XML stricts et PDF hybrides ont reçu des données internes de parité ; utilisez result_artifacts pour l’état de disponibilité et de validation. La base URL de production documentée est devenue https://www.invoice-converter.com/api/v1.

GET /api/v1/tasks/{task_id}/result sert uniquement à la récupération ; il ne génère, ne répare et ne valide aucun fichier. Les tâches strictes se terminent seulement après le stockage d’un artefact validé ; l’absence de preuve actuelle échoue en mode fermé. La conversion External API est fixée à l’émission stricte, sans brouillon ni contournement des avertissements. Le statut de tâche a reçu les diagnostics result_artifacts et les valeurs delivery_channel documentées.

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.

Le statut de tâche a reçu des diagnostics de disponibilité des artefacts XML/PDF. Les téléchargements stricts renvoient un fichier seulement après les contrôles d’artefact côté serveur.

Les téléchargements réussis ont reçu une preuve de validation côté serveur pour l’artefact renvoyé. Les dépendances de validation ou de preuve absentes renvoient 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE. Les téléchargements en cache sont réutilisés seulement si leur preuve de validation stockée reste à jour.

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.