Aller au contenu

Informations techniques

Introduction

Bienvenue sur la documentation technique des APIs v1 Insight du Groupe Intescia.

Pour accéder directement à la documentation OpenAPI 3.0 via une interface interactive, consultez : Swagger UI

Compatibilité

La compatibilité ascendante de la version 1 des APIs est garantie durant tout son cycle de vie. Toutefois, il est possible que :

  • de nouvelles APIs soient ajoutées ;
  • de nouveaux champs soient intégrés aux modèles ;
  • les champs de type enum soient enrichis de nouvelles valeurs ;
  • les règles de rate limiting évoluent.

Ces modifications ne devraient pas impacter vos intégrations si vous les avez bien antiticipées.

Fin de vie

La fin de vie des APIs sera annoncée à l’avance via différents canaux de communication, mais aussi par la présence d’un header Sunset dans les réponses. Ce header indiquera la date de fin de disponibilité de l’API.

Il est fortement recommandé de vérifier la présence de ce header afin d’anticiper les changements.

Une nouvelle version des APIs sera proposée pour assurer la continuité de vos intégrations.

Lorsque l’API sera désactivée, les appels n’auront plus d’effet et un statut HTTP 410 Gone sera retourné.

Enregistrement de votre application

Pour accéder aux APIs Intescia, votre application doit être enregistrée dans Insight en tant que client OAuth (voir explications ci-dessous).

Pour cela, allez dans le menu "Mon organisation", dans l'onglet "Configuration". Cliquez ensuite sur le bouton "Accès API's".

Vous pouvez enregistrer vos clients oauth ici. Si la coche "Accès API" n'est pas active sur cet écran, contactez svp votre service client qui vous l'activera selon votre abonnement.

Vous pourrez ensuite cliquer sur le bouton "Créer un client OAuth" pour enregistrer votre première application.

Il vous sera demandé de donner un nom à votre application : ce nom est purement informatif et pour votre bénéfice, afin de pouvoir distinguer les différentes applications que vous enregistrez. Suite à la création de votre client oauth, vous obtiendrez un client_id et un client_secret. Sauvegardez bien ces informations, car le client_secret ne sera plus affiché par la suite.

Paramètres de l'application

Vous pourrez aussi saisir les paramètres suivants :

  • URI de redirection : il s'agit des urls qui sont acceptées pour la redirection après authentification. C'est une sécurité qui permet d'éviter à quelqu'un de malveillant de se faire passer pour votre application. Par défaut, lors de la création d'une application nous ajoutons les urls correspondant à la documentation, ce qui vous permettra d'utiliser la documentation facilement, mais vous êtes libre de supprimer cette url si vous n'en avez pas besoin.
  • Type d'autorisation : permet de choisir entre une application publique (site web, application mobile) ou privée (exécutée sur vos serveurs, ex : robot d’extraction). Le choix de ce paramètre détermine le flux d'authentification à utiliser (voir plus bas) :
  • PASSWORD : connexion par un robot, qui spécifiera client_id, client_secret, email et mot de passe utilisateur. Attention, ce mode n'est pas compatible avec les connexions SSO (Azure, Google, etc.)
  • AUTHORIZATION_CODE : connexion par un utilisateur, une fenêtre s'ouvre pour permettre à l'utiilisateur de se connecter. Ce mode est compatible avec les connexions SSO (Azure, Google, etc.). Il est le mode de connexion recommandé.
  • Durée de vie du jeton d'accès : détermine combien de temps le jeton obtenu après authentification est valide. Au-delà de cette durée, il faut obtenir un nouveau jeton. Par défaut nous proposons 7 jours, mais pour des applications publiques (site web, application mobile) il est recommandé de mettre une durée plus courte (quelques minutes).
  • Durée de vie du jeton d'actualisation : détermine combien de temps le jeton de rafraîchissement est valide. Ce jeton permet d'obtenir un nouveau jeton d'accès sans que l'utilisateur ait à se ré-authentifier. Il doit être un peu plus long que la durée de vie du jeton d'accès. Vous pouvez laisser cette zone vide pour utiliser les paramètres par défaut d'Insight.
  • Durée de vie maximale de la session client : détermine combien de temps la session de l'utilisateur est valide. Au-delà de cette durée, l'utilisateur devra se ré-authentifier. Vous pouvez laisser cette zone vide pour utiliser les paramètres par défaut d'Insight.

Explication des durées de vie par un exemple :

  • Durée de vie du jeton d'accès : 5 minutes
  • Durée de vie du jeton d'actualisation : 3 jours
  • Durée de vie maximale de la session client : 30 jours

Avec cet exemple :

  • toutes les 5 minutes l'application doit renouveller le jeton d'accès avec le jeton d'actualisation
  • le jeton d'actualisation est renouvellé en même temps que le jeton d'accès et est à nouveau disponible pour 3 jours
  • cela veut dire que si l'utilisateur coupe son ordinateur pendant la nuit, le lendemain il peut continuer à utiliser l'application sans se ré-authentifier car le jeton d'actualisation est encore valide.
  • par contre si l'utilisateur coupe son ordinateur pendant un week-end prolongé (plus de 3 jours), il devra se ré-authentifier car le jeton d'actualisation ne sera plus valide.
  • enfin, quelque soit la situation, au bout de 30 jours, on redemandera à l'utilisateur de se ré-authentifier.

Test des identifiants

Pour tester la connexion, rendez-vous sur l’API getCurrentUser de la documentation et cliquez sur le cadenas en haut à droite :

Login with OpenId

Applications publiques

Dans la fenêtre, sélectionnez « OpenID (OAuth2, authorization_code) », puis saisissez le client_id (laissez client_secret vide) :

enter infos

Cliquez sur « Authorize », saisissez vos identifiants sur le site d’authentification, puis revenez à la documentation. Si la connexion est réussie, le bouton « Authorize » devient « Logout ». Fermez la fenêtre et testez les APIs via « try it out ».

Applications privées

Dans la fenêtre, sélectionnez « OpenID (OAuth2, password) », puis renseignez votre email et mot de passe utilisateur, ainsi que le client_id et client_secret :

enter infos

Cliquez sur « Authorize ». Si la connexion est réussie, le bouton « Authorize » devient « Logout ». Fermez la fenêtre et testez les APIs via « try it out ».

Gestion des erreurs

bad user info

Le message « Invalid user credentials » indique une erreur dans les champs username ou password : utilisateur inexistant, inactif ou mot de passe incorrect.

bad client info

Le message « Invalid client or invalid client credentials » indique une erreur dans client_id et/ou client_secret : application non enregistrée ou client-secret incorrect.

Authentification

OpenID Connect

L’authentification des utilisateurs repose sur un fournisseur d’identité conforme à la norme OpenID Connect (successeur d’OAuth 2).

Des librairies compatibles existent pour chaque langage, notamment :

Informations à fournir à la librairie :

  • Adresse du serveur : https://sso.intescia.com/realms/intescia
  • Client id
  • URL de redirection (application publique)
  • Client secret (application privée)
  • Email utilisateur (application privée)
  • Mot de passe utilisateur (application privée)

Endpoints :

Flux d’authentification

Deux flux standards permettent d’obtenir un token d’accès aux APIs Intescia :

Flux « Authorization Code »

Ce flux, recommandé pour les applications publiques (site web, mobile), garantit la sécurité sans exposer de mot de passe. Il est compatible SSO (ex : connexion via Microsoft ou Google).

Voir la spécification OpenID Connect.

Flux « Password »

Ce flux, hérité d’OAuth2, n’est pas décrit dans la norme OpenID Connect et est amené à disparaître. Il n’est pas compatible SSO.

Son usage est déconseillé au profit du flux « Authorization Code ».

Format des tokens

Les tokens d’accès sont au format JWT, avec une durée de vie variable selon l’application.

Pour appeler les APIs, placez le token dans le header Authorization sous la forme "Bearer ".

En mode application publique, les tokens ont une durée de vie courte (quelques minutes) et sont associés à un refresh token permettant d’obtenir un nouveau token d’accès. Les librairies OpenID gèrent ce mécanisme automatiquement.

Documentation API

Documentation OpenAPI

La documentation est au format OpenAPI 3.0, consultable sur la page dédiée. Vous pouvez également télécharger la documentation au format JSON pour générer du code client.

Testez les APIs directement depuis la documentation via « try it out » après authentification.

Pagination

Certaines APIs renvoient de nombreux résultats, ce qui peut entraîner des réponses volumineuses. Pour éviter cela, les résultats sont généralement paginés.

Les paramètres de pagination sont:

  • page : numéro de la page (à partir de 0).
  • size : nombre de résultats par page (par défaut 10 ou 20, selon l’API).
  • sort : critère de tri (si pris en charge).

Exemple :

GET /recherche?page=2&size=10&sort=nom,desc

L'exemple ci-dessus demande la page 2 d'un ensemble de résultats avec une pagination de 10 et des résultats triés par "nom" décroissant. En se rappelant bien que la page 2 est en réalité la 3ème page (les numéros de pages commençant à zéro), on obtiendra donc les résultats 20 à 29.

Statuts HTTP

Les statuts HTTP retournés sont standards. Récapitulatif :

  • 200 OK : succès.
  • 404 Not Found : ressource inexistante.
  • 401 Unauthorized : token d’accès invalide ou absent.
  • 403 Forbidden : accès non autorisé ou API inexistante.
  • 405 Method Not Allowed : mauvaise méthode HTTP utilisée.
  • 402 Payment Required : accès refusé faute de crédits.
  • 429 Too Many Requests : dépassement du rate limiting.

Rate limiting

Les APIs sont protégées par un système de rate limiting basé sur l’algorithme Token Bucket :

  • Sac de 10 jetons.
  • Chaque appel consomme un jeton.
  • Si le sac est vide, l’appel est rejeté.
  • 10 jetons sont ajoutés chaque seconde.
  • Capacité maximale : 20 jetons.

En pratique, cela permet 10 appels par seconde, avec un pic possible à 20 appels sur une seconde, suivi d’un retour à un rythme plus lent.

Exemple

Supposons que vous vouliez consommer les apis Intescia depuis le site make.com. Vous pourriez créer le client ainsi :

  • Nom : Make.com
  • URI de redirection: https://www.integromat.com/oauth/cb/oauth2

Ensuite dans make, créez une nouvelle connexion oauth2 avec les paramètres suivants :