# Documentation API externe V1 Pack documentaire technique pour l’implémentation et la revue API en libre-service. Cette page résume le contrat API externe, le modèle d’accès et les contraintes d’intégration. ## Vue d’ensemble Pack documentaire technique pour l’implémentation et la revue API en libre-service. Cette page résume le contrat API externe, le modèle d’accès et les contraintes d’intégration. L’API accepte les envois multipart, renvoie des réponses JSON et utilise les codes de statut HTTP standard ainsi que l’authentification Bearer. Envoyez une facture PDF, attendez le traitement asynchrone, puis récupérez le résultat généré. Envoyez une facture PDF à un endpoint unique et Invoice-Converter gère l’extraction, la validation et la génération de sortie. L’endpoint de résultat ne renvoie le fichier généré qu’après réussite des contrôles de validation ; sinon il renvoie 422 VALIDATION_FAILED. > **Statut: libre-service**: Chemin de base: /api/v1. Dernière synchronisation 2026-05-23. ## Fonctionnalités clés - Un endpoint unique pour convertir un PDF en XML - Extraction de données de facture assistée par IA - Validation automatique EN 16931 et KoSIT - Formats de sortie XRechnung, ZUGFeRD, UBL et CII - Traitement asynchrone avec polling, petites factures en environ 30 secondes et factures plus volumineuses jusqu’à 1-2 minutes - Écritures idempotentes pour des retries sûrs ## Artefacts de livraison Téléchargez les artefacts d’intégration lisibles par machine pour la Developer API. - [OpenAPI JSON](/developer-api/v1/openapi.json) - [Collection Postman](/developer-api/v1/postman.json) - [API Playground](/developer-api/playground) ## Démarrage rapide Trois appels API terminent une conversion. L’endpoint de conversion est servi sous /api/v1 et nécessite une authentification. ### POST /api/v1/invoices:convert (En développement) Convertir un PDF en e-facture structurée ### GET /api/v1/tasks/{task_id} (En développement) Interroger le statut de tâche ### GET /api/v1/tasks/{task_id}/result (En développement) Télécharger le résultat de conversion ## Demander l’accès bêta fermée - Connectez-vous et ouvrez la section profil. - Achetez des crédits API prépayés ou utilisez un plan Enterprise avec accès API inclus. - Créez une clé API pour votre tenant. - Envoyez la première requête avec Bearer token et une clé d’idempotence stable. ## URL de base et clés API - URL de base production : `https://invoice-converter.com/api/v1`. - Utilisez le même host API de production pour tout le trafic pilote : `https://invoice-converter.com/api/v1`. - Utilisez des requêtes fixture à faible volume pendant l’onboarding ; les conversions acceptées consomment des crédits API. - Traitez les clés comme des secrets serveur. Ne les intégrez pas dans des clients navigateur ou mobiles. ## Première requête réussie Utilisez cette séquence comme parcours minimal après création d’une clé API. - Téléversement : `POST /api/v1/invoices:convert` avec `Authorization`, `Idempotency-Key`, `file=@invoice.pdf` et `format=XRECHNUNG`. - Interrogez toutes les `2-5 secondes` : `GET /api/v1/tasks/{task_id}` jusqu’au statut `completed` ou `failed`. - Téléchargement : `GET /api/v1/tasks/{task_id}/result` et stockez `X-Correlation-ID` plus `X-Validation-Proof-Id` s’il est présent. - Pour une sortie PDF ZUGFeRD, envoyez `format=ZUGFERD` ; l’endpoint de résultat renvoie le PDF hybride par défaut. ## Exemples courants de payload - `XRECHNUNG` : envoyez `format=XRECHNUNG` ; c’est la valeur par défaut si format est omis. - `ZUGFERD` : envoyez `format=ZUGFERD` pour un PDF hybride EN16931 ZUGFeRD/Factur-X. - `UBL` : envoyez `format=UBL` pour du XML UBL EN16931. - `CII` : envoyez `format=CII` pour du XML CII EN16931. ## En-têtes requis - Authorization: Bearer ## Règles d’authentification L’accès API est disponible en libre-service. Créez des clés API depuis votre profil, utilisez-les comme Bearer token et achetez des crédits API prépayés pour l’automatisation de conversion. - Les clés sont scoped par tenant et utilisent le préfixe `icp_`. - Les clés sont créées, tournées et révoquées depuis le profil quand l’accès External API est activé. Copiez les nouvelles clés immédiatement, car elles ne sont affichées en clair qu’une seule fois. - Une clé manquante ou invalide renvoie `401`. - Les appels vers `/api/v1` reçoivent automatiquement un `X-Correlation-ID` s’il est omis. - Les appels d’écriture exigent `Idempotency-Key` ; gardez cette valeur stable entre les réessais. - Utilisez une intégration serveur-à-serveur depuis votre backend. L’accès depuis une origine navigateur est restreint en production. ## Contrat d’idempotence - Envoyez un `Idempotency-Key` à chaque appel d’écriture. - Les clés d’idempotence doivent correspondre à `[A-Za-z0-9._:-]+` et faire au plus 200 caractères. - Si vous fournissez votre propre clé, la même clé + le même payload renvoie la réponse en cache. - La même clé + un payload différent renvoie `409 IDEMPOTENCY_CONFLICT`. - Les clés d’idempotence expirent après `24 hours`. ## Référence des endpoints Tous les endpoints sont disponibles sous /api/v1. Les timeouts apparaissent en 504 et les autres erreurs temporaires de connectivité en 502 ; les ID de corrélation aident le support à suivre les requêtes de bout en bout. ### POST /api/v1/invoices:convert (En développement) Téléversez une facture PDF et démarrez la conversion asynchrone. Renvoie une task_id pour le polling. Requête: multipart/form-data. Réponse: 202 Accepted. ### GET /api/v1/tasks/{task_id} (En développement) Interrogez le statut actuel d’une tâche de conversion. Renvoie pending, processing, completed ou failed. En cas d’échec, la réponse inclut un champ error avec le motif. Requête: aucun (GET). Réponse: 200 OK. ### GET /api/v1/tasks/{task_id}/result (En développement) Téléchargez le fichier généré. Les tâches ZUGFERD renvoient par défaut un PDF hybride EN16931 ZUGFeRD/Factur-X ; les autres formats renvoient par défaut du XML. Les téléchargements répétés peuvent être servis depuis des artefacts générés en cache. Si des problèmes de validation bloquants subsistent, cet endpoint renvoie 422 VALIDATION_FAILED sans corps de fichier. Requête: aucun (GET). Réponse: 200 OK. ## Matrice des formats de sortie | Format | Syntaxe | Version / Profil | Content-Type | Extension | | --- | --- | --- | --- | --- | | XRECHNUNG | UBL 2.1 XML | XRechnung 3.0.2 | application/xml | .xml | | ZUGFERD | PDF/A-3 hybride EN16931 par défaut ; XML CII avec download=xml | ZUGFeRD 2.4 / Factur-X 1.08 | application/pdf ou application/xml | .pdf / .xml | | EN16931 | UBL 2.1 XML | EN 16931 | application/xml | .xml | | UBL | UBL 2.1 XML | OASIS UBL 2.1 | application/xml | .xml | | CII | UN/CEFACT CII XML | D16B | application/xml | .xml | ## Journal des modifications Dernières évolutions visibles de l’API. ### 2026-05-08 Crédits API externes prépayés ajoutés pour les tenants non Enterprise. 402 INSUFFICIENT_API_CREDITS documenté pour les tenants sans facturation Enterprise ni crédits prépayés. Confirmation que les relectures idempotentes ne consomment pas de crédits API supplémentaires. Requêtes de conversion simplifiées à fichier plus format ; le réglage d’extraction est géré côté serveur. ### 2026-03-06 Les téléchargements task-result respectent désormais le format pour les sorties CII et ZUGFERD. Réutilisation d’artefacts de résultat en cache ajoutée pour les téléchargements XML/PDF répétés d’une même tâche. Quotas de polling alignés sur les buckets de rate-limit pondérés par endpoint. ### 2026-02-23 Réponses d’erreur API plus claires et cohérentes ajoutées sur tous les endpoints. Options de conversion étendues et comportement de téléchargement XML/PDF documenté pour les résultats de tâche. Sécurité des réessais améliorée avec des exigences d’idempotence et une validation plus strictes. Artefacts OpenAPI/Postman mis à jour pour correspondre au comportement actuel de l’API. ### 2026-02-20 Réponses de statut simplifiées vers une sortie centrée sur le statut. Validation de soumission IndexNow et contrôles d’authentification renforcés. Contrôles d’accès API et comportement de limitation de requêtes durcis en production. ## Contrat d’erreur | Code | HTTP | À retenter | Notes | | --- | --- | --- | --- | | AUTHENTICATION_REQUIRED | 401 | Non | Bearer token manquant/vide | | INVALID_API_KEY | 401 | Non | Clé API introuvable, révoquée ou expirée | | INSUFFICIENT_API_CREDITS | 402 | Non | Achetez au moins 10 crédits API prépayés ou utilisez la facturation Enterprise | | IDEMPOTENCY_KEY_REQUIRED | 400 | Non | Endpoint d’écriture appelé sans Idempotency-Key | | INVALID_IDEMPOTENCY_KEY | 400 | Non | Format de clé d’idempotence invalide | | IDEMPOTENCY_CONFLICT | 409 | Non | Même clé utilisée avec un hash de requête différent | | IDEMPOTENCY_IN_PROGRESS | 409 | Oui | Réessai sûr plus tard avec la même clé/le même payload | | AUTH_SERVICE_UNAVAILABLE | 503 | Oui | Backend d’auth indisponible | | RATE_LIMIT_SERVICE_UNAVAILABLE | 503 | Oui | Backend de rate-limit indisponible | | RATE_LIMITED | 429 | Oui | Respecter Retry-After et les headers de quota | | BAD_REQUEST | 400 | Non | JSON invalide ou paramètre de chemin UUID invalide | | PAYLOAD_TOO_LARGE | 413 | Non | Limite de taille d’upload dépassée | | INVALID_UPLOAD | 400 | Non | Échec de lecture/parsing de l’upload | | UPLOAD_FAILED | 4xx/5xx | Conditionnel | Corriger les options de requête invalides ; réessayer uniquement pour les cas 5xx transitoires | | TASK_NOT_READY | 202 | Oui | Poller à nouveau pour la fin asynchrone | | TASK_STATUS_FAILED | 4xx/5xx | Conditionnel | Réessayer si la condition de service est transitoire | | TASK_RESULT_FAILED | 4xx/5xx | Conditionnel | Réessayer si la condition de service est transitoire | | XML_GENERATION_FAILED | 500 | Oui | Échec transitoire ou timeout de génération XML | | PDF_GENERATION_FAILED | 500 | Oui | Échec transitoire ou timeout de génération PDF | | PROFILE_MISMATCH | 422 | Non | Invoice CustomizationID conflicts with the selected public format | | PROXY_ERROR | 502/504 | Oui | Erreur de connectivité temporaire (504 pour timeout) | ## Erreurs courantes et actions à mener - Réessayez avec backoff : `429`, `500`, `502`, `503`, `504`. - Corrigez la requête ou les données source : `400`, `409`, `413`, `422`. - Corrigez l’accès ou les identifiants : `401`, `403`. - Continuez à poller plus tard : `202 TASK_NOT_READY`. - Pour `422 VALIDATION_FAILED`, montrez le champ, l’ID de règle et la correction proposée à une personne chargée de la revue avant de réessayer avec les données corrigées. ## Limites de débit et de payload Les rate limits par clé et les contraintes de taille de payload s’appliquent à tous les appels API. Les requêtes refusées ne consomment pas de quota. - Les quotas sensibles à l’endpoint sont pondérés par coût. Convert utilise le quota de base du plan (par défaut `30/min` et `500/hour`), tandis que les endpoints de polling utilisent des quotas à pondération plus faible. - Lisez les limites effectives dans `X-RateLimit-Limit-Minute` et `X-RateLimit-Limit-Hour` sur les réponses. - Taille maximale d’upload PDF : `20 MB` - Taille maximale de payload JSON : `1 MB` - Les réponses de rate-limit incluent `Retry-After`, `X-RateLimit-Limit-Minute` et `X-RateLimit-Limit-Hour`. ## Guide de nouvelle tentative - Utilisez un backoff exponentiel avec jitter. - Ne réessayez que les classes transitoires (`429`, `500`, `502`, `503`, `504`) avec le même payload et la même clé d’idempotence lorsque possible. - Ne réessayez pas aveuglément les erreurs de validation ou de contrat (`400`, `401`, `403`, `409`, `413`). ## Cycle de vie des tâches et rétention - Les tâches completed et failed restent disponibles pendant `10 minutes` après l’état terminal. - Le traitement expire après `5 minutes` ; les tâches bloquées sont automatiquement marquées `failed`. - Les clés d’idempotence expirent après `24 hours`. - Les compteurs de rate-limit se réinitialisent sur une fenêtre glissante. ## Modèle de support - Support pendant les heures ouvrées. - Objectif de première réponse : 1 jour ouvré. ## Envoyer un retour technique Partagez avec notre équipe les questions d’implémentation, risques et changements de contrat nécessaires. - [Envoyer un retour technique par e-mail](mailto:contact@invoice-converter.com?subject=Retour%20de%20revue%20technique%20API%20externe%20V1&body=Bonjour%20%C3%A9quipe%20Invoice-Converter%2C%0D%0A%0D%0ANous%20avons%20revu%20la%20documentation%20API%20externe%20V1%20et%20avons%20les%20retours%20suivants%20%3A%0D%0A%0D%0A1)%2520%0D%0A2)%2520%0D%0A3)%2520%0D%0A%0D%0ACordialement%2C) ## Utiliser Postman et OpenAPI - Importez la collection Postman et définissez `baseUrl`, `apiKey` et une nouvelle variable `idempotencyKey`. - Exécutez la collection dans l’ordre : convert, polling du statut, puis récupération du résultat. - Utilisez l’OpenAPI JSON pour générer des clients typés, mais couvrez upload fichier, polling et résultat binaire par des tests d’intégration. - Enregistrez `X-Correlation-ID` dans les logs afin que le support puisse tracer les requêtes de bout en bout.