Documentation API externe V1

Fonctionnalités clés#

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

• Endpoints d’upload pour factures PDF et données de facture structurées
• Extraction de données de facture assistée par IA
• Validation automatique EN 16931 et KoSIT
• Formats de sortie XRechnung, ZUGFeRD, EN16931, 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.

Obtenir un accès API#

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

• Créez un compte et demandez l’accès API.
• Utilisez des crédits API prépayés pour les tests approuvés ou une facturation Enterprise par order form pour l’usage production.
• Après approbation, créez une clé API live depuis la section d’accès API.
• Envoyez la première requête avec des identifiants côté serveur, puis surveillez l’usage et tournez les clés depuis votre profil.

URL de base et clés API#

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

• URL de base production : https://www.invoice-converter.com/api/v1.
• Les clés live utilisent le host de production et le préfixe icp_....
• Lancez les requêtes d’onboarding et de validation avec des clés live approuvées avant d’envoyer du volume de production.
• 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 10-15 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 pour le traçage support.
• Pour une sortie PDF ZUGFeRD, demandez format=ZUGFERD au convert et download=pdf au result.
• Pour une entrée structurée, appelez POST /api/v1/invoices:convert-structured avec pdf_file=@invoice.pdf, data_file=@invoice-data.json et le format cible.
• Envoyez éventuellement client_reference ou external_invoice_id et source_system pour le rapprochement ERP.
• Pour des exports ERP fractionnés d’une facture, répétez data_file ; pour plusieurs factures, démarrez une tâche par facture avec sa propre clé d’idempotence.
• Conservez result_artifacts depuis la réponse de statut pour savoir quels artefacts XML/PDF sont validés, mis en cache ou encore indisponibles à cause de dépendances.

Exemples courants de payload#

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

• XRECHNUNG : envoyez format=XRECHNUNG.
• ZUGFERD : envoyez format=ZUGFERD ; utilisez download=pdf au result pour la sortie hybride PDF/A-3.
• Entrée structurée : envoyez pdf_file avec une ou plusieurs parties data_file ; les formats de données acceptés sont CSV, JSON, XML, XLSX et TXT, avec tout format cible pris en charge. Les parties data_file doivent contenir toutes les données obligatoires ; le PDF ne complète pas les champs manquants. .xls, les PDF et les images sont refusés comme data_file.
• Factures multiples : envoyez des requêtes convert séparées et suivez chaque task_id renvoyé ; les parties data_file répétées servent uniquement aux exports fractionnés de la même facture.
• UBL : envoyez format=UBL ; pour les intégrations déterministes, définissez un profile explicite comme PEPPOL, XRECHNUNG ou EN16931.
• CII : envoyez format=CII ; pour les intégrations déterministes, définissez 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 soumis à approbation. Les comptes approuvés peuvent créer des clés API depuis le profil, les utiliser comme Bearer token et utiliser des crédits prépayés pour les tests approuvés ou une facturation Enterprise par order form pour la production.

• Les clés sont des identifiants live limités au tenant pour les comptes approuvés. Le préfixe de production actuel est icp_....
• Créez, tournez et révoquez les clés API depuis votre profil après activation de l’accès API. Copiez les nouvelles clés immédiatement, car leur valeur en clair n’est affichée 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 heures.

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.
• Confirmez l’approbation, les crédits de test prépayés ou la facturation Enterprise par order form : 402 INSUFFICIENT_API_CREDITS.
• 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.
• Pour 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE, récupérez le même résultat de tâche plus tard ; aucun artefact non vérifié n’a été livré.

Limites de débit et de payload#

Les rate limits par clé API et les contraintes de taille de payload s’appliquent à tous les appels API. Les conversions refusées ne consomment pas de crédits API prépayés ; les rate limits sont évaluées séparément par endpoint.

• Les limites sensibles à l’endpoint sont pondérées par coût. Les deux endpoints d’upload utilisent le quota de base du plan (par défaut 30/min et 500/hour) ; le polling de tâche est actuellement au moins 10/min et 120/hour, et les téléchargements de résultat au moins 10/min et environ 134/hour par défaut.
• 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 d’upload des données structurées : 2 MB au total sur toutes les parties data_file.
• 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, 402, 403, 409, 413, 422).

Cycle de vie des tâches et rétention#

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

• Les tâches terminées (completed) et échouées (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 heures.
• 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 en heures ouvrées selon des efforts commercialement raisonnables.
• Aucun SLA formel, crédit de service ou engagement de temps de réponse sauf accord dans un order form.

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.