# API externe Invoice Converter

Version: 1.32.0 · Dernière mise à jour: 2026-11-20 · URL de base: `https://www.invoice-converter.com/api/v1`

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.

**URL de base** `https://www.invoice-converter.com/api/v1` · **Authentification** `Authorization: Bearer <api_key>` · **Contrat** OpenAPI 3.1 (ce document)

Cette 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.

## Accès et tarifs

L'API externe V1 transforme des factures PDF ou les données de votre ERP, de votre logiciel de facturation ou de votre CRM en fichiers XRechnung, ZUGFeRD/Factur-X, UBL ou CII et ne renvoie un fichier qu'après une validation réussie. Une validation réussie prouve le format et les règles de la norme, pas la concordance des données avec la facture d'origine. Prévoyez votre propre contrôle pour les exceptions.

L'accès nécessite un abonnement Enterprise : 50 € HT par mois, ou 420 € HT par an avec la facturation annuelle. [Démarrer Enterprise](https://www.invoice-converter.com/fr/pricing)

- [Créer une clé API](https://www.invoice-converter.com/fr/profile#api-access)
- [Guide de l'import par e-mail](https://www.invoice-converter.com/fr/developer-api/email-invoices)
- [Guide des traitements par lots](https://www.invoice-converter.com/fr/developer-api/bulk-runs)
- [Comparer tous les canaux d'automatisation](https://www.invoice-converter.com/fr/automation)

## Vue d’ensemble

L’API convertit une facture par requête en une facture électronique validée. Chaque conversion est asynchrone :

1. **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`.
2. **Interroger ou attendre le webhook.** `GET /tasks/{task_id}` jusqu’à ce que `status` soit `completed` ou `failed`, ou recevoir l’événement de fin signé (voir *Webhooks*).
3. **Télécharger.** `GET /tasks/{task_id}/result?download=xml|pdf`. Facultatif : `GET /tasks/{task_id}/validation-report?download=html|xml`.

Une 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 d’endpoint batch ni d’endpoint de liste des tâches.

| Endpoint | Rôle | Limite de débit par clé API |
|---|---|---|
| `POST /invoices:convert` | Convertir un document | 30/min, 500/h |
| `POST /invoices:convert-structured` | Convertir des données structurées | 30/min, 500/h |
| `GET /tasks/{task_id}` | Statut de la tâche | 60/min, 1 500/h |
| `GET /tasks/{task_id}/result` | Télécharger l’artefact | 60/min, 1 000/h |
| `GET /tasks/{task_id}/validation-report` | Télécharger le rapport de validation | 30/min, 500/h |
| `GET /tasks/{task_id}/correction-result` | Télécharger la facture corrigée | 60/min, 1,000/h |
| `POST`, `GET`, `DELETE /webhook-endpoint` | Enregistrer, lire ou supprimer l’endpoint webhook | 30/min, 300/h |
| `POST /webhook-endpoint:test` | Envoyer un événement de test | 5/min, 50/h |

## Authentification et accès

- En-tête : `Authorization: Bearer <api_key>`.
- 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.
- Conservez les clés sur votre serveur. Ne les placez jamais dans du code navigateur ou mobile, dans des journaux ou dans des tickets.
- 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).

## Démarrage rapide

```bash
# 1. Convert
curl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Idempotency-Key: erp-inv-2026-0001' \
  -F 'file=@invoice.pdf' \
  -F 'format=XRECHNUNG' \
  -F 'client_reference=ERP-2026-0001'

# 2. Poll (first call about 20 s later)
curl 'https://www.invoice-converter.com/api/v1/tasks/<task_id>' \
  -H 'Authorization: Bearer <api_key>'

# 3. Download
download_tmp=$(mktemp) || exit 1
download_meta=$(curl --silent --show-error --output "$download_tmp" \
  --write-out '%{http_code} %{content_type}' --dump-header headers.txt \
  'https://www.invoice-converter.com/api/v1/tasks/<task_id>/result?download=xml' \
  -H 'Authorization: Bearer <api_key>') || { rm -f "$download_tmp"; exit 1; }
case "$download_meta" in
  '200 application/xml'|'200 application/xml;'*|'200 text/xml'|'200 text/xml;'*)
    mv "$download_tmp" invoice.xml ;;
  *)
    rm -f "$download_tmp"
    printf 'Download not saved (%s). Continue polling on 202.\n' "$download_meta" >&2
    exit 1 ;;
esac
```

Le 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) :

```json
{
  "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",
  "error": null,
  "client_reference": "ERP-2026-0001",
  "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml",
  "result_artifacts": {
    "xml": { "state": "cached", "artifact_state": "compliant", "validation_state": "passed" }
  }
}
```

Pour `failed`, `error` contient un résumé (chaîne ou objet) ; appelez `/result` pour obtenir l’erreur typée.

## Formats et profils

`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.

| `format` | `profile` autorisé | Par défaut | `download=xml` | `download=pdf` |
|---|---|---|---|---|
| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | PDF de rendu (au mieux) |
| `EN16931` | `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |
| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |
| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | PDF de rendu (au mieux) |
| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | PDF hybride ZUGFeRD/Factur-X |

- `format` et `profile` ne sont pas sensibles à la casse. Alias : `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED` ; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`.
- Un profil non listé pour le format : `422 OUTPUT_PROFILE_CONFLICT`. Un nom de profil inconnu : `422 INVALID_PROFILE` avec `details.allowed_profiles`.
- Pour les formats XML, `download=xml` est l’artefact principal. Le rendu PDF est une commodité et peut être indisponible.
- `format=ZUGFERD` exige une source PDF. Un envoi DOCX ou TXT est rejeté dès l’upload avec `422 ZUGFERD_SOURCE_PDF_REQUIRED`.
- `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`.

## Conversion de documents

`POST /invoices:convert`, `multipart/form-data` :

- `file` (obligatoire) : `.pdf`, `.docx` ou `.txt`. Une facture par fichier. Un document contenant plusieurs factures échoue avec `422 DOCUMENT_NOT_CONVERTIBLE`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT`.
- `format` (obligatoire), `profile`, champs de contexte comme ci-dessus.
- `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.
- `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`.
- `email_input` : instructions facultatives en texte libre pour l’extraction (PDF uniquement, ≤ 10 000 caractères, pas avec `use_embedded_xml=true`).
- `use_seller_master_data` et `seller_master_data` : voir *Données de base du vendeur*.

L’extraction lit le document. Elle n’invente pas de données juridiques, fiscales, de routage, bancaires ou de référence acheteur. Exception pour XRechnung (profil `XRECHNUNG` ou `ZUGFERD_XRECHNUNG`) : si ni les données de base du vendeur ni le document ne donnent l’adresse électronique du vendeur (BT-34), et que le document imprime exactement une adresse e-mail du vendeur qui n’est pas celle de l’acheteur, cette adresse devient BT-34 avec le schéma `EM`. Une sortie Peppol BIS ne la reprend jamais. Si des données obligatoires manquent, la tâche échoue et `/result` renvoie `422 VALIDATION_FAILED`.

## Données de facture structurées

`POST /invoices:convert-structured` convertit les données de votre ERP, de votre système de facturation ou de votre CRM (par exemple Salesforce).

- `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.**
- `data_file` (obligatoire, répétable ; alias `data_files`, `data_files[]`) : `.json`, `.csv`, `.xml`, `.xlsx` ou `.txt`, au total ≤ 2 MB.
- 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.

### Mappage déterministe ou interprété

| Entrée | Mappage | Résultat |
|---|---|---|
| **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 |
| Un fichier XML UBL 2.1 Invoice ou CII D16B | Déterministe, sans IA | Analyseur XML de facture existant |
| Plusieurs parties JSON canoniques `data_file` cohérentes | Fusion déterministe, sans IA | Les champs et lignes distincts sont combinés |
| 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 |

Pour une intégration reproductible, envoyez un seul fichier JSON canonique :

- JSON Schema : <https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json>
- Exemple (XRechnung B2G allemande ; réussit les contrôles EN 16931, XRechnung et ZUGFeRD strict) : <https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json>

Le 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`.

Les 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.

Le 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.

**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.

- 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.`.
- 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.
- Les noms en camelCase comme `invoiceNumber` et les noms d’API Salesforce comme `Invoice_Number__c` sont reconnus.
- Un numéro absent ou contradictoire renvoie `400 INVALID_UPLOAD` avec `details.reason` `bundle_invoice_id_missing` ou `bundle_invoice_id_mismatch`.

Les 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.

### Données obligatoires

| Toujours | Pour XRechnung (y compris `UBL`/`CII` avec le profil `XRECHNUNG`, et `ZUGFERD_XRECHNUNG`) | Pour ZUGFeRD strict |
|---|---|---|
| `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 |

Des données manquantes terminent la tâche avec `failed` ; `/result` renvoie `422 VALIDATION_FAILED` avec `details.items[]` (`field`, `business_term`, `rule_id`, `severity`, `source`, `message`, `suggestion`, et `proposal` pour une ligne qui n’indique qu’un montant).

### Chemins JSON les plus utilisés

`AccountingSupplierParty.Party` est abrégé en `Seller`, `AccountingCustomerParty.Party` en `Buyer`. XR = obligatoire pour XRechnung.

| Chemin JSON | EN 16931 | XR |
|---|---|---|
| `ID` | BT-1 | oui |
| `IssueDate` | BT-2 | oui |
| `InvoiceTypeCode` (par exemple `380` facture commerciale) | BT-3 | oui |
| `DocumentCurrencyCode` | BT-5 | oui |
| `DueDate` | BT-9 | – |
| `BuyerReference` | BT-10 | oui |
| `OrderReference.ID` | BT-13 | – |
| `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – |
| `PaymentTerms.Note` | BT-20 | – |
| `Seller.PartyLegalEntity.RegistrationName` | BT-27 | oui |
| `Seller.PartyTaxScheme.CompanyID` (numéro de TVA) | BT-31 | oui¹ |
| `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | oui |
| `Seller.PostalAddress.StreetName` | BT-35 | – |
| `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | oui |
| `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | oui |
| `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | oui |
| `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | oui |
| `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | oui |
| `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | oui |
| `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | oui |
| `Delivery.ActualDeliveryDate` | BT-72 | – |
| `PaymentMeans.PaymentMeansCode` | BT-81 | oui |
| `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | pour un virement |
| `TaxTotal.TaxAmount` | BT-110 | oui |
| `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | oui |
| `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | oui |
| `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | oui |
| `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | oui |
| `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | oui |
| `InvoiceLine[].LineExtensionAmount` | BT-131 | oui |
| `InvoiceLine[].Price.PriceAmount` | BT-146 | oui |
| `InvoiceLine[].Item.Name` | BT-153 | oui |
| `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | oui |

¹ Numéro de TVA du vendeur (BT-31) ou numéro fiscal (BT-32, `PartyTaxScheme` avec `TaxScheme.ID` `FC`).

## Données de base du vendeur

`seller_master_data` est une chaîne contenant un objet JSON. Elle s’applique uniquement avec `use_seller_master_data=true` ; sans cet indicateur, le réglage du compte s’applique. Le schéma OpenAPI `SellerMasterData` décrit les champs facultatifs et leurs termes EN 16931.

Autres champs facultatifs : `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`, `58`), `payment_terms_note`.

- Chaque valeur fournie remplace la valeur extraite correspondante du vendeur ou du paiement. Une liste `payment_accounts` non vide remplace tous les comptes de virement dans l’ordre enregistré. Les IBAN, BIC et noms de compte extraits pour ces comptes sont ignorés. Les autres moyens de paiement conservent leurs règles de sélection.
- `payment_accounts` contient au plus 5 comptes avec `iban` et, facultativement, `bic` et `account_name`. Chaque IBAN doit être valide et unique ; tout BIC fourni doit être valide. Les champs scalaires `payment_iban`, `payment_bic` et `payment_account_name` sont supprimés : envoyez la liste.
- `electronic_address` et `electronic_address_scheme` forment une paire : envoyez les deux ou aucun.
- Un document d’autofacturation (code de type 261, 389 ou 527) reste tel qu’il a été lu : l’acheteur l’émet, le vendeur et le bénéficiaire sont la contrepartie, et les données de référence du vendeur n’y remplacent rien. La protection des comptes bancaires ne refuse pas son IBAN lorsque le document désigne le titulaire du compte comme acheteur et une autre partie comme vendeur.
- Lorsqu’un autre document désigne le titulaire du compte comme acheteur et une autre partie comme vendeur, les parties restent telles qu’elles ont été lues et la conversion s’arrête pour vérification (`party_roles_conflict_with_seller_profile`). Corrigez les parties, ou choisissez le type 389 s’il s’agit d’une autofacturation.
- JSON invalide, clés inconnues, comptes invalides, plus de cinq comptes ou paire incomplète : `400 INVALID_SELLER_MASTER_DATA`.

### Valeurs appliquées

Une tâche terminée indique dans `applied_values` chaque valeur que le service a définie au lieu de la lire dans le document : les valeurs issues des données de base du vendeur et les valeurs dérivées. Chaque entrée indique le champ de vérification (`field`), le terme EN 16931 (`business_term`), la source `source` (`seller_master_data` ou `derived`), un `code`, la valeur émise `value` et, lorsqu'une valeur du document a été remplacée, `previous_value`. Une valeur enregistrée identique à celle du document n'est pas indiquée. La liste est vide lorsque rien n'a été défini. Elle est purement informative et ne fait jamais échouer une tâche.

| `code` | Signification |
|---|---|
| `seller_master_data_filled` | Le document ne contenait aucune valeur ; la valeur enregistrée a été utilisée. |
| `seller_master_data_replaced` | La valeur enregistrée a remplacé la valeur du document indiquée dans `previous_value`. |
| `seller_master_data_removed` | Un compte bancaire imprimé sans successeur enregistré a été supprimé ; `value` est absent. |
| `delivery_country_derived_domestic_touchless`, `delivery_country_derived_from_buyer`, `delivery_country_from_matching_party_address` | Le pays de livraison (BT-80) a été dérivé des adresses des parties. |
| `seller_endpoint_derived_from_printed_email_touchless` | L'adresse électronique du vendeur (BT-34) a été reprise de l'adresse e-mail imprimée du vendeur. |

D'autres codes peuvent être ajoutés ; traitez un code inconnu comme une information.

## Idempotence et nouvelles tentatives

- `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`.
- Portée : tenant et endpoint, pas la clé API individuelle. Les enregistrements sont conservés 24 heures.
- 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.
- **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é.
- 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é.
- 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é). La clé a déjà servi à une conversion terminée et ses enregistrements de 24 h ont expiré : `409 IDEMPOTENCY_KEY_ALREADY_USED` (nouvelle clé).
- 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é.

## Limites, interrogation et pics de charge

**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.

**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.

**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.

**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é :

1. Gardez une file côté client avec environ 2–4 conversions en cours ; adaptez-la à `SERVER_BUSY`.
2. Sur `429` et `503 SERVER_BUSY`, attendez `Retry-After`, puis réessayez avec **la même** `Idempotency-Key`.
3. Interrogez chaque tâche avec le délai croissant ci-dessus ou attendez son événement webhook ; démarrez la conversion suivante lorsqu’une se termine. V1 ne propose ni endpoint de lot ni endpoint de liste de tâches.

## Webhooks

Au lieu d’interroger, enregistrez un endpoint HTTPS pour l’entreprise de votre clé API. Lorsqu’une conversion acceptée via cette API se termine, le service envoie un `POST` signé avec un petit événement JSON. L’événement est une notification, pas le résultat : téléchargez le résultat comme d’habitude avec `GET /tasks/{task_id}/result`. L’interrogation continue de fonctionner et reste la solution de repli.

**Enregistrer.** `POST /webhook-endpoint` avec le corps JSON `{"url": "https://..."}` renvoie `201` (ou `200` s’il remplace l’endpoint) avec le `secret` de signature. Le secret n’apparaît que dans cette réponse ; conservez-le sur votre serveur. Renvoyer la requête remplace l’URL et renouvelle le secret. `GET /webhook-endpoint` affiche l’URL et la dernière livraison, jamais le secret. `DELETE /webhook-endpoint` arrête toutes les livraisons. `POST /webhook-endpoint:test` met en file un événement `webhook.test` vers votre endpoint.

**Événements.** `conversion.succeeded` (tâche `completed`) et `conversion.failed` (tâche `failed` ; `data.error.code` est le code que renvoie `/result`). Le corps contient `id`, `type`, `api_version`, `created_at` et `data` avec `task_id`, `status`, `client_reference`, `source_system`, `format`, `profile`, `created_at`, `completed_at` et `error`. Il ne contient aucune donnée de facture ni lien de téléchargement.

```json
{"api_version":"v1","created_at":"2026-11-18T10:00:05+00:00","data":{"client_reference":"ERP-2026-0001","completed_at":"2026-11-18T10:00:04+00:00","created_at":"2026-11-18T09:58:51+00:00","error":null,"format":"XRECHNUNG","profile":"XRECHNUNG","source_system":null,"status":"completed","task_id":"550e8400-e29b-41d4-a716-446655440000"},"id":"evt_9b2f0c1e7a3d4e5f8a6b0c1d2e3f4a5b","type":"conversion.succeeded"}
```

**Vérifier la signature.** Chaque requête porte `X-Invoice-Converter-Signature: t=<unix seconds>,v1=<hex>`, `X-Invoice-Converter-Event-Id` et `X-Invoice-Converter-Event-Type`. Calculez HMAC-SHA256 sur `<t>.<raw body>` avec le secret complet, préfixe `whsec_` compris, comme clé. Comparez le résultat à `v1` en temps constant et rejetez la requête lorsque `t` s’écarte de plus de 5 minutes de votre horloge. Vérifiez les octets bruts avant d’analyser le JSON.

```python
import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp = int(parts["t"])
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return abs(time.time() - timestamp) <= 300 and hmac.compare_digest(expected, parts["v1"])
```

**Livraison et nouvelles tentatives.** Répondez avec n’importe quel `2xx` en moins de 10 secondes ; le service ignore le corps de la réponse et ne suit aucune redirection. Tout autre statut, un délai dépassé ou une erreur de connexion compte comme une tentative échouée. Le service essaie jusqu’à 8 fois sur environ 23 heures (après environ 1 min, 5 min, 30 min, 1 h, 3 h, 6 h et 12 h, avec une variation aléatoire), puis abandonne. La livraison a lieu au moins une fois et sans ordre garanti : dédupliquez par `X-Invoice-Converter-Event-Id` et considérez `GET /tasks/{task_id}` comme la source de vérité.

**Règles d’URL.** `https` sur le port 443 et un nom DNS public, sans adresse IP, nom d’utilisateur, mot de passe ni fragment. Le nom ne doit se résoudre que vers des adresses publiques ; c’est vérifié à l’enregistrement et de nouveau avant chaque livraison. Une URL refusée renvoie `422 INVALID_WEBHOOK_URL` avec `details.reason`.

## Erreurs

Chaque 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`.

Le 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 :

| Code | HTTP | Réessayer ? | Action |
|---|---|---|---|
| `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | non | Corrigez la clé. |
| `ACCOUNT_DELETED` | 410 | non | Le compte de cette clé a été supprimé. La suppression est définitive. |
| `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | non | Envoyez un `Idempotency-Key` valide. |
| `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | non | Envoyez un `format` pris en charge. |
| `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | non | Utilisez un profil du tableau ou omettez-le. |
| `INVALID_UPLOAD` | 400 / 415 | non | Corrigez le corps multipart, le type de fichier ou les numéros de facture des exports scindés. |
| `FUNCTION_PAYLOAD_TOO_LARGE` (texte brut) / `PAYLOAD_TOO_LARGE` | 413 | non | Envoyez une requête plus petite. |
| `API_NOT_ENABLED_FOR_TENANT` | 403 | non | Activez l’accès API via `details.action_url`. |
| `INSUFFICIENT_API_CREDITS` | 402 | non | Achetez des crédits via `details.action_url` ou attendez le mois suivant. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | même clé | Réessayez après un court délai. |
| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED`, `IDEMPOTENCY_KEY_ALREADY_USED` | 409 | non | Utilisez une nouvelle clé. |
| `RATE_LIMITED` | 429 | même clé | Attendez la durée `Retry-After`. |
| `SERVER_BUSY` | 503 | même clé | File de traitement pleine. Attendez la durée `Retry-After`. |
| `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é. |
| `UPLOAD_FAILED` | 422 | non | `jurisdiction`, `transaction_scope` ou `delivery_channel` invalide. |
| `TASK_NOT_READY` | 202 | interroger | Continuez à interroger le statut. |
| `VALIDATION_FAILED` | 422 | non | Corrigez les données (`details.items`), puis relancez la conversion. |
| `DOCUMENT_NOT_CONVERTIBLE` | 422 | non | Corrigez le document source (`details.recovery_hint`), puis relancez la conversion. |
| `TASK_FAILED` | 500 | si `details.retryable` | Lisez `details.code`. Si l’erreur permet une nouvelle tentative : nouvelle conversion avec une nouvelle clé. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 409 | nouvelle tâche | La tâche ne peut pas reprendre. Démarrez une nouvelle conversion avec une nouvelle clé. |
| `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | non | Faites remonter le problème avec l’ID de corrélation. |
| `TASK_NOT_FOUND` | 404 | non | Tâche inconnue, tâche d’un autre tenant, ou supprimée après 24 h. |
| `PROXY_ERROR` | 502 / 504 | même clé | Réessayez avec un backoff. |

Motifs de `500 TASK_FAILED` dans `details.code` : `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (définitifs) ; `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (suivez `details.retryable`) ; `task_interrupted` (réessayable : le serveur s’est arrêté avant la fin de la conversion). Motifs de `422 DOCUMENT_NOT_CONVERTIBLE` : `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `EMBEDDED_INVOICE_XML_INVALID`, `EMBEDDED_INVOICE_XML_UNREPRESENTABLE`, ainsi qu’un `SOURCE_TEXT_UNAVAILABLE` non réessayable ou un `PROVIDER_ERROR` avec `classification=provider_context_too_large`. `409 ARTIFACT_GENERATION_RERUN_REQUIRED` avec `details.code=AUTHORITATIVE_VALIDATION_UNAVAILABLE` : le validateur ou une autre dépendance d’artefact est resté indisponible malgré les nouvelles tentatives côté serveur. Une tâche en échec reste en échec. Une nouvelle tentative automatique nécessite une nouvelle conversion et une nouvelle clé ; une correction manuelle crée un résultat distinct et lié.

Pour les tâches échouées, `review_url` ouvre une correction dans l’application web pour l’entreprise concernée. Connectez-vous avec un accès à cette entreprise. Les données conservées s’ouvrent dans l’éditeur ; sinon, l’application propose un nouvel envoi. La correction terminée est liée dans `correction` ; la tâche initiale et `/result` conservent leur état initial. Le délai de conservation initial reste applicable.

## Résultats, preuves et rapport de validation

- `/result` est une simple récupération. Il renvoie `200` uniquement pour un artefact stocké disposant d’une preuve de validation à jour. Seules les tâches acceptées via `POST /invoices:convert` ou `POST /invoices:convert-structured` ont un résultat ; pour toute autre tâche de votre compte, `GET /tasks/{task_id}` et `/result` renvoient `404 TASK_NOT_FOUND`.
- 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`).
- `/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`.
- `result_artifacts.<xml|pdf>.state` dans le statut de la tâche : `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`.

## Conservation, facturation et archivage

- **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).
- **Facturation.** Chaque conversion acceptée consomme une unité. Enterprise inclut un quota partagé avec l’import par e-mail et les traitements par lot : 100 unités par mois calendaire en facturation mensuelle, ou 1 200 unités par année contractuelle en facturation annuelle, disponibles en une fois dès le premier paiement annuel (100 par mois pendant l’essai). Les unités non utilisées expirent à la fin de la période. 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, tous les appels de tâche et les webhooks sont gratuits. Lorsque rien ne couvre une unité : `402 INSUFFICIENT_API_CREDITS` (deux structures de `details`, voir la réponse OpenAPI `PaymentRequired`).
- **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.

## Support et contrat

- Contact : `contact@invoice-converter.com`. Indiquez le `X-Correlation-ID`.
- 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.
- 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.
- 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.

## Artefacts de référence

- OpenAPI 3.1 : <https://www.invoice-converter.com/developer-api/v1/openapi.json>
- Collection Postman : <https://www.invoice-converter.com/developer-api/v1/postman.json> (définissez `base_url`, `api_key`, `idempotency_key`)
- JSON Schema et exemple de facture structurée : voir *Données de facture structurées*
- Canal de factures par e-mail : <https://www.invoice-converter.com/fr/developer-api/email-invoices>
- Cette documentation au format Markdown (pour les LLM et la lecture hors ligne) : <https://www.invoice-converter.com/fr/developer-api/md>

## Endpoints

### POST /invoices:convert — Convertir un document de facture

Envoyez un document de facture et démarrez une conversion stricte.

- `file` : `.pdf`, `.docx` ou `.txt`, une facture par fichier. Fichier source ≤ 20 MB (20 000 000 octets) ; corps multipart complet ≤ 21 MB.
- `format` est obligatoire ; `profile` est facultatif (valeur par défaut par format ci-dessous).
- Le XML intégré dans un PDF est ignoré, sauf si `use_embedded_xml=true`.
- Limite de débit : 30/min et 500/h par clé API.

| `format` | `profile` autorisé | Par défaut | `download=xml` | `download=pdf` |
|---|---|---|---|---|
| `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | PDF de rendu (au mieux) |
| `EN16931` | `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |
| `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | PDF de rendu (au mieux) |
| `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | PDF de rendu (au mieux) |
| `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | PDF hybride ZUGFeRD/Factur-X |

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | oui | 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`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Corps de la requête** (`multipart/form-data`)

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `file` | string (binary) | oui | 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` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | oui | 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`. |
| `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` |  | 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`. |
| `jurisdiction` | string |  | Pays de la transaction selon ISO 3166-1 alpha-2, par exemple `DE`. Contexte facultatif. Invalide → `422 UPLOAD_FAILED`. |
| `transaction_scope` | string: `B2B`, `B2G`, `B2C` |  | Indication de contexte facultative. Invalide → `422 UPLOAD_FAILED`. |
| `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` |  | 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` | string |  | 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`. |
| `source_system` | string |  | 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. |
| `use_embedded_xml` | boolean |  | 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` | string |  | 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`. |
| `use_seller_master_data` | boolean |  | 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` | string |  | 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`. |

```json
{
  "$ref": "#/components/schemas/ConvertInvoiceRequest"
}
```

**Réponses**

- `202`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ConvertAcceptedResponse"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `402`: `402 INSUFFICIENT_API_CREDITS`. Pas de nouvelle tentative : achetez un paquet de crédits prépayés via `details.action_url` ou attendez la prochaine période de quota. Deux structures de `details` ; lisez les clés présentes.

`application/json`

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError"
    },
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError"
    }
  ]
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: 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`, `IDEMPOTENCY_REPLAY_EXPIRED` et `IDEMPOTENCY_KEY_ALREADY_USED` : utilisez une nouvelle clé.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: 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).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `415`: `415 INVALID_UPLOAD` : envoyez `multipart/form-data`. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: 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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR` : le proxy edge n’a pas pu joindre le backend. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR` : le backend n’a pas répondu à temps. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /invoices:convert-structured — Convertir des données de facture structurées

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).

- **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)).
- **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.
- 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`.
- 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.
- 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.
- Les règles de `format` et `profile` sont les mêmes que pour `POST /invoices:convert`.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | oui | 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`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Corps de la requête** (`multipart/form-data`)

| Nom | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `pdf_file` | string (binary) | oui | 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(string (binary), array of string (binary)) | oui | 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` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | oui | 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`. |
| `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` |  | 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`. |
| `jurisdiction` | string |  | Pays de la transaction selon ISO 3166-1 alpha-2, par exemple `DE`. Contexte facultatif. Invalide → `422 UPLOAD_FAILED`. |
| `transaction_scope` | string: `B2B`, `B2G`, `B2C` |  | Indication de contexte facultative. Invalide → `422 UPLOAD_FAILED`. |
| `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` |  | 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` | string |  | 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`. |
| `source_system` | string |  | 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. |
| `use_seller_master_data` | boolean |  | 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` | string |  | 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`. |

```json
{
  "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest"
}
```

**Réponses**

- `202`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ConvertAcceptedResponse"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `402`: `402 INSUFFICIENT_API_CREDITS`. Pas de nouvelle tentative : achetez un paquet de crédits prépayés via `details.action_url` ou attendez la prochaine période de quota. Deux structures de `details` ; lisez les clés présentes.

`application/json`

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError"
    },
    {
      "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError"
    }
  ]
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: 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`, `IDEMPOTENCY_REPLAY_EXPIRED` et `IDEMPOTENCY_KEY_ALREADY_USED` : utilisez une nouvelle clé.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: 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).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `415`: `415 INVALID_UPLOAD` : envoyez `multipart/form-data`. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: 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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR` : le proxy edge n’a pas pu joindre le backend. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR` : le backend n’a pas répondu à temps. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id} — Lire le statut de la tâche

Renvoie l’état de la tâche. Interrogez jusqu’à ce que `status` soit `completed` ou `failed`.

- 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.
- `completed` : téléchargez depuis `primary_result_url`. `failed` : appelez `/result` pour obtenir l’erreur typée.
- Tâche inconnue, tâche non acceptée via cette API (par exemple un import web), ou plus de 24 h après la fin : `404 TASK_NOT_FOUND`.
- Limite de débit : 60/min et 1 500/h par clé API.

Pour les tâches échouées, `review_url` ouvre une correction dans l’application web pour l’entreprise concernée. Connectez-vous avec un accès à cette entreprise. Les données conservées s’ouvrent dans l’éditeur ; sinon, l’application propose un nouvel envoi. La correction terminée est liée dans `correction` ; la tâche initiale et `/result` conservent leur état initial. Le délai de conservation initial reste applicable.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | oui | `task_id` issu de la réponse `202`. Pas un UUID → `400 BAD_REQUEST`. |
| `include_validation_report_html` | query | string: `true`, `false` |  | `true` ajoute le HTML nettoyé du rapport de validation dans `validation_report_html`. Valeurs autres que `true`/`false` → `400 INVALID_QUERY_PARAMETER`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `200`: État actuel de la tâche.

`application/json`

```json
{
  "$ref": "#/components/schemas/TaskStatusResponse"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND` : tâche inconnue, tâche d’un autre tenant, tâche non acceptée via cette API, ou supprimée 24 h après la fin. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR` : le proxy edge n’a pas pu joindre le backend. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un backoff : `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR` : le backend n’a pas répondu à temps. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/result — Télécharger le résultat

Téléchargez l’artefact validé. Simple récupération : cet appel ne génère, ne répare et ne valide rien.

- `download=xml` : UBL (`XRECHNUNG`, `EN16931`, `UBL`) ou CII (`CII`, `ZUGFERD`). Toujours l’artefact principal pour les formats XML.
- `download=pdf` : PDF hybride ZUGFeRD/Factur-X pour `ZUGFERD` ; un rendu au mieux pour les autres formats.
- Seules les tâches acceptées via les deux endpoints de conversion ont un résultat. Toute autre tâche (par exemple un import web) renvoie `404 TASK_NOT_FOUND`.
- Pendant le traitement : `202 TASK_NOT_READY`. Tâche en échec : son erreur typée (`409 ARTIFACT_GENERATION_RERUN_REQUIRED`, `422 VALIDATION_FAILED`, `422 DOCUMENT_NOT_CONVERTIBLE`, `500 TASK_FAILED`).
- Limite de débit : 60/min et 1 000/h par clé API.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | oui | `task_id` issu de la réponse `202`. Pas un UUID → `400 BAD_REQUEST`. |
| `download` | query | string: `xml`, `pdf` | oui | Artefact à télécharger (insensible à la casse). Absent → `400 DOWNLOAD_FORMAT_REQUIRED` ; autres valeurs → `400 INVALID_DOWNLOAD_FORMAT`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `200`: Les octets de l’artefact. Les en-têtes `X-*` décrivent les octets livrés ; enregistrez-les pour votre archive.

`application/xml`

```json
{
  "type": "string"
}
```

`application/pdf`

```json
{
  "type": "string",
  "format": "binary"
}
```

- `202`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND` : tâche inconnue, tâche d’un autre tenant, tâche non acceptée via cette API, 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: `409` : la tâche a échoué pour une raison temporaire et ne peut pas reprendre ; répéter cette requête n’aboutit jamais. Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key. Codes : `ARTIFACT_GENERATION_RERUN_REQUIRED` (motif dans `details.code`, par exemple `AUTHORITATIVE_VALIDATION_UNAVAILABLE`), `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: La facture ne peut pas être émise. Pas de nouvelle tentative : corrigez les données ou le document source et démarrez une nouvelle conversion. Codes : `VALIDATION_FAILED` (`details.items`), `DOCUMENT_NOT_CONVERTIBLE` (`details.code`, `details.recovery_hint`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`, `PROTECTED_BANK_DETAILS_MISMATCH` (`details.items`).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR` : le proxy edge n’a pas pu joindre le backend. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un backoff : `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR` : le backend n’a pas répondu à temps. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/validation-report — Télécharger le rapport de validation

Téléchargez le rapport de validation lié à l’artefact livré.

- `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).
- Les en-têtes `X-Artifact-*` décrivent l’artefact de résultat validé, pas les octets du rapport.
- La preuve Factur-X atteste uniquement la validation du XML stocké, pas la fidélité à la source ni la conformité PDF/A.
- Limite de débit : 30/min et 500/h par clé API.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | oui | `task_id` issu de la réponse `202`. Pas un UUID → `400 BAD_REQUEST`. |
| `download` | query | string: `html`, `xml` | oui | `html` pour un rapport lisible, `xml` pour le rapport lisible par machine. Absent → `400 DOWNLOAD_FORMAT_REQUIRED` ; autres valeurs → `400 INVALID_DOWNLOAD_FORMAT`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `200`: Le rapport.

`text/html`

```json
{
  "type": "string"
}
```

`application/xml`

```json
{
  "type": "string"
}
```

- `202`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `405`: `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`.

`application/json`

```json
{
  "$ref": "#/components/schemas/EdgeError"
}
```

- `409`: `409` : la tâche a échoué pour une raison temporaire et ne peut pas reprendre ; répéter cette requête n’aboutit jamais. Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key. Codes : `ARTIFACT_GENERATION_RERUN_REQUIRED` (motif dans `details.code`, par exemple `AUTHORITATIVE_VALIDATION_UNAVAILABLE`), `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: La facture ne peut pas être émise. Pas de nouvelle tentative : corrigez les données ou le document source et démarrez une nouvelle conversion. Codes : `VALIDATION_FAILED` (`details.items`), `DOCUMENT_NOT_CONVERTIBLE` (`details.code`, `details.recovery_hint`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`, `PROTECTED_BANK_DETAILS_MISMATCH` (`details.items`).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `500`: 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é.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `502`: `502 PROXY_ERROR` : le proxy edge n’a pas pu joindre le backend. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un backoff : `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `504`: `504 PROXY_ERROR` : le backend n’a pas répondu à temps. Réessayez avec un backoff et le même Idempotency-Key.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /tasks/{task_id}/correction-result — Télécharger la facture corrigée

Téléchargez la correction liée après sa finalisation par un membre de l’entreprise dans l’éditeur web. Les droits de la clé API et le délai de conservation initiaux s’appliquent. Le téléchargement ne modifie pas le résultat initial et ne consomme pas d’unité supplémentaire. Limite : 60/min et 1,000/h.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | oui | `task_id` issu de la réponse `202`. Pas un UUID → `400 BAD_REQUEST`. |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `200`: Fichier de la facture corrigée et validée.

`application/xml`

```json
{
  "type": "string",
  "format": "binary"
}
```

`application/pdf`

```json
{
  "type": "string",
  "format": "binary"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: Correction indisponible, expirée, non terminée ou devenue invalide. Consultez `code` avant de réessayer.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `409`: Correction indisponible, expirée, non terminée ou devenue invalide. Consultez `code` avant de réessayer.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: Correction indisponible, expirée, non terminée ou devenue invalide. Consultez `code` avant de réessayer.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Correction indisponible, expirée, non terminée ou devenue invalide. Consultez `code` avant de réessayer.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Correction indisponible, expirée, non terminée ou devenue invalide. Consultez `code` avant de réessayer.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /webhook-endpoint — Lire l’endpoint webhook

Renvoie l’URL enregistrée et le résultat de la dernière tentative de livraison. Le secret n’est jamais renvoyé.

- Limite de débit : 30/min et 300/h par clé API, partagée par `POST`, `GET`, `DELETE /webhook-endpoint`.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `200`: L’endpoint enregistré.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpoint"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Aucun endpoint n’est enregistré pour l’entreprise de la clé API.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un délai croissant : `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /webhook-endpoint — Enregistrer ou remplacer l’endpoint webhook

Enregistre l’endpoint HTTPS qui reçoit les événements de fin de l’entreprise de la clé API, ou le remplace. La réponse contient le `secret` de signature ; il n’est plus jamais affiché.

- Un nouvel endpoint renvoie `201`, un remplacement `200`. Un remplacement renouvelle le secret immédiatement : les événements encore en attente partent vers la nouvelle URL, signés avec le nouveau secret.
- L’URL doit utiliser `https` sur le port 443 et désigner un hôte DNS public (voir *Webhooks* dans le guide) ; sinon `422 INVALID_WEBHOOK_URL` avec `details.reason`.
- Aucun `Idempotency-Key` n’est nécessaire. Répéter l’appel remplace l’endpoint et renouvelle à nouveau le secret.
- Limite de débit : 30/min et 300/h par clé API, partagée par `POST`, `GET`, `DELETE /webhook-endpoint`.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `200`: L’endpoint a été remplacé et le secret renouvelé.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpointCreated"
}
```

- `201`: L’endpoint a été enregistré.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpointCreated"
}
```

- `400`: Requête invalide. Pas de nouvelle tentative : corrigez la requête. Voir `ErrorEnvelope.code` pour tous les codes 400.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `413`: 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).

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

`text/plain`

```json
{
  "type": "string"
}
```

- `422`: `422 INVALID_WEBHOOK_URL`. Pas de nouvelle tentative : envoyez une URL conforme aux règles de *Webhooks*. `details.reason` nomme la règle : `scheme`, `port`, `userinfo`, `fragment`, `ip_literal`, `host`, `characters`, `length`, `syntax`, `dns_failed` ou `address_not_allowed`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un délai croissant : `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### DELETE /webhook-endpoint — Supprimer l’endpoint webhook

Supprime l’endpoint et chaque événement encore en attente de livraison. L’interrogation n’est pas affectée.

- Limite de débit : 30/min et 300/h par clé API, partagée par `POST`, `GET`, `DELETE /webhook-endpoint`.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `204`: L’endpoint a été supprimé.
- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Aucun endpoint n’est enregistré pour l’entreprise de la clé API.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un délai croissant : `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /webhook-endpoint:test — Envoyer un événement de test

Place un événement `webhook.test` signé en file pour l’endpoint enregistré. La livraison suit les règles et les nouvelles tentatives habituelles ; `GET /webhook-endpoint` en affiche le résultat.

- Limite de débit : 5/min et 50/h par clé API.

**Paramètres**

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `X-Correlation-ID` | header | string (uuid) |  | 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. |

**Réponses**

- `202`: L’événement de test a été mis en file.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookTestQueued"
}
```

- `401`: Échec de l’authentification. Pas de nouvelle tentative.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Pas de nouvelle tentative : activez un abonnement Enterprise via `details.action_url` ou contactez le support.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Aucun endpoint n’est enregistré pour l’entreprise de la clé API.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: 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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `429`: `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.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `503`: Temporairement indisponible. Réessayez avec un délai croissant : `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

## Schémas

### `ConvertInvoiceRequest`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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"
    },
    "AdvancePaymentSettlement": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AdvancePaymentSettlementRow"
          },
          "maxItems": 200,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Advancepaymentsettlement"
    },
    "UninvoicedPrepaidAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Paiement brut déjà reçu sans facture d’acompte. Inclus dans BT-113 en plus des lignes AdvancePaymentSettlement numérotées et indiqué séparément dans l’annexe de décompte. Ne pas inclure également ce montant dans une ligne d’acompte numérotée.",
      "title": "Uninvoicedprepaidamount"
    },
    "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"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "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`

```json
{
  "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_accounts": {
      "type": "array",
      "maxItems": 5,
      "description": "Comptes bénéficiaires enregistrés, dans l’ordre de sortie. Chaque IBAN doit être valide et unique. Lorsque les données de référence s’appliquent, une liste non vide remplace tous les comptes de virement extraits (codes 30/42/58) ; les autres moyens de paiement conservent leurs règles de sélection.",
      "items": {
        "type": "object",
        "required": [
          "iban"
        ],
        "additionalProperties": false,
        "properties": {
          "iban": {
            "type": "string",
            "maxLength": 34,
            "description": "IBAN bénéficiaire valide (BT-84), normalisé sans espaces."
          },
          "bic": {
            "type": "string",
            "maxLength": 11,
            "description": "BIC de la banque bénéficiaire (BT-86), 8 ou 11 caractères si renseigné."
          },
          "account_name": {
            "type": "string",
            "maxLength": 240,
            "description": "Nom du titulaire du compte 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_accounts": [
        {
          "iban": "DE02120300000000202051"
        }
      ]
    }
  ]
}
```

### `ConvertAcceptedResponse`

```json
{
  "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=<primary_result_format>`."
    },
    "client_reference": {
      "type": "string",
      "description": "Reprise de `client_reference`."
    },
    "source_system": {
      "type": "string",
      "description": "Reprise de `source_system`."
    }
  },
  "additionalProperties": false
}
```

### `TaskStatusResponse`

```json
{
  "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"
    },
    "review_url": {
      "type": "string",
      "format": "uri",
      "description": "Ouvrir la correction dans l’application web. Nécessite un accès à l’entreprise."
    },
    "correction": {
      "type": [
        "object",
        "null"
      ],
      "description": "Correction liée, si elle a été commencée.",
      "required": [
        "status",
        "run_id",
        "item_id"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "review_required",
            "reviewing",
            "completed",
            "expired"
          ]
        },
        "run_id": {
          "type": "string",
          "format": "uuid"
        },
        "item_id": {
          "type": "string",
          "format": "uuid"
        },
        "result_url": {
          "type": "string",
          "description": "URL de téléchargement relative, présente uniquement pour une correction terminée et conservée."
        }
      },
      "additionalProperties": false
    },
    "applied_values": {
      "type": "array",
      "description": "Présent pour une tâche terminée dont le résultat est encore conservé. Valeurs que le service a définies au lieu de les lire dans le document : valeurs issues des données de base du vendeur et valeurs dérivées. Vide lorsque rien n'a été défini. Voir *Valeurs appliquées*.",
      "items": {
        "$ref": "#/components/schemas/AppliedValue"
      }
    }
  },
  "additionalProperties": false
}
```

### `ResultArtifacts`

```json
{
  "type": "object",
  "description": "Disponibilité du téléchargement par artefact.",
  "properties": {
    "xml": {
      "$ref": "#/components/schemas/ResultArtifactStatus"
    },
    "pdf": {
      "$ref": "#/components/schemas/ResultArtifactStatus"
    }
  },
  "additionalProperties": false
}
```

### `ResultArtifactStatus`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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",
        "IDEMPOTENCY_KEY_ALREADY_USED",
        "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",
        "DOCUMENT_NOT_CONVERTIBLE",
        "PROFILE_MISMATCH",
        "ZUGFERD_SOURCE_PDF_INCOMPATIBLE",
        "PROTECTED_BANK_DETAILS_MISMATCH",
        "ZUGFERD_CII_CONVERSION_FAILED",
        "ZUGFERD_PDF_GENERATION_FAILED",
        "XML_GENERATION_FAILED",
        "PDF_GENERATION_FAILED",
        "ARTIFACT_GENERATION_RERUN_REQUIRED",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE",
        "INTERNAL_ARTIFACT_INVARIANT_FAILED",
        "VALIDATION_REPORT_NOT_FOUND",
        "VALIDATION_REPORT_FAILED",
        "PROXY_ERROR",
        "INVALID_WEBHOOK_URL",
        "WEBHOOK_ENDPOINT_NOT_FOUND",
        "WEBHOOK_STORE_UNAVAILABLE",
        "CORRECTION_RESULT_UNAVAILABLE"
      ],
      "x-enumDescriptions": {
        "AUTHENTICATION_REQUIRED": "401 · non · Envoyez `Authorization: Bearer <api_key>`.",
        "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. Activez un abonnement Enterprise via `details.action_url` ou 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 via `details.action_url` 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é.",
        "IDEMPOTENCY_KEY_ALREADY_USED": "409 · non · La clé a déjà servi à une conversion terminée, et ses enregistrements de rejeu de 24 h ont expiré. Utilisez une nouvelle clé pour une nouvelle conversion.",
        "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`, le corps multipart ou un corps webhook (8 Ko) 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, GET sur les chemins de tâche et les méthodes des chemins webhook (voir `Allow`).",
        "NOT_FOUND": "404 · non · Chemin inconnu sous /api/v1.",
        "BAD_REQUEST": "400 · non · `task_id` doit être un UUID, ou un corps webhook n’est pas l’objet JSON `{\"url\": \"...\"}`.",
        "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. Sur `/tasks/{task_id}` et `/result`, aussi une tâche non acceptée via cette API.",
        "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.",
        "DOCUMENT_NOT_CONVERTIBLE": "422 · non · Le document source ne peut pas être converti tel quel (motif dans `details.code`, étape suivante dans `details.recovery_hint`). Corrigez le document 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`.",
        "PROTECTED_BANK_DETAILS_MISMATCH": "422 · non · Un IBAN du bénéficiaire (BT-84) ne fait pas partie des comptes bancaires protégés par l'adresse de contrôle du compte. Aucun fichier n'a été émis et aucune unité n'a été utilisée. Corrigez l'IBAN dans le document source ou ajoutez le compte dans le profil (l'adresse de contrôle doit le confirmer), puis lancez une nouvelle conversion.",
        "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.",
        "ARTIFACT_GENERATION_RERUN_REQUIRED": "409 · nouvelle tâche · Aucun artefact n’a été émis : la génération ou la validation de référence a échoué après les nouvelles tentatives du serveur (motif dans `details.code`, par exemple `AUTHORITATIVE_VALIDATION_UNAVAILABLE`). Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key.",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "409 · nouvelle tâche · Des groupes d’extraction ont échoué (`details.failed_groups`). Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key.",
        "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.",
        "CORRECTION_RESULT_UNAVAILABLE": "400/404/409/410/422/503 · sous conditions · Correction indisponible ou non terminée. Consultez son état. Réessayez les erreurs temporaires ; les données expirées ou supprimées nécessitent un nouvel envoi.",
        "INVALID_WEBHOOK_URL": "422 · non · L’URL du webhook enfreint une règle de *Webhooks*, ou son hôte se résout vers une adresse non publique. Voir `details.reason`.",
        "WEBHOOK_ENDPOINT_NOT_FOUND": "404 · non · Aucun endpoint webhook n’est enregistré pour l’entreprise de la clé.",
        "WEBHOOK_STORE_UNAVAILABLE": "503 · oui · La configuration du webhook n’a pas pu être lue ni enregistrée. Réessayez avec un délai croissant."
      },
      "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`

```json
{
  "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`

```json
{
  "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`, `access`, `message`."
    },
    "code": {
      "type": "string",
      "description": "Code de l’échec sous-jacent : le motif pour `500 TASK_FAILED`, `422 DOCUMENT_NOT_CONVERTIBLE` et `409 ARTIFACT_GENERATION_RERUN_REQUIRED` ; voir `x-enumDescriptions`.",
      "examples": [
        "MULTIPLE_INVOICES_IN_DOCUMENT",
        "NO_INVOICE_DETECTED",
        "INSUFFICIENT_INVOICE_SIGNAL",
        "EMBEDDED_INVOICE_XML_INVALID",
        "EMBEDDED_INVOICE_XML_UNREPRESENTABLE",
        "SOURCE_TEXT_UNAVAILABLE",
        "SCHEMA_PARSE_FAILED",
        "ARTIFACT_PARITY_FAILED",
        "PROVIDER_ERROR",
        "task_interrupted",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE"
      ],
      "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.",
        "EMBEDDED_INVOICE_XML_INVALID": "Définitif. Uniquement avec `use_embedded_xml=true` : le XML intégré au PDF n’a pas pu être lu. Corrigez-le dans le système émetteur ou envoyez le PDF sans `use_embedded_xml`.",
        "EMBEDDED_INVOICE_XML_UNREPRESENTABLE": "Définitif. Uniquement avec `use_embedded_xml=true` : le XML intégré contient une valeur qui ne peut pas être reprise telle quelle, par exemple une date qui n’est pas au format 102 (`YYYYMMDD`). Corrigez-la dans le système émetteur ou envoyez le PDF sans `use_embedded_xml`.",
        "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.",
        "task_interrupted": "Réessayable. Le serveur qui exécutait la conversion s’est arrêté avant la fin. Aucun artefact n’a été émis et aucune unité n’a été utilisée. Démarrez une nouvelle conversion avec une nouvelle clé.",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "Pour `409 ARTIFACT_GENERATION_RERUN_REQUIRED` : le validateur ou une autre dépendance d’artefact est resté indisponible malgré les nouvelles tentatives côté serveur. Aucun artefact n’a été émis et aucune unité n’a été utilisée. Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key."
      }
    },
    "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": "Étape suivante lisible par machine : `start_new_conversion`, `fix_source_document`, `buy_api_credits` ou `activate_api_access`."
    },
    "action_url": {
      "type": "string",
      "format": "uri",
      "description": "Page où le titulaire du compte résout `402 INSUFFICIENT_API_CREDITS` (acheter des crédits) ou `403 API_NOT_ENABLED_FOR_TENANT` (activer l’accès API)."
    },
    "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`

```json
{
  "type": "object",
  "description": "Un problème de validation bloquant.",
  "properties": {
    "field": {
      "type": [
        "string",
        "null"
      ],
      "description": "Chemin du champ de facture, par exemple `BuyerReference`."
    },
    "business_term": {
      "type": [
        "string",
        "null"
      ],
      "description": "Terme métier EN 16931 du champ lorsqu’il est connu, par exemple `BT-10`."
    },
    "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. Pour une ligne qui n’indique qu’un montant, décrit la proposition de `proposal`."
    },
    "proposal": {
      "type": [
        "object",
        "null"
      ],
      "description": "Présent uniquement sur les constats d’une ligne qui n’indique que son montant net (BT-131), sans quantité ni prix unitaire : quantité 1, unité `C62` et prix unitaire = montant net, ce qui est correct pour un forfait ou un article unique. Une proposition, pas une conversion : si la facture indique une quantité et un prix, envoyez-les ; sinon confirmez la proposition en envoyant ces valeurs dans une nouvelle conversion. Absent pour une ligne avec une unité physique, une remise ou des frais, une remise sur le prix, une quantité de base différente de 1 ou un montant négatif.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "amount_only_line"
          ]
        },
        "requires_confirmation": {
          "type": "boolean",
          "description": "Toujours `true` : rien n’est appliqué avant que l’appelant n’envoie les valeurs."
        },
        "line_index": {
          "type": "integer",
          "description": "Position de la ligne dans `InvoiceLine` (ou `CreditNoteLine`), à partir de zéro."
        },
        "line_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "L’identifiant de la ligne (BT-126)."
        },
        "values": {
          "type": "object",
          "description": "Valeurs proposées par chemin de ligne : `InvoicedQuantity` (ou `CreditedQuantity`) `1`, son `@unitCode` `C62` et `Price.PriceAmount` égal au montant net de la ligne.",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [
            {
              "InvoicedQuantity": "1",
              "InvoicedQuantity.@unitCode": "C62",
              "Price.PriceAmount": "250"
            }
          ]
        }
      },
      "required": [
        "kind",
        "requires_confirmation",
        "line_index",
        "values"
      ]
    },
    "message": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true
}
```

### `InsufficientApiCreditsPrepaidError`

```json
{
  "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",
        "recovery",
        "action_url"
      ],
      "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)."
        },
        "recovery": {
          "type": "string",
          "const": "buy_api_credits"
        },
        "action_url": {
          "type": "string",
          "format": "uri",
          "description": "Page de profil qui vend les paquets de crédits API."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `InsufficientApiCreditsAllowanceError`

```json
{
  "type": "object",
  "description": "Structure 402 pour les comptes avec un quota inclus 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",
        "recovery",
        "action_url"
      ],
      "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)."
        },
        "recovery": {
          "type": "string",
          "const": "buy_api_credits"
        },
        "action_url": {
          "type": "string",
          "format": "uri",
          "description": "Page de profil qui vend les paquets de crédits API."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `StructuredInvoice_AccountingCustomerParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "AccountingCustomerParty",
  "type": "object"
}
```

### `StructuredInvoice_AccountingSupplierParty`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "AccountingSupplierParty",
  "type": "object"
}
```

### `StructuredInvoice_AdditionalDocumentReference`

```json
{
  "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_AdvancePaymentSettlementRow`

```json
{
  "additionalProperties": false,
  "description": "Un acompte reçu qu'une facture finale cumulative déduit dans BT-113.\n\nLes lignes ne sont pas un groupe EN 16931 : la facture électronique les contient sous forme de tableau de décompte PDF en pièce jointe\n(BG-24, ID \"advance-settlement\"). Indiquez uniquement les valeurs imprimées sur l'acompte ;\nla TVA n'est jamais déduite du montant brut. La somme des montants bruts doit être égale à BT-113.",
  "properties": {
    "ID": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Issuedate"
    },
    "NetAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Netamount"
    },
    "TaxPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxpercent"
    },
    "TaxAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxamount"
    },
    "GrossAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Grossamount"
    }
  },
  "required": [
    "ID",
    "GrossAmount"
  ],
  "title": "AdvancePaymentSettlementRow",
  "type": "object"
}
```

### `StructuredInvoice_AllowanceCharge`

```json
{
  "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": "string"
        },
        {
          "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": [
        {
          "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`

```json
{
  "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": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Percent"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "ID",
    "TaxScheme"
  ],
  "title": "AllowanceChargeTaxCategory",
  "type": "object"
}
```

### `StructuredInvoice_Attachment`

```json
{
  "additionalProperties": false,
  "properties": {
    "EmbeddedDocumentBinaryObject": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "ExternalReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ExternalReference"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "Attachment",
  "type": "object"
}
```

### `StructuredInvoice_BuyersItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "BuyersItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_CardAccount`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ItemClassificationCode": {
      "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode"
    }
  },
  "required": [
    "ItemClassificationCode"
  ],
  "title": "CommodityClassification",
  "type": "object"
}
```

### `StructuredInvoice_Contact`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "ContractDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_Country`

```json
{
  "additionalProperties": false,
  "properties": {
    "IdentificationCode": {
      "title": "Identificationcode",
      "type": "string"
    }
  },
  "required": [
    "IdentificationCode"
  ],
  "title": "Country",
  "type": "object"
}
```

### `StructuredInvoice_Delivery`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "DespatchDocumentReference",
  "type": "object"
}
```

### `StructuredInvoice_EmbeddedDocumentBinaryObject`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "#text": {
      "title": "#Text",
      "type": "string"
    },
    "@schemeID": {
      "title": "@Schemeid",
      "type": "string"
    }
  },
  "required": [
    "#text",
    "@schemeID"
  ],
  "title": "EndpointID",
  "type": "object"
}
```

### `StructuredInvoice_ExternalReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "URI": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Uri"
    }
  },
  "title": "ExternalReference",
  "type": "object"
}
```

### `StructuredInvoice_FinancialInstitutionBranch`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "FinancialInstitutionBranch",
  "type": "object"
}
```

### `StructuredInvoice_InvoiceLine`

```json
{
  "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": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Invoicedquantity"
    },
    "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`

```json
{
  "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": [
        {
          "enum": [
            "3",
            "35",
            "432"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Descriptioncode"
    }
  },
  "title": "InvoicePeriod",
  "type": "object"
}
```

### `StructuredInvoice_Item`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "IdentificationCode": {
      "title": "Identificationcode",
      "type": "string"
    }
  },
  "required": [
    "IdentificationCode"
  ],
  "title": "OriginCountry",
  "type": "object"
}
```

### `StructuredInvoice_Party`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "CompanyID": {
      "title": "Companyid",
      "type": "string"
    },
    "TaxScheme": {
      "$ref": "#/components/schemas/StructuredInvoice_TaxScheme"
    }
  },
  "required": [
    "CompanyID",
    "TaxScheme"
  ],
  "title": "PartyTaxScheme",
  "type": "object"
}
```

### `StructuredInvoice_PayeeFinancialAccount`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "Party": {
      "$ref": "#/components/schemas/StructuredInvoice_Party"
    }
  },
  "required": [
    "Party"
  ],
  "title": "PayeeParty",
  "type": "object"
}
```

### `StructuredInvoice_PaymentMandate`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "Note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Note"
    },
    "PenaltySurchargePercent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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"
    },
    "DiscountDayBasis": {
      "anyOf": [
        {
          "enum": [
            "calendar_days_from_invoice_date",
            "working_days",
            "goods_receipt_or_other_anchor",
            "unknown"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discountdaybasis"
    },
    "DiscountPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "PriceAmount": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Priceamount"
    },
    "BaseQuantity": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "ProjectReference",
  "type": "object"
}
```

### `StructuredInvoice_SalesOrderReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "SalesOrderReference",
  "type": "object"
}
```

### `StructuredInvoice_SellersItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "SellersItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_StandardItemIdentification`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "schemeID": {
      "default": "0160",
      "title": "Schemeid",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "StandardItemIdentification",
  "type": "object"
}
```

### `StructuredInvoice_TaxCategory`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    },
    "Percent": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "TaxScheme",
  "type": "object"
}
```

### `StructuredInvoice_TaxSubtotal`

```json
{
  "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`

```json
{
  "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`

```json
{
  "additionalProperties": false,
  "properties": {
    "ID": {
      "minLength": 1,
      "title": "Id",
      "type": "string"
    }
  },
  "required": [
    "ID"
  ],
  "title": "TenderOrLotReference",
  "type": "object"
}
```

### `WebhookEndpointRequest`

```json
{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "URL `https` sur le port 443 avec un hôte DNS public. Une chaîne de requête est autorisée ; elle n’est jamais journalisée."
    }
  },
  "additionalProperties": false
}
```

### `WebhookEndpointCreated`

```json
{
  "type": "object",
  "required": [
    "url",
    "secret",
    "created_at",
    "updated_at",
    "event_types",
    "correlation_id"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "secret": {
      "type": "string",
      "pattern": "^whsec_[A-Za-z0-9_-]{43}$",
      "description": "Secret de signature : `whsec_` et 32 octets aléatoires. Affiché uniquement dans cette réponse."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Date du premier enregistrement de l’endpoint (UTC)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Date à laquelle l’URL et le secret ont été définis pour la dernière fois (UTC)."
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "conversion.succeeded",
          "conversion.failed"
        ]
      },
      "description": "Les types d’événements que l’endpoint reçoit."
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookLastDelivery`

```json
{
  "type": [
    "object",
    "null"
  ],
  "required": [
    "at",
    "outcome",
    "status_code",
    "error",
    "event_id"
  ],
  "description": "La dernière tentative de livraison, ou `null` avant la première.",
  "properties": {
    "at": {
      "type": "string",
      "format": "date-time",
      "description": "Date d’enregistrement de la tentative (UTC)."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "delivered",
        "retrying",
        "failed"
      ],
      "description": "`delivered` : une réponse `2xx`. `retrying` : la tentative a échoué et une autre est planifiée. `failed` : la dernière tentative a échoué et l’événement est abandonné."
    },
    "status_code": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Statut HTTP de votre réponse, si elle est arrivée."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cause de l’échec : `http_status`, `timeout`, `connection_failed`, `request_failed`, `dns_failed`, `address_not_allowed` ou une autre règle d’URL de `INVALID_WEBHOOK_URL`."
    },
    "event_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "`id` de l’événement de cette tentative."
    }
  },
  "additionalProperties": false
}
```

### `WebhookEndpoint`

```json
{
  "type": "object",
  "required": [
    "url",
    "created_at",
    "updated_at",
    "event_types",
    "last_delivery",
    "correlation_id"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "conversion.succeeded",
          "conversion.failed"
        ]
      },
      "description": "Les types d’événements que l’endpoint reçoit."
    },
    "last_delivery": {
      "$ref": "#/components/schemas/WebhookLastDelivery"
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookTestQueued`

```json
{
  "type": "object",
  "required": [
    "event_id",
    "type",
    "correlation_id"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "description": "`id` de l’événement mis en file ; la requête le transmet dans `X-Invoice-Converter-Event-Id`."
    },
    "type": {
      "type": "string",
      "enum": [
        "webhook.test"
      ]
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookConversionEventData`

```json
{
  "type": "object",
  "required": [
    "task_id",
    "status",
    "created_at",
    "completed_at",
    "client_reference",
    "source_system",
    "format",
    "profile",
    "error"
  ],
  "description": "Les mêmes valeurs que `GET /tasks/{task_id}` renvoie pour la tâche, plus le `format` et le `profile` demandés.",
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "failed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "client_reference": {
      "type": [
        "string",
        "null"
      ],
      "description": "Écho de `client_reference`."
    },
    "source_system": {
      "type": [
        "string",
        "null"
      ],
      "description": "Écho de `source_system`."
    },
    "format": {
      "type": [
        "string",
        "null"
      ],
      "description": "Le `format` demandé, par exemple `XRECHNUNG`."
    },
    "profile": {
      "type": [
        "string",
        "null"
      ],
      "description": "Le profil effectif, par exemple `XRECHNUNG`."
    },
    "error": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "code"
      ],
      "description": "`null` pour `conversion.succeeded`. Pour `conversion.failed`, le `code` que renvoie `GET /tasks/{task_id}/result` ; appelez-le pour les détails.",
      "properties": {
        "code": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}
```

### `WebhookTestEventData`

```json
{
  "type": "object",
  "required": [
    "test"
  ],
  "properties": {
    "test": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "additionalProperties": false
}
```

### `WebhookEvent`

```json
{
  "type": "object",
  "required": [
    "id",
    "type",
    "api_version",
    "created_at",
    "data"
  ],
  "description": "Corps d’une requête webhook, signé tel qu’envoyé. Récupérez les résultats via les endpoints de tâche.",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^evt_[0-9a-f]{32}$",
      "description": "ID de l’événement, aussi dans `X-Invoice-Converter-Event-Id`. Les nouvelles tentatives le conservent."
    },
    "type": {
      "type": "string",
      "enum": [
        "conversion.succeeded",
        "conversion.failed",
        "webhook.test"
      ]
    },
    "api_version": {
      "type": "string",
      "enum": [
        "v1"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Date de création de l’événement (UTC)."
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/WebhookConversionEventData"
        },
        {
          "$ref": "#/components/schemas/WebhookTestEventData"
        }
      ]
    }
  },
  "additionalProperties": false
}
```

### `AppliedValue`

```json
{
  "type": "object",
  "required": [
    "field",
    "source",
    "code"
  ],
  "properties": {
    "field": {
      "type": "string",
      "description": "Champ de vérification de la valeur, par exemple `Seller.City` ou `Payment.Accounts.0.IBAN`."
    },
    "business_term": {
      "type": "string",
      "description": "Terme métier EN 16931, par exemple `BT-37`. Absent lorsque le champ n'en a pas."
    },
    "source": {
      "type": "string",
      "enum": [
        "seller_master_data",
        "derived"
      ],
      "description": "Origine de la valeur émise."
    },
    "code": {
      "type": "string",
      "description": "Code de motif, voir *Valeurs appliquées*. D'autres codes peuvent être ajoutés."
    },
    "previous_value": {
      "type": "string",
      "description": "La valeur du document qui a été remplacée. Absent lorsque le document n'en contenait pas."
    },
    "value": {
      "type": "string",
      "description": "La valeur émise. Absent lorsqu'une valeur a été supprimée."
    }
  },
  "additionalProperties": false
}
```

## Codes d’erreur

| Code | Description |
| --- | --- |
| `AUTHENTICATION_REQUIRED` | 401 · non · Envoyez `Authorization: Bearer <api_key>`. |
| `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. Activez un abonnement Enterprise via `details.action_url` ou 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 via `details.action_url` 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é. |
| `IDEMPOTENCY_KEY_ALREADY_USED` | 409 · non · La clé a déjà servi à une conversion terminée, et ses enregistrements de rejeu de 24 h ont expiré. Utilisez une nouvelle clé pour une nouvelle conversion. |
| `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`, le corps multipart ou un corps webhook (8 Ko) 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, GET sur les chemins de tâche et les méthodes des chemins webhook (voir `Allow`). |
| `NOT_FOUND` | 404 · non · Chemin inconnu sous /api/v1. |
| `BAD_REQUEST` | 400 · non · `task_id` doit être un UUID, ou un corps webhook n’est pas l’objet JSON `{"url": "..."}`. |
| `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. Sur `/tasks/{task_id}` et `/result`, aussi une tâche non acceptée via cette API. |
| `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. |
| `DOCUMENT_NOT_CONVERTIBLE` | 422 · non · Le document source ne peut pas être converti tel quel (motif dans `details.code`, étape suivante dans `details.recovery_hint`). Corrigez le document 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`. |
| `PROTECTED_BANK_DETAILS_MISMATCH` | 422 · non · Un IBAN du bénéficiaire (BT-84) ne fait pas partie des comptes bancaires protégés par l'adresse de contrôle du compte. Aucun fichier n'a été émis et aucune unité n'a été utilisée. Corrigez l'IBAN dans le document source ou ajoutez le compte dans le profil (l'adresse de contrôle doit le confirmer), puis lancez une nouvelle conversion. |
| `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. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED` | 409 · nouvelle tâche · Aucun artefact n’a été émis : la génération ou la validation de référence a échoué après les nouvelles tentatives du serveur (motif dans `details.code`, par exemple `AUTHORITATIVE_VALIDATION_UNAVAILABLE`). Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key. |
| `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 409 · nouvelle tâche · Des groupes d’extraction ont échoué (`details.failed_groups`). Démarrez une nouvelle conversion avec une nouvelle Idempotency-Key. |
| `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. |
| `CORRECTION_RESULT_UNAVAILABLE` | 400/404/409/410/422/503 · sous conditions · Correction indisponible ou non terminée. Consultez son état. Réessayez les erreurs temporaires ; les données expirées ou supprimées nécessitent un nouvel envoi. |
| `INVALID_WEBHOOK_URL` | 422 · non · L’URL du webhook enfreint une règle de *Webhooks*, ou son hôte se résout vers une adresse non publique. Voir `details.reason`. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` | 404 · non · Aucun endpoint webhook n’est enregistré pour l’entreprise de la clé. |
| `WEBHOOK_STORE_UNAVAILABLE` | 503 · oui · La configuration du webhook n’a pas pu être lue ni enregistrée. Réessayez avec un délai croissant. |
