API pour la Lecture Automatique de Bilans

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

  • ExtractLive : 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*)

    • 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

  • ExtractBatch : extraction des données sur un grand volume de fichier

    • Priorité : priorité moyenne de traitement automatique/manuel (< 48h les jours ouvrés*)

    • Limite : 1 appel toutes les 10 secondes

    • Charge : 100 fichiers par requête

    • Format : chaque liasse est à fournir à l'api en base64 dans le propriété data

  • ExtractLiveAutoOnly : extraction des données en temps réel sur un fichier [obsolète]

    • Priorité : priorité maximum de traitement automatique

    • Limite : 1 appel toutes les 5 secondes

    • Facturé uniquement si l'extraction automatique est réussie

  • GetProcessStatus : obtenir l'avancement du traitement des documents envoyés par ExtractLive ou ExtractLiveAutoOnly

    • 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" : 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" : la liasse 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 de la liasse

        • "Finished" : la liasse est extraite avec succès

    • Cette méthode n'est pas disponible pour ExtractBatch

  • GetProcessData : obtenir le résultat de l'extraction des données par par ExtractLive ou ExtractLiveAutoOnly

    • Limite : 1 appel toutes les 5 secondes

    • Cette méthode n'est pas disponible pour ExtractBatch

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

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 effectués par ExtractLive et ExtractLiveAutoOnly. La réponse fournie par cette méthode contient l'ensemble des avancements de traitement pour chacune des liasses ainsi que les liens vous permettant de recueillir les résultats liasse par liasse (GetLiasseData) ou au total (GetProcessData).

Picture

A noter: seules les url possédant un domaine sont autorisées dans les callbacks. Aussi durant la phase de développement il est possible pour des raisons de facilité d'utiliser des solutions tunnels pour transmettre les informations sur un serveur local avec des solutions telles que ngrok, frp, localtunel... ou aussi intercepter les réponses via des intercepteurs de réponse en ligne comme pipedream ou webhook.site (attention à bien vérifier la confidentialité de ces solutions).

Il est fortement recommandé dans le cadre d'un production de privilégier un système de traitement via Webhook plutôt que par polling.
En effet le système par polling pose de nombreux problèmes de limites d'usage et n'est pas adapté à un véritable usage de production.

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 (optionnel)

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.

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

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

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:

  • forcedDetails.siren

  • forcedDetails.closingDate (format yyyy-MM-dd => 2018-12-31)

  • forcedDetails.dureeInMonths

Attention les données forcées sont prioritaires sur les données extraites par Inovaclic.

Cas de tests

Pour requête automatique

* Les cellules extraites comportent un marqueur
* Les cellules extraites portent le même label indiqué sur le bilan, sauf si le LabApi utilise un autre label, dans quel cas ce dernier est écrit dans la cellule.

La réponse est reçue directement sur callbackCompleted

Pour requête avec traitement manuel

Une réponse est reçue sur callbackManual : liste de liasses traitées manuellement.

La réponse est reçue sur callbackCompleted : liste de toutes les liasses envoyées initialement.

Pour requête avec erreur

La réponse est reçue directement sur callbackCompleted : liste de toutes liasses, dont celles en statut erreur

Résultats

Réponses

Exemple CallbackCompleted Télécharger

Exemple CallbackManual Télécharger

Profiles de liasses acceptés

Automatisés

Non Automatisés

  • Agris Simplifiés - 2139 Cellules extraites bientot disponibles.

  • Agris Complets - 2144 Cellules extraites bientot disponibles.

  • BNC - 2035 Cellules extraites bientot disponibles.

  • SCI Simplifiés - 2072-S Cellules extraites bientot disponibles.

  • SCI Complets - 2072-C Cellules extraites bientot disponibles.

Performances

1 seconde par page

Il faut compter au maximum 1 seconde par page du bilan sur lesquelles sont extraites les cellules. 

Exemple : 10 secondes pour 2050, 5 secondes pour 2033.

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.