API pour la Lecture Automatique de Bilans (LAB)
Retrouvez un exemple et une documentation complète de l'api sur postman : LAB | Inovaclic | API
Généralités
Le fonctionnement du LabApi se caractérise par 2 événements principaux :
Le bilan reçu peut être traité automatiquement : 1 seconde maximum par page du bilan à extraire
Le bilan reçu doit être validé manuellement : un opérateur spécialisé interviendra pour valider les résultats de l'extraction
Méthodes exposées
Extract Live : extraction des données en temps réel, utilisé pour des applications "Live"
Priorité : priorité maximum de traitement automatique/manuel (< 20 minutes les jours ouvrés (2))
Limite : 1 appel toutes les 3 secondes
Charge : 10 fichiers par requête
Format : chaque liasse est à fournir à l'api en base64 dans le propriété data
Extract Batch : extraction des données sur un grand volume de fichier
Priorité : priorité moyenne de traitement automatique/manuel (< 48h les jours ouvrés (2))
Limite : 1 appel toutes les 8 secondes
Charge : 100 fichiers par requête
Format : chaque liasse est à fournir à l'api en base64 dans le propriété data
Get Process Status : obtenir l'avancement du traitement des documents envoyés par un Extract
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 la liasse
"None" : le process n'est pas encore démarré
"Automatic" : la reconnaissance est gérée de manière automatique par Inovaclic
"Manual" : la liasse requière une intervention manuelle (cette étape peut durer de quelques secondes en cas de vérification semi-automatique) (1)
ExtractionStatus : indique le statut de l'extraction
"InProgress" : en cours de traitement
"Failed" : erreur technique Inovaclic
"Rejected" : rejeté fonctionnellement (pages manquantes, données fausses, mauvais imprimé etc.)
"Canceled" : annulé/timeout
"Succeeded" : terminé avec succès (il peut y avoir un message d'information en completion dans le champs statusMessage)
Cette méthode n'est pas disponible pour Extract Batch
Get Process Data : obtenir le résultat de l'extraction des données par un Extract
Limite : 1 appel toutes les 3 secondes
Cette méthode n'est pas disponible pour Extract Batch
Get Liasse Data : obtenir le résultat de l'extraction d'un document par un Extract
Limite : 5 appels toutes les 5 secondes
Cette méthode n'est pas disponible pour Extract Batch
Limites d’utilisation de l’API
En plus des restrictions propres à chaque méthode, l’API est soumise aux limites suivantes :
10 000 appels par heure
1 500 Mo de bande passante par heure
Dépassement des limites
Si le nombre maximal d’appels est dépassé, l’API renvoie un code HTTP 429 – Too Many Requests.
Si la bande passante autorisée est dépassée, l’API renvoie un code HTTP 403 – Forbidden.
Assurez-vous de mettre en place un mécanisme de gestion des erreurs et de reprise pour éviter toute interruption de service lors du dépassement de ces limites.
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 (schéma de réponse identique à la méthode Get Process Data)
callbackManual: Si une intervention manuelle est requise (par exemple en cas de doute sur les données, de documents non natifs ou d’erreurs dans les données), cet endpoint sera utilisé pour vous notifier que l’analyse ne peut pas être finalisée automatiquement. Une fois l’intervention manuelle terminée, le résultat final vous sera transmis via la première callback
callbackCompleted. (Schema)
Recommandation sur l’utilisation de l’API
Nous déconseillons fortement de développer des systèmes de polling pour interagir avec notre API.
En raison des limites d’usage et de sécurité, la réception des traitements peut être fortement ralentie et la mise en place de tels systèmes peut entraîner une complexité de développement accrue.
Les méthodes suivantes ne doivent être utilisées que pour des besoins ponctuels :
Elles sont destinées, par exemple, au rafraîchissement ponctuel des données dans votre système, et non à un usage intensif ou continu.
Restrictions sur les URL de callback
Seules les URL de callback utilisant un domaine à résolution statique sont autorisées. Les domaines avec résolution dynamique ne sont pas acceptés.
Pendant la phase de développement, il est possible, pour des raisons de praticité, d’utiliser des solutions de tunnel permettant de rediriger les informations vers un serveur local, par exemple : ngrok, frp, localtunnel
Il est également possible d’intercepter les réponses via des services en ligne d’inspection de webhooks, tels que : Pipedream et Webhook.site
Attention : Avant d’utiliser ces services, assurez-vous de vérifier leur niveau de confidentialité et de sécurité, afin d’éviter toute fuite de données sensibles.
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.
En cas d'erreur de communication avec votre serveur une notification live apparait sur votre espace client.
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 (Recommandé)
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
Filtrage par IP
Nos services ne prennent pas officiellement en charge le filtrage par adresse IP lors de l’envoi des réponses, car l’adresse IP source peut être amenée à changer.
Cependant, si vous souhaitez malgré tout mettre en place un filtrage IP, vous pouvez vous baser sur le ou les adresses IP associées au domaine suivant :
A: senders.api.inovaclic.io
Remarque : L’utilisation de ce filtrage reste à votre propre discrétion, et nous ne garantissons pas sa fiabilité dans le temps.
Ajouter une en-tête personnalisée (optionnel)
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
Données forcées lors de l'extraction
Certaines liasses peuvent ne pas contenir de Siren, Date de clôture (ClosingDate) ou Durée d'exercices (DureeInMonths). (documentation)
Ces informations sont requises pour finaliser avec succès une extraction.
Afin de ne pas bloquer le processus d'extraction et si vous possédez ces informations il vous est possible de les transmettre lors de l'appel à l'extraction via les propriétés:
options.forcedDetails.siren
options.forcedDetails.sirenUsagePolicy ("UseIfNotFound | Replace")
options.forcedDetails.closingDate (format yyyy-MM-dd => 2018-12-31)
options.forcedDetails.dureeInMonths
Attention les données forcées sont prioritaires sur les données extraites par Inovaclic.
Résultats
Réponses sur les callbacks
Profiles de liasses acceptés
Automatisés
Cerfa Simplifiés - 2033
Cerfa Complets - 2050
Partiellement automatisés
Agris Simplifiés - 2139
Agris Complets - 2144
BNC - 2035
SCI Simplifiés - 2072-S
SCI Complets - 2072-C
Champs récupérés (exemple 2050)
Les champs récupérés dépendent de la configuration affectée à votre compte:
Simplifié
AA, AB, CX, AF, AH, AJ, AL, AN, AP, AR, AT, AV, AX, CS, CU, BB, BD, BF, BH, BJ, BL, BN, BP, BR, BT, BV, BX, BZ, CB, CD, CF, CH, CJ, CW, CM, CN, CO, AC, CQ, AG, AI, AK, AM, AO, AQ, AS, AU, AW, AY, CT, CV, BC, BE, BG, BI, BK, BM, BO, BQ, BS, BU, BW, BY, CA, CC, CE, CG, CI, CK, 1A, DA, DB, DC, DD, DE, DF, DG, DH, DI, DJ, DK, DL, DM, DN, DO, DP, DQ, DR, DS, DT, DU, DV, DW, DX, DY, DZ, EA, EB, EC, ED, EE, EH, EK, EI, FA, FD, FG, FJ, FB, FE, FH, FK, FC, FF, FI, FL, FM, FN, FO, FP, FQ, FR, FS, FT, FU, FV, FW, FX, FY, FZ, GA, GB, GC, GD, GE, GF, GG, GH, GI, GJ, GK, GL, GM, GN, GO, GP, GQ, GR, GS, GT, GU, GV, GW, HA, HB, HC, HD, HE, HF, HG, HH, HI, HJ, HK, HL, HM, HN, HP, HQ, KC, KF, LP, LS, 0J, LT, LV, NG, NJ, 0K, LT1, LV1, NG1, NJ1, 0K1, KB, KE, LO, LR, 0H, KA, KD, LN, LQ, 0G, LU, LW, NH, NK, 0L, CY, PE, QU, 0N, EL, PF, QV, 0P, EM, PG, QW, 0Q, EN, PH, QX, 0R, Z8, SR, Z9, SP, Z92, SP2, Z91, SP1, 3Z, 5Z, 6A, 6E, 02, 9U, 06, 6N, 6T, 6X, 7B, 7C, TS, TV, 6B, 6F, 03, 9V, 07, 6P, 6U, 6Y, TY, UB, TT, TW, 6C, 6G, 04, 9W, 08, 6R, 6V, 6Z, TZ, UC, TU, TX, 6D, 6H, 05, 9X, 09, 6S, 6W, 7A, UA, UD, UL, UP, UT, VA, UX, Z1, UY, UZ, VM, VB, VN, VP, VC, VR, VS, VT, 7Y, 7Z, VG, VH, 8A, 8B, 8C, 8D, 8E, VW, VX, VQ, 8J, VI, 8K, SZ, 8L, VY, VJ, VK, VZ, 7Y2, 7Z2, VG2, VH2, 8A2, 8B2, 8C2, 8D2, 8E2, VW2, VX2, VQ2, 8J2, VI2, 8K2, SZ2, 8L2, YQ, YR, YS, YT, XQ, YU, SS, YV, ST, ZJ, YY, YZ, ZE, YP
Etendue
AA, AB, CX, AF, AH, AJ, AL, AN, AP, AR, AT, AV, AX, CS, CU, BB, BD, BF, BH, BJ, BL, BN, BP, BR, BT, BV, BX, BZ, CB, CD, CF, CH, CJ, CW, CM, CN, CO, AC, CQ, AG, AI, AK, AM, AO, AQ, AS, AU, AW, AY, CT, CV, BC, BE, BG, BI, BK, BM, BO, BQ, BS, BU, BW, BY, CA, CC, CE, CG, CI, CK, 1A, DA, DB, DC, DD, DE, DF, DG, DH, DI, DJ, DK, DL, DM, DN, DO, DP, DQ, DR, DS, DT, DU, DV, DW, DX, DY, DZ, EA, EB, EC, ED, EE, 1B, 1C, 1D, 1E, EF, EG, EH, EJ, EI, FA, FD, FG, FJ, FB, FE, FH, FK, FC, FF, FI, FL, FM, FN, FO, FP, FQ, FR, FS, FT, FU, FV, FW, FX, FY, FZ, GA, GB, GC, GD, GE, GF, GG, GH, GI, GJ, GK, GL, GM, GN, GO, GP, GQ, GR, GS, GT, GU, GV, GW, HA, HB, HC, HD, HE, HF, HG, HH, HI, HJ, HK, HL, HM, HN, HO, HY, 1G, HP, HQ, 1H, 1J, 1K, HX, A1, A2, A3, A4, KC, 0J, LT, LV, LX, MA, MD, MG, MJ, MM, MP, MS, MV, MZ, ND, NG, NJ, 0K, LT1, 0K1, KB, 0H, KA, 0G, LU, 0L, 0N, 0P, EM, PG, QW, 0Q, 0R, Z9, SP, Z8, SR, Z91, SP1, Z92, SP2, 7B, 7C, TY, UB, UE, UG, UJ, 6C, 6G, 04, 9W, 08, 6R, 6V, 6Z, TZ, UC, UF, UH, UK, TC, TF, TI, TO, D6, IM, TR, TU, UA, UD, UL, UP, UT, VA, UX, UU, UY, UZ, VM, VB, VN, VP, VC, VR, VS, VT, VF, UM, UR, UV, VA2, UX2, UU2, UY2, UZ2, VM2, VB2, VN2, VP2, VC2, VR2, VS2, VU, UN, US, UW, VA3, UX3, UU3, UY3, UZ3, VM3, VB3, VN3, VP3, VC3, VR3, VS3, VV, 7Y, 7Z, VG, VH, 8A, 8B, 8C, 8D, 8E, VW, VX, VQ, 8J, VI, 8K, SZ, 8L, VY, VJ, VK, VZ, 7Y2, 7Z2, VG2, VH2, 8A2, 8B2, 8C2, 8D2, 8E2, VW2, VX2, VQ2, 8J2, VI2, 8K2, SZ2, 8L2, 7Y3, 7Z3, VG3, VH3, 8A3, 8B3, 8C3, 8D3, 8E3, VW3, VX3, VQ3, 8J3, VI3, 8K3, SZ3, 8L3, VZ3, 7Y4, 7Z4, VG4, VH4, 8A4, 8B4, 8C4, 8D4, 8E4, VW4, VX4, VQ4, 8J4, VI4, 8K4, SZ4, 8L4, VZ4, VL, WJ, YQ, YR, YS, YT, XQ, YU, SS, YV, ST, ZJ, YW, 9Z, YX, YY, YZ, 0B, 0S, ZE, YP
Complète
AA, AB, CX, AF, AH, AJ, AL, AN, AP, AR, AT, AV, AX, CS, CU, BB, BD, BF, BH, BJ, BL, BN, BP, BR, BT, BV, BX, BZ, CB, CD, CF, CH, CJ, CW, CM, CN, CO, AC, CQ, AG, AI, AK, AM, AO, AQ, AS, AU, AW, AY, CT, CV, BC, BE, BG, BI, BK, BM, BO, BQ, BS, BU, BW, BY, CA, CC, CE, CG, CI, CK, 1A, CP, CR, DA, DB, DC, DD, DE, DF, DG, DH, DI, DJ, DK, DL, DM, DN, DO, DP, DQ, DR, DS, DT, DU, DV, DW, DX, DY, DZ, EA, EB, EC, ED, EE, 1B, 1C, 1D, 1E, EF, EG, EH, EK, EI, B1, EJ, FA, FD, FG, FJ, FB, FE, FH, FK, FC, FF, FI, FL, FM, FN, FO, FP, FQ, FR, FS, FT, FU, FV, FW, FX, FY, FZ, GA, GB, GC, GD, GE, GF, GG, GH, GI, GJ, GK, GL, GM, GN, GO, GP, GQ, GR, GS, GT, GU, GV, GW, HA, HB, HC, HD, HE, HF, HG, HH, HI, HJ, HK, HL, HM, HN, HO, HY, 1G, HP, HQ, 1H, 1J, 1K, HX, RC, RD, A1, A2, A3, A4, A6, A9, KC, KF, KI, KL, KO, KR, KU, KX, LA, LD, LG, LJ, LM, LP, 8T, 8W, 1S, 1V, LS, 0J, LT, LV, LX, MA, MD, MG, MJ, MM, MP, MS, MV, MZ, ND, NG, 0U, 0X, 2B, 2E, NJ, 0K, LT1, LV1, LX1, MA1, MD1, MG1, MJ1, MM1, MP1, MS1, MV1, MY, NC, NG1, 0U1, 0X1, 2B1, 2E1, NJ1, 0K1, KB, KE, KH, KK, KN, KQ, KT, KW, KZ, LC, LF, LI, LL, LO, 8M, 8V, 1R, 1U, LR, 0H, KA, KD, KG, KJ, KM, KP, KS, KV, KY, LB, LE, LH, LK, LN, 8G, 8U, 1P, 1T, LQ, 0G, LU, LW, LY, MB, ME, MH, MK, MN, MQ, MT, MW, NA, NE, NH, 0V, 0Y, 2C, 2F, NK, 0L, 1W, 1X, NI, 2H, 0M, CY, PE, PI, PM, PR, PV, PZ, QD, QH, QL, QP, QU, 0N, EL, PF, PJ, PN, PS, PW, QA, QE, QI, QM, QR, QV, 0P, EM, PG, PK, PO, PT, PX, QB, QF, QJ, QN, QS, QW, 0Q, EN, PH, PL, PQ, PU, PY, QC, QG, QK, QO, QT, QX, 0R, Z9, SP, Z8, SR, Z92, 2SP, Z91, 1SP, 3T, 3U, 3V, 3X, D3, IJ, 3Y, 3Z, 4A, 4E, 4J, 4N, 4T, 4X, 5B, 5F, 5L, 5R, 5V, 5Z, 6A, 6E, 02, 9U, 06, 6N, 6T, 6X, 7B, 7C, TA, TD, TG, TM, D4, IK, TP, TS, 4B, 4F, 4K, 4P, 4U, 4Y, 5C, 5H, 5M, 5S, 5W, TV, 6B, 6F, 03, 9V, 07, 6P, 6U, 6Y, TY, UB, UE, UG, UJ, TB, TE, TH, TN, D5, IL, TQ, TT, 4C, 4G, 4L, 4R, 4V, 4Z, 5D, 5J, 5N, 5T, 5X, TW, 6C, 6G, 04, 9W, 08, 6R, 6V, 6Z, TZ, UC, UF, UH, UK, TC, TF, TI, TO, D6, IM, TR, TU, 4D, 4H, 4M, 4S, 4W, 5A, 5E, 5K, 5P, 5U, 5Y, TX, 6D, 6H, 05, 9X, 09, 6S, 6W, 7A, UA, UD, UL, UP, UT, VA, UX, UU, UY, UZ, VM, VB, VN, VP, VC, VR, VS, VT, VD, VE, VF, UM, UR, UV, VA2, UX2, UU2, UY2, UZ2, VM2, VB2, VN2, VP2, VC2, VR2, VS2, VU, UN, US, UW, VA3, UX3, UU3, UY3, UZ3, VM3, VB3, VN3, VP3, VC3, VR3, VS3, VV, 7Y, 7Z, VG, VH, 8A, 8B, 8C, 8D, 8E, VW, VX, VQ, 8J, VI, 8K, SZ, 8L, VY, VJ, VK, VZ, 7Y2, 7Z2, VG2, VH2, 8A2, 8B2, 8C2, 8D2, 8E2, VW2, VX2, VQ2, 8J2, VI2, 8K2, SZ2, 8L2, 7Y3, 7Z3, VG3, VH3, 8A3, 8B3, 8C3, 8D3, 8E3, VW3, VX3, VQ3, 8J3, VI3, 8K3, SZ3, 8L3, VZ3, 7Y4, 7Z4, VG4, VH4, 8A4, 8B4, 8C4, 8D4, 8E4, VW4, VX4, VQ4, 8J4, VI4, 8K4, SZ4, 8L4, VZ4, VL, UQ, WJ, YQ, YR, YS, YT, XQ, YU, SS, YV, ST, ZJ, YW, 9Z, YX, YY, YZ, 0B, 0S, ZK, 0C, 0D, 0E, 0F, ZB, ZD, ZE, ZF, ZG, ZH, YP, YF, YG, RL, OA, OK, OL, OT, OX, OH, OE, OF, OD, OI, XT, OM, ON, OQ, OR, OS, OZ, OW, OU, O9, OY, OJ, OG
Automatisation
Une mise à jour est réalisée par Inovatic Technologies pour augmenter le taux de reconnaissance du LabApi.
Il existe plusieurs aspects qui influent sur le taux de reconnaissance, notamment le format des PDF encodés sur certaines pages qui constitue la majeure partie des rejets des algorithmes de validation des résultats du LabApi.
(1) jour ouvré de 9h à 17h
(2) durée à titre indicatif dépendant du type/qualité de la liasse et de la charge Inovaclic. Les durées de traitement annoncés sont proportionnelles au nombre de liasses fourni dans la requête.