arrow bold forward circle chevron up rotate cw rotate ccw refresh cw refresh cw alert refresh ccw refresh ccw alert circle chevrons up circle chevrons right circle chevrons left circle chevrons down circle arrow up circle arrow down circle chevron right circle chevron left circle chevron down circle arrow down left circle arrow up right circle arrow up left circle arrow right circle arrow right curved circle arrow left circle arrow left curved arrow bold reply circle arrow down right arrow bold right chevrons up chevrons right chevrons left chevrons down chevron up chevron right chevron left chevron down arrows hv arrows diagonals arrows diagonals tlbr arrows diagonals bltr arrow undo arrow up arrow up right arrow up left arrow right arrow right curved arrow reply arrow reply all arrow redo arrow left arrow left curved arrow forward arrow forward all arrow down arrow down right arrow down left arrow bold undo arrow bold up arrow bold redo arrow bold left arrow bold reply all arrow bold forward all arrow bold down toggle right toggle left zoom out trash empty video user text italic zoom in text underline video no trash share arrow text align center thumbs up thumbs down newspaper text bgcolor text color text bold star no text align right text align left text align justify table sticker star send share link no settings lightning no search screenshot scan pulse printer presentation plus pencil edit pencil create paperclip paperclip no options inbox more vertical more horizontal minus minimize mic mic no menu menu dots maximize mail list link flame lightning circle x layers external link image home heart heart no globe 2 globe no glasses bookmark no flag eye eye no book drop download download bold delete dashboard cut copy clear style circle circle block circle star circle plus circle checked circle more vertical bookmark add bookmark circle more horizontal circle minus circle menu camera no bookmarks check marks check mark case camera brush camera create calculator browser browser no box bar chart call incoming call voicemail call missed call received call phone call hold call outcoming call numbers call no call muted call number call forwarded call end call decline call calling call add question comment minus comment text comment plus comment comment delete comment checked bluetooth no bluetooth broadcast wi fi wi fi no cast broadcasting airplay note folder opened note text folder folder zip folder photo folder plus folder minus folder delete file upload folder music folder create folder checked clipboard text folder cloud folder arrow file clipboard plus file text clipboard minus file shredder file scan file plus file minus file draft file download file delete file create file code file checked clipboard clipboard delete clipboard checked creditcard income creditcard face creditcard add strongbox ethereum wallet creditcard scan paypass creditcard creditcard outcome creditcard no bitcoin coffee egg icecream chicken bread avocado ipad laptop iphone server monitor mobile memory card floppy flash card devices battery battery no battery 40 battery 80 battery 60 battery charging battery 20 battery 100 select area segment stack 1 text stack rotate right sidebar left sidebar right select ruler rotate left grid row 3 block align bottom block align left padding layout kanban iframe grid grid small grid slides grid row 2 block align horizontally grid row 2 copy grid frame grid dynamic grid col 3 grid col 2 grid 6 frame elements edit shape break page block distribute vertically block distribute horizontally block align vertically block align top block align right apps compass direction 45 direction route radar pin pin start pin round pin question pin no pin add panorama map map pin location location location no globe 360 player fast forward volume volume off volume no shuffle volume low volume high repeat tuner sound wave player list player fast back record radio queue player stop player stop circle player skip forward player skip back player play player play pause player play circle player pause player pause circle player list play player list add music note eject artist equalizer music library listen later add to library cd alert triangle bell add app notification x octagon question circle minus octagon info bell bell no bell minus bell checked bell alert alert octagon alert circle shocked sad neutral smile laughing verified verified copy unlock shield shield ok lock no lock circle key shield no shield lock lock key no tote filter pos gift tag coupon cart cut coupon discount delivery basket bag cloud no cloud checked cloud download terminal database code cloud cloud upload cloud connect сс0 dribbble behance сс youtube twitter peace linkedin command instagram hash google gitlab github facebook at sign alarm plus calendar delete alarm no watch timer time time history stopwatch calendar calendar plus calendar minus alarm minus calendar dates calendar create calendar checked alarm alarm snooze alarm checked brightness high sun toy horse pocket atom rocket bone planet nut moon lightbulb items infinity form cup crosshair cross contrast brightness low cc cc0

Documentation générale

Étape 1 : L’API Entreprise correspond-elle à mon besoin ?


API Entreprise répond à deux grands types d’usages :

Le pré-remplissage d’un formulaire à destination du public

Vous pouvez mettre en place une aide à la saisie pour vos usagers, avec les endpoints entreprises, etablissements et associations. L’usager renseigne son numéro de SIRET, ou toute autre valeur discriminante ; le formulaire est alors pré-rempli des champs disponibles par votre API.

L’exemple du formulaire DUME
L’AIFE a mis en place une démarche dématérialisée pour permettre aux entreprises d’obtenir leur document Unique de Marché Européen. Elle utilise l’API Entreprise pour pré-remplir les formulaires de ses utilisateurs.

Quel avantage à passer par API Entreprise si les données sont libres ? API Entreprise vous simplifie l’implémentation de cette aide à la saisie, en vous donnant accès à une information structurée, facilement intégrable dans votre produit.

Le pré-remplissage est possible uniquement pour des APIs distribuant des informations publiques. Par exemple, l’endpoint entreprise qui regroupe des données ouvertes et fermées, ne peut être utilisé pour le pré-remplissage, que si et seulement si les entreprises non-diffusibles (dont les données sont confidentielles) ne sont pas appelées.

La création d’un formulaire pré-rempli est faite pour assister l’usager, celui-ci doit toujours pouvoir amender, rectifier ces mêmes informations sans difficultés.

L’obtention d’une donnée en back office par un agent habilité

L’API entreprise sert aux agents habilités à récupérer automatiquement des informations, elle donne accès :

  • soit à des justificatifs, certificats, bilans, … papiers numérisés ou document PDF ;
  • soit à la donnée brute, décrite par un champ JSON, qui permet une automatisation plus performante encore ;
  • soit les deux.
Découvrir tous les cas d'usage

Les qualités du service

API Entreprise démarche les administrations et fait les différentes demandes d’accès auprès des multiples fournisseurs. Si votre demande d’habilitation est validée, vous avez une seule clé d’accès sécurisée. De plus, API Entreprise agrège et vous restitue les connaissances techniques et métiers de chaque API.

Sans API Entreprise, vous êtes obligé de demander toutes les APIs nécessaires à votre service, auprès des différentes administrations. Cette recherche n’est pas toujours fructueuse car les organisations n’ont pas toutes un site ou un contact public pour leurs APIs. Par ailleurs, vous devez ensuite comprendre plusieurs systèmes techniques, générer plusieurs mots de passe, collaborer avec plusieurs contacts techniques et métiers.

La liste exhaustive des données

Informations générales
Données Producteur Endpoint Type Ouverture
Données de référence d’une entreprise INSEE & Infogreffe entreprises données JSON publiques et confidentielles
Données de référence d’un établissement INSEE etablissements données JSON publiques et confidentielles
Extrait RCS Infogreffe extraits_rcs_infogreffe données JSON confidentielles
Informations déclaratives d’une association Ministère de l’Intérieur associations données JSON publiques
Divers documents d’une association Ministère de l’Intérieur documents_associations PDF (image) publiques
Actes INPI actes_inpi Archive ZIP (PDF et XML) publiques
Conventions collectives Fabrique numérique des Ministères Sociaux conventions_collectives données JSON publiques
Informations financières
Données Producteur Endpoint Type Ouverture
Chiffre d’affaires DGFIP exercices données JSON confidentielles
Bilans annuels INPI bilans_inpi données JSON publiques et confidentielles
3 derniers bilans annuels Banque de France bilans_entreprises_bdf données JSON confidentielles
Déclarations de résultats DGFIP liasses_fiscales_dgfip données JSON confidentielles
Attestations sociales et fiscales
Données Producteur Endpoint Type Ouverture
Attestation fiscale DGFIP attestations_fiscales_dgfip PDF (texte) confidentielles
Attestation de vigilance ACOSS attestations_sociales_acoss PDF (texte) confidentielles
Conformité emploi des travailleurs handicapés AGEFIPH attestations_agefiph données JSON confidentielles
Cotisation de sécurité sociale agricole MSA cotisations_msa données JSON confidentielles
Cotisations retraite bâtiment PROBTP attestations_cotisation_retraite_probtp données JSON confidentielles
Carte professionnelle travaux publics FNTP cartes_professionnelles_ftp PDF publiques
Cotisations congés payés & chômage intempéries CNETP certificats_cnetp PDF confidentielles
Certifications professionnelles
Données Producteur Endpoint Type Ouverture
Certification RGE ADEME certificats_rge_ademe données JSON et PDF publiques
Certification de qualification bâtiment OPQIBI certificats_qualibat données JSON publiques
Certification de qualification d’ingénierie OPQIBI certificats_opqibi données JSON publiques
Propriété intellectuelle
Données Producteur Endpoint Type Ouverture
Brevets, modèles et marques déposés INPI extraits_courts_inpi données JSON publiques


Une documentation technique et métier par endpoint

Toutes les données de la liste précédente sont détaillées dans le catalogue de données.

Dans ce catalogue, une barre de recherche est à votre disposition pour filtrer les données :
   
Chaque endpoint est présenté de façon synthétique :
   
Des informations complémentaires, dont le détail précis des champs délivrés par l’API sont disponibles en cliquant sur le bouton “documentation” :
Parcourir le catalogue des données

Nos engagements

Utiliser le service API Entreprise, c’est aussi bénéficier des engagements de la Direction du Numérique :

  • L’engagement de disponibilité est de 99,5 %. La disponibilité des données est consultable en temps réel pour chaque endpoint dans le catalogue des donnée. Une historisation est aussi publiée, ainsi que les rapports d’incidents et les perspectives de résolution. Par ailleurs, les informations sur votre consommation sont disponibles dans votre tableau de bord.

    Toutefois, ce service agrégeant de nombreux fournisseurs de données et étant donc dépendant de leurs disponibilités, API Entreprise ne porte donc aucune responsabilité s’agissant de la qualité ou du contenu intrinsèque des données. Par ailleurs, le service ne modifie pas les données à l’exception d’une standardisation contextuelle limitée (minuscule vers majuscule, format de date, nombre d’espaces).

  • L’utilisation d’API Entreprise est gratuite. Les coûts d’investissements et de fonctionnement sont pris en charge par la DINUM. En revanche, les coûts de raccordement à API Entreprise vous incombent.
  • API Entreprise propose une assistance technique et fonctionnelle permettant aux utilisateurs de définir et de mettre en œuvre au mieux leur projet.
  • API Entreprise respecte le cadre légal. Le service s’engage à respecter en totalité les conditions de protection des données et les règles de confidentialité.

Une habilitation instruite par la DINUM

Tout accès à l’API Entreprise se fait sous réserve d’en avoir obtenu l’habilitation.

L’API entreprise est réservée aux acteurs publics investis d’une mission de service public : les administrations, leurs opérateurs et les collectivités, les acteurs de santé, etc. Leurs prestataires privés peuvent être destinataires des informations techniques permettant l’usage de l’API mais en aucun cas des données elles-même.

S’engager à ne pas diffuser les données reçues

Premièrement, avant toute transmission de données, l’usager doit être informé, et en cas d’exposition des données, son consentement doit être explicite.

Dans le cas d’un pré-remplissage à destination du public

Une partie des données des endpoints entreprise, etablissement et associations, les données publiques, peuvent servir au pré-remplissage de formulaires publics. Même si ces données ne sont pas confidentielles, le fournisseur de service s’engage à ne pas commercialiser les données reçues au travers d’API Entreprise et à ne pas les communiquer à des tiers en dehors des cas prévus par la loi.

Dans le cas d’une utilisation par un agent habilité en back office

La plupart des données disponibles sur API Entreprise sont protégées par des secrets. Vous assurez donc la protection de ces données et le respect des règles de confidentialité.

Entre autres, le service ne doit pas permettre à quiconque n’ayant pas un niveau d’authentification suffisant, d’accéder à des données. Leur accès est restreint aux seuls agents dûment habilités, dont les requêtes sont tracées pour une durée de 36 mois.

Avoir un équipement technique minimal

Vous êtes techniquement en mesure de pouvoir démarrer avec API Entreprise si :

  • vous travaillez ou vous vous apprêtez à travailler avec un éditeur de logiciel. Celui-ci doit être en mesure d’intégrer API Entreprise.
  • ou bien vous avez une direction des systèmes d’information (DSI) qui peut intégrer des APIs.

Pour comprendre en détail les éléments techniques nécessaires consulter la rubrique Les fondamentaux à mettre en place avec l’équipe technique.

Étape 2 : Les prérequis techniques avant d’aller plus loin

Une API permet d’agir sur des ressources contenues dans un autre système d’information, sans soi-même avoir la main sur ce système d’information.

Dans le cas d’API Entreprise, les ressources sont des informations sur les entreprises et les associations, et l’action est une consultation.

Comment se déroule un appel à l’API ?

Voici, décrit en quelques étapes, la façon dont vous ou votre équipe technique, allez faire votre requête à l’API Entreprise pour accéder aux données :

Étape 1 : Je suis préalablement habilité, et j’ai donc accès à différentes données, regroupées par endpoint.

Étape 2 : Je construis mon URL d’appel avec l’endpoint qui m’intéresse.

Les différents éléments de l’URL d’appel.
Éléments composant la requête Exemples
Domaine
(ou préfixe)
qui conduit à l’API de façon sécurisée
http://entreprise.api.fouv.fr
Numéro de la version
(par défaut désormais en V2)
/v2
Nom de la donnée recherchée
(ou endpoint)
/attestation_fiscale_dgfip
Identité de l’établissement concerné
(souvent SIREN ou SIRET)
/SIRENouSIRETdeL'Etablissement
Votre jeton d’accès ?token=JetonD'Habilitation
Des paramètres de traçabilité &context=CadreDeLaRequête
&recipientBénéficiareDeL'Appel=
&object=RaisonDeL'AppelOuIdentifiant
?user_id=IdentifiantDeL'UtilisateurPhysique
et autres selon les endpoints …

Tous ces éléments mis bout à bout constituent une requête HTTP qui appelle l’API :

https://entreprise.api.gouv.fr/v2/attestation_fiscales_dgfip/SirenDeL’Entreprise?token=JetonD’Habilitation&user_id=IdentifiantDeL’UtilisateurPhysique&context=CadreDeLaRequête&recipient=BénéficaireDeL’Appel&object=RaisonDeL’AppelOuIdentifiant

Étape 3 : Je passe mon appel :

  • À des fins de tests, au travers de mon navigateur :

    Pour passer votre appel, vous pourriez écrire l’URL dans votre navigateur. La page chargée vous renverrait les données demandées. C’est ce que nous vous proposons de faire ici par le biais d’un test uniquement. ⚠️ En effet, il y a des précautions à prendre : Par défaut, l’historique de votre navigateur enregistre des informations confidentielles dont votre jeton d’accès. Or comme vous avez pu le lire dans la rubrique précédente Un accès sous habilitation et sous conditions, la grande majorité des données accessibles par API Entreprise sont protégées par des secrets, vous êtes donc tenus de vous assurer qu’elles ne soient pas diffusées.

  • En production, par le biais d’un logiciel métier :

    Pour veiller à la protection des données, l’ensemble des appels que vous allez réaliser en production seront passés par l’intermédiaire d’un logiciel métier.

Étape 4 : Je reçois une réponse comportant les données. La réponse est au format JSON, nous détaillons sa structure dans la prochaine partie.

Comment s’interprète la réponse de l’API ?

Structure d’une réponse JSON

Pour chaque appel effectué vous allez recevoir une réponse au format JSON. Ce langage informatique présente l’avantage d’être lisible par un non expert ; tout en étant compréhensible par une machine.

Une réponse JSON est composée de paires “champ” / “valeur” :

  • Le “champ”, ou “nom”, ou “clé”, décrit le type d’information, c’est un invariable.
  • La “valeur” est une variable, c’est justement la donnée que vous recherchez.
Trois types de réponses

Cas n°1 : Le JSON vous renvoie un lien URL, permettant d’accéder à un document PDF :

{
  "url":"http://la-fameuse-url-permettant-d-acceder-au-document.pdf"
}

Cas n°2 : Le JSON vous renvoie un lien URL, permettant d’accéder à une archive de plusieurs documents, au format ZIP:

{
   "http://la-fameuse-url-permettant-d-acceder-a-l-archive-de-documents.zip"
}

Cas n°3 : Le JSON vous renvoie les données structurées :

Dans ce cas précis, les données étant toutes renvoyées au format JSON, les couples “champ” / “valeur” peuvent être regroupé dans différentes catégories.

{
  "eligible": true,
  "message": "00 Compte éligible pour attestation de cotisation"`
}

Pour une information détaillée par endpoint, reportez-vous au catalogue de données.

Le token, une clé unique et privée

Le token est votre code secret vous permettant d’accéder à API Entreprise.

Si votre demande d’habilitation est validée, il vous est délivré dans votre espace personnel.

Cette clé est unique et privée ; nous nous appuyons sur un standard ouvert et normalisé de l’industrie : le Json Web Token (aka JWT) (RFC 7519). Ce jeton est autonome et permet de transmettre de façon sécurisée les informations d’authentifications nécessaires pour utiliser l’API. Ces jetons sont vérifiés et fiables car signés numériquement avec une date d’expiration.

Ne jamais divulguer son token

Votre token vous est propre, il ne faut pas le diffuser : c’est comme votre clé d’appartement, vous ne l’envoyez pas par la poste car il y a un risque que celle-ci soit interceptée par une personne mal intentionnée.

C’est pourquoi, vous ne devez jamais copier-coller un token dans un moteur de recherche ou dans un e-mail.L’usage de votre token se fait uniquement dans votre logiciel métier sécurisé utilisé pour réaliser vos appels.

Un token a une fin de vie

La durée de vie d’un token est limitée, sa date d’expiration est indiqué dans votre espace personnel.

Le token peut également être supprimé s’il a été diffusé par mégarde. Le renouvellement d’un token est très facile et rapide. C’est pourquoi, si vous avez divulgué votre token par erreur, n’hésitez pas à écrire rapidement à support@entreprise.api.gouv.fr. Pour en savoir plus sur le renouvellement d’un token, consultez la rubrique Renouveler un token en fin de vie.

Vous travaillez avec la DSI de votre administration ou avec un éditeur de logiciel, voici la liste des fondamentaux que votre équipe technique doit être en mesure de mettre en place pour un bon fonctionnement de l’API Entreprise :

✅ Pouvoir prendre en charge la mise à jour des protocoles de sécurité HTTPS ;

✅ Anticiper la mise à jour du logiciel métier ;

✅ Avoir une version de langage suffisamment récente. API Entreprise ne fonctionne qu’avec Java 1.7 minimum (pour la gestion des certificats de +1024 bit) ;

✅ Prévoir de whitelister l’adresse IP du service API Entreprise si votre réseau est derrière un pare-feu. En effet, l’API Entreprise est accessible depuis internet.

✅ Anticiper les coûts de maintenance qui s’ajouteront aux coûts de mise en place.

Il se peut qu’un incident survienne chez un fournisseur de données. Votre logiciel doit vous permettre de fonctionner de manière dégradée :

  • si vous effectuez une fonction de pré-remplissage et que le service est à l’arrêt, prévoyez un fonctionnement sans pré-remplissage.
  • en cas d’utilisation de justificatifs, prévoyez de permettre à vos usagers de pouvoir transmettre un document par eux-même.

Le Dîtes-le-nous-une-fois ne doit pas bloquer les usagers en cas d’incidents techniques : vos usagers préfèreront toujours vous redonner leurs informations plutôt que de ne pas pouvoir utiliser votre service.

Étape 3 : Démarrer avec API Entreprise

La demande d’habilitation pour API Entreprise est relativement simple, et se compose de 3 étapes expliquées en détail ci-dessous :

Étape 0 : Anticiper sa demande 🔎

Après avoir lu les étapes 1 et 2, L’API Entreprise correspond-elle à mon besoin ? et Les prérequis techniques avant d’aller plus loin, vous êtes désormais prêt à faire une demande d’accès. Pour vous permettre d’anticiper, ci-dessous la liste des informations nécessaires :

  • le numéro siret de votre administration. Vous pouvez vous aider du site entreprise.data.gouv.fr pour le retrouver.
  • les données que vous souhaitez obtenir. Une sélection vous sera proposée parmi une liste de données décrites dans la section “données délivrées”.

    Aidez-vous des cas d’usage décrits pour vous assurer de votre légitimité. L’ensemble des données disponibles sur API Entreprise est détaillé dans le catalogue des données. Vous pouvez filtrer les données par cas d’usage.

    Une demande d’accès ne peut pas couvrir plusieurs contextes métiers différents et doit être adaptée au public utilisateur final. Si vous avez plusieurs contextes métiers pour lesquels vous souhaitez demander un accès, il vous faudra formuler une demande par contexte.

Exemple de la Région Occitanie :

Dans le cadre de son hub entreprises, trois demandes différentes ont été faites : une demande pour faciliter le renseignement des données par l’usager en pré-remplissant des formulaires à partir d’un numéro de SIRET ; une demande pour la pré-qualification des dossiers d’aides publiques avec l’accès à quelques données sensibles ; une demande pour l’instruction de dossiers avec l’accès à un nombre important de données sensibles pour aider les agents instructeurs.
La région s’est vue remettre un espace client avec 3 tokens d’accès aux permissions différentes.

  • le cadre administratif et légal (texte ou délibération/décision) qui vous légitime à recevoir ces données. Il est possible de mettre un lien vers le texte de loi, ajouter des pièces jointes ou décrire votre contexte.
  • les coordonnées du responsable du traitement. Le responsable du traitement des données est la personne physique ou morale qui, seul ou conjointement avec d’autres, détermine les finalités et les moyens du traitement des données à caractère personnel. Seule une personne appartenant à l’organisme demandeur peut être renseignée.
  • les coordonnées de votre délégué·e à la protection des données (DPD). Le DPD est la personne qui s’assure que l’organisation protège convenablement les données à caractère personnel, conformément à la législation en vigueur. C’est généralement une personne appartenant à l’organisme demandeur.

Je n’ai pas de DPD, que faire ?

Si vous n’avez pas de DPD, c’est que vous n’êtes probablement pas habilité à pouvoir utiliser API Entreprise. En effet, la nomination d’un DPD est obligatoire pour toute autorité publique ou tout organisme public, ainsi que pour toute entreprise effectuant un suivi régulier et systématique de données personnelles à grande échelle ou de données personnelles sensibles. Ce qui est au coeur de l’usage d’API Entreprise.

  • les coordonnées du contact métier.
  • les coordonnées du contact technique. La personne ou l’équipe en charge du développement de l’interface logicielle qui va permettre l’interconnection effective avec API Entreprise.

L’ensemble des coordonnées renseignées seront strictement utilisées pour communiquer avec vous.

Vous devrez également accepter nos conditions générales d’utilisation.

Étape 1 : Faire sa demande d’habilitation sur api.gouv.fr 📝

Création du compte api.gouv.fr

Toute demande d’accès à l’API Entreprise nécessite la création d’un compte sur la plateforme api.gouv.fr.
Avec un même compte vous pouvez réaliser plusieurs demandes, et également accéder à API Particulier.
Une fois que vous avez inscrit votre adresse mail et un mot de passe, la plateforme vous demande un code à 10 chiffres. Ce code vous est envoyé, sous quelques minutes, par l’équipe api.gouv.fr, sur l’adresse que vous avez indiqué.
Ensuite, il vous est demandé le numéro de SIRET de votre organisation, celui-ci est indispensable pour toute création de compte.

Remplir le formulaire d’accès

Remplissez le formulaire de demande d’accès api.gouv.fr puis validez-le.
Au cas où il vous manquerait une information, vous pourrez reprendre ultérieurement le formulaire. Pour cela, n’oubliez pas de cliquer sur le bouton “Sauvegarder le brouillon” se trouvant en bas du formulaire.

Se rendre sur api.gouv.fr

Étape 2 : Suivre l’instruction du dossier par la DINUM ⚙️

Une fois votre demande validée, nous instruisons alors votre dossier puis prenons une décision d’acceptation ou de refus de la demande d’accès. Cette instruction prend en moyenne 11 jours selon l’affluence des demandes. La durée de traitement est aussi dépendante de la précision et de l’exhaustivité des informations que vous nous transmettez, qui influeront sur le nombre d’aller-retour que nous aurons à faire pour le finaliser.

  • ❌ Si votre dossier est refusé, des précisions supplémentaires vous seront demandée avant tout refus définitif ;
  • ✅ Si votre dossier est validé, un mail de confirmation vous est envoyé. Connectez-vous à votre tableau de bord avec vos identifiants api.gouv.fr.

Pour récupérer vos tokens ou jetons d’accès, il faut vous rendre dans votre tableau de bord à l’onglet “Jetons” :

Tous vos jetons sont valables pour une durée de 18 mois.

Instruire les paramètres de traçabilité

API Entreprise vous permet d’accéder à des données protégées. C’est pourquoi, dans un objectif de traçabilité, nous vous demandons de renseigner dans chacune de vos requêtes, non seulement un jeton d’accès, mais aussi certaines informations qualifiant votre requête.

Ces paramètres sont obligatoires. Les appels ne comportant pas ces paramètres sont rejetés, et un code erreur vous est renvoyé.

Pour chaque endpoint, nous précisons dans le catalogue des données les paramètres obligatoires spécifiques, ci-dessous la liste de tous ces paramètres :

Paramètres obligatoires Informations à renseigner
&context=CadreDeLaRequête Cadre de la requête
Par exemple : aides publiques, marchés publics ou gestion d’un référentiel tiers utilisé pour tel type d’application.
&recipient=BénéficaireDeL'Appel Bénéficiaire de l’appel
(siret de l’administration destinatrice des données)
&object= RaisonDeL'AppelOuIdentifiant La raison de l’appel
ou l’identifiant de la procédure
(numéro de marché publique, nom de la procédure, description courte (< 50 caractères))
?user_id= IdentifiantDeL'UtilisateurPhysique [obligatoire pour les endpoints DGFIP]
L’identifiant de l’utilisateur physique qui fait l’appel
Par exemple dans le cas d’une place de marché, il s’agit de l’identifiant de l’acheteur public qui consulte la pièce. Il servira, en cas d’utilisation anormale de l’API, pour remonter à la source et vérifier que l’utilisateur avait bien le droit d’accéder à cette donnée.

Voir ma première trace d’appel dans le tableau de bord

Une fois que vous avez fait un premier appel, celui-ci est répertorié dans votre tableau de bord, en passant par la liste de tous vos tokens, et en cliquant sur “Voir les statistiques”.

Respecter la volumétrie

Sur API Entreprise, vous avez le droit à 2000 requêtes par tranche de 10 minutes par IP interrogeant nos services.

Au delà de ce taux, votre IP sera bannie temporairement de nos serveurs. Les appels depuis une IP bannie ne renvoient pas de codes http, le serveur ne répond tout simplement pas. Par contre, dans votre tableau de bord, vous pouvez vérifier si vous avez dépassé ce seuil. Si par mégarde vous vous retrouviez dans cette situation, adressez-nous un email à support@entreprise.api.gouv.fr

Si vous avez besoin de plus de volumétrie, veuillez également nous contacter, nous étudierons votre demande et si la situation s’y prête, nous whitelisterons votre / vos IPs pour éviter qu’elles ne se fassent bannir.

Pour les appels de traitement de masse, il est souhaitable que vous fassiez vos batchs automatiques la nuit ou durant les heures creuses afin de ne pas affecter la qualité du service pour le reste des usagers.

Installer un timeout

Le timeout est le temps d’attente maximal de réponse à une requête. Pour chaque endpoint, nous vous indiquons le timeout idéal dans le catalogue de donnée.

Le timout est un outil important qui permet de ne pas immobiliser votre logiciel en le laissant bloqué sur un appel sans réponse.

De façon générale, nous vous recommandons un timeout :

  • de 5 secondes pour les appels de données structurées JSON ;
  • de 12 secondes pour les appels retournant un PDF ou un ZIP.

De même, pour ne pas immobiliser nos serveurs, nous attendons les réponses de nos fournisseurs un maximum de 10 secondes avant de vous les retransmettre. Si ce délai d’attente est dépassé un code erreur HTTP 504 vous sera renvoyé.

Les requêtes multi-origines non-autorisées

API Entreprise étant un service mettant à disposition des données souvent protégées par des secrets, le CORS (CORS -Cross Origin Ressource Sharing) n’est pas autorisé car il permet d’interroger directement API Entreprise depuis un site ou une application web. Cela implique que le token d’accès soit présent dans le code source du site web en question, et donc soit disponible au public.

Pour mettre à disposition les données API Entreprise depuis un navigateur, il vous faut mettre en place un système de proxy pour ne pas appeler directement nos APIs.

Construire en compatibilité ascendante

🚧 Ce contenu est en cours de construction et sera bientôt disponible. 🚧

🚧 Ce contenu est en cours de construction et sera bientôt disponible. 🚧

Étape 4 : API Entreprise au quotidien

Toute réponse de l’API Entreprise comprend une réponse JSON ainsi qu’un code HTTP. Celui-ci n’est pas immédiatement lisible par un humain, il est destiné aux traitements automatiques. Ces codes permettent de se renseigner sur le statut de l’appel, toutes les explications complémentaires sont indiquées dans le JSON.

Pour en savoir plus sur les codes HTTP, l’article de Wikipedia constitue une bonne base explicative : https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP.

API Entreprise a harmonisé les codes erreur de l’ensemble des fournisseurs de données, en s’appuyant sur le protocole HTTP, afin de vous en simplifier la compréhension :

En cas de succès, le code HTTP commence par 2 :
Code HTTP Signification
200 Tout va bien.
206 Réponse incomplète - La requête a fonctionné mais un des fournisseurs de données a renvoyé une erreur ou une réponse incomplète. Les valeurs concernées dans le JSON contiennent le message : “Donnée indisponible”.
En cas d’échec, si l’erreur vient de votre côté, le code HTTP commence par 4 :
Code HTTP Signification
400 Mauvaise requête – La syntaxe de votre requête est erronée.
401 Non autorisé – Votre token est invalide ou manquant.
403 Interdit – Le serveur a compris votre requête mais refuse de l’exécuter car votre jeton ne vous donne pas accès à cette ressource.
404 Non trouvé – La ressource (l’entreprise, le certificat, …) demandée n’a pas été trouvée. Cette erreur intervient par exemple lors de l’entrée d’un numéro de SIREN qui n’existe pas, ou bien lorsque l’entreprise qu’il designe est en dehors du périmètre de l’endpoint.
422 Entité non traitable – Le format de la donnée passée en paramètre n’est pas accepté. Par exemple, si vous entrez 20 chiffres dans le paramètre SIREN, votre requête est automatiquement rejetée, car un SIREN fait obligatoirement 9 chiffres.
451 Indisponible pour raisons légales - ce code est spécifiquement renvoyé lorsque vous demandez les informations d’une entreprise ou d’un établissement non diffusible au travers des endpoints entreprises et etablissements de l’INSEE, sans avoir utilisé l’option d’appel spécifique. Pour en savoir plus, consultez la documentation de cet endpoint dans le catalogue de données.
En cas d’échec, si l’erreur provient d’API Entreprise ou bien des fournisseurs de données, le code HTTP commence par 5 :
Code HTTP Signification
500 Erreur interne à API Entreprise – Une erreur interne du serveur d’API Entreprise est survenue. Consultez votre tableau de bord, l’historique de l’incident devrait y être affiché ; ainsi que les actions à venir.
502 Erreur interne fournisseur – Une erreur interne du serveur du ou des fournisseurs est survenue. Consultez votre tableau de bord, l’historique de l’incident devrait y être affiché ; ainsi que les actions à venir.
503 Service non disponible – Le service est temporairement indisponible ou en maintenance. Pour connaître l’historique de disponibilité et les incidents type de l’endpoint, vous pouvez consulter le catalogue de données.
504 Intermédiaire hors délai – Le(s) producteur(s) de données ont mis trop de temps à répondre. Notre temps d’attente, nous permettant de ne pas immobiliser le serveur sur un appel sans réponse, est fixé à 10 secondes et a été dépassé.

En cas d’erreur, le JSON vous détaille la raison de l’erreur, le champ concerné se nomme “errors”. Lorsqu’un endpoint retourne des données agrégées de plusieurs fournisseurs, le JSON renvoyé contient un champ “gateway error”. Sa valeur vaut “true” lorsqu’une erreur survient auprès d’au moins un fournisseur.

Pour des raisons de sécurité, tous les jetons émis sont valables pour une durée de 18 mois. Au delà de ce délai, ils ne fonctionnent plus, et votre accès à l’API Entreprise est donc totalement arrêté.

En réalité, cette situation n’est pas censée arriver car API Entreprise a mis en place une procédure simple de renouvellement de token. En voici les étapes :

Étape 1 : Lire les notifications de renouvellement 📬

Trois mois avant l’arrivée à terme d’un jeton, vous recevez des notifications automatiques vous informant de l’expiration à venir de votre jeton ainsi qu’une invitation à le renouveler. Les notifications sont envoyées régulièrement jusqu’au renouvellement (90 jours avant la date d’expiration, puis 60 jours avant, puis 30, 15, …).

Étape 2 : Remplir le formulaire de renouvellement 📝

Un renouvellement de jeton est en pratique une nouvelle demande d’accès. Il existe deux possibilités de renouvellement de votre token selon que vous ayez fait votre dernière demande avant septembre 2019 ou après. Nous avons en effet transformé l’outil pour effectuer une demande d’accès à l’API Entreprise. Hier, il s’agissait de demarches-simplifiees.fr ; aujourd’hui, il s’agit d’api.gouv.fr.

Cas n°1 : Votre dernière demande remonte avant septembre 2019 et a été réalisée au travers de demarches-simplifiees.fr

La notification d’expiration vous a conduit directement sur cette documentation. Effectivement, la plateforme demarches-simplifiees.fr n’étant plus la plateforme utilisée par API Entreprise, nous allons devoir vous demander de créer un compte sur api.gouv.fr. Nous vous prions d’accepter nos excuses pour la gêne occasionnée, ce transfert étant dans l’objectif de vous fournir un meilleur service.

Pour renouveler votre token, vous allez donc suivre la démarche d’une demande d’accès. Tout est expliqué en détail ici.

Si votre situation d’usage de l’API Entreprise n’a pas changé, inscrivez les mêmes informations utilisées dans votre demande sur demarches-simplifiees.fr. Pensez surtout à mettre à jour les informations de contact.

Cas n°2 : Votre dernière demande est intervenue après septembre 2019, et a été réalisée au travers d’api.gouv.fr.

La notification de d’expiration contient directement un lien vers le formulaire de renouvellement api.gouv.fr. Le formulaire de renouvellement de token est directement pré-rempli avec les informations renseignées lors de la demande initiale. Pensez à mettre à jour les informations de contacts.

Étape 3: Attendre la validation et récupérer son nouveau jeton 🔐

Une fois la demande de renouvellement envoyé, un instructeur API Entreprise valide le renouvellement du jeton. L’utilisateur pourra alors le récupérer dans son tableau de bord.

Le service API Entreprise est indisponible pour l’un des endpoints ? Il se peut que ce soit dû à un incident côté fournisseurs de données.

  1. Dans une telle situation, la première chose à faire est de consulter la page incident et de vérifier si l’indisponibilité n’y est pas répertoriée. Toutes les indisponibilités y sont inscrites dans le délai le plus court possible et parfois même anticipées lorsque le fournisseur de donnée nous prévient à l’avance d’une indisponibilité pour maintenance.
    Vous pouvez également consulter la page temps réel et ainsi vérifier si l’endpoint ne fonctionnant pas est indiqué comme DOWN dans l’interface. API Entreprise a effectivement mis en place un système de test permettant de vérifier l’état de disponibilité de tous les endpoints.
  2. Si l’incident n’est pas répertorié, deux options se présentent : l’erreur provient de votre côté, ou bien elle n’a pas encore été identifiée par API Entreprise. Après avoir pris soin de regarder qu’il ne s’agit pas de la première option, vous pouvez nous contacter sur support@entreprise.api.gouv.fr.

Vérifier ne pas avoir dépassé la volumétrie autorisée

Le service API Entreprise semble soudainement rejeter vos requêtes ? Vérifiez que vous avez bien respecté les limites de volumétrie.

Agir en cas d’indisponibilité globale avérée

🚧 Ce contenu est en cours de construction et sera bientôt disponible. 🚧

Vous souhaitez élargir le périmètre des endpoints auxquels vous avez accès ?
Il vous faut refaire une demande d’habilitation.

Pour toute nouvelle demande, il vous faudra justifier le cadre légal.

Si l’habilitation vous est donnée, API Entreprise vous fournira un nouveau jeton contenant le nouveau périmètre des endpoints accessibles.

🚧 Ce contenu est en cours de construction et sera bientôt disponible. 🚧

Endpoints en particulier

Paramètres d’appel

Nouvelles API

Changement de la source de données

Sécurité et volumétrie

Demander une information

Vous n’avez pas trouvé la réponse à votre question dans notre documentation et dans le catalogue des données ? Vous pouvez nous contacter sur support@entreprise.api.gouv.fr.

Pour améliorer le temps de traitement de votre demande, il est important de nous fournir, au minimum, les informations suivantes :

  • le ou les endpoints sur lesquels le problème est rencontré ;
  • le siret, siren ou tout autre paramètre passé à la requête ;
  • l’adresse email sous laquelle est enregistré votre jeton d’authentification ;
  • Toute autre information, capture d’écran, etc détaillant l’erreur rencontrée est évidemment bienvenue.

Attention de ne pas partager votre jeton d’authentification dans votre demande de support ! L’échange d’emails n’est pas un support de communication sécurisé et certaines APIs donnent accès à des données sensibles. Le cas échéant, nous serons obligés de supprimer votre jeton, et vous devrez faire une nouvelle demande.

API Entreprise rédige régulièrement une infolettre faisant état des dernières évolutions. Lors de votre inscription à API Entreprise, vous êtes automatiquement abonnés à notre infolettre.

Si vous n’avez pas demandé expressement de vous désabonner, et que vous ne recevez pas nos infolettres, il se peut qu’elle soit dans vos spams. Autrement, écrivez-nous à support@entreprise.api.gouv.fr

Co-construire le service

Vous avez repéré un bug ? une erreur ?

N’hésitez pas à nous transmettre cette information, en précisant s’il s’agit d’une anomalie :

  • spécifique à un seul endpoint, repéré suite à un appel, dans ce cas, indiquez-nous le paramètre utilisé (SIRET, SIREN …) ;
  • générale à API Entreprise ;
  • concernant la documentation, nous agrégeons beaucoup de contenus métiers et techniques, il peut arriver qu’une erreur se soit glissée, ou bien que la documentation n’ait pas été mise à jour suffisamment rapidement. Précisez-nous autant que possible l’emplacement du bug avec une capture d’écran par exemple. Indiquez-nous si possible la version de votre navigateur ;
  • concernant le site internet.
Signaler un bug ou une erreur

Vous êtes une administration en relation avec les entreprises et les associations ? Vous avez des données et souhaitez les faire circuler inter-administration dans le cadre du “Dîtes-le-nous-une fois” ?

Contactez-nous !

API Entreprise réalise régulièrement des ateliers ou des conférences pour présenter les évolutions fonctionnelles de l’API ou les nouveaux endpoints. Retrouvez ici tous les évènements passés et à venir :

Date Évènement Lieu Horaires Annexes
17 oct. 2019 Présentation des nouveautés API Entreprise
Évolutions réglementaires, nouvelles données disponibles…
DINUM, 20 avenue de Ségur, 75007 Paris 14:00-17:00 /

🚧 Ce contenu est en cours de construction et sera bientôt disponible. 🚧