Guide de migration 📋

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.

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

🚀 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é.

Pour en savoir plus sur les paramètres obligatoires d’appel, consultez les spécifications techniques.

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

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

🚀 Avec la V.3 : Toutes les API pourront évoluer indépendamment les unes des autres. Les anciennes versions resteront disponibles si le fournisseur de la donnée continue de nous transmettre les informations. 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

🚀 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

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

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
• “V.2 - Données de référence d’un établissement” - INSEE
• “V.2 - Extrait RCS” - Infogreffe
• “V.2 - Informations déclaratives d’une association” - Ministère de l’Intérieur
• “V.2 - Divers documents d’une association” - Ministère de l’Intérieur
• “V.2 - Actes” - INPI
• “V.2 - Conventions collectives” - Fabrique numérique des Ministères sociaux
• “V.2 - Données de référence d’une entreprise artisanale” - CMA France
• “V.2 - Effectifs d’une entreprise” - URSSAF
• “V.2 - Immatriculation EORI” - Douanes
• “V.2 - Chiffre d’affaires” - DGFIP
• “V.2 - Bilans annuels”- INPI
• “V.2 - 3 derniers bilans annuels” - Banque de France
• “V.2 - Déclarations de résultats” - DGFIP
• “V.2 - Attestation fiscale” - DGFIP
• “V.2 - Attestation de vigilance” - ACOSS
• “V.2 - Conformité emploi des travailleurs handicapés” - Agefiph
• “V.2 - Cotisations de sécurité agricole” - MSA
• “V.2 - Cotisations retraite bâtiment” - PROBTP
• “V.2 - Carte professionelle travaux publics” - FNTP
• “V.2 - Cotisations congés payés & chômage intempéries” - CNETP
• “V.2 - Certification en BIO” - Agence BIO
• “V.2 - Certification RGE” - ADEME
• “V.2 - Certification de qualification du bâtiment” - Qualibat
• “V.2 - Certification de qualification d’ingénierie” - OPQIBI
• “V.2 - Brevets, modèle et marques déposés” - INPI

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 :

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

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 :

La migration V.3 introduit de nouvelles données sur les associations. Par conséquent, en migrant, vous trouverez deux nouvelles API :

• Une API en open data, délivrant le même type d’informations que celles données par l’API V.2 données RNA d’une association et l’API V.2 Divers documents d’une associations.
• 🎁 Une API délivrant de nouvelles données : des informations protégées uniquement accessibles aux agents publics habilités. Il vous faudra effectuer une demande d’habilitation pour accéder à cette API. Pour élargir votre périmètre des API accessibles, consulter cette rubrique de la FAQ.

La migration V.3 introduit de nouvelles données sur les associations. Par conséquent, en migrant, vous trouverez deux nouvelles API :

• Une API en open data, délivrant le même type d’informations que celles données par l’API V.2 données RNA d’une association et l’API V.2 Divers documents d’une associations.
• 🎁 Une API délivrant de nouvelles données : des informations protégées uniquement accessibles aux agents publics habilités. Il vous faudra effectuer une demande d’habilitation pour accéder à cette API. Pour élargir votre périmètre des API accessibles, consulter cette rubrique de la FAQ.