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.

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

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

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

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

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

• Authorization: Bearer <api_key>

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#

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.