Pré-remplir automatiquement les informations d'une entreprise à partir de son numéro de SIRET ? Connaître le statut boursier d'un étudiant qui demande une réduction de transport ? C'est possible grâce aux API référencées dans le catalogue de Simplifions.data. Néanmoins, entre le moment où vous prenez connaissance de l'existence d'une API et le moment où elle est utilisée en production dans votre service, plusieurs étapes se succèdent.
Ce guide s'adresse aux acteurs publics souhaitant intégrer des API et donne une vision détaillée des étapes et prérequis nécessaires à l'intégration de toute API conçue pour simplifier des démarches via la récupération des données de l'usager — principe du « Dites-le-nous une fois ».
💡 Les informations de cet article s'appliquent si vous intégrez vous-même une API. Si vous passez par un éditeur de logiciel métier, la charge est bien plus légère : il s'agit d'identifier vos cas d'usages, les données utiles et de prendre connaissance des logiciels éditeurs les ayant intégrées.
Lire plus • Comprendre ce qu'est une API sans vocabulaire technique.
Qu'est-ce qu'une API ?Les prérequis avant de démarrer
Voici quatre familles de prérequis que vous pouvez vérifier bien avant d'intégrer une API pour gagner du temps :
1. Un prérequis de conception : penser au parcours de vos usagers
Vérifier que l'API délivre les données dont vous avez besoin
Avant de demander l'accès à une API ou de vous y raccorder, prenez le temps de consulter la documentation technique de l'API (souvent un swagger ou une spécification OpenAPI) pour vérifier que les données renvoyées correspondent réellement à votre besoin. Trois points de vigilance reviennent régulièrement :
- La granularité de la réponse. Certaines API renvoient un simple statut ou une réponse par oui ou par non - par exemple, « est demandeur d'emploi : oui/non » -, tandis que d'autres renvoient un objet complet avec de nombreuses données associées - état civil, coordonnées, dates d'inscription... -. Dans le cas d'une API délivrant des données protégées, une API plus riche que nécessaire vous imposera de gérer, sécuriser et minimiser des données dont vous n'avez pas l'usage — au moment de votre demande d'habilitation, il vous sera demandé de veiller au respect du principe de minimisation des données.
- Le périmètre couvert. Une API peut comporter des exceptions géographiques, temporelles ou statutaires : par exemple, certains territoires ou situations particulières peuvent être exclus du périmètre. Vérifiez que votre public cible est bien couvert et anticipez des parcours alternatifs pour les usagers qui ne le sont pas.
- La fraîcheur des données. Selon l'API, la donnée peut être mise à jour en temps réel, quotidiennement, ou selon une fréquence propre au fournisseur. Assurez-vous que la fréquence de mise à jour est compatible avec votre cas d'usage.
Identifier comment récupérer les informations de l'usager qui permettront d'appeler l'API
Pour appeler une API, il faut lui fournir un ou plusieurs paramètres d'appel qui permettent d'identifier l'entité dont on souhaite récupérer/pré-remplir les données. Selon l'API, ces paramètres peuvent être un numéro de SIRET/SIREN pour une association ou une entreprise, un numéro fiscal ou les données d'état civil pour un particulier.
Avant d'intégrer une API, il faut donc décider à quel endroit et comment vous allez pouvoir obtenir ce paramètre auprès de l'usager ou de l'agent. C'est un choix de conception produit à part entière qui est déterminant pour la qualité de l'expérience usager.
Maquetter ou prototyper avant de développer
Il n'est pas nécessaire d'attendre l'accès aux API pour valider vos parcours. Au contraire, les anticiper en lisant les spécifications des API vous permettra de vous assurer que l'API correspond à votre besoin. Certaines API délivrant de la donnée protégée mettent à disposition des environnements de tests qui permettent même de concevoir tout votre produit avec de la donnée fictive en attendant d'obtenir l'accès.
Lire plus • Découvrez comment utiliser les API au sein du parcours usager, selon que la donnée est publique ou protégée :
Anticiper le parcours usager avant d'intégrer vos API2. Un prérequis juridique si l'API distribue des données protégées
Cadre légal
L'accès aux API permettant la mise en œuvre du « Dites-le-nous une fois » et distribuant des données protégées requiert une habilitation.
Chaque demande d'accès doit être justifiée par un cadre juridique précis : texte de loi ou règlementaire spécifiant que votre administration est habilitée à demander ces informations pour traiter une démarche usager. Pour les collectivités, une délibération décrivant précisément les données nécessaires, par exemple le barème tarifaire lié au quotient familial pour une tarification de cantine, est souvent requise.
Simplifions.data vous aide dans l'identification de ce cadre juridique :
Contacts
Une demande d'habilitation mobilise généralement plusieurs contacts au sein de votre administrtation (qui peuvent parfois être la même personne) :
| Rôle | Responsabilité |
|---|---|
| Contact technique | Responsable de l'intégration technique et de la maintenance de l'API dans votre système d'information. C'est lui qui pourra récupérer les « clés d'accès techniques », en aura la gestion et devra s'assurer de leur validité. Il devra également s'informer des opérations de maintenance et des incidents. Certains services l'abonneront par défaut à ces informations. |
|
Contact métier
— contact moins fréquemment demandé |
Point de contact pour les questions fonctionnelles/métier sur le service. Lorsqu'il est demandé, c'est lui qui est informé des nouvelles API et des incidents majeurs. Distinct du contact technique, il est orienté usage plutôt qu'intégration. |
| Délégué à la protection des données | S'assure que l'organisation protège correctement les données personnelles conformément à la réglementation. Cette personne doit pouvoir exercer en toute indépendance en étant à l'abri des conflits d'intérêt, elle ne peut donc pas être ni le contact technique, ni le contact métier. C'est le point de contact de la CNIL en cas de problème. Dans les collectivités, le DPD est souvent mutualisé avec d'autres collectivités. |
| Responsable de traitement | Détermine seul ou conjointement les finalités et moyens du traitement des données personnelles. Dans les communes, le responsable de traitement est le ou la maire. |
3. Un prérequis technique minimal
Le niveau d'exigence technique dépend de l'ouverture de l'API utilisée.
Pour les API en accès libre, les prérequis sont légers :
- gérer des appels HTTPS simples, sans authentification particulière ;
- pouvoir traiter du JSON et l'intégrer dans votre système d'information ou votre site.
Pour les API à accès restreint, les exigences sont plus poussées. Votre équipe technique doit être en mesure de :
- gérer des appels HTTPS sortants depuis un serveur back-end (jamais depuis un site en front-end : le jeton d'accès serait exposé) ;
- autoriser, le cas échéant, l'adresse IP du service dans votre pare-feu ;
- selon le fournisseur, justifier d'un niveau de sécurité suffisant de votre système d'information (questionnaire ou homologation de sécurité) ;
- gérer le renouvellement des jetons d'accès à l'API.
Que ce soit pour les API en accès libre ou restreint , il est indispensable de prévoir de la maintenance dans la durée pour gérer les montées de version des API, suivre les accidents, etc...
4. Un prérequis budgétaire
L'utilisation des API référencées sur Simplifions.data et utiles pour le « Dites-le-nous une fois » est gratuite. Mais le raccordement (développement, tests, maintenance, montée de version de l'API) reste à votre charge, il est donc nécessaire de prévoir ces coûts de développement initial et de maintien en conditions opérationnelles.
Les étapes d'intégration d'une API
Les étapes d'intégration d'une API dépendent de l'ouverture de l'API : une API en accès libre est appelable sans habilitation ni clé d'accès, tandis qu'une API en accès restreint (délivrant des données protégées) requiert plus d'étapes pour être utilisable dans vos systèmes d'information.
Étape 1 — Explorer la documentation et tester l'API
Après avoir réfléchi aux parcours de vos usagers, il est utile de vérifier que l'API correspond bien à votre besoin en consultant ses spécifications via sa documentation et son swagger ou fichier OpenAPI.
Cette étape est commune à toutes les API :
- Pour une API en accès libre, vous pouvez tester directement l'API en conditions réelles, sans attendre de validation préalable.
- Pour une API à accès restreint, la plupart proposent un environnement de test (bac à sable) avec des données fictives, ce qui permet à votre équipe technique de se familiariser avec les types de données renvoyés et les différentes situations d'usage possibles. Si les exemples proposés ne répondent pas à tous les cas de figure possibles de votre cas d'usage, certains opérateurs proposent une option permettant de contribuer à l'environnement de bac à sable afin de l'enrichir.
Toutes les API référencées sur Simplifions.data sont aussi
cataloguées dans Data.gouv.fr où elles ont leur propre page
d'information. Cette page recense les éléments essentiels pour vous
permettre d'intégrer l'API.
Cette page data.gouv.fr est toujours mise en lien sur simplifions.data
lorsqu'une API ou un jeu de donnée est référencé.
Étape 2 — Récupérer et, le cas échéant, sécuriser vos accès
Pour une API en libre accès, cette étape est généralement superflue : aucune clé n'est nécessaire, l'API est appelable directement depuis une page web, sans avoir à sécuriser l'appel.
Pour une API à accès restreint, une fois la demande d'habilitation validée, une clé d'accès technique — un jeton, aussi appelé token, généralement au format JWT — est délivrée à votre organisation. Selon l'API concernée, la récupération de ce jeton se fait dans un espace dédié du site de l'API, ou par échange sur une messagerie sécurisée. Ce jeton ne doit jamais être partagé à un tiers non autorisé, ni transiter par e-mail, ni être saisi dans un moteur de recherche. Il est propre à votre organisation et ne doit être donné qu'à des tiers habilités à le manipuler, c'est-à-dire votre direction des systèmes d'information ou votre éditeur si vous lui avez délégué la gestion technique. En cas de doute sur une fuite du jeton, même accidentelle, contactez immédiatement l'opérateur de l'API pour le faire révoquer.
Étape 3 — Intégrer techniquement l'API dans le parcours usager
L'équipe technique développe l'appel à l'API dans votre service, en implémentant le parcours décidé en amont : développement du formulaire ou du service et interconnexion des champs de saisie (pour les paramètres d'appel) et des champs de saisie pré-remplis (pour les réponses de l'API) ; distinction entre données publiques (affichables sans authentification) et données protégées (réservées aux usagers authentifiés ou agents habilités).
Pour une API en accès libre, l'intégration reste simple : il suffit de gérer les appels HTTPS, le traitement du JSON reçu, et les codes d'erreur HTTP standards — notamment le 429 (limite de débit dépassée) ou un timeout en cas de lenteur du service. Pas de logique de jeton ni de traçabilité particulière à mettre en œuvre.
Pour une API à accès restreint, aux erreurs HTTP standards s'ajoutent des codes propres à l'authentification (401 en cas de jeton invalide ou expiré, 403 en cas d'accès à une donnée hors du périmètre habilité) et le respect des limites de volumétrie propres à votre habilitation — au-delà, un bannissement temporaire peut intervenir. Il est également souvent requis de renseigner, dans chaque appel, des paramètres de traçabilité permettant d'identifier l'origine de la requête.
Aucune API n'est fiable à 100 %. Or votre service doit continuer à fonctionner en cas de panne :
- si l'API sert à pré-remplir un formulaire, prévoyez une saisie manuelle de secours ;
- si l'API sert à récupérer un justificatif, prévoyez que l'usager puisse encore le déposer lui-même.
⚠️ Le « Dites-le-nous une fois » ne doit jamais devenir un obstacle. Un usager préférera souvent ressaisir une information plutôt que de ne pas pouvoir finaliser sa démarche.
Lire plus • Découvrez comment utiliser les API au sein du parcours usager, selon que la donnée est publique ou protégée :
Anticiper le parcours usager avant d'intégrer vos APIÉtape 4 — Mettre en production, surveiller, faire évoluer
Après des tests concluants, l'accès en production peut démarrer. Quelques bonnes pratiques à mettre en place dès le lancement lorqu'elles sont rendues possibles par l'opérateur de l'API :
- utiliser les kits de développement (SDK) officiels ;
- s'abonner aux pages de statut / notifications d'incidents ;
- s'abonner aux actualités de l'API indiquant les nouveautés, les montées en version et le changelog ;
- utiliser les routes de monitoring dédiées ("ping"), plutôt que d'appeler les vraies routes de données, pour surveiller la disponibilité.
Lire plus • Durant l'intégration et l'usage d'une API, identifiez les acteurs pour savoir qui sont vos interlocuteurs :
Vos interlocuteurs selon le type d'APILes limites des API
Comprendre les limites des API vous permet d'anticiper les solutions à mettre en œuvre pour contrebalancer leurs manques.
| Limite d'une API | Explication | Exemple concret |
|---|---|---|
| Couverture partielle des structures et du périmètre visés | La plupart des API ne couvrent pas la totalité des personnes ou des organisations cibles. En raison d'une absence de collecte de la donnée, certaines zones géographiques peuvent ne pas être couvertes, certaines entités non plus. Ce périmètre est aussi souvent lié au périmètre de l'administration fournisseur de la donnée elle-même. | Le statut boursier n'est pas encore disponible pour tous les types d'études ou tous les régimes de bourse — un usager réellement boursier peut donc, dans certains cas, ne pas être détecté comme tel par l'API. |
| Qualité de la donnée | La donnée renvoyée par l'API peut elle-même être erronée ou incomplète. L'API ne fait que refléter la qualité de la donnée détenue par l'administration qui la fournit. | Cas d'une donnée déclarative : Une adresse postale contient une erreur car cette donnée a été saisie par l'usager qui a fait une faute de frappe. |
| Fraîcheur de la donnée | Une modification très récente d'information concernant l'entité effectuant la démarche peut ne pas être immédiatement répercutée sur l'API (ex. changement de statut). | Un usager vient d'obtenir son statut de demandeur d'emploi ce matin, mais l'API renvoie encore « false » quelques heures plus tard, le temps que la mise à jour se propage depuis le système source. |
| Indisponibilité ponctuelle de l'API | Aucune API ne garantit une disponibilité à 100 % : elle peut être en panne ou en maintenance, indépendamment de tout ce que vous avez bien anticipé côté conception ou technique. L'appel peut alors échouer totalement (timeout, erreur), sans lien avec le contenu de la demande. | Une entreprise a besoin de transmettre son attestation fiscale mais le service de la DGFiP connaît un incident technique ce jour-là : l'appel renvoie une erreur, sans aucune donnée. L'entreprise doit pouvoir téléverser son propre document pour poursuivre sa démarche. |
| Volumétrie plafonnée | Les traitements de masse (ex. relance annuelle de milliers de dossiers) doivent être planifiés en heures creuses pour ne pas saturer les quotas partagés par habilitation. | Un CCAS lance en pleine journée une vérification automatique de 5 000 dossiers d'un coup : le quota de 1000 requêtes/minute est dépassé, l'habilitation se retrouve bannie pendant 12h en plein traitement, bloquant aussi les autres agents qui utilisent la même habilitation. |
| Paramètres d'appel incorrects | Toutes les API, sauf les API FranceConnectées, supposent que l'usager saisisse correctement ses informations ; en cas d'erreur de saisie, aucune donnée n'est retournée. Cette difficulté est parfois plus complexe qu'une simple erreur de saisie. Parfois les éléments identifiants à donner pour permettre l'appel ne sont pas forcément évidents pour l'usager lui-même. L'interface utilisateur et l'explication des éléments à fournir est alors cruciale pour limiter les erreurs. De même, la gestion des messages d'erreur donnée à l'usager est également très importante pour lui permettre d'apporter des corrections. | Un étudiant se trompe d'un chiffre dans son numéro INE : l'API Statut étudiant ne renvoie aucun résultat, alors qu'il est réellement inscrit. Un parent doit saisir le code COG de sa commune de naissance en plus d'autres informations pour récupérer son quotient familial. Il se trompe et renseigne le code postal de sa commune de naissance. |
Dans tous les cas, gardez toujours un chemin de secours pour l'usager (ressaisie, dépôt manuel du justificatif).
Lire plus • En savoir plus sur les parcours alternatifs à proposer :
Anticiper le parcours usager avant d'intégrer vos API — Parcours alternatifsPour résumer
- Quatre prérequis avant de lancer un chantier d'intégration d'API : conception, technique, budget — et juridique si l'API délivre des données protégées.
- Quatre étapes pour intégrer les API. Explorer et tester l'API, sécuriser vos accès si l'API est en accès restreint, intégrer les données dans le parcours de l'usager, puis surveiller en production.
- Anticipez les limites des API. Couverture partielle, erreurs de saisie, données pas toujours à jour, quotas limités, pannes ponctuelles — un usager doit toujours pouvoir ressaisir une information ou déposer un document lui-même, sans que sa démarche soit bloquée.