API pour la Lecture Automatique des Relevés Bancaires
Généralités
Le fonctionnement du R.B API se caractérise par 2 événements principaux :
Le relevé bancaire reçu peut être traité automatiquement
Le relevé bancaire reçu doit être validé manuellement (accès limité) (1): un opérateur spécialisé interviendra pour valider les résultats de l'extraction
La facturation est réalisée par page présente dans le document envoyé.
A noter: le traitement manuel est désactivé pour les comptes de test de ce fait une liasse devant être traitée manuellement passera en erreur.
Méthodes exposées
ExtractLive : extraction des données en temps réel, utilisé pour des applications "Live"
Priorité : priorité maximum de traitement automatique/manuel
Limite : 1 appel toutes les 10 secondes
Charge : 10 fichiers par requête
Format : chaque document est à fournir à l'api en base64 dans le propriété data
Try extract auto (en cours) : extraction des données en temps réel sur un fichier de manière synchrone
Priorité : priorité maximum de traitement automatique
Limite : 1 appel toutes les 5 secondes
Facturé uniquement si l'extraction automatique est réussie
Retourné en erreur si le document ne peut pas être traité sans intervention manuelle
GetProcessStatus : obtenir l'avancement du traitement des documents envoyés
Limite : 1 appel toutes les secondes
Le suivi de l'extraction se fait par deux de ses propriétés :
ExtractionMode : indique le mode d'extraction utilisé pour le document
"None" : mode inconnu car le process n'est pas encore démarré
"Automatic" : la reconnaissance est gérée de manière automatique par Inovaclic
"Manual" : le document requière une intervention manuelle
ExtractionStatus : indique le statut de l'extraction
"InProgress" : extraction en cours
"Error" : une erreur est survenue lors de l'extraction du document
"Finished" : le document est extrait avec succès
Get Process Data : obtenir le résultat de l'extraction des données d'un ensemble de relevé bancaire
Limite : 1 appel toutes les 5 secondes
Get Rb Data : obtenir le résultat de l'extraction des données d'un relevé bancaire spécifique
Limite : 1 appel toutes les secondes
Attention, en plus des restrictions par méthode, l'api est limitée à 10 000 appels et 1500 mo de bande passante par heure.
En cas de dépassement des limites, l'api renverra le code http 429 (too many requests) dans le cas d'un trop grand nombre d'appel ou http 403 (forbidden) dans le cas où la bande passante autorisée est dépassée.
Paramètres
L'api du Lab fonctionnant en mode asynchrone, il est nécessaire pour un fonctionnement optimal de fournir deux callbacks dans votre système:
callbackCompleted: correspond à l'endroit où vous souhaitez recevoir vos résultats
callbackManual: si les fichiers que vous nous envoyez sont au format natif, nous n'aurons jamais besoin de ce callback. Dans le cas contraire c'est l'endroit dans lequel nous vous notifierons que l'analyse requiert une intervention manuelle. Le résultat vous sera donc fournit dans la première callback callbackCompleted lorsque l'intervention manuelle sera terrminée (EN COURS DE DEVELOPPEMENT)
Dans l'éventualité où vous ne possédez pas de serveur pour recueillir les résultats via Webbook, nous vous fournissons un système de polling par le biais de la méthode GetProcessStatus pour obtenir le status des traitements. La réponse fournie par cette méthode contient l'ensemble des avancements de traitement pour chacun des relevés de compte.
Gestion des erreurs de réception
Si votre serveur est indisponible au moment de l'envoi des résultats (http code non compris entre 200-299), 8 nouvelles tentatives pourront être réalisées avec le schéma de temporalité suivant: 1min > 30min > 1h > 3h > 6h > 12h > 24h > 36h.
De plus un email de notification d'erreur peut vous être envoyé. L'email de réception est actuellement uniquement configurable auprès du service client Inovaclic.
Vérifier la signature des requêtes Inovaclic (optionnel) (en cours)
Inovaclic signe les réponses envoyées au callback en incluant une signature dans l’en-tête inovaclic-signature. Cela vous permet de vérifier que les évènements ont été envoyés par Inovaclic et non par un tiers.
Avant de pouvoir vérifier les signatures, vous devez récupérer la clé publique de signature d'Inovaclic via la section Développeur de l'espace client : https://inovaclic.io/administration/developer
Copiez la clé.
La clé est une clé publique RSA SHA256 au format XML (utf8) en base64 et la signature est égale au hash SHA-256 en base64 du contenu du corps de la réponse. Vous pouvez vérifier la signature dans n’importe quel langage de programmation, voici des exemples d’implémentation.
.NET: voir le code
Node.js: voir le code
Java: voir le code
Ajouter une en-tête personnalisée (optionnel) (en cours)
Inovaclic peut ajouter une en-tête personnalisée à chacun des évènements envoyés afin de pouvoir par exemple être autorisé à joindre vos apis.
Vous pouvez ajouter une en-tête personnalisée via l’espace client dans la section Développeur : https://inovaclic.io/administration/developer
Clé: clé de l'entête
limité à 256 caractères
chiffre, lettre et tiret acceptés
Valeur: valeur affectée à l'entête
limité à 1024 caractères
caractères ASCII acceptés
Codes d'erreur
En cas de problème, un message d'erreur est fourni dans statusInfo.message selon le format : "[CODE] DESCRIPTION (DETAILS_FACULTATIFS)"
Voici la liste des codes d'erreur possibles :
E0100 : Le document soumis n'est pas un relevé bancaire valide
E0101 : Le document soumis présente une ou plusieurs pages manquantes
E0102 : Le document soumis est endommagé et illisible
E0200 : La mauvaise qualité du document empêche son traitement
E0300 : Les données ne sont pas cohérentes avec le total des opérations
E0301 : Les données ne sont pas cohérentes avec les soldes ancien et nouveau
E0000 : Autre
Exemple :
[E0200] La mauvaise qualité du document empêche son traitement (Page 11 illisible)
[E0100] Le document n'est pas un relevé bancaire valide
Note : Seul le CODE est permanent et doit être utilisé pour détecter automatiquement le type d'erreur.
Résultats
Fichier d'exemple: Télécharger
Exemple de requête: Télécharger
Extraction réussie: Télécharger
Le taux de reconnaissance automatique sur les banques gérées varie entre 60% et 90%. Ce score dépend en grande partie:
Du type de banque
De la qualité du document
Des potentielles erreurs dans le document
De l'origine géographique de la banque (seules les banques Françaises sont actuellement officiellement supportées)
De la monnaie (seul l'euro est actuellement géré)
L'ancienneté du format du relevé bancaire
En cas d'echec de reconnaissance automatique, le traitement est réalisé/complété de façon manuelle par un opérateur de saisie Inovaclic.
(1) jour ouvré de 9h à 17h