Introduction

Ce guide liste les changements effectués entre la version 2 de l’API Entreprise et la version 3, et vous livre les éléments nécessaires pour effectuer la migration.

Les évolutions présentées ici ont été guidées par trois objectifs : 

  • assurer une meilleure sécurité de la donnée des fournisseurs ;
  • normaliser les formats pour faciliter la compréhension et l’industrialisation ;
  • clarifier, documenter les réponses et les rendre actionnables par vos logiciels.

Votre jeton d’accès reste identique 🔑
Pour accéder à la version 3 de l’API Entreprise, utilisez le même token qu’en V.2. En effet, tant que votre jeton est valide, il est inutile de refaire une demande d’accès car la migration vers la V.3 ne change pas les droits que vous avez déjà obtenu.

Évolutions générales

1. Jeton d'accès à paramétrer dans le header

🚀 Avec la V.3 : Le jeton est à paramétrer uniquement dans le header de l’appel.

Avant : Le jeton JWT pouvait être un paramètre de l’URL d’appel (query parameter).

🤔 Pourquoi ?

  • Respecter les standards de sécurité ;
  • Garantir que le token ne sera pas utilisé dans un navigateur.

🧰 Comment ?
Utilisez un client REST API pour tester les API pendant le développement.
Des clients sont disponibles gratuitement. API Entreprise utilise pour ses propres tests le client Insomnia. Le plus connu sur le marché est Postman.
Une fois le client installé, vous pouvez directement intégrer notre fichier Swagger/OpenAPI dedans.

2. Votre numéro de SIRET obligatoire dans le "recipient"

🚀 Avec la V.3 : Le paramètre obligatoire recipient de l’URL d’appel devra obligatoirement être complété par votre numéro de SIRET.

Avant : Ce paramètre obligatoire n’était pas contraint en termes de syntaxe.

🤔 Pourquoi ?

  • Pour garantir la traçabilité de l’appel jusqu’au bénéficiaire ayant obtenu l’habilitation à appeler l’API Entreprise et respecter nos engagements auprès des fournisseurs de données ;
  • Nous avions trop d’utilisateurs inscrivant le numéro de SIRET ou RNA de l’entreprise/association recherchée.

⚠️ Cas particulier, vous êtes un éditeur ?
Ce n’est pas votre numéro de SIRET mais celui de votre client public qu’il s’agira de renseigner. API Entreprise doit pouvoir tracer pour quelle entité publique l’appel a été passé.

3. Codes erreurs spécifiques à chaque situation, actionnables et documentés

🚀 Avec la V.3 : 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 de relancer un appel après le nombre de secondes indiquées.

Exemple de payload d’un code HTTP 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
      }
    }
  ]
}

Avant : Seul le code HTTP standard vous était fourni. Il pouvait correspondre à de nombreuses situations.

Exemple de payload d’un code HTTP 502 :
{
  "errors": [
    "L'ACOSS ne peut répondre à votre requête, réessayez ultérieurement  (erreur: Analyse de la situation du compte en cours)"
  ]
}

🤔 Pourquoi ?

  • Pour préciser la nature de l’erreur et vous aider à la comprendre ;
  • Pour vous permettre d’actionner automatiquement l’erreur en utilisant le code.

🧰 Comment ?
Utiliser les libellés pour comprendre l’erreur rencontrée, voire automatiser votre logiciel en fonction du code.
La liste de tous les codes erreurs spécifiques (environ 80) est disponible dans le Swagger. La gestion des erreurs et l’explication des codes retours est détaillée dans la documentation technique générale.

4. Volumétrie indiquée dans le header et actionnable

La gestion de la volumétrie est maintenue identique à la dernière évolution de la V.2 et expliquée dans cette documentation

5. Gestion des évolutions futures

🚀 Avec la V.3 : Toutes les API pourront évoluer indépendamment les unes des autres. Les anciennes versions resteront toujours disponibles. Le numéro de version devient donc un paramètre de l’appel et non plus une valeur fixe pour toutes les API.
📩 Une infolettre annoncera systématiquement les nouvelles évolutions.

Avant : L’évolution d’un endpoint exigeait la montée en version de toute l’API.

🤔 Pourquoi ?

  • Permettre l’ajout de nouvelles informations sans forcer les fournisseurs de service à monter de version ;
  • Continuer de garantir la continuité des API dans le temps.

🧰 Comment ?
Renseigner directement le numéro de la version voulue dans l’URL, au même endroit qu’avant, par exemple :

https://entreprise.api.gouv.fr/v3/insee/sirene/etablissements/:siret

6. Un seul fournisseur et un seul type de données par API

🚀 Avec la V.3 : Chaque API appelle un seul et unique fournisseur de données.

Il n’existe plus d’API à contenu multiple, comme celle de l’INSEE/Infogreffe, les informations des différents fournisseurs ont été séparées.

Avant : Certaines API appelaient deux fournisseurs à la fois. Certaines API regroupaient de très nombreuses informations différentes.

🤔 Pourquoi ?

  • Faciliter la compréhension métier des données transmises ;
  • Réduire le nombre d’erreurs car le périmètre de la donnée disponible est plus explicite ;
  • Accélérer le temps de réponse des API, car il y a moins d’appels externes ;

🧰 Comment ?
Utiliser la table de correspondance pour identifier les API en version 3, qui correspondent à celle en version 2 :

Table de correspondance
des API v.2 > v.3

7. Les payloads normalisées et enrichies

🚀 Avec la V.3 : La payload de réponse est normalisée est composée systématiquement de 3 clés :

  • data, qui regroupe l’ensemble des données de la ou les ressources (si c’est une ressource seule, la données est un objet json, si c’est une collection, la données est un tableau json) ;
  • links, qui donne des liens vers d’autres endpoints relatifs à cette ressource, liens qui peuvent être utilisés par vos logiciels pour relancer un appel ;
  • meta, qui regroupe des metadonnées liées à API Entreprise ou au fournisseur de données.
Architecture de la payload V.3 :
{
  "data" : { … },
  "links" :  { … },
  "meta" : { … }
}

Avant : La structure de la payload n’était pas normalisée ni conventionnée ; elle ne contenait aucune information explicitant la nature de la réponse. Les liens permettant d’appeler une autre API n’étaient pas disponibles.

Architecture de la payload V.2 :
{
  LES DONNÉES,
}

🤔 Pourquoi ?

  • Uniformiser toutes les payloads de réponses ;
  • Permettre la connexion entre les API grâce à l’ajout des liens URL.

Table de correspondance V.2 > V.3

Cette partie du guide de migration permet de trouver la correspondance de chaque API de la V.2 avec les API de la V3 : 

Sommaire des tables de correspondance des API V.2 :

V.2 - Données de référence d'une entité - INSEE

L’API V.2 /entreprise de l’INSEE a été découpée en plusieurs API différentes dans la V.3 :

  • les données de référence de l’unité légale tirées de l’Insee ;
  • les données sur le siège social de l’unité légale sont séparées ;
  • les mandataires socaux tirés d’Infogreffe font aussi l’objet d’une autre API.

La distinction entre les “diffusibles” et les “non-diffusibles” n’est plus faite par une option d’appel. Nous avons créé des API distinctes :

API V.2 API V.3 correspondantes
API Données de référence d’une entité - INSEE
Sans
l’option d’appel des “non-diffusibles”
 
Données concernant les unités légales “diffusibles”. API Données unité légale diffusible
v3/insee/sirene/unites_legales/diffusibles/{siren}
📖 Fiche métier
📟 Swagger

Ces informations sont aussi disponibles depuis : < br/> API Données établissement diffusible
v3/insee/sirene/etablissements/diffusibles/{siret}
📖 Fiche métier
📟 Swagger

🎁 Nouvelle donnée disponible : Sexe des personnes physiques.
Données concernant les mandataires sociaux de l’entreprise. API Mandataires sociaux
v3/infogreffe/mandataires_sociaux/{siren}
📖 Fiche métier
📟 Swagger

🎁 Nouvelle donnée disponible : Lieu de naissance des mandataires sociaux.
Données concernant le siège social d’une unité légale “diffusible”. API Données siège social diffusible
v3/insee/sirene/unites_legales/diffusibles/{siren}/siege
📖 Fiche métier
📟 Swagger
Adresse du siège social d´une unité légale “diffusible” API Adresse établissement diffusible
v3/insee/sirene/etablissements/diffusibles/{siret}/adresse
📖 Fiche métier
📟 Swagger
Numéro de TVA intracommunautaire API N°TVA intracommunautaire français
v3/european_commission/unites_legales/{siren}/numero_tva
📖 Fiche métier
📟 Swagger
API Données de référence d’une entité - INSEE
Avec
l’option d’appel des “non-diffusibles”
 
Données concernant toutes les unités légales, y compris les “non-diffusibles”. API Données unité légale
v3/insee/sirene/unites_legales/{siren}
📖 Fiche métier
📟 Swagger

Ces informations sont aussi disponibles depuis l’API Données établissement
v3/insee/sirene/etablissements/{siret}
📖 Fiche métier
📟 Swagger

🎁 Nouvelle donnée disponible : Sexe des personnes physiques.
Données concernant les mandataires sociaux de l’entreprise. API Mandataires sociaux
v3/infogreffe/mandataires_sociaux/{siren}
📖 Fiche métier
📟 Swagger

🎁 Nouvelle donnée disponible : Lieu de naissance des mandataires sociaux.
Données concernant le siège social d’une unité légale, qu’elle soit “diffusible” ou non. API Données siège social
v3/insee/sirene/unites_legales/{siren}/siege
📖 Fiche métier
📟 Swagger
Adresse du siège social d´une unité légale, qu´elle soit “diffusible” ou non. API Adresse établissement
v3/insee/sirene/etablissements/{siret}/adresse
📖 Fiche métier
📟 Swagger
Numéro de TVA intracommunautaire API N°TVA intracommunautaire français
v3/european_commission/unites_legales/{siren}/numero_tva
📖 Fiche métier
📟 Swagger

Le champ booléen dirigeant des mandataires sociaux retiré en V.3 car non-effectif
En V.2, parmi les informations relatives aux mandataires sociaux, API Entreprise semblait transmettre une information sur le statut dirigeant ou non du mandataire social. Cette information n’était pas effective car toujours à true. Nous avons donc retiré ce champ inutile de l’API V.3 Mandataires sociaux.
Pour connaître les rôles des mandataires sociaux, vous pouvez vous aider du champ fonction qui renvoie des valeurs telles que “PRESIDENT”, “DIRECTEUR GENERALE”.

V.2 - Données de référence d'un établissement - INSEE

L’API V.2 /etablissement de l’INSEE devient l’API centrale des données Insee en V.3. À partir du SIRET de l’établissement, vous récupérez les données de l’établissement, dont son adresse postale, ainsi que les données de l’unité légale qui le concerne.

La distinction entre les “diffusibles” et les “non-diffusibles” n’est plus faite par une option d’appel. Nous avons créé des API distinctes :

API V.2 API V.3 correspondantes
API Données de référence d’un établissement - INSEE  
Sans l’option d’appel des “non-diffusibles” API Données établissement diffusible
v3/insee/sirene/etablissements/diffusibles/{siret}
📖 Fiche métier
📟 Swagger

🧩 Cette API délivre en plus des informations sur l’unité légale de l’établissement.
Avec l’option d’appel des “non-diffusibles” API Données établissement
v3/insee/sirene/etablissements/{siret}
📖 Fiche métier
📟 Swagger

🧩 Cette API délivre en plus des informations sur l’unité légale de l’établissement.

V.2 - Extrait RCS - Infogreffe

API V.2 API V.3 correspondante
API Extrait RCS - Infogreffe API Extrait RCS
/v3/infogreffe/rcs/unites_legales/{siren}/extrait_kbis
📖 Fiche métier
📟 Swagger

V.2 - Informations déclaratives d'une association - Ministère de l'Intérieur

API V.2 API V.3 correspondante
API Informations déclaratives d’une association - Ministère de l’Intérieur API Données du RNA d’une association
/v3/ministere_interieur/rna/associations/{siret_or_rna}
📖 Fiche métier
📟 Swagger

V.2 - Divers documents d'une association - Ministère de l'Intérieur

API V.2 API V.3 correspondante
API Divers documents d’une association - Ministère de l’Intérieur API Divers documents d’une association
/v3/ministere_interieur/rna/associations/{siret_or_rna}/documents
📖 Fiche métier
📟 Swagger

V.2 - Actes - INPI

API V.2 API V.3 correspondante
API Actes - INPI API Actes
/v3/inpi/unites_legales/{siren}/actes
📖 Fiche métier
📟 Swagger

V.2 - Conventions collectives - Fabrique numérique des Ministères sociaux

API V.2 API V.3 correspondante
API Conventions collectives - Fabrique numérique des Ministères sociaux API Conventions collectives
/v3/fabrique_numerique_ministeres_sociaux/etablissements/{siret}/conventions_collectives
📖 Fiche métier
📟 Swagger

V.2 - Données de référence d'une entreprise artisanale - CMA France

API V.2 API V.3 correspondante
API Données de référence d’une entreprise artisanale - CMA France API Données du RNM d’une entreprise artisanale
/v3/cma_france/rnm/unites_legales/{siren}
📖 Fiche métier
📟 Swagger

V.2 - Effectifs d'une entreprise - URSSAF

API V.2 API V.3 correspondante
API Effectifs d’une entreprise - URSSAF API Effectifs
📖 Fiche métier
⚙️ Swagger prochainement disponible

V.2 - Immatriculations EORI - Douanes

API V.2 API V.3 correspondante
API Immatriculations EORI - Douanes API Immatriculations EORI
/v3/douanes/etablissements/{siret_or_eori}/immatriculations_eori
📖 Fiche métier
📟 Swagger

V.2 - Chiffre d'affaires - DGFIP

API V.2 API V.3 correspondante
API Chiffre d’affaires - DGFIP API Chiffre d’affaires
v3/dgfip/etablissements/{siret}/chiffres_affaires
📖 Fiche métier
📟 Swagger

V.2 - Bilans annuels - INPI

API V.2 API V.3 correspondante
API Bilans annuels - INPI API Comptes annuels du RNCS

📖 Fiche métier
⚙️ Swagger prochainement disponible

V.2 - 3 derniers bilans annuels - Banque de France

API V.2 API V.3 correspondante
API 3 derniers bilans annuels - Banque de France API Trois derniers bilans annuels

📖 Fiche métier
⚙️ Swagger prochainement disponible

V.2 - Déclarations de résultats - DGFIP

API V.2 API V.3 correspondante
API Déclarations de résulats - DGFIP API Liasses fiscales
v3/dgfip/unites_legales/{siren}/liasses_fiscales/{year}
📖 Fiche métier
📟 Swagger

V.2 - Attestation fiscale - DGFIP

API V.2 API V.3 correspondante
API Attestation fiscale - DGFIP API Attestation fiscale - DGFIP
v3/dgfip/unites_legales/{siren}/attestation_fiscale
📖 Fiche métier
📟 Swagger

V.2 - Attestation de vigilance - ACOSS

API V.2 API V.3 correspondante
API Attestation de vigilance - ACOSS API Attestation de vigilance - URSSAF Caisse nationale
v3/urssaf/unites_legales/{siren}/attestation_vigilance
📖 Fiche métier
📟 Swagger

V.2 - Conformité emploi des travailleurs handicapés - Agefiph

API V.2 API V.3 correspondante
API Conformité emploi des travailleurs handicapés - Agefiph ❌ Ressource supprimée en V3 - Depuis 2021, la contribution annuelle de l’OETH (Obligation d’Emploi de Travailleur Handicapé) relève de l’URSSAF et non plus de l’Agefiph.

La conformité à l’OETH est donc désormais incluse dans l’API attestation de vigileance - URSSAF ou dans l’API conformité cotisations de sécurité sociale agricole - MSA pour les entreprises relevant du régime agricole.

V.2 - Cotisations de sécurité agricole - MSA

API V.2 API V.3 correspondante
API Cotisations de sécurité agricole - MSA API Conformité cotisations de sécurité sociale agricole
v3/msa/etablissements/{siret}/conformite_cotisations
📖 Fiche métier
📟 Swagger

V.2 - Cotisations retraite bâtiment - PROBTP

API V.2 API V.3 correspondante
API Cotisations retraite bâtiment - PROBTP API Conformité cotisations retraite bâtiment

📖 Fiche métier
⚙️ Swagger prochainement disponible

🚀 En V.3, plus besoin de faire deux appels différents. Avec un seul appel, vous obtenez l’état de conformité et l’URL de téléchargement de l’attestation si elle est disponible.

V.2 - Carte professionnelle travaux publics - FNTP

API V.2 API V.3 correspondante
API Carte professionnelle travaux publics - FNTP API Carte professionnelle travaux publics
v3/fntp/unites_legales/{siren}/carte_professionnelle_travaux_publics
📖 Fiche métier
📟 Swagger

V.2 - Cotisations congés payés & chômage intempéries - CNETP

API V.2 API V.3 correspondante
API Cotisations congés payés & chômage intempéries - CNETP API Attestation de cotisations congés payés & chômage-intempéries
v3/cnetp/unites_legales/{siren}/attestation_cotisations_conges_payes_chomage_intemperies
📖 Fiche métier
📟 Swagger

V.2 - Certification en BIO - Agence BIO

API V.2 API V.3 correspondante
API Certification en BIO - Agence BIO API Certifications en BIO

📖 Fiche métier
⚙️ Swagger prochainement disponible

V.2 - Certification RGE - ADEME

API V.2 API V.3 correspondante
API Certification RGE - ADEME API Certificat RGE
v3/ademe/etablissements/{siret}/certification_rge
📖 Fiche métier
📟 Swagger

V.2 - Certification de qualification du bâtiment - Qualibat

API V.2 API V.3 correspondante
API Certification de qualification du bâtiment - Qualibat API Certification Qualibat
v3/qualibat/etablissements/{siret}/certification_batiment
📖 Fiche métier
📟 Swagger

V.2 - Certification de qualification d'ingénierie - OPQIBI

API V.2 API V.3 correspondante
API Certification de qualification d’ingénierie - OPQIBI API Certification d’ingénierie OPQIBI

📖 Fiche métier
⚙️ Swagger prochainement disponible

V.2 - Brevets, modèles et marques déposés - INPI

API V.2 API V.3 correspondantes
API Brevets, modèles et marques déposés - INPI  
Données des brevets API Brevets déposés
v3/inpi/unites_legales/{siren}/brevets
📖 Fiche métier
📟 Swagger
Données des dessins & modèles API Modèles déposés
v3/inpi/unites_legales/{siren}/modeles
📖 Fiche métier
📟 Swagger
Données des marques API Marques déposées
v3/inpi/unites_legales/{siren}/marques
📖 Fiche métier
📟 Swagger