Introduce Données de référence entreprise artisanale, api RNM CMA

skelz0r commented 3 years ago

Que fait cette PR ?

Ajout de la documentation pour l'API RNM / CMA

Pourquoi fait-on ça ? Contexte, PR, issue liée ?

https://3.basecamp.com/4318089/projects/18987221

Par où commencer la review ?

Il n'y a qu'un fichier, c'est l'ajout de la fiche pour l'API.

Je mentionne le Swagger dans la documentation, mais celle-ci n'est pas encore en production. Celui-ci explique pour chaque clé à quoi elle sert, ces valeurs possibles etc etc..

J'ai fait une copie à l'adresse suivante: https://gist.github.com/skelz0r/a0807f6ed568f0c361c399b470c7b914

Pour voir le swagger, rien de plus simple.

Prendre l'url "raw" du lien ci-dessus : https://gist.githubusercontent.com/skelz0r/a0807f6ed568f0c361c399b470c7b914/raw/b7e385bdbda89fa0fadfc4262897e7fc2b32d9be/open-api.yml
Aller sur https://editor.swagger.io/
Cliquer sur File -> Import URL et copier le lien ci-dessus

De là, vous pouvez naviguer jusqu'au endpoint entreprises_artisanales, cliquer dessus, scroller jusqu'aux réponses, cliquer sur le mot clé "Schema" à coté de "Example Value" afin d'avoir le détail complet de chaque clé.

Exemple ci-dessous:

brindu commented 3 years ago

RAS

DorineLam commented 3 years ago

@skelz0r j'ai fait une première restructuration de la réponse JSON et repris la description. Je dois encore commenter les champs, et créer les blocs questions/réponses.

J'ai besoin de ton aide concernant l'apparition du logo fournisseur. Il me semble avoir fait ce qu'il fallait mais pour l'instant, en local, l'image n'apparaît pas.

skelz0r commented 3 years ago

J'ai besoin de ton aide concernant l'apparition du logo fournisseur. Il me semble avoir fait ce qu'il fallait mais pour l'instant, en local, l'image n'apparaît pas.

C'est fixé (c'est pas très robuste, faut que le nom du fichier ET le nom du label match le nom du logo => cma.png (et d'ailleurs ça ne marche que avec les png))

skelz0r commented 3 years ago

j'ai fait une première restructuration de la réponse JSON et repris la description. Je dois encore commenter les champs, et créer les blocs questions/réponses.

Pour info il y a déjà un bloc Q&A

DorineLam commented 3 years ago

@skelz0r oui mais c'est le bon ;)

DorineLam commented 3 years ago

@skelz0r

Ça y est, je pense que j'ai fait le max du possible avec la matière que nous avions. Reste en suspend quelques questions que je vais transmettre au fournisseur et que je mets en note ici :

Clé non_sedentaire : Activité ambulante => quelles sont les variables et leur signification ? Seul 0 est indiqué.
Clé denomination_sociale => s’agit-il de la dénomination et de la raison sociale confondue ? Qu’en est-il pour les entreprises individuelles qui n’en ont pas ? Pourquoi l'exemple donné est donc un nom de famille ? Au final est ce que le nom de la clé n'est pas erroné ? => Sur service-public.fr, la dénomination sociale "ne concerne que les sociétés (SARL, EURL, SA, SAS, SNC, etc.) et ne s'applique pas aux entreprises individuelles (EI, EIRL)."
Clés adresse => de quel type de format s'agit-il ? Nous n'avons pas de documentation et de fait, on s'appuie sur la doc de l'INSEE qui n'a peut-être rien à voir ...
Clé adresse_type_voie => Donner d'autres exemples que celui de RUE, qui plus est, qui est un mauvais exemple car il fait croire que nous donnons un intitulé, or il s'agit probablement d'un code comme dans la doc INSEE.
Clés effectif_salarie et effectif_apprenti => A-t'on plus d'informations à ce sujet ? Quel types d'effectifs sont pris en compte ?
Clé declaration_procedures => il y a pas mal d'informations dans la doc, mais aucun exemple qui permet à l'utilisateur de bien comprendre ce qu'on reçoit de ces déclarations ? Les observations sont elles écrites ? Y-at'il des identifiants ? des URLs ?

DorineLam commented 3 years ago

De fait, mis à part s'il est impossible de changer la clé denomination_sociale (cf mon commentaire précédent) après mise en prod, on peut merger.

skelz0r commented 3 years ago

Aucun souci pour changer le nom d'une clé.

Quelques remarques:

non_sedentaire j'ai en effet pas trouvé d'exemples en cherchant
denomination_sociale je lis sur https://www.economie.gouv.fr/entreprises/changer-nom-denomination-sociale-entreprise#:~:text=Dans%20le%20cadre%20de%20la,s'accompagner%20de%20votre%20pr%C3%A9nom. : Dans le cadre de la création d'une entreprise individuelle (EI) et de ses formes dérivées (entreprise individuelle à responsabilité limitée (EIRL) ou micro-entreprise), la dénomination sociale se confond avec la raison sociale et correspond obligatoirement à votre nom de famille, qui peut s'accompagner de votre prénom.. Du coup pour moi notre définition est juste.
je ne suis pas sûr de comprendre ta remarque sur les clés adresse_*, je pense pas que ça soit spécifiquement normalisé (comme tous les autres FDs qui sont yolo)
adresse_type_voie ça suit la nomenclature en lien de la description de la clé ici: https://www.sirene.fr/sirene/public/variable/typvoie j'ai flemmé de mettre la liste exhaustive dans le swagger (y'a une jolie todo) je peux le faire comme ça cela sera exhaustif.
Pour les effectifs c'est pareil, je ne suis pas sûr de comprendre ta question. A la limite demande leur si ils utilisent les définition officielles de l'insee à savoir https://www.insee.fr/fr/metadonnees/definition/c1965 et https://www.insee.fr/fr/metadonnees/definition/c1767#:~:text=Un%20apprenti%20est%20un%20jeune,et%20des%20enseignements%20dispens%C3%A9s%20dans afin qu'on le link dans la doc (mais pour moi ça me semble assez logique)
declaration_procedures clairement oui on veut des exemples (même si je pense que ça sera une valeur immonde et pas réellement actionnable).

DorineLam commented 3 years ago

* `non_sedentaire` j'ai en effet pas trouvé d'exemples en cherchant

=> Je fais la demande au fournisseur

* `denomination_sociale` je lis sur https://www.economie.gouv.fr/entreprises/changer-nom-denomination-sociale-entreprise#:~:text=Dans%20le%20cadre%20de%20la,s'accompagner%20de%20votre%20pr%C3%A9nom. : `Dans le cadre de la création d'une entreprise individuelle (EI) et de ses formes dérivées (entreprise individuelle à responsabilité limitée (EIRL) ou micro-entreprise), la dénomination sociale se confond avec la raison sociale et correspond obligatoirement à votre nom de famille, qui peut s'accompagner de votre prénom.`. Du coup pour moi notre définition est juste.

=> Ok, du coup je vais reprendre la formulation donnée par economie.gouv. parce qu'elle éclaircit bien le sujet et ça nous évite de changer la clé.

* je ne suis pas sûr de comprendre ta remarque sur les clés `adresse_*`, je pense pas que ça soit spécifiquement normalisé (comme tous les autres FDs qui sont yolo)

=> Dans l'endpoint entreprisesont parle d'un format : "Depuis 2018, l’INSEE ne fournit plus d’adresse au format RNVP, API Entreprise opère donc une reconstruction de l’adresse à partir des champs disponibles dans leur nouvelle API. Cette reconstruction n’est en aucun cas un traitement RNVP." => Je me demandais si le format qu'ils utilisent à un nom et quel lien ou non il avec le format d'adresse RNVP. @brindu est-ce que tu en sais plus ? Ou est-ce que pareil ma question n'a pas de sens. ^^

* `adresse_type_voie` ça suit la nomenclature en lien de la description de la clé ici: https://www.sirene.fr/sirene/public/variable/typvoie j'ai flemmé de mettre la liste exhaustive dans le swagger (y'a une jolie todo) je peux le faire comme ça cela sera exhaustif.

=> Super si tu mets effectivement ça dans le swagger. Et du coup on pourrait presque faire pareil avec les paramètres des codes NAR 4 et 20. Je t'épargne le NAFA.

=> De mes premières recherches : NAR 4 : 4 catégories : ALIMENTATION BATIMENT PRODUCTION SERVICES

NAR 20 : 20 catégories : MATERIAUX DE CONSTRUCTION CERAMIQUE VIANDES ET POISSONS ALIMENTATION (AUTRE QUE VIANDES ET P (à compléter/vérifier) TEXTILE ET HABILLEMENT CUIR ET CHAUSSURES PAPIER IMPRIMERIE REPRODUCTION AR (à compléter/vérifier) FABRICATION D'ARTICLES DIVERS TRAVAIL DES MÉTAUX BOIS ET AMEUBLEMENT REPARATION AUTRES SERVICES MAÇONNERIE TERRASSEMENT, TRAVAUX DIVERS INSTALLATION DELECTRICITE COUVERTURE PLOMBERIE CHAUFFAGE AMENAGEMENT FINITIONS MENUISERIE SERRURERIE TRANSPORT BLANCHISSERIE TEINTURERIE SOINS A LA (à compléter/vérifier) Il manque une catégorie, à recouper une seconde fois ici : https://entreprise.api.gouv.fr/assets/pdf/liste-nar.pdf

* Pour les effectifs c'est pareil, je ne suis pas sûr de comprendre ta question. A la limite demande leur si ils utilisent les définition officielles de l'insee à savoir https://www.insee.fr/fr/metadonnees/definition/c1965 et https://www.insee.fr/fr/metadonnees/definition/c1767#:~:text=Un%20apprenti%20est%20un%20jeune,et%20des%20enseignements%20dispens%C3%A9s%20dans afin qu'on le link dans la doc (mais pour moi ça me semble assez logique)

= > L'objet de ma demande est le fait qu'il y a plein de calcul d'effectifs différents : c'est le même problème que pour l'endpoint ACOSS : Ils donnent un effectif mais en réalité ils ne prennent pas en compte certains contrats (Tu peux regarder la partie périmètre de la doc de l'acoss . J'aimerais donc savoir précisément ce qu'il y a de pris en compte.

* `declaration_procedures` clairement oui on veut des exemples (même si je pense que ça sera une valeur immonde et pas réellement actionnable).

=> Top je vais insister là dessus également

DorineLam commented 3 years ago

@skelz0r La documentation du catalogue de données est OK, prête à la mise en prod !

Côté swagger, il y a pas mal de rectifs à faire pour harmoniser les deux. Je pense qu'il faut qu'on réduise les infos métiers disponibles dans le swagger et qu'on pousse l'utilisateur à aller consulter le catalogue. Ça pose une question d'harmonisation de tous nos contenus.

Est-ce qu'on envoit en prod avec le swagger actuel et on ouvre une autre PR ?

skelz0r commented 3 years ago

On a changé le nom du endpoint en entreprises_artisanales_cma j'ai corrigé du coup.

Par contre ça:

C'est chelou, généralement le commentaire d'explication d'un morceau de code est avant ce morceau de code, et non avant. Je me rends compte que ça a l'air d'être comme ça ailleurs donc bon.. simple remarque.

skelz0r commented 3 years ago

J'ai ajouté la disponibilité. Je merge du coup.

etalab / entreprise.api.gouv.fr