Prérequis techniques

Voici la liste des fondamentaux techniques à mettre en place pour le bon fonctionnement de l’API Entreprise :

  • ☑️ Être en mesure de gérer le protocole HTTPS ;
  • ☑️ Avoir une version de langage récente. Si vous utilisez Java, une version >= 1.8 est nécessaire (pour la gestion des certificats de +1024 bit, du TLS 1.2 minimum et des suites cryptographiques - ciphers) ;
  • ☑️ S’assurer que nos Autorités de Certification (AC) pour les certificats SSL sont autorisées par vos systèmes ;
  • ☑️ L’API Entreprise est uniquement accessible par internet. Si vous avez un pare-feu, il faut donc prévoir de whitelister l’adresse IP du service API Entreprise ;
  • ☑️ Il est interdit d’interroger l’API Entreprise depuis un site web en front-end, car le jeton d’accès serait alors divulgué. Il vous faut donc interroger nos API depuis une application en back-end. Nous n’autoriserons pas le CORS (CORS - Cross Origin Ressource Sharing) ;
  • ☑️ Prévoir non seulement les coûts de développement mais également les coûts de maintenance ;
  • ☑️ Être en capacité de gérer les mises à jour de l’API Entreprise.



💡 Pour mieux comprendre l’API Entreprise avant de demander un accès, vous pouvez utiliser notre environnement de test.

Spécifications générales 🎛

Respecter la volumétrie

Les plafonds

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 comptes annuels du RNCS de l’INPI : 5 requêtes/min/jeton ;
    - Les effectifs de l’URSSAF : 250 requêtes/min/jeton ;

Informations volumétrie dans le header

Pour toutes les réponses :

Dans toutes les réponses de nos API, le header vous transmet des informations sur la volumétrie :

Champs du header Signification Format
RateLimit-Limit La limite concernant l’endpoint appelé, soit le nombre de requête/minute. Nombre
RateLimit-Remaining Le nombre d’appels restants durant la période courante d’une minute. Nombre
RateLimit-Reset La fin de la période courante. Timestamp

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 1min plus tard.

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

En cas de dépassement :

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.
Champs du header Signification Format
RateLimit-Limit La limite concernant l’endpoint appelé, soit le nombre de requête/minute. Nombre
RateLimit-Remaining Le nombre d’appels restants durant la période courante d’une minute. Nombre
RateLimit-Reset La fin de la période courante. Timestamp
Uniquement pour le header associé au code erreur 429
Retry-after
Décompte du nombre de secondes restantes avant la prochaine période Secondes

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

Règles de bannissement en cas de surconsommation

En cas de non prise en compte des codes erreurs 429 ou 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 compte utilisateur.

ℹ️ 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.

Configurer vos timeout

Le timeout est le temps d’attente maximal de réponse à une requête. Il vous 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é.

Autoriser nos Autorités de Certifications

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.

Gérer les erreurs - codes HTTPS

Un code standard HTTPS pour catégoriser le statut de l’appel

Toutes les réponse de l’API Entreprise sont envoyées avec un code HTTPS. Ces codes permettent de se renseigner sur le statut de l’appel, et sont harmonisés pour l’ensemble des API quelque soir le fournisseur de données.
Pour en savoir plus sur les codes HTTPS, cet article de Wikipedia constitue une bonne base explicative.

En cas de succès, le code HTTP commence par 2 :
Code HTTPS Signification
200 Tout va bien.
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 compte utilisateur, 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 compte utilisateur, 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é.

Un code supplémentaire pour préciser l’erreur et enclencher une action

Tous les codes erreur HTTPS sont accompagnés de codes plus précis, spécifiques à chaque situation d’erreur. Une explication en toutes lettres est également donnée dans la payload. Enfin, dans certains cas, une métadonnée actionnable est disponible.

Dans l’exemple ci-dessous, la clé retry_in permet justement de relancer un appel après le nombre de secondes indiquées.

Exemple de payload d’un code HTTPS 502 :

{
   "errors": [
      {
           "code": "04501",
           "title": "Analyse de la situation du compte en cours",
           "detail": "La situation de l'entreprise requiert une analyse manuelle d'un agent de l'URSSAF. Une >demande d'analyse vient d'être envoyée, cela prend au maximum 2 jours.",
           "meta": {
               "provider": "ACOSS",
               "retry_in": 172800
          }
       }
   ]
}

Retrouvez tous les codes erreurs pour chaque endpoint dans notre swagger, partie “Response samples”.
La liste des codes spécifiques à chaque endpoint y est disponible.

Renseigner les paramètres d'appel et 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 swagger, rubrique “Query parameters” les paramètres obligatoires spécifiques, ci-dessous une explication détaillée des éléments à fournir pour chaque paramètre de traçabilité :

Paramètre Information à renseigner
&context=CadreDeLaRequête Le 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 Le bénéficiaire de l’appel

Ce paramètre permet la traçabilité de l’appel et doit correspondre au SIRET de l’organisation publique habilitée à utiliser la donnée.

Si vous êtes une collectivité ou une administration, ce paramètre doit donc être votre numéro de SIRET. Si vous êtes un éditeur, il s’agit du SIRET de l’organisation publique cliente demandant la donnée.

Une vérification est effectuée par API Entreprise pour refuser tout format qui ne serait pas un numéro de SIRET et pour refuser un SIRET qui serait identique à l’entité appelée.
&object= RaisonDeL'AppelOuIdentifiant La raison de l’appel
ou l’identifiant de la procédure.

L’identifiant peut être interne à votre organisation ou bien un numéro de marché publique, un nom de procédure ; l’essentiel est que celui-ci vous permette de tracer et de retrouver les informations relatives à l’appel. En effet, vous devez pouvoir justifier de la raison d’un appel auprès du fournisseur de données.
Description courte (< 50 caractères).

Gérer les évolutions de version

Il est fréquent que les API évoluent et que, par conséquent, de nouvelles versions soient publiées.
La version majeure V.3 de l’API Entreprise permet de créer facilement de nouvelles versions, tout en gardant les précédentes, rendant ainsi accessibles rapidement les évolutions qu’API Entreprise obtient de ses fournisseurs.

Toute évolution implique une montée de version

Les montés de version d’une API interviennent pour toute évolution, c’est-à-dire :

  • l’ajout d’un nouveau champ par le fournisseur de la donnée ;

    Par exemple : Ajout du champ “économie sociale et solidaire” lors d’une évolution mineure par l’Insee.

  • la transformation de la structure de l’API par le fournisseur de la donnée ;

    Par exemple : Sortie d’une évolution majeure chez le fournisseur donnée.

  • l’ajout d’une fonctionnalité par API Entreprise

    Par exemple : Délivrance d’un nouveau champ “Certification valide” pour une API qui ne renvoyait avant que l’URL de téléchargement de l’attestation.

Pour comprendre comment monter en version, consultez la rubrique suivante.

Les anciennes versions maintenues tant que le fournisseur de la donnée le permet

Depuis la V.3 de l’API Entreprise, les anciennes versions sont maintenues par le service API Entreprise tant que cela est possible.
En pratique, cela signifie que :

  • tant que le fournisseur continue d’envoyer la strcuture de données de l’ancienne version, cette ancienne version est maintenue par l’API Entreprise ;
  • si le fournisseur ne renvoie plus la même structure de donnée, API Entreprise supprimera l’ancienne version car la maintenir reviendrait à renvoyer des champs vides.

Changer de version

Depuis la version 3 de l’API Entreprise, toutes les API peuvent évoluer indépendamment les unes des autres. Les anciennes versions (à partir de la V.3) restent donc toujours disponibles si le fournisseur de la donnée continue de transmettre les informations.
Depuis la version 3, le numéro de version est un paramètre de l’appel et non plus une valeur fixe pour toutes les API comme en version 1 et 2 (Les versions 1 et 2 sont définitivement dépréciées, la version 1 étant déjà fermée et la version 2 fermant le 30 juin 2023).

Exemple d’utilisation du paramètre d’appel de version :
Imaginons un exemple fictif : l’API documents, cette API est disponible en v.3 et une nouvelle version est sortie, la V.4.
Pour appeler la version souhaitée, il vous faudra directement inscrire le numéro de la version dans l’URL : https://entreprise.api.gouv.fr/v3/... pour la V.3 ou https://entreprise.api.gouv.fr/v4/... pour la V.4.

📩 Une lettre d’information annonce systématiquement les nouvelles évolutions. Vous pouvez vous abonner ici.

Monitorer la disponibilité des API

Pour vous informer de la disponibilité de nos API :

  • vous pouvez retrouver tous les incidents et opérations de maintenance directement depuis notre page de statut, cette page est complétée manuellement par nos services ;
  • vous pourrez bientôt utiliser nos API de monitoring (⚙️ développements en cours).

Retrouver les droits d'un jeton JWT

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 utilisateurs, 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 JSON :

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

La réponse JSON renvoie la liste des API autorisées. Retrouvez-leurs spécifications techniques dans le Swagger.

Kit de mise en production 🚀

Tester l'API en préproduction

L’API Entreprise est testable avec un jeton accessible à tous depuis notre environnement de staging. Ce bac à sable retourne des données fictives.

Pour utiliser l’environnement de test, plusieurs moyens sont possibles :

  • Utilisez l’interface disponible depuis API.gouv :
    1. Copiez le jeton de test disponible dans les premiers paragraphes de la page.
    2. Sélectionnez “https://staging.entreprise.api.gouv.fr - Environnement de staging” dans le menu déroulant situé un peu plus bas du jeton de test, à gauche.
    3. Cliquez sur le bouton à droite “Authorize”, et entrez le jeton de test dans le champ “Value” de la modale qui s’est ouverte ; validez en cliquant sur “Authorize”. L’environnement de test est configuré, fermez la modale.
    4. Pour terminer, pour chacune des API, un bouton “Try it out” vous permet de préremplir les paramètres d’appel avec différents exemples. Appuyez sur “Execute” pour obtenir les différentes réponses possibles.
  • Utilisez un logiciel de type Postman à partir du fichier OpenAPI :
    1. Téléchargez le fichier OpenAPI de l’API Entreprise depuis la page de swagger, avec le bouton “Download” situé en début de page.
    2. Importer ce fichier dans un logiciel de test de type Postman.
    3. Configurez votre environnement avec l’url de l’environnement de staging https://staging.entreprise.api.gouv.fr.
      API Entreprise ne recommande pas un logiciel plus qu’un autre, de nombreux tutoriels sont disponibles sur internet.
  • Interrogez le staging depuis votre terminal avec une ligne de commande :
    1. Rendez-vous sur la documentation swagger du site API Entreprise, copiez le jeton de staging disponible en début de page.
    2. Dans la partie “Request samples” disponible pour chaque API dans le swagger, recopiez les lignes de commandes proposées débutant par curl -X GET en remplaçant $token par le jeton de test et en veillant à ajouter staging au début de l’URL : https://staging.entreprise.api.gouv.fr/v3/...
    3. Lancez cette ligne de commande dans votre terminal.

Récupérer le jeton JWT 🔑

Seule la personne ayant fait la demande d’habilitation a accès au token, au travers du compte utilisateur API Entreprise.

  • Si vous avez réalisé la demande d’habilitation, vous pouvez récupérer vos tokens ou jetons d’accès directement depuis votre compte.

  • Si vous n’avez pas réalisé la demande d’habilitation mais que vous êtes la personne en charge d’intégrer l’API Entreprise, la personne ayant effectué la demande d’habilitation peut vous transmettre le token de façon sécurisée depuis son compte, en cliquant sur le bouton “Transmettre le jeton à mon équipe technique”. Vous recevrez alors, par e-mail, un lien d’une durée de 4 heures vous donnant accès au jeton.

⚠️ L’utilisation de cette fonctionnalité du compte utilisateur doit avoir pour unique objectif la transmission sécurisée de la clé aux services techniques qui intégreront l’API Entreprise. Le jeton JWT ne doit jamais être transmis par e-mail.

Faire sa première requête

Utiliser l’environnement de production - Swagger

Après avoir récupéré votre jeton, vous pouvez faire un premier appel de test.

Utilisez l’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.

⚠️ Attention, pour rappel, vous ne devez jamais copier-coller un token dans la barre de recherche classique d’un moteur de recherche ou dans un e-mail. Pour récupérer votre jeton de façon sécurisée, consultez cette rubrique.

Éléments constitutifs de la requête HTTP d’API Entreprise

Chaque URL de requête est spécifiée dans le Swagger,

Exemple de requête :
https://entreprise.api.gouv.fr/v3/attestation_fiscales_dgfip/SirenDeL’Entreprise?token=📝&user_id=📝&context=📝&recipient=📝&object=📝
Éléments composant la requête État Exemples
Domaine
(ou préfixe)
qui conduit à l’API de façon sécurisée
prédéfini par endpoint https://entreprise.api.gouv.fr
Numéro de la version
(par défaut désormais en V3)
prédéfini par endpoint /v3
Nom de la donnée recherchée
(ou endpoint)
prédéfini par endpoint /attestation_fiscale_dgfip
Identité de l’établissement concerné
(souvent SIREN ou SIRET)
à choisir 📝 /SIRENouSIRETdeL'Etablissement
Votre jeton d’accès à renseigner 📝 ?token=JetonD'Habilitation
Des paramètres de traçabilité à renseigner 📝 &context=CadreDeLaRequête
ℹ️ Plus d’informations disponibles dans la partie Instruire les paramètres de traçabilité

Constatez votre première trace d’appel depuis le compte utilisateur

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

Configurer le logiciel métier

Documentation en construction 🚧

Incidents et maintenances 🚧

Que faire en cas de rupture de service ?

Le service ne répond plus ? consultez cette rubrique de notre FAQ.

Être informé des ruptures de service

Pour être informé des différentes indisponibilités, abonnez-vous aux notifications par e-mail depuis notre page de statut.

Renouvellement du JWT 🔑

Pour comprendre comment renouveler votre jeton, consultez cette rubrique de notre FAQ.