{ "openapi": "3.1.0", "info": { "title": "API externe Invoice Converter", "version": "1.20.0", "x-last-updated": "2026-10-02", "description": "Convertissez des documents de facture (PDF, DOCX, TXT) ou des données de facture structurées issues de votre ERP, de votre système de facturation ou de votre CRM en factures électroniques XRechnung, ZUGFeRD/Factur-X, EN 16931, UBL ou CII validées.\n\n**URL de base** `https://www.invoice-converter.com/api/v1` · **Authentification** `Authorization: Bearer ` · **Contrat** OpenAPI 3.1 (ce document)\n\nCette page est la documentation complète : les sections du guide ci-dessous expliquent le flux, et les sections des endpoints et des schémas listent chaque champ, chaque valeur et chaque réponse.\n\n## Vue d’ensemble\n\nL’API convertit une facture par requête en une facture électronique validée. Chaque conversion est asynchrone :\n\n1. **Convertir.** `POST /invoices:convert` (document PDF, DOCX ou TXT) ou `POST /invoices:convert-structured` (vos données de facture avec un PDF support). Réponse : `202` avec `task_id`.\n2. **Interroger.** `GET /tasks/{task_id}` jusqu’à ce que `status` soit `completed` ou `failed`.\n3. **Télécharger.** `GET /tasks/{task_id}/result?download=xml|pdf`. Facultatif : `GET /tasks/{task_id}/validation-report?download=html|xml`.\n\nUne tâche se termine uniquement lorsque l’artefact a réussi la validation pour le profil demandé. Il n’existe ni sortie brouillon ni contournement des avertissements. La V1 n’a pas de webhooks, pas d’endpoint batch et pas d’endpoint de liste des tâches.\n\n| Endpoint | Rôle | Limite de débit par clé API |\n|---|---|---|\n| `POST /invoices:convert` | Convertir un document | 30/min, 500/h |\n| `POST /invoices:convert-structured` | Convertir des données structurées | 30/min, 500/h |\n| `GET /tasks/{task_id}` | Statut de la tâche | 60/min, 1 500/h |\n| `GET /tasks/{task_id}/result` | Télécharger l’artefact | 60/min, 1 000/h |\n| `GET /tasks/{task_id}/validation-report` | Télécharger le rapport de validation | 30/min, 500/h |\n\n## Authentification et accès\n\n- En-tête : `Authorization: Bearer `.\n- Les clés sont des identifiants de production propres à chaque tenant, avec le préfixe `icp_...`. Créez, renouvelez et révoquez-les sur la page de profil avec un abonnement Enterprise actif. Aucune approbation séparée n’est nécessaire.\n- Conservez les clés sur votre serveur. Ne les placez jamais dans du code navigateur ou mobile, dans des journaux ou dans des tickets.\n- Jeton absent : `401 AUTHENTICATION_REQUIRED`. Clé inconnue ou révoquée : `401 INVALID_API_KEY`. Clé valide sans accès à l’API : `403 API_NOT_ENABLED_FOR_TENANT`. Clé d’un compte supprimé : `410 ACCOUNT_DELETED` (la suppression est définitive ; ne réessayez pas).\n\n## Démarrage rapide\n\n```bash\n# 1. Convert\ncurl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \\\n -H 'Authorization: Bearer ' \\\n -H 'Idempotency-Key: erp-inv-2026-0001' \\\n -F 'file=@invoice.pdf' \\\n -F 'format=XRECHNUNG' \\\n -F 'client_reference=ERP-2026-0001'\n\n# 2. Poll (first call about 20 s later)\ncurl 'https://www.invoice-converter.com/api/v1/tasks/' \\\n -H 'Authorization: Bearer '\n\n# 3. Download\ndownload_tmp=$(mktemp) || exit 1\ndownload_meta=$(curl --silent --show-error --output \"$download_tmp\" \\\n --write-out '%{http_code} %{content_type}' --dump-header headers.txt \\\n 'https://www.invoice-converter.com/api/v1/tasks//result?download=xml' \\\n -H 'Authorization: Bearer ') || { rm -f \"$download_tmp\"; exit 1; }\ncase \"$download_meta\" in\n '200 application/xml'|'200 application/xml;'*|'200 text/xml'|'200 text/xml;'*)\n mv \"$download_tmp\" invoice.xml ;;\n *)\n rm -f \"$download_tmp\"\n printf 'Download not saved (%s). Continue polling on 202.\\n' \"$download_meta\" >&2\n exit 1 ;;\nesac\n```\n\nLe corps de la réponse `202` contient `task_id`, `status` (`pending` ou `processing`), `status_url` et `primary_result_url`. Basez votre logique sur `status`, pas sur `message`. Enregistrez le `X-Correlation-ID` de chaque réponse ; le support en a besoin. Une réponse de statut terminée (abrégée) :\n\n```json\n{\n \"task_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"completed\",\n \"progress\": 100,\n \"created_at\": \"2026-09-30T08:00:00+00:00\",\n \"completed_at\": \"2026-09-30T08:01:12+00:00\",\n \"error\": null,\n \"client_reference\": \"ERP-2026-0001\",\n \"primary_result_url\": \"/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml\",\n \"result_artifacts\": {\n \"xml\": { \"state\": \"cached\", \"artifact_state\": \"compliant\", \"validation_state\": \"passed\" }\n }\n}\n```\n\nPour `failed`, `error` contient un résumé (chaîne ou objet) ; appelez `/result` pour obtenir l’erreur typée.\n\n## Formats et profils\n\n`format` est obligatoire et sélectionne la syntaxe et le conteneur. `profile` est facultatif et sélectionne le jeu de règles. Si vous omettez `profile`, la valeur par défaut du format s’applique.\n\n| `format` | `profile` autorisé | Par défaut | `download=xml` | `download=pdf` |\n|---|---|---|---|---|\n| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | PDF de rendu (au mieux) |\n| `EN16931` | `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |\n| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |\n| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | PDF de rendu (au mieux) |\n| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | PDF hybride ZUGFeRD/Factur-X |\n\n- `format` et `profile` ne sont pas sensibles à la casse. Alias : `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED` ; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`.\n- Un profil non listé pour le format : `422 OUTPUT_PROFILE_CONFLICT`. Un nom de profil inconnu : `422 INVALID_PROFILE` avec `details.allowed_profiles`.\n- Pour les formats XML, `download=xml` est l’artefact principal. Le rendu PDF est une commodité et peut être indisponible.\n- `format=ZUGFERD` exige une source PDF. Un envoi DOCX ou TXT est rejeté dès l’upload avec `422 ZUGFERD_SOURCE_PDF_REQUIRED`.\n- `jurisdiction` (ISO 3166-1 alpha-2), `transaction_scope` (`B2B`, `B2G`, `B2C`) et `delivery_channel` (`PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN`) sont des indications de contexte facultatives. Pour les flux B2G allemands ou Peppol, fournissez le contexte de l’appelant lors de l’upload. Une valeur invalide renvoie `422 UPLOAD_FAILED`.\n\n## Conversion de documents\n\n`POST /invoices:convert`, `multipart/form-data` :\n\n- `file` (obligatoire) : `.pdf`, `.docx` ou `.txt`. Une facture par fichier. Un document contenant plusieurs factures échoue avec `500 TASK_FAILED`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT`.\n- `format` (obligatoire), `profile`, champs de contexte comme ci-dessus.\n- `client_reference` (≤ 200 caractères) ou son alias `external_invoice_id`, et `source_system` (≤ 100 caractères) : renvoyés tels quels dans la réponse `202` et dans le statut de la tâche.\n- `use_embedded_xml` (par défaut `false`) : le XML Factur-X/ZUGFeRD/XRechnung intégré dans un PDF est ignoré, sauf si cette valeur est `true`.\n- `email_input` : instructions facultatives en texte libre pour l’extraction (PDF uniquement, ≤ 10 000 caractères, pas avec `use_embedded_xml=true`).\n- `use_seller_master_data` et `seller_master_data` : voir *Données de base du vendeur*.\n\nL’extraction lit le document. Elle n’invente pas de données juridiques, fiscales, de routage, bancaires ou de référence acheteur. Si des données obligatoires manquent, la tâche échoue et `/result` renvoie `422 VALIDATION_FAILED`.\n\n## Données de facture structurées\n\n`POST /invoices:convert-structured` convertit les données de votre ERP, de votre système de facturation ou de votre CRM (par exemple Salesforce).\n\n- `pdf_file` (obligatoire) : le PDF support. Pour `ZUGFERD`, le XML validé y est intégré ; pour les formats XML, il est conservé comme PDF original. **Il ne fournit jamais de données de facture.**\n- `data_file` (obligatoire, répétable ; alias `data_files`, `data_files[]`) : `.json`, `.csv`, `.xml`, `.xlsx` ou `.txt`, au total ≤ 2 MB.\n- Les champs `format`, `profile`, de contexte, de référence client et de données de base du vendeur fonctionnent comme pour la conversion de documents. `email_input` et `use_embedded_xml` ne sont pas acceptés.\n\n### Mappage déterministe ou interprété\n\n| Entrée | Mappage | Résultat |\n|---|---|---|\n| **Un seul** `data_file` JSON au format JSON canonique de facture, au premier niveau ou encapsulé dans `invoice_data` | Déterministe, sans IA | Même entrée, même sortie |\n| Un fichier XML UBL 2.1 Invoice ou CII D16B | Déterministe, sans IA | Analyseur XML de facture existant |\n| Plusieurs parties JSON canoniques `data_file` cohérentes | Fusion déterministe, sans IA | Les champs et lignes distincts sont combinés |\n| CSV, XLSX, TXT, autre XML, JSON personnalisé ou à plat, ou parties de formats mixtes | Mappage par IA | Fonctionne avec des libellés clairs ; non déterministe |\n\nPour une intégration reproductible, envoyez un seul fichier JSON canonique :\n\n- JSON Schema : \n- Exemple (XRechnung B2G allemande ; réussit les contrôles EN 16931, XRechnung et ZUGFeRD strict) : \n\nLe format utilise les noms d’éléments UBL 2.1 / EN 16931. Le chemin canonique est détecté lorsqu’au moins 3 des clés de premier niveau `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, `AccountingSupplierParty`, `AccountingCustomerParty`, `TaxTotal`, `LegalMonetaryTotal`, `InvoiceLine` sont présentes, dont `ID`, `InvoiceLine` ou `LegalMonetaryTotal`.\n\nLes champs inconnus du JSON canonique renvoient `400 INVALID_UPLOAD` avant la création du task. `details.unknown_paths` liste jusqu’à 100 chemins JSON concernés ; `details.unknown_path_count` donne le total. Supprimez les champs non déclarés au lieu de compter sur leur suppression silencieuse.\n\nLe mappage par IA a pour consigne de ne pas inventer les champs manquants. Les données manquantes font donc échouer la validation au lieu d’être devinées.\n\n**Exports scindés.** Pour une facture répartie sur plusieurs fichiers (par exemple en-tête et lignes), répétez `data_file`. Envoyez une requête par facture.\n\n- Chaque partie doit contenir le même numéro de facture dans une colonne ou une clé nommée `invoice number`, `invoice no`, `invoice no.`, `invoice id`, `rechnungsnr`, `rechnungsnr.`, `rechnung nr`, `rechnung nr.`, `belegnr` ou `belegnr.`.\n- Les noms ne sont pas sensibles à la casse, et `_` et `-` comptent comme des espaces : `Invoice_Number` fonctionne donc. `document no` et `document number` servent de solution de repli moins fiable.\n- Les noms en camelCase comme `invoiceNumber` et les noms d’API Salesforce comme `Invoice_Number__c` sont reconnus.\n- Un numéro absent ou contradictoire renvoie `400 INVALID_UPLOAD` avec `details.reason` `bundle_invoice_id_missing` ou `bundle_invoice_id_mismatch`.\n\nLes parties JSON canoniques utilisent le même `ID` au premier niveau. Chaque partie doit satisfaire la règle de détection canonique ci-dessus. Les lignes doivent avoir des valeurs `InvoiceLine[].ID` explicites et uniques dans chaque partie. Les lignes identiques répétées entre les parties sont dédupliquées ; les valeurs contradictoires ou les lignes différentes avec le même ID renvoient `400 INVALID_UPLOAD`, `details.reason=canonical_bundle_conflict` et `details.path`. Le serveur ne choisit pas entre les valeurs contradictoires et ne recalcule pas les totaux. Une valeur null est considérée comme absente lorsqu’une autre partie fournit l’information.\n\n\n### Données obligatoires\n\n| Toujours | Pour XRechnung (y compris `UBL`/`CII` avec le profil `XRECHNUNG`, et `ZUGFERD_XRECHNUNG`) | Pour ZUGFeRD strict |\n|---|---|---|\n| `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, nom du vendeur et de l’acheteur, ventilation de TVA, totaux, au moins une ligne | `BuyerReference` (Leitweg-ID, BR-DE-15) ; `PaymentMeans` (BR-DE-1) ; nom, téléphone et e-mail du contact vendeur (BR-DE-2/5/6/7) ; ville et code postal du vendeur et de l’acheteur ; `EndpointID` du vendeur et de l’acheteur avec `@schemeID` ; `Percent` de TVA pour chaque sous-total ; numéro de TVA ou numéro fiscal du vendeur | Une date de livraison, une période de facturation ou des périodes de ligne ; un pays de livraison le cas échéant |\n\nDes données manquantes terminent la tâche avec `failed` ; `/result` renvoie `422 VALIDATION_FAILED` avec `details.items[]` (`field`, `rule_id`, `severity`, `source`, `suggestion`).\n\n### Chemins JSON les plus utilisés\n\n`AccountingSupplierParty.Party` est abrégé en `Seller`, `AccountingCustomerParty.Party` en `Buyer`. XR = obligatoire pour XRechnung.\n\n| Chemin JSON | EN 16931 | XR |\n|---|---|---|\n| `ID` | BT-1 | oui |\n| `IssueDate` | BT-2 | oui |\n| `InvoiceTypeCode` (par exemple `380` facture commerciale) | BT-3 | oui |\n| `DocumentCurrencyCode` | BT-5 | oui |\n| `DueDate` | BT-9 | – |\n| `BuyerReference` | BT-10 | oui |\n| `OrderReference.ID` | BT-13 | – |\n| `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – |\n| `PaymentTerms.Note` | BT-20 | – |\n| `Seller.PartyLegalEntity.RegistrationName` | BT-27 | oui |\n| `Seller.PartyTaxScheme.CompanyID` (numéro de TVA) | BT-31 | oui¹ |\n| `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | oui |\n| `Seller.PostalAddress.StreetName` | BT-35 | – |\n| `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | oui |\n| `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | oui |\n| `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | oui |\n| `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | oui |\n| `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | oui |\n| `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | oui |\n| `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | oui |\n| `Delivery.ActualDeliveryDate` | BT-72 | – |\n| `PaymentMeans.PaymentMeansCode` | BT-81 | oui |\n| `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | pour un virement |\n| `TaxTotal.TaxAmount` | BT-110 | oui |\n| `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | oui |\n| `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | oui |\n| `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | oui |\n| `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | oui |\n| `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | oui |\n| `InvoiceLine[].LineExtensionAmount` | BT-131 | oui |\n| `InvoiceLine[].Price.PriceAmount` | BT-146 | oui |\n| `InvoiceLine[].Item.Name` | BT-153 | oui |\n| `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | oui |\n\n¹ Numéro de TVA du vendeur (BT-31) ou numéro fiscal (BT-32, `PartyTaxScheme` avec `TaxScheme.ID` `FC`).\n\n## Données de base du vendeur\n\n`seller_master_data` est une chaîne contenant un objet JSON. Elle ne s’applique que lorsque `use_seller_master_data=true` ; si l’indicateur est omis, la valeur par défaut du compte s’applique. Clés : `business_name`, `trading_name`, `street`, `additional_address`, `postal_code`, `city`, `country`, `vat_id`, `tax_number`, `electronic_address`, `electronic_address_scheme`, `contact_name`, `contact_email`, `contact_phone`, `payment_means_code` (`30`, `42` ou `58`), `payment_iban`, `payment_bic`, `payment_account_name`, `payment_terms_note`. Le schéma OpenAPI `SellerMasterData` indique le terme EN 16931 de chaque clé.\n\n- Chaque valeur fournie remplace la valeur extraite du vendeur ou du paiement. Les clés absentes laissent la facture inchangée.\n- `electronic_address` et `electronic_address_scheme` forment une paire : envoyez les deux ou aucune.\n- JSON invalide, clés inconnues ou paire incomplète : `400 INVALID_SELLER_MASTER_DATA`.\n\n## Idempotence et nouvelles tentatives\n\n- `Idempotency-Key` est obligatoire sur les deux endpoints POST. Format : 1–200 caractères, le premier étant une lettre ou un chiffre, puis des lettres, chiffres, `.`, `_`, `:` ou `-` (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`). Une bonne clé est l’ID de votre facture suivi d’une version, par exemple `sf-a0B5g00000XyZ12-v1`.\n- Portée : tenant et endpoint, pas la clé API individuelle. Les enregistrements sont conservés 24 heures.\n- Réutilisez la même clé **et** le même payload à chaque nouvelle tentative. Une relecture (replay) renvoie la réponse `202` d’origine avec `Idempotency-Replayed: true`, sans seconde facturation.\n- **Une clé, une tâche.** Dès qu’un upload est accepté, chaque nouvelle tentative avec la même clé et le même payload renvoie cette tâche : le même `task_id` et le même corps `202`. Cela vaut aussi lorsque vous n’avez pas reçu la première réponse, ou lorsque vous avez reçu une `5xx` après l’acceptation de la tâche. Une nouvelle tentative ne démarre jamais de seconde tâche et ne réserve ni ne facture jamais de seconde unité.\n- Les requêtes avec la même clé s’exécutent l’une après l’autre : les autres reçoivent `409 IDEMPOTENCY_IN_PROGRESS`. Une nouvelle tentative après l’échec de la tâche renvoie cette tâche en échec ; pour réessayer, utilisez une nouvelle clé.\n- La même clé avec un payload différent : `409 IDEMPOTENCY_CONFLICT`. La première requête est encore en cours : `409 IDEMPOTENCY_IN_PROGRESS` (réessayez plus tard avec la même clé). La tâche d’origine est déjà supprimée : `409 IDEMPOTENCY_REPLAY_EXPIRED` (nouvelle clé).\n- Réessayer une `429` ou une `5xx` avec la même clé est sans risque : ces réponses ne bloquent pas la clé. Une nouvelle tentative avec la même clé ne facture jamais deux fois : si une tâche a déjà été acceptée, elle renvoie cette tâche ; sinon, elle exécute de nouveau l’upload. Une `5xx` seule n’indique pas si une tâche a été acceptée : réessayez donc toujours avec la même clé.\n\n## Limites, interrogation et pics de charge\n\n**Les limites de débit** s’appliquent par clé API, avec un compteur par endpoint (tableau dans *Vue d’ensemble*), sur des fenêtres fixes de minute et d’heure calendaires. Une requête refusée n’est pas comptée. `429 RATE_LIMITED` contient `Retry-After`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour` ainsi que `details.minute_count`, `hour_count`, `limit_minute`, `limit_hour`. Les réponses réussies ne contiennent pas d’en-têtes de quota.\n\n**Interrogation.** Premier appel de statut environ 20 s après la réponse `202`, puis après 20, 30, 45 et 60 s, puis toutes les 60 s. Arrêtez à `completed` ou `failed`. La plupart des conversions se terminent en moins de deux minutes. Le serveur fait échouer une tâche après 5 minutes sans progression ou après 15 minutes au total : réglez donc le délai d’expiration de votre client sur environ 16 minutes.\n\n**Taille.** Les deux chemins d’upload de `www.invoice-converter.com` acheminent directement vers le backend, sans Vercel Function. Limites par défaut : fichier source `file` ou support `pdf_file` ≤ 20 000 000 octets (20 MB) ; parties `data_file` ≤ 2 000 000 octets (2 MB) au total. Le corps multipart dispose de 1 000 000 octets supplémentaires : 21 MB pour un document, 23 MB pour des données structurées. Au maximum 20 parties de fichier et 50 champs de texte (`400 INVALID_UPLOAD`). Tout dépassement d’une limite de fichier ou de corps renvoie JSON `413 PAYLOAD_TOO_LARGE` avec `details.limit_bytes`. L’authentification précède l’admission du corps. Les erreurs d’infrastructure peuvent encore renvoyer une réponse non JSON.\n\n**Pics de charge** (par exemple des centaines de factures récurrentes le premier du mois) : les tâches acceptées attendent dans une file de traitement partagée. Les envois API occupent collectivement au plus la moitié des places configurées par processus backend, arrondie à l’entier inférieur. La file par défaut de huit places accepte quatre tâches API et laisse quatre places aux canaux web ou autres. Cela protège la capacité d’admission ; cela ne garantit ni vitesse ni priorité. Une file ou une part API pleine renvoie `503 SERVER_BUSY` avec `Retry-After: 15` avant de consommer une place du quota de conversion ou de réserver une unité. La répétition d’une tâche acceptée ne nécessite pas de nouvelle place. Schéma client recommandé :\n\n1. Gardez une file côté client avec environ 2–4 conversions en cours ; adaptez-la à `SERVER_BUSY`.\n2. Sur `429` et `503 SERVER_BUSY`, attendez `Retry-After`, puis réessayez avec **la même** `Idempotency-Key`.\n3. Interrogez chaque tâche avec le délai croissant ci-dessus ; démarrez la conversion suivante lorsqu’une se termine. V1 ne propose ni webhook de fin, ni endpoint de lot ou de liste de tâches.\n\n## Erreurs\n\nChaque erreur JSON contient `code`, `message`, `correlation_id` et généralement `details`. Basez votre logique sur `code` ; pour `500 TASK_FAILED`, également sur `details.code` et `details.retryable`. `details.type` est généralement présent, mais pas toujours. Ne vous basez jamais uniquement sur le statut HTTP ou sur `message`.\n\nLe catalogue complet (chaque code avec son statut HTTP, sa règle de nouvelle tentative et l’action à mener) se trouve dans `ErrorEnvelope.code` de la référence OpenAPI. Les codes les plus fréquents :\n\n| Code | HTTP | Réessayer ? | Action |\n|---|---|---|---|\n| `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | non | Corrigez la clé. |\n| `ACCOUNT_DELETED` | 410 | non | Le compte de cette clé a été supprimé. La suppression est définitive. |\n| `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | non | Envoyez un `Idempotency-Key` valide. |\n| `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | non | Envoyez un `format` pris en charge. |\n| `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | non | Utilisez un profil du tableau ou omettez-le. |\n| `INVALID_UPLOAD` | 400 / 415 | non | Corrigez le corps multipart, le type de fichier ou les numéros de facture des exports scindés. |\n| `FUNCTION_PAYLOAD_TOO_LARGE` (texte brut) / `PAYLOAD_TOO_LARGE` | 413 | non | Envoyez une requête plus petite. |\n| `INSUFFICIENT_API_CREDITS` | 402 | non | Achetez des crédits ou attendez le mois suivant. |\n| `IDEMPOTENCY_IN_PROGRESS` | 409 | même clé | Réessayez après un court délai. |\n| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` | 409 | non | Utilisez une nouvelle clé. |\n| `RATE_LIMITED` | 429 | même clé | Attendez la durée `Retry-After`. |\n| `SERVER_BUSY` | 503 | même clé | File de traitement pleine. Attendez la durée `Retry-After`. |\n| `UPLOAD_FAILED` | 503 / 500 | même clé | L’upload n’a pas été accepté, ou il a été accepté mais sa première réponse n’a pas pu être reconstituée. Réessayez avec un backoff et la même clé. |\n| `UPLOAD_FAILED` | 422 | non | `jurisdiction`, `transaction_scope` ou `delivery_channel` invalide. |\n| `TASK_NOT_READY` | 202 | interroger | Continuez à interroger le statut. |\n| `VALIDATION_FAILED` | 422 | non | Corrigez les données (`details.items`), puis relancez la conversion. |\n| `TASK_FAILED` | 500 | si `details.retryable` | Lisez `details.code`. Si l’erreur permet une nouvelle tentative : nouvelle conversion avec une nouvelle clé. |\n| `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 | oui | Réessayez le même téléchargement plus tard. |\n| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 | nouvelle tâche | Démarrez une nouvelle conversion. |\n| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | non | Faites remonter le problème avec l’ID de corrélation. |\n| `TASK_NOT_FOUND` | 404 | non | Tâche inconnue, tâche d’un autre tenant, ou supprimée après 24 h. |\n| `PROXY_ERROR` | 502 / 504 | même clé | Réessayez avec un backoff. |\n\nMotifs de `500 TASK_FAILED` dans `details.code` : `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (définitifs) ; `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (suivez `details.retryable`). Une tâche en échec reste en échec : la seule reprise possible est une nouvelle conversion avec une nouvelle clé.\n\n## Résultats, preuves et rapport de validation\n\n- `/result` est une simple récupération. Il renvoie `200` uniquement pour un artefact stocké disposant d’une preuve de validation à jour.\n- Enregistrez les en-têtes de réponse : `X-Correlation-ID`, `X-Artifact-Sha256` (hachage des octets livrés), `X-Validation-Proof-Id`, `X-Artifact-State` (`compliant`), `X-Validation-State` (`passed`).\n- `/validation-report?download=html|xml` (paramètre obligatoire) renvoie le rapport lié à l’artefact livré : le rapport KoSIT ou, pour Factur-X, un XML `validation-evidence` avec `source=\"facturx_php\"`. La preuve Factur-X atteste uniquement la validation du XML stocké, pas la fidélité à la source ni la conformité PDF/A. Sur cet endpoint, `X-Artifact-Sha256` est le hachage de l’artefact de résultat validé, pas celui du rapport. Aucun rapport pour l’artefact actuel : `404 VALIDATION_REPORT_NOT_FOUND`.\n- `result_artifacts..state` dans le statut de la tâche : `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`.\n\n## Conservation, facturation et archivage\n\n- **Conservation.** Les tâches, les artefacts et les enregistrements d’idempotence sont supprimés 24 heures après la fin de la tâche. Ensuite, chaque endpoint de tâche renvoie `404 TASK_NOT_FOUND`. Les éléments d’assurance qualité suivent le calendrier de conservation de la section 9 de l’[accord de traitement des données](https://www.invoice-converter.com/fr/dpa).\n- **Facturation.** Chaque conversion acceptée consomme une unité. Enterprise inclut 100 unités par mois calendaire, partagées avec l’import par e-mail. Les unités supplémentaires utilisent des crédits prépayés : 100 pour 50 EUR, 200 pour 100 EUR, 500 pour 250 EUR, 1 000 pour 400 EUR. Les relectures (replays), les conversions en échec et tous les appels de tâche sont gratuits. Lorsque rien ne couvre une unité : `402 INSUFFICIENT_API_CREDITS` (deux structures de `details`, voir la réponse OpenAPI `PaymentRequired`).\n- **Archivage.** Constituez votre paquet d’archivage pendant le flux, pas plus tard : PDF original, XML généré ou PDF hybride, rapport de validation et un enregistrement de métadonnées avec `task_id`, `client_reference`, format/profil, `X-Artifact-Sha256`, `X-Validation-Proof-Id`, `X-Validation-Report-Proof-Id`, `created_at`/`completed_at` et les ID de corrélation.\n\n## Support et contrat\n\n- Contact : `contact@invoice-converter.com`. Indiquez le `X-Correlation-ID`.\n- L’API est fournie selon les Conditions générales et l’accord de traitement des données standard, ainsi que tout bon de commande Enterprise. Aucun SLA de disponibilité, de délai de traitement ou de support ne s’applique, sauf mention contraire dans un bon de commande.\n- Les documents source de mauvaise qualité et les cas particuliers exigent une vérification humaine. Conservez votre propre processus pour les exceptions, la correction, la transmission et l’archivage.\n- L’accès à l’API est réservé à l’usage professionnel de votre propre entreprise. La revente, la marque blanche ou l’usage en tant que prestataire de services nécessitent un contrat de partenariat.\n\n## Artefacts de référence\n\n- OpenAPI 3.1 : \n- Collection Postman : (définissez `base_url`, `api_key`, `idempotency_key`)\n- JSON Schema et exemple de facture structurée : voir *Données de facture structurées*\n- Canal de factures par e-mail : \n- Cette documentation au format Markdown (pour les LLM et la lecture hors ligne) : ", "contact": { "name": "Support Invoice Converter", "email": "contact@invoice-converter.com", "url": "https://www.invoice-converter.com/fr/developer-api" } }, "servers": [ { "url": "https://www.invoice-converter.com/api/v1", "description": "Production" } ], "security": [ { "HTTPBearer": [] } ], "tags": [ { "name": "Conversion", "description": "Démarrez une conversion asynchrone. Chaque requête acceptée consomme une unité de facturation ; les relectures idempotentes et les conversions en échec n’en consomment pas.", "x-displayName": "Conversion" }, { "name": "Tasks", "description": "Interrogez le statut de la tâche et téléchargez le résultat validé et son rapport de validation. Ces appels sont gratuits, mais soumis à une limite de débit.", "x-displayName": "Tâches" } ], "paths": { "/invoices:convert": { "post": { "tags": [ "Conversion" ], "summary": "Convertir un document de facture", "operationId": "convertInvoice", "description": "Envoyez un document de facture et démarrez une conversion stricte.\n\n- `file` : `.pdf`, `.docx` ou `.txt`, une facture par fichier. Fichier source ≤ 20 MB (20 000 000 octets) ; corps multipart complet ≤ 21 MB.\n- `format` est obligatoire ; `profile` est facultatif (valeur par défaut par format ci-dessous).\n- Le XML intégré dans un PDF est ignoré, sauf si `use_embedded_xml=true`.\n- Limite de débit : 30/min et 500/h par clé API.\n\n| `format` | `profile` autorisé | Par défaut | `download=xml` | `download=pdf` |\n|---|---|---|---|---|\n| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | PDF de rendu (au mieux) |\n| `EN16931` | `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |\n| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |\n| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | PDF de rendu (au mieux) |\n| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | PDF hybride ZUGFeRD/Factur-X |", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ConvertInvoiceRequest" }, "encoding": { "file": { "contentType": "application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain" }, "seller_master_data": { "contentType": "application/json" } } } } }, "responses": { "202": { "description": "Acceptée. Interrogez `status_url`. Une nouvelle tentative avec le même Idempotency-Key et le même payload renvoie la tâche déjà acceptée : le même task_id et le même corps 202, avec l’en-tête Idempotency-Replayed: true. Cela vaut aussi lorsque la première réponse a été perdue ou était une 5xx après l’acceptation de la tâche, et après l’échec de la tâche. Elle ne démarre jamais de seconde tâche et ne réserve ni ne facture jamais de seconde unité.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertAcceptedResponse" }, "example": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "message": "PDF accepted. Strict conversion started.", "filename": "invoice.pdf", "file_size": 245832, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "client_reference": "ERP-2026-0001", "source_system": "salesforce" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowedConversionPath" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UploadFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ConvertServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/invoices:convert-structured": { "post": { "tags": [ "Conversion" ], "summary": "Convertir des données de facture structurées", "operationId": "convertStructuredInvoice", "description": "Convertissez des données de facture issues de votre système. `data_file` est la seule source de données ; `pdf_file` sert uniquement de support (intégré pour ZUGFeRD, conservé comme PDF original sinon).\n\n- **Déterministe :** un JSON `data_file` au format `StructuredInvoiceData`, des parties JSON canoniques cohérentes ou un fichier XML UBL 2.1 Invoice / CII D16B sont mappés sans IA ([schéma](https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json), [exemple](https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json)).\n- **Interprété :** CSV, XLSX, TXT, autre XML, JSON personnalisé et parties de formats mixtes utilisent le mappage par IA, qui laisse les champs manquants vides.\n- Exports scindés : répétez `data_file` ; toutes les parties doivent avoir le même numéro de facture. Les colonnes comme `Invoice Number`, `Rechnungsnr`, `invoiceNumber` et `Invoice_Number__c` sont reconnues ; le JSON canonique utilise `ID`.\n- JSON canonique : les champs inconnus renvoient `400 INVALID_UPLOAD` avec `details.unknown_paths` ; les valeurs contradictoires de l’ensemble renvoient `details.reason=canonical_bundle_conflict` et `details.path`. Les lignes doivent avoir des valeurs `InvoiceLine[].ID` explicites et uniques dans chaque partie.\n- Limites : `pdf_file` ≤ 20 MB, parties `data_file` ≤ 2 MB au total, corps multipart complet ≤ 23 MB. Limite de débit : 30/min et 500/h par clé API.\n- Les règles de `format` et `profile` sont les mêmes que pour `POST /invoices:convert`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest" }, "encoding": { "pdf_file": { "contentType": "application/pdf" }, "data_file": { "contentType": "application/json, text/csv, application/xml, text/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, text/plain" }, "seller_master_data": { "contentType": "application/json" } } } } }, "responses": { "202": { "description": "Acceptée. Interrogez `status_url`. Une nouvelle tentative avec le même Idempotency-Key et le même payload renvoie la tâche déjà acceptée : le même task_id et le même corps 202, avec l’en-tête Idempotency-Replayed: true. Cela vaut aussi lorsque la première réponse a été perdue ou était une 5xx après l’acceptation de la tâche, et après l’échec de la tâche. Elle ne démarre jamais de seconde tâche et ne réserve ni ne facture jamais de seconde unité.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Idempotency-Replayed": { "$ref": "#/components/headers/IdempotencyReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertAcceptedResponse" }, "example": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "message": "PDF and structured data accepted. Strict conversion started.", "filename": "invoice.pdf", "pdf_filename": "invoice.pdf", "data_filename": "invoice.json", "data_filenames": [ "invoice.json" ], "data_file_count": 1, "file_size": 249832, "pdf_file_size": 245832, "data_file_size": 4000, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "client_reference": "ERP-2026-0001", "source_system": "salesforce" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowedConversionPath" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UploadFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ConvertServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/tasks/{task_id}": { "get": { "tags": [ "Tasks" ], "summary": "Lire le statut de la tâche", "operationId": "getTaskStatus", "description": "Renvoie l’état de la tâche. Interrogez jusqu’à ce que `status` soit `completed` ou `failed`.\n\n- Backoff : premier appel ~20 s après la réponse `202`, puis 20, 30, 45, 60 s, puis toutes les 60 s. Arrêtez après ~16 min.\n- `completed` : téléchargez depuis `primary_result_url`. `failed` : appelez `/result` pour obtenir l’erreur typée.\n- Tâche inconnue, ou plus de 24 h après la fin : `404 TASK_NOT_FOUND`.\n- Limite de débit : 60/min et 1 500/h par clé API.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/IncludeValidationReportHtmlQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "État actuel de la tâche.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusResponse" }, "examples": { "pending": { "summary": "Queued", "value": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "pending", "progress": 0, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": null, "filename": "invoice.pdf", "error": null, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "client_reference": "ERP-2026-0001", "source_system": "salesforce", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "not_ready", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml" }, "pdf": { "state": "not_ready", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=pdf" } } } }, "completed": { "summary": "Completed", "value": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "progress": 100, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": "2026-09-30T08:01:12+00:00", "filename": "invoice.pdf", "error": null, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "client_reference": "ERP-2026-0001", "source_system": "salesforce", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "cached", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "content_type": "application/xml", "filename": "invoice.xml", "bytes": 18572, "artifact_state": "compliant", "validation_state": "passed" }, "pdf": { "state": "cached", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=pdf", "content_type": "application/pdf", "filename": "invoice.pdf", "bytes": 245832, "artifact_state": "compliant", "validation_state": "passed" } } } }, "failed": { "summary": "Failed (call /result for the typed error)", "value": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "failed", "progress": 100, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": "2026-09-30T08:00:41+00:00", "filename": "invoice.pdf", "error": { "code": "MULTIPLE_INVOICES_IN_DOCUMENT", "classification": "multiple_invoices", "message": "Document contains multiple invoices", "category": "extraction", "retryable": false, "can_review": false, "recovery_hint": "Split the PDF into one file per invoice and start a separate conversion for each invoice." }, "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "client_reference": "ERP-2026-0001", "source_system": "salesforce", "primary_result_format": "xml", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "validation_failed", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml" }, "pdf": { "state": "validation_failed", "download_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=pdf" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TaskNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowedTaskPath" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/tasks/{task_id}/result": { "get": { "tags": [ "Tasks" ], "summary": "Télécharger le résultat", "operationId": "getTaskResult", "description": "Téléchargez l’artefact validé. Simple récupération : cet appel ne génère, ne répare et ne valide rien.\n\n- `download=xml` : UBL (`XRECHNUNG`, `EN16931`, `UBL`) ou CII (`CII`, `ZUGFERD`). Toujours l’artefact principal pour les formats XML.\n- `download=pdf` : PDF hybride ZUGFeRD/Factur-X pour `ZUGFERD` ; un rendu au mieux pour les autres formats.\n- Pendant le traitement : `202 TASK_NOT_READY`. Tâche en échec : son erreur typée (`422 VALIDATION_FAILED`, `500 TASK_FAILED`, `503 ...`).\n- Limite de débit : 60/min et 1 000/h par clé API.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/DownloadQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "Les octets de l’artefact. Les en-têtes `X-*` décrivent les octets livrés ; enregistrez-les pour votre archive.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" }, "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" }, "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "X-Artifact-Sha256": { "$ref": "#/components/headers/XArtifactSha256" }, "X-Validation-Proof-Id": { "$ref": "#/components/headers/XValidationProofId" }, "X-Artifact-Proof-Id": { "$ref": "#/components/headers/XArtifactProofId" }, "X-Artifact-State": { "$ref": "#/components/headers/XArtifactState" }, "X-Validation-State": { "$ref": "#/components/headers/XValidationState" }, "X-Proof-Status": { "$ref": "#/components/headers/XProofStatus" }, "X-Validator-Bundle-Id": { "$ref": "#/components/headers/XValidatorBundleId" } }, "content": { "application/xml": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "202": { "$ref": "#/components/responses/TaskNotReady" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TaskResultNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowedTaskPath" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } }, "/tasks/{task_id}/validation-report": { "get": { "tags": [ "Tasks" ], "summary": "Télécharger le rapport de validation", "operationId": "getTaskValidationReport", "description": "Téléchargez le rapport de validation lié à l’artefact livré.\n\n- `download=html` pour une lecture humaine ; `download=xml` pour le rapport KoSIT, ou le XML `validation-evidence` de Factur-X (`source=\"facturx_php\"`, pas au format KoSIT).\n- Les en-têtes `X-Artifact-*` décrivent l’artefact de résultat validé, pas les octets du rapport.\n- La preuve Factur-X atteste uniquement la validation du XML stocké, pas la fidélité à la source ni la conformité PDF/A.\n- Limite de débit : 30/min et 500/h par clé API.", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" }, { "$ref": "#/components/parameters/ValidationReportDownloadQuery" }, { "$ref": "#/components/parameters/XCorrelationIdHeader" } ], "responses": { "200": { "description": "Le rapport.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/ContentDisposition" }, "Cache-Control": { "$ref": "#/components/headers/CacheControlNoStore" }, "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "X-Artifact-Sha256": { "description": "SHA-256 de l’artefact de résultat validé (désigné par `X-Report-Source-Artifact-Format`), pas des octets du rapport. Ne l’utilisez pas comme somme de contrôle du rapport.", "schema": { "type": "string" } }, "X-Validation-Proof-Id": { "$ref": "#/components/headers/XValidationProofId" }, "X-Artifact-Proof-Id": { "$ref": "#/components/headers/XArtifactProofId" }, "X-Artifact-State": { "$ref": "#/components/headers/XArtifactState" }, "X-Validation-State": { "$ref": "#/components/headers/XValidationState" }, "X-Proof-Status": { "$ref": "#/components/headers/XProofStatus" }, "X-Validator-Bundle-Id": { "$ref": "#/components/headers/XValidatorBundleId" }, "X-Task-Id": { "description": "Tâche du rapport.", "schema": { "type": "string", "format": "uuid" } }, "X-Validation-Report-Proof-Id": { "description": "Enregistrement de preuve qui a fourni le rapport. Égal à `X-Validation-Proof-Id` pour les artefacts XML.", "schema": { "type": "string" } }, "X-Validation-Report-Content-Type": { "description": "Type de média du rapport.", "schema": { "type": "string" } }, "X-Validation-Report-Format": { "description": "Format du rapport renvoyé.", "schema": { "type": "string", "enum": [ "html", "xml" ] } }, "X-Validation-Report-Source": { "description": "Origine du rapport, par exemple `artifact`, `embedded_xml` ou `source_xml`.", "schema": { "type": "string" } }, "X-Report-Source-Artifact-Format": { "description": "Artefact de résultat auquel le rapport est lié.", "schema": { "type": "string", "enum": [ "xml", "pdf" ] } } }, "content": { "text/html": { "schema": { "type": "string" } }, "application/xml": { "schema": { "type": "string" } } } }, "202": { "$ref": "#/components/responses/TaskNotReady" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/ValidationReportNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowedTaskPath" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/ProxyErrorBadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/ProxyErrorGatewayTimeout" } } } } }, "components": { "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "icp_... API key", "description": "Clé API de production (`icp_...`) issue de la page de profil. Conservez-la côté serveur. Absente → `401 AUTHENTICATION_REQUIRED` ; inconnue ou révoquée → `401 INVALID_API_KEY`." } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obligatoire sur les deux endpoints POST. Réutilisez la même clé avec le même payload à chaque nouvelle tentative ; une relecture renvoie la réponse `202` d’origine sans seconde facturation. Portée : tenant + endpoint, conservée 24 h. Absente → `400 IDEMPOTENCY_KEY_REQUIRED` ; mal formée → `400 INVALID_IDEMPOTENCY_KEY` ; même clé avec un autre payload → `409 IDEMPOTENCY_CONFLICT`.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$" }, "example": "sf-a0B5g00000XyZ12-v1" }, "XCorrelationIdHeader": { "name": "X-Correlation-ID", "in": "header", "required": false, "description": "UUID facultatif pour le traçage. Une valeur absente ou qui n’est pas un UUID est remplacée par un UUID généré par le serveur. Renvoyé dans l’en-tête de réponse `X-Correlation-ID` ; indiquez-le au support.", "schema": { "type": "string", "format": "uuid" } }, "TaskIdPath": { "name": "task_id", "in": "path", "required": true, "description": "`task_id` issu de la réponse `202`. Pas un UUID → `400 BAD_REQUEST`.", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, "DownloadQuery": { "name": "download", "in": "query", "required": true, "description": "Artefact à télécharger (insensible à la casse). Absent → `400 DOWNLOAD_FORMAT_REQUIRED` ; autres valeurs → `400 INVALID_DOWNLOAD_FORMAT`.", "schema": { "type": "string", "enum": [ "xml", "pdf" ] }, "example": "xml" }, "ValidationReportDownloadQuery": { "name": "download", "in": "query", "required": true, "description": "`html` pour un rapport lisible, `xml` pour le rapport lisible par machine. Absent → `400 DOWNLOAD_FORMAT_REQUIRED` ; autres valeurs → `400 INVALID_DOWNLOAD_FORMAT`.", "schema": { "type": "string", "enum": [ "html", "xml" ] }, "example": "html" }, "IncludeValidationReportHtmlQuery": { "name": "include_validation_report_html", "in": "query", "required": false, "description": "`true` ajoute le HTML nettoyé du rapport de validation dans `validation_report_html`. Valeurs autres que `true`/`false` → `400 INVALID_QUERY_PARAMETER`.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } }, "headers": { "XCorrelationId": { "description": "ID de traçage de cette requête. Journalisez-le et indiquez-le au support.", "schema": { "type": "string", "format": "uuid" } }, "IdempotencyReplayed": { "description": "`true` lorsque la réponse est la relecture d’une requête antérieure avec le même Idempotency-Key.", "schema": { "type": "string", "enum": [ "true" ] } }, "RetryAfter": { "description": "Secondes à attendre avant la prochaine tentative. Envoyé avec 429 et avec 503 SERVER_BUSY.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimitMinute": { "description": "Limite par minute du compteur de cet endpoint. Envoyé uniquement avec 429.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimitHour": { "description": "Limite par heure du compteur de cet endpoint. Envoyé uniquement avec 429.", "schema": { "type": "integer", "minimum": 1 } }, "ContentDisposition": { "description": "Nom du fichier joint, par exemple `attachment; filename=invoice.xml`.", "schema": { "type": "string" } }, "CacheControlNoStore": { "description": "Toujours `no-store`.", "schema": { "type": "string", "enum": [ "no-store" ] } }, "XArtifactSha256": { "description": "SHA-256 des octets de l’artefact livré.", "schema": { "type": "string" } }, "XValidationProofId": { "description": "Enregistrement de preuve qui lie l’artefact à son exécution de validation.", "schema": { "type": "string" } }, "XArtifactProofId": { "description": "Enregistrement de preuve au niveau de l’artefact.", "schema": { "type": "string" } }, "XArtifactState": { "description": "Statut de conformité de l’artefact. Toujours `compliant` pour un artefact livré par l’API.", "schema": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ] } }, "XValidationState": { "description": "Résultat de la validation. Toujours `passed` pour un artefact livré par l’API.", "schema": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ] } }, "XProofStatus": { "description": "Actualité de la preuve.", "schema": { "type": "string" } }, "XValidatorBundleId": { "description": "Jeu de règles du validateur utilisé pour la preuve.", "schema": { "type": "string" } }, "AllowConversionPath": { "description": "Méthodes autorisées.", "schema": { "type": "string", "enum": [ "POST, OPTIONS" ] } }, "AllowTaskPath": { "description": "Méthodes autorisées.", "schema": { "type": "string", "enum": [ "GET, OPTIONS" ] } } }, "responses": { "BadRequest": { "description": "Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "idempotencyKeyRequired": { "summary": "Missing Idempotency-Key", "value": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "Idempotency-Key header is required for write endpoints", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "downloadRequired": { "summary": "Missing download parameter", "value": { "code": "DOWNLOAD_FORMAT_REQUIRED", "message": "download query parameter is required. Supported values: xml, pdf.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "field": "download" } } }, "bundleInvoiceIdMismatch": { "summary": "Split data_file parts carry different invoice numbers", "value": { "code": "INVALID_UPLOAD", "message": "Structured data bundle contains multiple invoice IDs", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "reason": "bundle_invoice_id_mismatch", "invoice_ids": [ "INV-HEADER", "INV-LINE" ], "files": { "invoice-header.xlsx": [ "INV-HEADER" ], "invoice-lines.xlsx": [ "INV-LINE" ] } } } }, "badTaskId": { "summary": "task_id is not a UUID", "value": { "code": "BAD_REQUEST", "message": "task_id must be a valid UUID", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "Unauthorized": { "description": "Échec de l’authentification. Pas de nouvelle tentative.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "WWW-Authenticate": { "description": "Toujours `Bearer`.", "schema": { "type": "string", "enum": [ "Bearer" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missingToken": { "summary": "No bearer token", "value": { "code": "AUTHENTICATION_REQUIRED", "message": "Authorization bearer token is required", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "invalidKey": { "summary": "Unknown or revoked key", "value": { "code": "INVALID_API_KEY", "message": "Invalid API key", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "PaymentRequired": { "description": "`402 INSUFFICIENT_API_CREDITS`. Pas de nouvelle tentative : achetez un paquet de crédits prépayés ou attendez le prochain quota mensuel. Deux structures de `details` ; lisez les clés présentes.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError" }, { "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError" } ] }, "examples": { "prepaidOnly": { "summary": "Prepaid-only account without credits", "value": { "code": "INSUFFICIENT_API_CREDITS", "message": "Prepaid API credits are required for External API conversions", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "context", "remaining": 0, "minimum_purchase": 100 } } }, "allowanceExhausted": { "summary": "Included allowance and credits used up", "value": { "code": "INSUFFICIENT_API_CREDITS", "message": "Included API allowance is exhausted and prepaid API credits are required", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "context", "included_remaining": 0, "credit_remaining": 0, "shortfall": 1, "minimum_purchase": 100 } } } } } } }, "Forbidden": { "description": "`403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : contactez le support.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notEnabled": { "summary": "No API access", "value": { "code": "API_NOT_ENABLED_FOR_TENANT", "message": "External API is not enabled", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "MethodNotAllowedConversionPath": { "description": "`405 METHOD_NOT_ALLOWED` : les chemins de conversion acceptent POST ; OPTIONS renvoie 204. Le backend renvoie une erreur JSON avec `correlation_id` pour les méthodes non prises en charge. HEAD ne renvoie aucun corps.", "headers": { "Allow": { "$ref": "#/components/headers/AllowConversionPath" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeError" }, "example": { "code": "METHOD_NOT_ALLOWED", "message": "Use POST for this endpoint." } } } }, "MethodNotAllowedTaskPath": { "description": "`405 METHOD_NOT_ALLOWED` : les chemins de tâche acceptent uniquement GET. Envoyé par le proxy edge ; le corps ne contient donc pas de `correlation_id`.", "headers": { "Allow": { "$ref": "#/components/headers/AllowTaskPath" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeError" }, "example": { "code": "METHOD_NOT_ALLOWED", "message": "Use GET for this endpoint." } } } }, "Conflict": { "description": "Conflit d’idempotence. `IDEMPOTENCY_IN_PROGRESS` : réessayez la même clé après un court délai (une réservation bloquée est libérée après 15 min). `IDEMPOTENCY_CONFLICT` et `IDEMPOTENCY_REPLAY_EXPIRED` : utilisez une nouvelle clé.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "inProgress": { "summary": "Retry the same key later", "value": { "code": "IDEMPOTENCY_IN_PROGRESS", "message": "Request with this idempotency key is already being processed", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "idempotency_in_progress", "state": "in_progress" } } }, "conflict": { "summary": "Same key, different payload", "value": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key was already used with a different payload", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "idempotency_conflict", "reason": "different_payload_for_same_key" } } }, "replayExpired": { "summary": "Original task past retention", "value": { "code": "IDEMPOTENCY_REPLAY_EXPIRED", "message": "The original conversion task for this idempotency key is no longer available. Start a new conversion with a new Idempotency-Key.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "context", "reason": "task_expired_or_removed", "task_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } } }, "PayloadTooLarge": { "description": "Requête trop volumineuse. Non réessayable : envoyez une requête plus petite. Les uploads vont directement au backend. Les limites de fichier et de corps multipart renvoient JSON `413 PAYLOAD_TOO_LARGE` avec `details.limit_bytes`. Limites par défaut : fichier source ou support 20 MB, parties de données structurées 2 MB au total ; corps multipart complet 21 MB pour un document ou 23 MB pour les données structurées (dont 1 MB supplémentaire).", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": "PAYLOAD_TOO_LARGE", "message": "Uploaded data_file payload exceeds max allowed total size (2000000 bytes)", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "limit_bytes": 2000000, "received_bytes": 2150000 } } }, "text/plain": { "schema": { "type": "string" }, "example": "Request Entity Too Large\n\nFUNCTION_PAYLOAD_TOO_LARGE" } } }, "UnsupportedMediaType": { "description": "`415 INVALID_UPLOAD` : envoyez `multipart/form-data`. Pas de nouvelle tentative.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notMultipart": { "summary": "JSON body instead of multipart", "value": { "code": "INVALID_UPLOAD", "message": "Unable to parse multipart request body. Send multipart/form-data with a file field named 'file'.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "expected_content_type": "multipart/form-data", "required_file_field": "file", "received_content_type": "application/json", "docs_url": "https://www.invoice-converter.com/en/developer-api" } } } } } } }, "UploadFailed": { "description": "La validation de l’upload ou des options de la requête a échoué. Pas de nouvelle tentative : corrigez la requête. Codes : `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (valeur de contexte invalide), `ZUGFERD_SOURCE_PDF_REQUIRED`.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalidProfile": { "summary": "Unknown profile name", "value": { "code": "INVALID_PROFILE", "message": "Invalid profile.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "profile": "XRECHNUNG_2024", "allowed_profiles": [ "EN16931", "PEPPOL", "XRECHNUNG", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ] } } }, "invalidContext": { "summary": "Unknown delivery_channel", "value": { "code": "UPLOAD_FAILED", "message": "Invalid delivery_channel. Allowed values: DIRECT_XML, EMAIL_PDF, PEPPOL, PORTAL, UNKNOWN.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "zugferdNeedsPdf": { "summary": "format=ZUGFERD with a DOCX/TXT source", "value": { "code": "ZUGFERD_SOURCE_PDF_REQUIRED", "message": "ZUGFeRD PDF output requires a PDF source upload. Upload a PDF source or request CII, EN16931, UBL, or XRechnung XML output for DOCX/TXT input.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "field": "file", "format": "ZUGFERD", "reason": "source_document_is_not_pdf", "received_source_format": "docx", "required_source_format": "pdf", "xml_only_formats": [ "CII", "EN16931", "UBL", "XRECHNUNG" ] } } } } } } }, "TooManyRequests": { "description": "`429 RATE_LIMITED`. Nouvelle tentative possible : attendez `Retry-After` secondes et réessayez avec le même Idempotency-Key. Les limites s’appliquent par clé API et par endpoint, sur des fenêtres fixes de minute et d’heure calendaires. Les requêtes refusées ne sont pas comptées.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit-Minute": { "$ref": "#/components/headers/XRateLimitLimitMinute" }, "X-RateLimit-Limit-Hour": { "$ref": "#/components/headers/XRateLimitLimitHour" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rateLimited": { "summary": "Minute bucket of the convert endpoint exhausted", "value": { "code": "RATE_LIMITED", "message": "Rate limit exceeded", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "rate_limit", "minute_count": 30, "hour_count": 212, "limit_minute": 30, "limit_hour": 500 } } } } } } }, "ConvertServiceUnavailable": { "description": "Temporairement indisponible. Réessayez avec le même Idempotency-Key. `SERVER_BUSY` : la file de traitement est pleine ; attendez `Retry-After` secondes. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (autre échec d’acceptation) : réessayez avec un backoff.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "serverBusy": { "summary": "Processing queue full (wait Retry-After, same key)", "value": { "code": "SERVER_BUSY", "message": "PDF processing queue is full. Please retry shortly.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "uploadNotAccepted": { "summary": "Upload not accepted (retry with the same key)", "value": { "code": "UPLOAD_FAILED", "message": "Failed to upload invoice", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ServiceUnavailable": { "description": "Temporairement indisponible. Réessayez avec un backoff : `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Démarrez plutôt une NOUVELLE conversion : `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validatorUnavailable": { "summary": "Validator unavailable (retry the download)", "value": { "code": "AUTHORITATIVE_VALIDATION_UNAVAILABLE", "message": "Authoritative validation is temporarily unavailable. Retry later.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "extractionIncomplete": { "summary": "Start a new conversion", "value": { "code": "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "message": "Invoice extraction was incomplete. Start a new conversion to retry.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "dependency", "code": "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "dependency": "parallel_extraction", "stage": "extraction", "retryable": true, "same_task_retryable": false, "recovery": "start_new_conversion", "failed_groups": [ "line_items", "payment" ] } } } } } } }, "InternalError": { "description": "Erreur côté serveur. Par défaut, une 500 ne permet pas de nouvelle tentative. `TASK_FAILED` : lisez `details.code` ; seul `details.retryable: true` autorise une nouvelle tentative, et uniquement sous forme de NOUVELLE conversion avec un nouvel Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED` : faites remonter le problème. `UPLOAD_FAILED` lors de l’upload : réessayez avec la même clé.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "multipleInvoices": { "summary": "Terminal: split the document", "value": { "code": "TASK_FAILED", "message": "The conversion failed before a compliant artifact could be issued.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "code": "MULTIPLE_INVOICES_IN_DOCUMENT", "classification": "multiple_invoices", "message": "Document contains multiple invoices", "category": "extraction", "retryable": false, "can_review": false, "recovery_hint": "Split the PDF into one file per invoice and start a separate conversion for each invoice." } } }, "providerError": { "summary": "Retryable as a new conversion", "value": { "code": "TASK_FAILED", "message": "The conversion failed before a compliant artifact could be issued.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "code": "PROVIDER_ERROR", "message": "Extraction provider timed out", "category": "extraction", "retryable": true, "can_review": false, "recovery_hint": "Retry the extraction. The provider timed out before returning structured data." } } }, "invariantFailed": { "summary": "Escalate", "value": { "code": "INTERNAL_ARTIFACT_INVARIANT_FAILED", "message": "The completed task has no safe stored artifact for the requested download.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ProxyErrorBadGateway": { "description": "`502 PROXY_ERROR` : le proxy edge n’a pas pu joindre le backend. Réessayez avec un backoff et le même Idempotency-Key.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "proxyError": { "summary": "Transport failure", "value": { "code": "PROXY_ERROR", "message": "Proxy request failed", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ProxyErrorGatewayTimeout": { "description": "`504 PROXY_ERROR` : le backend n’a pas répondu à temps. Réessayez avec un backoff et le même Idempotency-Key.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "proxyTimeout": { "summary": "Transport timeout", "value": { "code": "PROXY_ERROR", "message": "Upstream timeout", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "TaskNotReady": { "description": "`202 TASK_NOT_READY` : traitement en cours. Le corps est une enveloppe d’erreur, pas un fichier. Continuez à interroger le statut de la tâche.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notReady": { "summary": "Still processing", "value": { "code": "TASK_NOT_READY", "message": "Strict conversion is still processing. No validated artifact is available yet.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "TaskNotFound": { "description": "`404 TASK_NOT_FOUND` : tâche inconnue, tâche d’un autre tenant, ou supprimée 24 h après la fin. Pas de nouvelle tentative.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notFound": { "summary": "Unknown or expired task", "value": { "code": "TASK_NOT_FOUND", "message": "Task not found", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "TaskResultNotFound": { "description": "`404 TASK_NOT_FOUND` : tâche inconnue, tâche d’un autre tenant, ou supprimée 24 h après la fin. `404 TASK_RESULT_FAILED` : la tâche existe, mais ses données de résultat sont indisponibles ; faites remonter le problème avec l’ID de corrélation. Pas de nouvelle tentative.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "notFound": { "summary": "Unknown or expired task", "value": { "code": "TASK_NOT_FOUND", "message": "Task not found", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "resultUnavailable": { "summary": "Result data unavailable", "value": { "code": "TASK_RESULT_FAILED", "message": "Task metadata unavailable for file download", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ValidationReportNotFound": { "description": "`404 TASK_NOT_FOUND` (tâche inconnue ou expirée) ou `404 VALIDATION_REPORT_NOT_FOUND` (aucun rapport lié à l’artefact actuel ; `details.reason`). Pas de nouvelle tentative.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "reportNotFound": { "summary": "No report for the current artifact", "value": { "code": "VALIDATION_REPORT_NOT_FOUND", "message": "No validation report is available for the current validated artifact.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "validation_report", "reason": "proof_not_found" } } }, "taskNotFound": { "summary": "Unknown task", "value": { "code": "TASK_NOT_FOUND", "message": "Task not found", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } } }, "ValidationFailed": { "description": "La facture ne peut pas être émise. Pas de nouvelle tentative : corrigez les données et démarrez une nouvelle conversion. Codes : `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validationFailed": { "summary": "Missing Leitweg-ID for XRechnung", "value": { "code": "VALIDATION_FAILED", "message": "The conversion failed validation. No compliant artifact was issued.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "validation", "items": [ { "field": "BuyerReference", "rule_id": "BR-DE-15", "severity": "error", "source": "task-result-download", "suggestion": "Provide Leitweg-ID / BuyerReference." } ] } } }, "sourcePdfIncompatible": { "summary": "Source PDF cannot carry the hybrid", "value": { "code": "ZUGFERD_SOURCE_PDF_INCOMPATIBLE", "message": "The source PDF is not compatible with strict ZUGFeRD generation.", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "details": { "type": "artifact_generation", "stage": "zugferd_pdf_merge", "bridge_status": 422 } } } } } } }, "Gone": { "description": "410 ACCOUNT_DELETED. La clé API s’authentifie toujours, mais son compte a été supprimé. La suppression est définitive : la réponse est donc 410 Gone sur chaque chemin qui la signale. Pas de nouvelle tentative. Une clé révoquée renvoie plutôt 401 INVALID_API_KEY.", "headers": { "X-Correlation-ID": { "$ref": "#/components/headers/XCorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": "ACCOUNT_DELETED", "message": "The account for this API key was deleted", "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } } }, "schemas": { "ConvertInvoiceRequest": { "type": "object", "required": [ "file", "format" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Le document de facture : `.pdf`, `.docx` ou `.txt`, une facture par fichier. `.doc`, `.rtf` et les images sont rejetés (`400 INVALID_UPLOAD`). `format=ZUGFERD` exige un PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`)." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Format de sortie cible. Obligatoire ; il n’y a pas de valeur par défaut. Comparé sans tenir compte de la casse. Absent → `400 FORMAT_REQUIRED` ; inconnu → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Jeu de règles par rapport auquel l’artefact est validé. Facultatif : chaque `format` a une valeur par défaut (voir le tableau de l’opération). Comparé sans tenir compte de la casse. Alias : `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED` ; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931` ; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Non accepté pour ce format → `422 OUTPUT_PROFILE_CONFLICT` ; nom inconnu → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "Pays de la transaction selon ISO 3166-1 alpha-2, par exemple `DE`. Contexte facultatif. Invalide → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Indication de contexte facultative. Invalide → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Indication de contexte facultative : `EMAIL_PDF` pour une transmission en PDF hybride, `DIRECT_XML` pour une intégration XML directe, `PEPPOL` pour une transmission via le réseau. Invalide → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Votre référence de facture ou de traitement. Renvoyée telle quelle dans la réponse 202 et dans le statut de la tâche. Pas de caractères de contrôle. `external_invoice_id` est accepté comme alias ; si les deux sont envoyés, ils doivent être identiques, sinon `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Libellé de l’ERP ou du système de facturation appelant. Renvoyé tel quel dans la réponse 202 et dans le statut de la tâche.", "examples": [ "salesforce" ] }, "use_embedded_xml": { "type": "boolean", "default": false, "description": "Utilise le XML Factur-X/ZUGFeRD/XRechnung intégré dans le PDF comme source d’extraction. Par défaut `false` : le XML intégré est ignoré et le document visible est lu." }, "email_input": { "type": "string", "maxLength": 10000, "description": "Instructions en texte libre pour l’extraction, dans n’importe quelle langue (source PDF uniquement). Non combinable avec `use_embedded_xml=true`. Fait partie de l’identité d’idempotence. Invalide → `400 INVALID_EMAIL_INPUT`.", "examples": [ "Use purchase order number PO-42." ] }, "use_seller_master_data": { "type": "boolean", "description": "Applique les données de base du vendeur. Omis : la valeur par défaut du compte s’applique. `false` : ignore les données vendeur enregistrées pour cette requête. `true` : applique les données enregistrées et `seller_master_data`." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "Chaîne contenant un objet JSON (schéma : `SellerMasterData`). Appliquée uniquement lorsque `use_seller_master_data=true`. Chaque valeur fournie remplace la valeur extraite du vendeur ou du paiement ; les clés absentes laissent la facture inchangée. Invalide → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false }, "ConvertStructuredInvoiceRequest": { "type": "object", "required": [ "pdf_file", "data_file", "format" ], "properties": { "pdf_file": { "type": "string", "format": "binary", "description": "PDF support. Pour `ZUGFERD`, le XML validé y est intégré ; pour les formats XML, il est conservé comme PDF original. Il ne fournit jamais de données de facture." }, "data_file": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "binary" } } ], "description": "Données de facture : `.json`, `.csv`, `.xml`, `.xlsx` ou `.txt` (≤ 2 MB au total). Le JSON canonique (au premier niveau ou encapsulé dans `invoice_data`), les parties JSON canoniques cohérentes et un fichier XML UBL 2.1 Invoice / CII D16B sont mappés sans IA ; les autres formats utilisent le mappage par IA. Les champs canoniques inconnus et les données contradictoires de l’ensemble renvoient `400 INVALID_UPLOAD`. Répétez la partie pour une facture répartie sur plusieurs fichiers ; toutes les parties doivent avoir le même numéro de facture et les lignes canoniques des ID explicites et uniques. Schéma : https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. Les noms de champs `data_files` et `data_files[]` sont acceptés comme alias." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Format de sortie cible. Obligatoire ; il n’y a pas de valeur par défaut. Comparé sans tenir compte de la casse. Absent → `400 FORMAT_REQUIRED` ; inconnu → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Jeu de règles par rapport auquel l’artefact est validé. Facultatif : chaque `format` a une valeur par défaut (voir le tableau de l’opération). Comparé sans tenir compte de la casse. Alias : `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED` ; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931` ; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Non accepté pour ce format → `422 OUTPUT_PROFILE_CONFLICT` ; nom inconnu → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "Pays de la transaction selon ISO 3166-1 alpha-2, par exemple `DE`. Contexte facultatif. Invalide → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Indication de contexte facultative. Invalide → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Indication de contexte facultative : `EMAIL_PDF` pour une transmission en PDF hybride, `DIRECT_XML` pour une intégration XML directe, `PEPPOL` pour une transmission via le réseau. Invalide → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Votre référence de facture ou de traitement. Renvoyée telle quelle dans la réponse 202 et dans le statut de la tâche. Pas de caractères de contrôle. `external_invoice_id` est accepté comme alias ; si les deux sont envoyés, ils doivent être identiques, sinon `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Libellé de l’ERP ou du système de facturation appelant. Renvoyé tel quel dans la réponse 202 et dans le statut de la tâche.", "examples": [ "salesforce" ] }, "use_seller_master_data": { "type": "boolean", "description": "Applique les données de base du vendeur. Omis : la valeur par défaut du compte s’applique. `false` : ignore les données vendeur enregistrées pour cette requête. `true` : applique les données enregistrées et `seller_master_data`." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "Chaîne contenant un objet JSON (schéma : `SellerMasterData`). Appliquée uniquement lorsque `use_seller_master_data=true`. Chaque valeur fournie remplace la valeur extraite du vendeur ou du paiement ; les clés absentes laissent la facture inchangée. Invalide → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false }, "StructuredInvoiceData": { "additionalProperties": false, "properties": { "CustomizationID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Customizationid" }, "ProfileID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profileid" }, "ID": { "title": "Id", "type": "string" }, "IssueDate": { "title": "Issuedate", "type": "string" }, "DueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Duedate" }, "TaxCurrencyCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxcurrencycode" }, "TaxPointDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxpointdate" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "InvoiceTypeCode": { "title": "Invoicetypecode", "type": "string" }, "DocumentCurrencyCode": { "title": "Documentcurrencycode", "type": "string" }, "OrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OrderReference" }, { "type": "null" } ], "default": null }, "SalesOrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SalesOrderReference" }, { "type": "null" } ], "default": null }, "ContractDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ContractDocumentReference" }, { "type": "null" } ], "default": null }, "ProjectReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ProjectReference" }, { "type": "null" } ], "default": null }, "TenderOrLotReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TenderOrLotReference" }, { "type": "null" } ], "default": null }, "DespatchDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Despatchdocumentreference" }, "PrecedingInvoiceReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_PrecedingInvoiceReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Precedinginvoicereference" }, "AdditionalDocumentReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AdditionalDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Additionaldocumentreference" }, "AllowanceCharge": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" }, "AccountingSupplierParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingSupplierParty" }, "AccountingCustomerParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingCustomerParty" }, "PayeeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeParty" }, { "type": "null" } ], "default": null }, "TaxRepresentativeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativeParty" }, { "type": "null" } ], "default": null }, "Delivery": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Delivery" }, "DeliveryTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryTerms" }, { "type": "null" } ], "default": null }, "PaymentMeans": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Paymentmeans" }, "PaymentTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentTerms" }, { "type": "null" } ], "default": null }, "TaxTotal": { "$ref": "#/components/schemas/StructuredInvoice_TaxTotal" }, "LegalMonetaryTotal": { "$ref": "#/components/schemas/StructuredInvoice_LegalMonetaryTotal" }, "InvoiceLine": { "items": { "$ref": "#/components/schemas/StructuredInvoice_InvoiceLine" }, "title": "Invoiceline", "type": "array" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "BuyerReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyerreference" }, "BuyerAccountingReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyeraccountingreference" } }, "required": [ "ID", "IssueDate", "InvoiceTypeCode", "DocumentCurrencyCode", "AccountingSupplierParty", "AccountingCustomerParty", "TaxTotal", "LegalMonetaryTotal", "InvoiceLine" ], "title": "Invoice Converter structured invoice JSON", "type": "object", "description": "JSON canonique de facture pour POST /api/v1/invoices:convert-structured. Les noms d’éléments suivent UBL 2.1 / EN 16931. Envoyez une facture sous la forme d’un seul data_file JSON, au premier niveau ou encapsulé dans un objet 'invoice_data' ; ce format est mappé sans interprétation par IA. La détection exige au moins 3 des clés de premier niveau ID, IssueDate, InvoiceTypeCode, DocumentCurrencyCode, AccountingSupplierParty, AccountingCustomerParty, TaxTotal, LegalMonetaryTotal, InvoiceLine, dont ID, InvoiceLine ou LegalMonetaryTotal. Téléchargeable : https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json", "examples": [ { "ID": "RE-2026-00123", "IssueDate": "2026-09-30", "DueDate": "2026-10-30", "InvoiceTypeCode": "380", "DocumentCurrencyCode": "EUR", "BuyerReference": "04011000-1234512345-06", "OrderReference": { "ID": "PO-4711" }, "InvoicePeriod": { "StartDate": "2026-09-01", "EndDate": "2026-09-30" }, "Note": "Monthly subscription September 2026", "AccountingSupplierParty": { "Party": { "EndpointID": { "#text": "billing@seller.example", "@schemeID": "EM" }, "PartyName": { "Name": "Seller GmbH" }, "PostalAddress": { "StreetName": "Hauptstraße 1", "CityName": "Berlin", "PostalZone": "10115", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE123456789", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Seller GmbH", "CompanyID": "HRB 12345" }, "Contact": { "Name": "Erika Muster", "Telephone": "+49 30 123456", "ElectronicMail": "erika@seller.example" } } }, "AccountingCustomerParty": { "Party": { "EndpointID": { "#text": "04011000-1234512345-06", "@schemeID": "0204" }, "PartyName": { "Name": "Buyer AG" }, "PostalAddress": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE987654321", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Buyer AG" } } }, "Delivery": { "ActualDeliveryDate": "2026-09-30", "DeliveryLocation": { "Address": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } } } }, "PaymentMeans": { "PaymentMeansCode": "58", "PaymentID": "RE-2026-00123", "PayeeFinancialAccount": { "ID": "DE02120300000000202051", "Name": "Seller GmbH", "FinancialInstitutionBranch": { "ID": "BYLADEM1001" } } }, "PaymentTerms": { "Note": "Zahlbar innerhalb von 30 Tagen ohne Abzug", "NetDays": 30 }, "TaxTotal": { "TaxAmount": "285.00", "TaxSubtotal": [ { "TaxableAmount": "1500.00", "TaxAmount": "285.00", "TaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } } ] }, "LegalMonetaryTotal": { "LineExtensionAmount": "1500.00", "TaxExclusiveAmount": "1500.00", "TaxInclusiveAmount": "1785.00", "PayableAmount": "1785.00" }, "InvoiceLine": [ { "ID": "1", "InvoicedQuantity": 10, "unitCode": "HUR", "LineExtensionAmount": "1200.00", "Item": { "Name": "Consulting", "SellersItemIdentification": { "ID": "SRV-01" }, "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "120.00" } }, { "ID": "2", "InvoicedQuantity": 2, "unitCode": "C62", "LineExtensionAmount": "300.00", "Item": { "Name": "Software licence", "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "150.00" } } ] } ] }, "SellerMasterData": { "type": "object", "description": "Valeurs par défaut du vendeur, envoyées sous forme de chaîne JSON dans le champ de formulaire `seller_master_data`. Chaque clé est facultative. `electronic_address` et `electronic_address_scheme` forment une paire : envoyez les deux ou aucune.", "properties": { "business_name": { "type": "string", "maxLength": 240, "description": "Raison sociale (BT-27)." }, "trading_name": { "type": "string", "maxLength": 240, "description": "Nom commercial (BT-28)." }, "street": { "type": "string", "description": "Rue et numéro (BT-35)." }, "additional_address": { "type": "string", "description": "Ligne d’adresse complémentaire (BT-36)." }, "postal_code": { "type": "string", "description": "Code postal (BT-38)." }, "city": { "type": "string", "description": "Ville (BT-37)." }, "country": { "type": "string", "description": "Code pays ISO 3166-1 alpha-2 (BT-40).", "examples": [ "DE" ] }, "vat_id": { "type": "string", "description": "Numéro de TVA (BT-31).", "examples": [ "DE123456789" ] }, "tax_number": { "type": "string", "description": "Numéro d’enregistrement fiscal (BT-32)." }, "electronic_address": { "type": "string", "description": "Adresse électronique (BT-34). Exige `electronic_address_scheme`." }, "electronic_address_scheme": { "type": "string", "description": "Schéma EAS de l’adresse électronique, par exemple `EM` ou `0204`." }, "contact_name": { "type": "string", "description": "Personne de contact (BT-41)." }, "contact_email": { "type": "string", "description": "E-mail du contact (BT-43)." }, "contact_phone": { "type": "string", "description": "Téléphone du contact (BT-42)." }, "payment_means_code": { "type": "string", "enum": [ "30", "42", "58" ], "description": "Code du moyen de paiement par virement (BT-81) : 30 virement, 42 paiement sur compte bancaire, 58 virement SEPA." }, "payment_iban": { "type": "string", "description": "IBAN du compte du bénéficiaire (BT-84)." }, "payment_bic": { "type": "string", "description": "BIC de la banque du bénéficiaire (BT-86)." }, "payment_account_name": { "type": "string", "description": "Nom du compte du bénéficiaire (BT-85)." }, "payment_terms_note": { "type": "string", "description": "Conditions de paiement sous forme de texte (BT-20)." } }, "additionalProperties": false, "examples": [ { "business_name": "Seller GmbH", "street": "Hauptstraße 1", "postal_code": "10115", "city": "Berlin", "country": "DE", "vat_id": "DE123456789", "electronic_address": "billing@seller.example", "electronic_address_scheme": "EM", "contact_name": "Erika Muster", "contact_email": "erika@seller.example", "contact_phone": "+49 30 123456", "payment_means_code": "58", "payment_iban": "DE02120300000000202051" } ] }, "ConvertAcceptedResponse": { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid", "description": "À utiliser pour tous les appels de tâche." }, "status": { "type": "string", "enum": [ "pending", "processing" ], "description": "`pending` : en file d’attente. `processing` : démarrée." }, "message": { "type": "string", "description": "Confirmation lisible par un humain. Ne basez pas votre logique dessus." }, "filename": { "type": [ "string", "null" ], "description": "Nom du document envoyé (ou du PDF support)." }, "pdf_filename": { "type": [ "string", "null" ], "description": "Nom du PDF support (endpoint structuré)." }, "data_filename": { "type": [ "string", "null" ], "description": "Nom du premier fichier de données (endpoint structuré)." }, "data_filenames": { "type": "array", "items": { "type": "string" }, "description": "Noms de tous les fichiers de données (endpoint structuré)." }, "data_file_count": { "type": "integer", "minimum": 1, "description": "Nombre de fichiers de données (endpoint structuré)." }, "file_size": { "type": "integer", "minimum": 0, "description": "Total des octets acceptés." }, "pdf_file_size": { "type": "integer", "minimum": 0, "description": "Octets du PDF support (endpoint structuré)." }, "data_file_size": { "type": "integer", "minimum": 0, "description": "Total des octets des fichiers de données (endpoint structuré)." }, "correlation_id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string", "description": "URL relative à interroger." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Téléchargement habituel pour le format demandé : `pdf` pour ZUGFERD, sinon `xml`." }, "primary_result_url": { "type": "string", "description": "URL relative du résultat avec `download=`." }, "client_reference": { "type": "string", "description": "Reprise de `client_reference`." }, "source_system": { "type": "string", "description": "Reprise de `source_system`." } }, "additionalProperties": false }, "TaskStatusResponse": { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "`pending` : en file d’attente. `processing` : en cours. `completed` : un artefact validé existe. `failed` : état final, aucun artefact." }, "progress": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "Progression approximative en pourcentage. Ne l’utilisez pas pour planifier vos appels." }, "created_at": { "type": "string", "format": "date-time", "description": "Moment où la tâche a été acceptée (UTC)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Moment où la tâche a atteint `completed` ou `failed` (UTC)." }, "filename": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "object", "null" ], "additionalProperties": true, "description": "Résumé de l’échec lorsque `status=failed` : un message ou un objet avec `code`, `message`, `retryable`. À titre informatif ; `/result` renvoie l’enveloppe d’erreur typée." }, "correlation_id": { "type": "string", "format": "uuid", "description": "ID de traçage de cet appel de statut." }, "client_reference": { "type": [ "string", "null" ], "description": "Reprise de `client_reference`." }, "source_system": { "type": [ "string", "null" ], "description": "Reprise de `source_system`." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Téléchargement habituel pour le format demandé." }, "primary_result_url": { "type": "string", "description": "URL relative du résultat." }, "result_artifacts": { "$ref": "#/components/schemas/ResultArtifacts" }, "validation_report_html": { "$ref": "#/components/schemas/ValidationReportHtmlStatus" } }, "additionalProperties": false }, "ResultArtifacts": { "type": "object", "description": "Disponibilité du téléchargement par artefact.", "properties": { "xml": { "$ref": "#/components/schemas/ResultArtifactStatus" }, "pdf": { "$ref": "#/components/schemas/ResultArtifactStatus" } }, "additionalProperties": false }, "ResultArtifactStatus": { "type": "object", "required": [ "state", "download_url" ], "properties": { "state": { "type": "string", "enum": [ "cached", "not_ready", "validation_failed", "dependency_failed", "artifact_generation_rerun_required", "artifact_invariant_failed" ], "description": "`cached` : téléchargeable. `not_ready` : pas encore produit. `validation_failed` : problème bloquant dans les données ou le PDF source. `dependency_failed` : panne du validateur ou du stockage. `artifact_generation_rerun_required` : démarrez une nouvelle conversion. `artifact_invariant_failed` : faites remonter le problème avec l’ID de corrélation." }, "download_url": { "type": "string", "description": "URL relative de téléchargement." }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "artifact_state": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ], "description": "Statut de conformité. `compliant` pour chaque artefact livré par l’API." }, "validation_state": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ], "description": "Résultat de la validation. `passed` pour chaque artefact livré par l’API." } }, "additionalProperties": false }, "ValidationReportHtmlStatus": { "type": "object", "description": "Présent uniquement avec `include_validation_report_html=true`.", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "content_type": { "type": "string", "enum": [ "text/html; charset=utf-8" ] }, "html": { "type": "string", "description": "HTML nettoyé du rapport ; les chemins du serveur sont masqués." }, "source": { "type": "string", "description": "Par exemple `artifact`, `embedded_xml` ou `source_xml`." }, "source_result_format": { "type": "string", "enum": [ "xml", "pdf" ] }, "reason": { "type": "string", "description": "Raison pour laquelle aucun rapport n’est disponible, par exemple `task_not_completed`, `proof_not_found`, `artifact_not_current`." } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "description": "Chaque erreur JSON. Basez votre logique sur `code` ; pour `500 TASK_FAILED`, également sur `details.code` et `details.retryable`. Ne réessayez une écriture qu’avec le même Idempotency-Key.", "required": [ "code", "message", "correlation_id" ], "properties": { "code": { "type": "string", "enum": [ "AUTHENTICATION_REQUIRED", "INVALID_API_KEY", "API_NOT_ENABLED_FOR_TENANT", "ACCOUNT_DELETED", "INSUFFICIENT_API_CREDITS", "AUTH_SERVICE_UNAVAILABLE", "PLAN_TIER_CHECK_FAILED", "RATE_LIMIT_SERVICE_UNAVAILABLE", "API_CREDIT_SERVICE_UNAVAILABLE", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_REPLAY_EXPIRED", "FORMAT_REQUIRED", "INVALID_FORMAT", "INVALID_PROFILE", "OUTPUT_PROFILE_CONFLICT", "OUTPUT_PROFILE_REQUIRED", "CLIENT_REFERENCE_CONFLICT", "INVALID_CLIENT_METADATA", "INVALID_SELLER_MASTER_DATA", "INVALID_EMBEDDED_XML_POLICY", "INVALID_EMAIL_INPUT", "INVALID_UPLOAD", "PAYLOAD_TOO_LARGE", "UPLOAD_FAILED", "SERVER_BUSY", "ZUGFERD_SOURCE_PDF_REQUIRED", "METHOD_NOT_ALLOWED", "NOT_FOUND", "BAD_REQUEST", "INVALID_QUERY_PARAMETER", "DOWNLOAD_FORMAT_REQUIRED", "INVALID_DOWNLOAD_FORMAT", "TASK_NOT_READY", "TASK_NOT_FOUND", "TASK_STATUS_FAILED", "TASK_RESULT_FAILED", "TASK_FAILED", "VALIDATION_FAILED", "PROFILE_MISMATCH", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE", "ZUGFERD_CII_CONVERSION_FAILED", "ZUGFERD_PDF_GENERATION_FAILED", "XML_GENERATION_FAILED", "PDF_GENERATION_FAILED", "AUTHORITATIVE_VALIDATION_UNAVAILABLE", "ARTIFACT_GENERATION_RERUN_REQUIRED", "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "INTERNAL_ARTIFACT_INVARIANT_FAILED", "VALIDATION_REPORT_NOT_FOUND", "VALIDATION_REPORT_FAILED", "PROXY_ERROR" ], "x-enumDescriptions": { "AUTHENTICATION_REQUIRED": "401 · non · Envoyez `Authorization: Bearer `.", "INVALID_API_KEY": "401 · non · La clé est inconnue, révoquée ou mal formée. Corrigez-la ou renouvelez-la.", "API_NOT_ENABLED_FOR_TENANT": "403 · non · La clé est valide, mais le compte n’a pas accès à l’API externe. Contactez le support.", "ACCOUNT_DELETED": "410 · non · Le compte de cette clé API a été supprimé. La suppression est définitive. Une clé révoquée renvoie `INVALID_API_KEY`.", "INSUFFICIENT_API_CREDITS": "402 · non · Le quota et les crédits prépayés sont épuisés. Achetez un paquet de crédits ou attendez le mois suivant. Deux structures de `details`.", "AUTH_SERVICE_UNAVAILABLE": "503 · oui · L’authentification est temporairement indisponible. Réessayez avec un backoff et le même Idempotency-Key.", "PLAN_TIER_CHECK_FAILED": "503 · oui · Impossible de vérifier l’offre ou l’accès à l’API. Réessayez avec un backoff et le même Idempotency-Key.", "RATE_LIMIT_SERVICE_UNAVAILABLE": "503 · oui · Le service de limitation de débit est indisponible. Réessayez avec un backoff et le même Idempotency-Key.", "API_CREDIT_SERVICE_UNAVAILABLE": "503 · oui · La vérification des crédits et du quota est indisponible. Réessayez l’upload avec le même Idempotency-Key.", "RATE_LIMITED": "429 · oui · Attendez `Retry-After` secondes, puis réessayez avec le même Idempotency-Key.", "IDEMPOTENCY_KEY_REQUIRED": "400 · non · Envoyez un en-tête `Idempotency-Key` sur les deux endpoints POST.", "INVALID_IDEMPOTENCY_KEY": "400 · non · Utilisez 1–200 caractères conformes à `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`.", "IDEMPOTENCY_IN_PROGRESS": "409 · oui · La première requête avec cette clé est encore en cours. Réessayez la même clé après un court délai.", "IDEMPOTENCY_CONFLICT": "409 · non · La clé a été utilisée avec un autre payload. Utilisez une nouvelle clé pour un nouveau payload.", "IDEMPOTENCY_REPLAY_EXPIRED": "409 · non · La tâche d’origine a dépassé sa durée de conservation de 24 h. Démarrez une nouvelle conversion avec une nouvelle clé.", "FORMAT_REQUIRED": "400 · non · Envoyez `format` avec chaque requête de conversion.", "INVALID_FORMAT": "422 · non · Envoyez l’une des valeurs XRECHNUNG, ZUGFERD, EN16931, UBL, CII.", "INVALID_PROFILE": "422 · non · Nom de profil inconnu. `details.allowed_profiles` liste les valeurs acceptées.", "OUTPUT_PROFILE_CONFLICT": "422 · non · Le profil n’est pas accepté pour ce `format`. Envoyez un profil compatible ou omettez-le.", "OUTPUT_PROFILE_REQUIRED": "422 · non · Défensif ; la V1 attribue un profil par défaut à chaque format, ce code n’est donc pas attendu.", "CLIENT_REFERENCE_CONFLICT": "400 · non · `client_reference` et `external_invoice_id` diffèrent. Envoyez l’un des deux, ou la même valeur dans les deux.", "INVALID_CLIENT_METADATA": "400 · non · Limitez `client_reference`/`external_invoice_id` à 200 caractères et `source_system` à 100 caractères, sans caractères de contrôle.", "INVALID_SELLER_MASTER_DATA": "400 · non · Envoyez `seller_master_data` sous forme de chaîne contenant un objet JSON avec des clés prises en charge ; envoyez `electronic_address` et `electronic_address_scheme` ensemble.", "INVALID_EMBEDDED_XML_POLICY": "400 · non · Envoyez `use_embedded_xml` avec `true` ou `false`, ou omettez-le.", "INVALID_EMAIL_INPUT": "400 · non · Envoyez `email_input` une seule fois, ≤ 10 000 caractères, source PDF uniquement, pas avec `use_embedded_xml=true`, jamais sur convert-structured.", "INVALID_UPLOAD": "400/415 · non · Corrigez l’upload : multipart/form-data, type de fichier pris en charge, ≤ 20 parties de fichier et 50 champs, un seul numéro de facture dans toutes les parties `data_file` (`details.reason`).", "PAYLOAD_TOO_LARGE": "413 · non · Un fichier, le total de `data_file` ou le corps multipart dépasse sa limite backend. Consultez `details.limit_bytes` ; envoyez une requête plus petite.", "UPLOAD_FAILED": "422 · non : valeur `jurisdiction`/`transaction_scope`/`delivery_channel` invalide. 500/503 · oui : l’upload n’a pas été accepté, ou il a été accepté mais sa première réponse n’a pas pu être reconstituée. Réessayez avec un backoff et le même Idempotency-Key ; la nouvelle tentative renvoie la tâche acceptée.", "SERVER_BUSY": "503 · oui · La file de traitement est pleine. Attendez `Retry-After` secondes (15), puis réessayez avec le même Idempotency-Key.", "ZUGFERD_SOURCE_PDF_REQUIRED": "422 · non · `format=ZUGFERD` exige une source PDF. Envoyez un PDF ou choisissez un format XML.", "METHOD_NOT_ALLOWED": "405 · non · Utilisez POST sur les chemins de conversion et GET sur les chemins de tâche (voir `Allow`).", "NOT_FOUND": "404 · non · Chemin inconnu sous /api/v1.", "BAD_REQUEST": "400 · non · `task_id` doit être un UUID.", "INVALID_QUERY_PARAMETER": "400 · non · Envoyez `include_validation_report_html` avec `true` ou `false`.", "DOWNLOAD_FORMAT_REQUIRED": "400 · non · Envoyez le paramètre de requête obligatoire `download`.", "INVALID_DOWNLOAD_FORMAT": "400 · non · Utilisez `download=xml|pdf` sur /result et `download=html|xml` sur /validation-report.", "TASK_NOT_READY": "202 · interroger · La tâche est encore en cours. Continuez à interroger le statut de la tâche avec un backoff.", "TASK_NOT_FOUND": "404 · non · Tâche inconnue, tâche d’un autre tenant, ou supprimée 24 h après la fin. Tous les endpoints de tâche.", "TASK_STATUS_FAILED": "5xx · oui · Impossible de lire le statut. Réessayez l’interrogation avec un backoff.", "TASK_RESULT_FAILED": "404/5xx · 5xx uniquement · Impossible de lire le résultat (par exemple métadonnées de tâche manquantes). Réessayez une 5xx avec un backoff ; faites remonter une 404 avec l’ID de corrélation.", "TASK_FAILED": "500 · seulement si `details.retryable` vaut true · Lisez `details.code`. Les échecs permettant une nouvelle tentative exigent une NOUVELLE conversion avec un nouvel Idempotency-Key.", "VALIDATION_FAILED": "422 · non · Erreurs de validation bloquantes. Corrigez les données (`details.items`) et démarrez une nouvelle conversion.", "PROFILE_MISMATCH": "422 · non · Le document stocké déclare un autre profil. Démarrez une nouvelle conversion avec le bon profil.", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE": "422 · non · Le PDF source ne peut pas porter un hybride PDF/A-3 strict. Normalisez le PDF ou utilisez `download=xml`.", "ZUGFERD_CII_CONVERSION_FAILED": "422/500 · non · La conversion CII hybride a échoué. Faites remonter le problème avec l’ID de corrélation.", "ZUGFERD_PDF_GENERATION_FAILED": "500 · non · La génération du PDF hybride a échoué. Faites remonter le problème avec l’ID de corrélation.", "XML_GENERATION_FAILED": "500 · oui, avec backoff · Ancien chemin de génération à la demande ; non attendu pour les tâches API strictes.", "PDF_GENERATION_FAILED": "500 · oui, avec backoff · Ancien chemin de génération à la demande ; non attendu pour les tâches API strictes.", "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "503 · oui · Le validateur est temporairement indisponible. Réessayez le même téléchargement plus tard.", "ARTIFACT_GENERATION_RERUN_REQUIRED": "503 · nouvelle tâche · La génération de l’artefact a échoué après les nouvelles tentatives du serveur. Démarrez une nouvelle conversion.", "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "503 · nouvelle tâche · Des groupes d’extraction ont échoué (`details.failed_groups`). Démarrez une nouvelle conversion.", "INTERNAL_ARTIFACT_INVARIANT_FAILED": "500 · non · Tâche terminée sans artefact stocké sûr. Faites remonter le problème avec l’ID de corrélation.", "VALIDATION_REPORT_NOT_FOUND": "404 · non · Aucun rapport n’est lié à l’artefact actuel (`details.reason`).", "VALIDATION_REPORT_FAILED": "4xx/5xx · 5xx uniquement · La récupération du rapport a échoué. Réessayez les 5xx transitoires avec un backoff.", "PROXY_ERROR": "502/504 · oui · Échec de transport entre le proxy edge et le backend. Réessayez avec un backoff et le même Idempotency-Key." }, "description": "Code d’erreur lisible par machine. Format de chaque description : statut HTTP · nouvelle tentative ? · action." }, "message": { "type": "string", "description": "Texte lisible par un humain. Ne l’analysez pas." }, "correlation_id": { "type": "string", "format": "uuid", "description": "À indiquer au support." }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "additionalProperties": false }, "EdgeError": { "type": "object", "description": "Erreur envoyée par le proxy edge avant que la requête n’atteigne l’API (`404 NOT_FOUND`, `405 METHOD_NOT_ALLOWED`). Pas de `correlation_id`.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "METHOD_NOT_ALLOWED" ] }, "message": { "type": "string" } } }, "ErrorDetails": { "type": "object", "description": "Contexte structuré. Les clés dépendent du code ; des clés inconnues peuvent apparaître. `type` est généralement présent, mais pas toujours (par exemple `{\"field\": \"download\"}`, `INVALID_UPLOAD`, `413`) ; basez donc votre logique sur le `code` de l’enveloppe.", "properties": { "type": { "type": "string", "description": "Famille du détail, par exemple `validation`, `rate_limit`, `idempotency_conflict`, `idempotency_in_progress`, `profile_mismatch`, `context`, `dependency`, `artifact_generation`, `validation_report`, `message`." }, "code": { "type": "string", "description": "Code de l’échec sous-jacent. Pour `500 TASK_FAILED`, c’est le motif ; voir `x-enumDescriptions`.", "examples": [ "MULTIPLE_INVOICES_IN_DOCUMENT", "NO_INVOICE_DETECTED", "INSUFFICIENT_INVOICE_SIGNAL", "SOURCE_TEXT_UNAVAILABLE", "SCHEMA_PARSE_FAILED", "ARTIFACT_PARITY_FAILED", "PROVIDER_ERROR" ], "x-enumDescriptions": { "MULTIPLE_INVOICES_IN_DOCUMENT": "Définitif. Le document contient plus d’une facture. Scindez-le et convertissez chaque facture séparément.", "NO_INVOICE_DETECTED": "Définitif. Le document n’est pas une facture. Transmettez-le à une personne.", "INSUFFICIENT_INVOICE_SIGNAL": "Définitif. Trop peu de données de facture. Envoyez une meilleure source ou utilisez convert-structured.", "SOURCE_TEXT_UNAVAILABLE": "Voir `retryable`. false : aucun texte lisible (envoyez un PDF texte ou une numérisation plus nette). true : l’OCR était temporairement indisponible ; démarrez une nouvelle conversion.", "SCHEMA_PARSE_FAILED": "Définitif pour cette tentative. Démarrez une nouvelle conversion ; faites remonter le problème s’il se répète.", "ARTIFACT_PARITY_FAILED": "Définitif. L’artefact ne correspondait pas aux données finales de la facture. Faites remonter le problème avec l’ID de corrélation.", "PROVIDER_ERROR": "Voir `retryable`. true : démarrez une nouvelle conversion après un délai. `classification=provider_context_too_large` : envoyez un document plus petit." } }, "retryable": { "type": "boolean", "description": "Fait foi lorsqu’il est présent. `true` sur `TASK_FAILED` : démarrez une NOUVELLE conversion avec un nouvel Idempotency-Key." }, "can_review": { "type": "boolean" }, "classification": { "type": "string", "description": "Par exemple `multiple_invoices`, `not_invoice`, `provider_context_too_large`." }, "category": { "type": "string" }, "recovery_hint": { "type": "string", "description": "Prochaine étape, lisible par un humain." }, "same_task_retryable": { "type": "boolean", "description": "`false` : la même tâche ne peut pas être reprise ; démarrez une nouvelle conversion." }, "recovery": { "type": "string", "description": "Par exemple `start_new_conversion`." }, "dependency": { "type": "string" }, "stage": { "type": "string" }, "failed_groups": { "type": "array", "items": { "type": "string" }, "description": "Groupes d’extraction en échec pour `EXTRACTION_INCOMPLETE_GROUP_FAILURE`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationDetail" }, "description": "Problèmes bloquants pour `VALIDATION_FAILED`." }, "field": { "type": "string", "description": "Champ de la requête en cause, par exemple `download` ou `file`." }, "reason": { "type": "string", "description": "Motif détaillé, par exemple `bundle_invoice_id_missing`, `bundle_invoice_id_mismatch`, `different_payload_for_same_key`." }, "profile": { "type": "string" }, "format": { "type": "string" }, "allowed_profiles": { "type": "array", "items": { "type": "string" }, "description": "Profils acceptés, pour les erreurs de profil." }, "minute_count": { "type": "integer" }, "hour_count": { "type": "integer" }, "limit_minute": { "type": "integer" }, "limit_hour": { "type": "integer" }, "limit_bytes": { "type": "integer", "description": "Limite de taille pour `413 PAYLOAD_TOO_LARGE`." }, "declared_size": { "type": "integer" }, "received_bytes": { "type": "integer" }, "remaining": { "type": "integer" }, "included_remaining": { "type": "integer" }, "credit_remaining": { "type": [ "integer", "null" ] }, "shortfall": { "type": "integer" }, "minimum_purchase": { "type": "integer" }, "bridge_status": { "type": "integer" } }, "additionalProperties": true }, "ValidationDetail": { "type": "object", "description": "Un problème de validation bloquant.", "properties": { "field": { "type": [ "string", "null" ], "description": "Chemin du champ de facture, par exemple `BuyerReference`." }, "rule_id": { "type": [ "string", "null" ], "description": "ID de règle, par exemple `BR-DE-15`." }, "severity": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "suggestion": { "type": [ "string", "null" ], "description": "Ce qu’il faut corriger." }, "message": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "InsufficientApiCreditsPrepaidError": { "type": "object", "description": "Structure 402 pour les comptes uniquement prépayés.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "remaining", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "remaining": { "type": "integer", "description": "Crédits prépayés restants." }, "minimum_purchase": { "type": "integer", "description": "Plus petit paquet de crédits (100)." } }, "additionalProperties": true } }, "additionalProperties": false }, "InsufficientApiCreditsAllowanceError": { "type": "object", "description": "Structure 402 pour les comptes avec un quota mensuel appliqué.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "included_remaining", "credit_remaining", "shortfall", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "included_remaining": { "type": "integer", "description": "Quota restant ce mois-ci." }, "credit_remaining": { "type": [ "integer", "null" ], "description": "Crédits prépayés restants, ou null." }, "shortfall": { "type": "integer", "description": "Unités non couvertes." }, "minimum_purchase": { "type": "integer", "description": "Plus petit paquet de crédits (100)." } }, "additionalProperties": true } }, "additionalProperties": false }, "StructuredInvoice_AccountingCustomerParty": { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingCustomerParty", "type": "object" }, "StructuredInvoice_AccountingSupplierParty": { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingSupplierParty", "type": "object" }, "StructuredInvoice_AdditionalDocumentReference": { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "DocumentTypeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documenttypecode" }, "DocumentDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documentdescription" }, "Attachment": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Attachment" }, { "type": "null" } ], "default": null } }, "title": "AdditionalDocumentReference", "type": "object" }, "StructuredInvoice_AllowanceCharge": { "additionalProperties": false, "description": "Remise ou frais au niveau du document (BG-20/BG-21)", "properties": { "ChargeIndicator": { "title": "Chargeindicator", "type": "boolean" }, "AllowanceChargeReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereasoncode" }, "AllowanceChargeReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereason" }, "MultiplierFactorNumeric": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Points de pourcentage de la source, exactement tels qu’imprimés. 30 % vaut 30, jamais 0.3 ; 0,3 % reste 0.3. Ne convertissez jamais des points de pourcentage en facteurs décimaux.", "title": "Multiplierfactornumeric" }, "BaseAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Baseamount" }, "Amount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "TaxCategory": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceChargeTaxCategory" }, { "type": "null" } ], "default": null } }, "required": [ "ChargeIndicator", "Amount" ], "title": "AllowanceCharge", "type": "object" }, "StructuredInvoice_AllowanceChargeTaxCategory": { "additionalProperties": false, "description": "Catégorie de TVA d’une remise ou de frais au niveau du document (BG-21)", "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "AllowanceChargeTaxCategory", "type": "object" }, "StructuredInvoice_Attachment": { "additionalProperties": false, "properties": { "EmbeddedDocumentBinaryObject": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject" }, { "type": "null" } ], "default": null } }, "title": "Attachment", "type": "object" }, "StructuredInvoice_BuyersItemIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "BuyersItemIdentification", "type": "object" }, "StructuredInvoice_CardAccount": { "additionalProperties": false, "properties": { "PrimaryAccountNumberID": { "title": "Primaryaccountnumberid", "type": "string" }, "NetworkID": { "title": "Networkid", "type": "string" }, "HolderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Holdername" } }, "required": [ "PrimaryAccountNumberID", "NetworkID" ], "title": "CardAccount", "type": "object" }, "StructuredInvoice_ClassifiedTaxCategory": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "ClassifiedTaxCategory", "type": "object" }, "StructuredInvoice_CommodityClassification": { "additionalProperties": false, "properties": { "ItemClassificationCode": { "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode" } }, "required": [ "ItemClassificationCode" ], "title": "CommodityClassification", "type": "object" }, "StructuredInvoice_Contact": { "additionalProperties": false, "properties": { "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "Telephone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Telephone" }, "ElectronicMail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Electronicmail" } }, "title": "Contact", "type": "object" }, "StructuredInvoice_ContractDocumentReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ContractDocumentReference", "type": "object" }, "StructuredInvoice_Country": { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "Country", "type": "object" }, "StructuredInvoice_Delivery": { "additionalProperties": false, "properties": { "ActualDeliveryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actualdeliverydate" }, "DeliveryLocation": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryLocation" }, { "type": "null" } ], "default": null }, "DeliveryParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Party" }, { "type": "null" } ], "default": null } }, "title": "Delivery", "type": "object" }, "StructuredInvoice_DeliveryAddress": { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Country" }, { "type": "null" } ], "default": null } }, "title": "DeliveryAddress", "type": "object" }, "StructuredInvoice_DeliveryLocation": { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Id" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" }, "Address": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryAddress" }, { "type": "null" } ], "default": null } }, "title": "DeliveryLocation", "type": "object" }, "StructuredInvoice_DeliveryTerms": { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "SpecialTerms": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Specialterms" } }, "title": "DeliveryTerms", "type": "object" }, "StructuredInvoice_DespatchDocumentReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "DespatchDocumentReference", "type": "object" }, "StructuredInvoice_EmbeddedDocumentBinaryObject": { "additionalProperties": false, "properties": { "#text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "#Text" }, "mimeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mimecode" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" } }, "title": "EmbeddedDocumentBinaryObject", "type": "object" }, "StructuredInvoice_EndpointID": { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "@schemeID": { "title": "@Schemeid", "type": "string" } }, "required": [ "#text", "@schemeID" ], "title": "EndpointID", "type": "object" }, "StructuredInvoice_FinancialInstitutionBranch": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "FinancialInstitutionBranch", "type": "object" }, "StructuredInvoice_InvoiceLine": { "additionalProperties": false, "properties": { "ID": { "description": "Identifiant de ligne : utilisez le numéro de position exact de la facture originale (par exemple '1.1.30', '10', '001'). Utilisez une numérotation séquentielle '1', '2', '3' uniquement en l’absence d’identifiants explicites. PAS le nom de l’article.", "title": "Id", "type": "string" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "InvoicedQuantity": { "title": "Invoicedquantity", "type": "number" }, "unitCode": { "title": "Unitcode", "type": "string" }, "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "PeriodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodstart" }, "PeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodend" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "OrderLineReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Orderlinereference" }, "Item": { "$ref": "#/components/schemas/StructuredInvoice_Item" }, "Price": { "$ref": "#/components/schemas/StructuredInvoice_Price" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "ID", "InvoicedQuantity", "unitCode", "LineExtensionAmount", "Item", "Price" ], "title": "InvoiceLine", "type": "object" }, "StructuredInvoice_InvoicePeriod": { "additionalProperties": false, "properties": { "StartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Startdate" }, "EndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enddate" }, "DescriptionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Descriptioncode" } }, "title": "InvoicePeriod", "type": "object" }, "StructuredInvoice_Item": { "additionalProperties": false, "properties": { "Description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "BuyersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_BuyersItemIdentification" }, { "type": "null" } ], "default": null }, "SellersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SellersItemIdentification" }, { "type": "null" } ], "default": null }, "StandardItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_StandardItemIdentification" }, { "type": "null" } ], "default": null }, "OriginCountry": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OriginCountry" }, { "type": "null" } ], "default": null }, "CommodityClassification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Commodityclassification" }, "ClassifiedTaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_ClassifiedTaxCategory" } }, "required": [ "ClassifiedTaxCategory" ], "title": "Item", "type": "object" }, "StructuredInvoice_ItemClassificationCode": { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "listID": { "title": "Listid", "type": "string" }, "listVersionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Listversionid" } }, "required": [ "#text", "listID" ], "title": "ItemClassificationCode", "type": "object" }, "StructuredInvoice_LegalMonetaryTotal": { "additionalProperties": false, "properties": { "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "AllowanceTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancetotalamount" }, "ChargeTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Chargetotalamount" }, "TaxExclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxexclusiveamount" }, "TaxInclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxinclusiveamount" }, "PrepaidAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prepaidamount" }, "PayableRoundingAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payableroundingamount" }, "PayableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Payableamount" } }, "required": [ "LineExtensionAmount", "TaxExclusiveAmount", "TaxInclusiveAmount", "PayableAmount" ], "title": "LegalMonetaryTotal", "type": "object" }, "StructuredInvoice_OrderReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "OrderReference", "type": "object" }, "StructuredInvoice_OriginCountry": { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "OriginCountry", "type": "object" }, "StructuredInvoice_Party": { "additionalProperties": false, "properties": { "EndpointID": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EndpointID" }, { "type": "null" } ], "default": null }, "PartyIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partyidentification" }, "PartyName": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Partyname" }, "PostalAddress": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PostalAddress" }, { "type": "null" } ], "default": null }, "PartyTaxScheme": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partytaxscheme" }, "PartyLegalEntity": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyLegalEntity" }, { "type": "null" } ], "default": null }, "Contact": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Contact" }, { "type": "null" } ], "default": null } }, "title": "Party", "type": "object" }, "StructuredInvoice_PartyIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" } }, "required": [ "ID" ], "title": "PartyIdentification", "type": "object" }, "StructuredInvoice_PartyLegalEntity": { "additionalProperties": false, "properties": { "RegistrationName": { "title": "Registrationname", "type": "string" }, "CompanyID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companyid" }, "CompanyLegalForm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companylegalform" } }, "required": [ "RegistrationName" ], "title": "PartyLegalEntity", "type": "object" }, "StructuredInvoice_PartyTaxScheme": { "additionalProperties": false, "properties": { "CompanyID": { "title": "Companyid", "type": "string" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "CompanyID", "TaxScheme" ], "title": "PartyTaxScheme", "type": "object" }, "StructuredInvoice_PayeeFinancialAccount": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "FinancialInstitutionBranch": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_FinancialInstitutionBranch" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PayeeFinancialAccount", "type": "object" }, "StructuredInvoice_PayeeParty": { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "PayeeParty", "type": "object" }, "StructuredInvoice_PaymentMandate": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "PayerFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PaymentMandate", "type": "object" }, "StructuredInvoice_PaymentMeans": { "additionalProperties": false, "properties": { "PaymentMeansCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentmeanscode" }, "PaymentID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentid" }, "PaymentChannelCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentchannelcode" }, "InstructionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionid" }, "InstructionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionnote" }, "PayeeFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null }, "CardAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CardAccount" }, { "type": "null" } ], "default": null }, "PaymentMandate": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMandate" }, { "type": "null" } ], "default": null } }, "title": "PaymentMeans", "type": "object" }, "StructuredInvoice_PaymentTerms": { "additionalProperties": false, "properties": { "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "PenaltySurchargePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Penaltysurchargepercent" }, "Amount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Amount" }, "NetDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Netdays" }, "DiscountDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Discountdays" }, "DiscountPercent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Discountpercent" }, "DiscountBaseAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Discountbaseamount" }, "ExplicitDueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Explicitduedate" } }, "title": "PaymentTerms", "type": "object" }, "StructuredInvoice_PostalAddress": { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" } }, "required": [ "Country" ], "title": "PostalAddress", "type": "object" }, "StructuredInvoice_PrecedingInvoiceReference": { "additionalProperties": false, "description": "BG-3 : référence à une facture antérieure (par exemple une Schlussrechnung faisant référence à des Abschlagsrechnungen)", "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "PrecedingInvoiceReference", "type": "object" }, "StructuredInvoice_Price": { "additionalProperties": false, "properties": { "PriceAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Priceamount" }, "BaseQuantity": { "anyOf": [ { "type": "number" }, { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Basequantity" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "PriceAmount" ], "title": "Price", "type": "object" }, "StructuredInvoice_ProjectReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ProjectReference", "type": "object" }, "StructuredInvoice_SalesOrderReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SalesOrderReference", "type": "object" }, "StructuredInvoice_SellersItemIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SellersItemIdentification", "type": "object" }, "StructuredInvoice_StandardItemIdentification": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "default": "0160", "title": "Schemeid", "type": "string" } }, "required": [ "ID" ], "title": "StandardItemIdentification", "type": "object" }, "StructuredInvoice_TaxCategory": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "TaxCategory", "type": "object" }, "StructuredInvoice_TaxRepresentativeParty": { "additionalProperties": false, "description": "BG-11 : représentant fiscal du vendeur\nObligatoire lorsque les codes de TVA S, Z, E, AE, K, G, L, M sont utilisés\net que ni BT-31 ni BT-32 n’est fourni (BR-DE-16)", "properties": { "PartyName": { "minLength": 1, "title": "Partyname", "type": "string" }, "PostalAddress": { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativePostalAddress" }, "PartyTaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" } }, "required": [ "PartyName", "PostalAddress", "PartyTaxScheme" ], "title": "TaxRepresentativeParty", "type": "object" }, "StructuredInvoice_TaxRepresentativePostalAddress": { "additionalProperties": false, "description": "BG-12 : adresse postale du représentant fiscal du vendeur", "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" } }, "required": [ "Country" ], "title": "TaxRepresentativePostalAddress", "type": "object" }, "StructuredInvoice_TaxScheme": { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TaxScheme", "type": "object" }, "StructuredInvoice_TaxSubtotal": { "additionalProperties": false, "properties": { "TaxableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxableamount" }, "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_TaxCategory" } }, "required": [ "TaxableAmount", "TaxAmount", "TaxCategory" ], "title": "TaxSubtotal", "type": "object" }, "StructuredInvoice_TaxTotal": { "additionalProperties": false, "properties": { "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxSubtotal": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, "type": "array" } ], "title": "Taxsubtotal" } }, "required": [ "TaxAmount", "TaxSubtotal" ], "title": "TaxTotal", "type": "object" }, "StructuredInvoice_TenderOrLotReference": { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TenderOrLotReference", "type": "object" } } } }