Documentation générale

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

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

Toutes les données sont détaillées dans le catalogue de 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 documentation technique et métier par endpoint

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” :

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 protégées, 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.

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.

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. Pour comprendre comment trouver le jeton d’accès, veuillez consulter la rubrique Habilitation validée, récupérer son token.

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.8 minimum (pour la gestion des certificats de +1024 bit, du TLS 1.2 minimum et des suites cryptographiques - ciphers) ;

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

✅ S’assurer que nos Autorités de Certification (AC) pour les certificats SSL sont autorisées par vos systèmes. Consulter la fin de la rubrique configurer le logiciel métier.

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.

Après avoir déterminé que l’API Entreprise répond à votre besoin et que vous disposez des prérequis techniques nécessaires, vous pouvez effectuer une demande d’habilitation.
⚠️ Une demande d’accès doit couvrir un seul contexte métier. 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.

Demande d’accès pour un cas d’usage standard (formulaires pré-remplis) :
En passant, par les formulaires pré-remplis proposés pour chaque cas d’usage standard, l’instruction de votre demande sera accélérée.
🔑 Demande par cas d’usage

Demande d’accès préremplie pour les éditeurs :
🔑 Demande éditeur

Demande d’accès avec formulaire libre :
Utilisez la demande libre, uniquement si votre situation ne correspond pas aux cas d’usage déjà proposés. 🔑 Demande libre

Le fonctionnement d’une demande

La demande d’habilitation se déroule en deux étapes :

Les informations demandées

La liste des données souhaitées

Le formulaire vous permet de cocher les données que vous souhaitez demander. Pour cela vous pouvez vous aider :

• du catalogue de données. Il présente l’ensemble des endpoints disponibles accompagnés d’une documentation fonctionnelle et technique.

• des cas d’usage proposés par API Entreprise. Nous y décrivons les données utiles. Si votre besoin correspond à l’un de ses cas d’usage, vous pourrez vous appuyez sur le formulaire pré-rempli adéquat.

Le cadre juridique

L’accès à un endpoint de l’API Entreprise se fait sous réserve que son utilisation soit justifiée. L’accès à la donnée requiert la fourniture d’un cadre juridique précis, c’est pourquoi, il vous sera systématiquement demandé :

• une description précise de votre service et de l’utilité des données demandées dans ce contexte

• Si vous êtes une administration centrale, une agence d’État, un opérateur, ou un service déconcentré, il vous faudra transmettre le décrêt ou l’arrêté justifiant votre demande.

Attention, quel que soit votre statut, le CRPA (Code des relations entre le public et l’administration), la loi ESSOC (pour un État au service d’une société de confiance) ou la loi Lemaire (pour une République numérique) ne sont pas suffisants car ils indiquent un principe d’échange qui doit être complété par un cadre juridique précis pour l’utilisation envisagée.

Les coordonnées des différents contacts

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

• Le responsable du traitement des données. C’est la personne physique ou morale qui, seule ou conjointement avec d’autres, détermine les finalités et les moyens du traitement des données à caractère personnel. Cette personne renseignée doit obligatoirement appartenir à l’organisation déclarée dans la demande.

• Le délégué·e à la protection des données. 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’organisation effectuant la demande.

  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.

• le contact métier. C’est une personne en responsabilité du projet, il peut s’agir du demandeur. API Entreprise contactera cette personne pour avertir de nouvelles fonctionnalités ou d’incidents majeurs sur nos APIs.
• le contact technique C’est une personne ou l’équipe en charge du développement de l’interface logicielle qui va permettre l’interconnection effective avec API Entreprise. API Entreprise contactera cette personne pour avertir d’évolutions techniques, d’incidents et de l’expiration des jetons. Le contact métier et le contact technique peuvent être confondus, notamment si vous passez par un éditeur.

L’acceptation des conditions d’utilisation API Entreprise

Avant tout envoi de votre demande, vous devez accepter nos conditions générales d’utilisation.
Nous vous invitons à les lire attentivement car une grande partie des données circulant par le biais d’API Entreprise sont sensibles. Votre futur accès à l’API s’accompagne d’engagements, notamment, entre autres, ceux de présenter les données uniquement aux agents habilités et de tracer l’accès de ces données.

Seule la personne ayant fait la demande d’habilitation a accès au token, au travers du tableau de bord. Elle est responsable de cette clé et de sa transmission sécurisée si cela est nécessaire dans le cadre de l’intégration de l’API Entreprise.

Récupérer le jeton d’accès

Si vous avez réalisé la demande d’habilitation, vous pouvez récupérer vos tokens ou jetons d’accès directement depuis votre tableau de bord, à l’onglet “Jetons” :

Transmettre le jeton d’accès

Si vous avez réalisé la demande d’habilitation mais que vous n’êtes pas la personne en charge d’intégrer l’API Entreprise, vous pouvez transmettre le token de façon sécurisée depuis le tableau de bord, en cliquant sur le bouton “Transmettre le jeton à mon équipe technique”.
Le destinataire recevra, par e-mail, un lien d’une durée de 4 heures, où il pourra copier/coller le token.

Votre clé d’accès est unique et privée. L’utilisation de cette fonctionnalité du tableau de bord doit avoir pour unique objectif la transmission sécurisée de votre clé à vos services techniques qui intégreront l’API Entreprise. Vous ne devez jamais transmettre votre clé d’accès par e-mail.

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.

Depuis son navigateur ou le swagger API Entreprise

Votre habilitation est validée, vous avez récupéré vos jetons, vous pouvez donc désormais faire un premier appel de test.

• Si vous êtes à l’aise avec les interfaces techniques, nous avons mis en place un environnement de production documenté (Swagger), disponible sur api.gouv.fr. Il permet, à l’aide d’un token d’authentification valide 🔑, d’effectuer directement depuis le navigateur des tests de l’API. Les données confidentielles restent bien protégées. Vous y trouverez aussi la spécification technique téléchargeable sous format YAML afin de pouvoir accélérer le développement de vos outils d’interfaçage avec API Entreprise.

• Autrement, vous pouvez effectuer votre appel de test directement dans la barre URL de votre navigateur, en collant votre requête HTTP renseignée de votre token 🔑.

Attention, vous ne devez jamais copier-coller un token dans la barre de recherche classique d’un moteur de recherche ou dans un e-mail.

Construire la requête HTTP

Que ce soit en environnement de production ou dans la barre URL de votre navigateur, vous avez besoin de construire une URL d’appel. Cette requête de l’endpoint que vous souhaitez tester est explicitée dans le catalogue des données, partie “Documentation” de l’endpoint. Nous vous y indiquons la structure de la requête et les paramètres à remplir.

Exemple de requête :

https://entreprise.api.gouv.fr/v2/attestation_fiscales_dgfip/SirenDeL’Entreprise?token=📝&user_id=📝&context=📝&recipient=📝&object=📝

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

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 une explication détaillée des éléments à fournir pour chaque paramètre de traçabilité :

Respecter la volumétrie

Limites

Les limites de volumétrie sur API Entreprise se décomposent en deux règles principales :

• Un plafond général par IP de 1000 requêtes/minute.
  

• Une volumétrie par jeton par groupe d’endpoints :

  • 1er groupe : Les endpoints renvoyant du JSON constituent un premier groupe. Vous pouvez effectuer jusqu’à 250 requêtes/min/jeton sur ce groupe.

  • 2ème groupe : Les endpoints transmettant des documents constituent un autre groupe. La volumétrie maximale d’appel concernant ce groupe est de 50 requêtes/min/jeton.

  • Exceptions : Certains endpoints échappent à cette règle et présentent une volumétrie spécifique par endpoint :

    • L’attestation fiscale de la DGFIP : 5 requêtes/min/jeton ;

    • Les actes de l’INPI : 5 requêtes/min/jeton ;

    • Les bilans de l’INPI : 5 requêtes/min/jeton ;

    • Les effectifs de l’URSSAF : 250 requêtes/min/jeton ;

    • La conformité des travailleurs handicapés de l’Agefiph : 250 requêtes/min/jeton.

Pour vous assurer de la volumétrie d’un endpoint en particulier, vous pouvez consulter la partie “disponibilité” de sa documentation dans le catalogue de données.

Informations actionnables et alertes

Header associé à chaque réponse

Le Header de chaque réponse de l’API Entreprise est complété de trois champs concernant les limites de volumétrie, respectant les spécifications des RateLimit définie dans la RFC suivante https://tools.ietf.org/id/draft-polli-ratelimit-headers-00.html.

Ce header vous permet donc d’avoir une visibilité constante et en temps réel de la volumétrie, et de gérer un dépassement.

Exemple :
Considérons un endpoint ayant une limite de 50 appels /minute. Vous faîtes un premier appel à 10h00 pile, et effectuez un second appel 20 secondes plus tard, puis un troisième 10 secondes plus tard, vous aurez les valeurs suivantes :
- RateLimit-Limit : 50 ;
- RateLimit-Remaining : 47 (50 moins les 3 appels effectués) ;
- RateLimit-Reset : [Timestamp correspondant au jour présent à 10h01]. Le premier appel initialise le compteur (à 10h00 pile), la période se termine 1m plus tard.

Vous pouvez donc jusqu’à 10h01 pile effectuer 47 appels, le compteur sera réinitialisé à 50 à ce moment-là.

Header associé à un code erreur 429

Si vous dépassez le nombre d’appels autorisés (RateLimit-Remaining = 0), le serveur répondra avec le status 429 sur tous les appels suivants dans la même période. 
Le header associé à ce code erreur 429 sera accompagné :

• des trois champs précédents ;
• d’un champ supplémentaire indiquant le temps à attendre avant de pouvoir effectuer des nouveaux appels.

Vous pouvez donc utiliser les champs du header pour optimiser votre consommation de l’API Entreprise.

Bannissement

En cas de non prise en compte des codes erreurs 429ou en cas de dépassement de la limite de volumétrie globale, votre IP sera temporairement bannie de nos serveurs pour une durée fixe et non révocable de 12h. Si vous avez plusieurs jetons, tous seront donc bloqués pendant ce laps de temps.
Les appels depuis une IP bannie ne renvoient pas de codes HTTP, le serveur ne répond tout simplement pas. Vous pouvez en revanche vérifier si vous avez dépassé ce seuil depuis votre tableau de bord.

Au bout de ces 12 heures, vos accès sont automatiquement rétablis ; il est donc inutile d’écrire au support.
Nous vous invitons à prendre les mesures nécessaires car le dépassement intervient généralement chez nos utilisateurs lorsque leur programme n’a pas été correctement configuré.

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.

Certificats SSL et Autorités de certification

API Entreprise utilise DHIMYOTIS comme organisme de délivrance de ses certificats SSL principaux ainsi que Let’s Encrypt pour certains services secondaires.

Il est conseillé d’ajouter ces Autorités de Certifications (AC) à votre base de confiance si vous en avez une. Une solution idéale est d’utiliser un paquet d’autorités mises à jour automatiquement (Mozilla par exemple)

API Entreprise utilise des certificats multi-domaines ; c’est à dire avec un “nom courant” (common name - CN) et plusieurs “noms alternatifs du sujet” (subject alternatives names - SAN), soyez certains que vos outils fonctionnent correctement avec.

Pour connaître la liste des APIs auxquelles vous avez le droit avec votre jeton d’accès, vous pouvez le vérifier avec l’API /privileges.

Si vous gérez les tokens pour vos clients, vous pouvez aussi utiliser cette API pour vérifier les droits associés à leurs tokens.

La requête HTTP :

https://entreprise.api.gouv.fr/v2/privileges?token=LeTokenATester

Le paramètre d’appel à renseigner est le token dont vous souhaitez connaître les droits.

Exemple de réponse :

{
  "privileges": [
    "attestations_agefiph",
    [...]
    "actes_bilans_inpi"
  ]
}

La réponse JSON renvoie la liste des endpoints autorisés. Retrouvez-les dans le catalogue des données.

ℹ️ Pour plus d’informations, vous pouvez vous référer à l’environnement de production documenté (swagger) disponible sur api.gouv.fr.

Pour connaître la disponibilité de tous les endpoints en temps réel, vous pouvez utiliser l’API /current_status. Cette API est ouverte et ne nécessite pas de token, attention à tout de même respecter les limites de volumétrie habituelle.

La requête HTTP :

https://entreprise.api.gouv.fr/watchdoge/dashboard/current_status

Exemple de réponse :

{
  "results": [
    {
      "uname": "apie_2_etablissements",
      "name": "Etablissements",
      "provider": "insee",
      "api_version": 2,
      "code": 200,
      "timestamp": "2020-10-14T14:36:33.640Z"
    },
    {
      "uname": "apie_2_certificats_qualibat",
      "name": "Certificats Qualibat",
      "provider": "qualibat",
      "api_version": 2,
      "code": 503,
      "timestamp": "2020-10-14T14:38:02.736Z"
    },
    [...]
  ]
}

ℹ️ Pour plus d’informations, vous pouvez vous référer à l’environnement de production documenté (swagger) disponible sur api.gouv.fr.

Pour connaître l’historique de disponibilité des données de API Entreprise ainsi que le taux d’erreurs constatées, vous pouvez utiliser l’API /provider_availabilities. Cette API est ouverte et ne nécessite pas de token, attention à tout de même respecter les limites de volumétrie habituelle.

La requête HTTP :

https://entreprise.api.gouv.fr/watchdoge/stats/provider_availabilities?period=ParamètreDeLaPeriode&endpoint=ParamètreDuEndpoint

Pour appeler l’API concernant l’endpoint et la période voulue, référez-vous à la suite de cet article ⤵️

Exemple de réponse :

{
  "endpoint": "api/v3/entreprises_restored",
  "days_availability": {
    "2020-04-13": {
      "total": 12615,
      "404": 9,
      "502": 0,
      "503": 0,
      "504": 0
    },
    "2020-04-14": {
      "total": 44677,
      "404": 25,
      "502": 0,
      "503": 16,
      "504": 0
    }
  },
  "total_availability": 99.96,
  "last_week_availability": 100.0
}

Nomenclature des paramètres de la requête HTTP :

Cette API possède deux paramètres, period et endpoint, voici leur nomenclature :

À partir de la nomenclature, Y(année), M(mois), W(semaine), D(jour), m(minute), s(seconde), vous pouvez obtenir l’historique de disponibilité de la période que vous souhaitez.

ℹ️ Pour plus d’informations, vous pouvez vous référer à l’environnement de production documenté (swagger) disponible sur api.gouv.fr.

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 :

En cas d’échec, si l’erreur vient de votre côté, le code HTTP commence par 4 :

En cas d’échec, si l’erreur provient d’API Entreprise ou bien des fournisseurs de données, le code HTTP commence par 5 :

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 :

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

Vous n’avez pas trouvé la réponse à votre question dans notre documentation et dans le catalogue des données ?

Nous avons une page de support dédiée à l’adresse suivante: Support

API Entreprise rédige régulièrement des lettres d’information faisant état des dernières évolutions. Après validation de vos accès à l’API Entreprise, vous êtes automatiquement abonné à ces lettres d’information selon votre statut :

• le demandeur et le contact métier reçoivent les infolettres 📮 ;
• le contact technique reçoit les techlettres ⚙️, et les notifications de maintenance et d’incidents 🚧. En cas d’incidents majeurs, les contacts métier et demandeur sont informés.

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

Vous souhaitez vous abonner à nos différentes lettres d’informations ? Une page dédiée vous permet de vous abonner aux infolettres, aux techlettres et aux notifications de maintenance et d’incidents. Cette page vous permet également de consulter les archives des communications envoyées par API Entreprise.

S’abonner aux lettres d’informations

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.

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” ?

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 :

Vous êtes intéressé-e par l’API Entreprise et souhaitez nous rejoindre ? Nos offres sont publiées sur le site de Beta.gouv.fr.