Documentation API externe V1

Fonctionnalités clés#

Utilisez ces points comme contrôles pratiques pour cette section.

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

Démarrage rapide#

Trois appels API terminent une conversion. L’endpoint de conversion est servi sous /api/v1 et nécessite une authentification.

Demander l’accès bêta fermée#

Utilisez ces points comme contrôles pratiques pour cette section.

• L’accès API est limité aux partenaires approuvés de la bêta fermée.
• Demandez l’accès par e-mail avec entreprise, cas d’usage, date cible d’intégration, volume mensuel attendu et formats requis.
• L’équipe confirme l’adéquation, provisionne les identifiants de test et partage les contacts de support onboarding.
• Les identifiants live sont émis après validation du workflow de test et approbation commerciale.

URL de base et environnements#

Utilisez ces points comme contrôles pratiques pour cette section.

• URL de base production : https://invoice-converter.com/api/v1.
• Les clés test et live utilisent le même host ; les préfixes (icp_test_*, icp_live_*) identifient l’environnement.
• Utilisez les clés icp_test_* pour l’onboarding et les runs de validation avant de passer aux clés live.
• 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 réception des identifiants de bêta fermée.

• 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?download=xml et stockez X-Correlation-ID plus X-Validation-Proof-Id s’il est présent.
• Pour une sortie PDF ZUGFeRD, demandez format=ZUGFERD au convert et download=pdf au result.

Exemples courants de payload#

Utilisez ces points comme contrôles pratiques pour cette section.

• XRECHNUNG : envoyez format=XRECHNUNG ; c’est la valeur par défaut si format est omis.
• ZUGFERD : envoyez format=ZUGFERD ; utilisez download=pdf au result pour la sortie hybride PDF/A-3.
• UBL : envoyez format=UBL avec un profile explicite comme PEPPOL, XRECHNUNG ou EN16931.
• CII : envoyez format=CII avec un profile explicite comme EN16931.

En-têtes requis#

Utilisez ces points comme contrôles pratiques pour cette section.

• Authorization: Bearer <api_key>

Règles d’authentification#

L’accès API est actuellement en bêta fermée. Les partenaires approuvés utilisent une clé API comme Bearer token ; les clés sont provisionnées pendant l’onboarding.

• Les clés sont scoped par tenant et par environnement (live / test). Le préfixe de clé détermine l’environnement.
• Les clés sont émises aux partenaires approuvés de la bêta fermée pendant l’onboarding ; contactez le support pour le provisionnement ou la rotation.
• 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#

Utilisez ces points comme contrôles pratiques pour cette section.

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

Matrice des formats de sortie#

Journal des modifications#

Dernières évolutions visibles de l’API.

Contrat d’erreur#

Erreurs courantes et actions à mener#

Utilisez ces points comme contrôles pratiques pour cette section.

• 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 ces points comme contrôles pratiques pour cette section.

• 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#

Utilisez ces points comme contrôles pratiques pour cette section.

• 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#

Utilisez ces points comme contrôles pratiques pour cette section.

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

Utiliser Postman et OpenAPI#

Utilisez ces points comme contrôles pratiques pour cette section.

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