SmartForm - Injection depuis une API

De YoWiki
Révision datée du 6 janvier 2022 à 01:35 par Damien (discussion | contributions) (→‎Endpoints disponibles)
(diff) ← Version précédente | Voir la version actuelle (diff) | Version suivante → (diff)
Sauter à la navigation Sauter à la recherche

Les champs de saisie du SmartForm (text-input, number-input, date-input…) peuvent être utilisé pour requêter certaines données externes (via des API) afin de récupérer des informations complémentaires et de les injecter dans les autres champs de la page.

Ce procédé peut être configuré via les options du champs en question. L'option "API" permet à la fois de personnaliser l'apparence (texte, icône etc.) du bouton d'appel, mais aussi d'indiquer le type de requête (attribut "endpoint"), ou les correspondances entre les variables de l'API et celles de votre formulaire.

Option API et ses attributs

Pour rappel, le champ Options du Fields-Form est au format YAML, c'est à dire sous la forme "attribut: valeur" et avec des indentations (4 espaces) pour identifier une série de sous-attributs.

button-label : cet attribut permet de personnaliser le libellé à l'intérieur du bouton d'appel. Par défaut, le texte est "Rechercher".

button-icon : cet attribut permet de personnaliser l'icône du bouton d'appel. Le contenu de cet attribut sera utilisé comme classes CSS, et il est par conséquent possible d'utiliser les classes d'icônes implémentées par l'application (ex: FontAwesome, Material Icons…). Ex : "fa fa-search" (pour une icône de loupe, par Font Awesome).

tooltip-text : cet attribut permet de personnaliser le contenu textuel de la bulle d'info qui apparait au survol du bouton d'appel.

endpoint : ⚠️ cet attribut est peut être le plus important, ou du moins, c'est celui qui est nécessaire pour indiquer au bouton d'appel ce qu'il doit aller chercher. La liste des endpoints disponibles et leurs caractéristiques sont décrites plus bas.

mapping : cet attribut permet d'indiquer des correspondances entre le nom des variables retourné par défaut par l'API et le nom (arbitraire) que vous souhaitez utiliser pour le pré-remplissage. Par exemple, si une API renvoie par défaut la variable "SIEGE_ADR" avec l'adresse du siège de l'entreprise, mais que votre formulaire utilise la variable "ADRESSE_ENTREPRISE" alors il faut faudra indiquer la correspondance "SIEGE_ADR: ADRESSE_ENTREPRISE", pour que le système sache où injecter l'information. La liste des variables par défaut est indiquée ci-dessous pour chaque end-point. Notez que le mapping est facultatif, et que par défaut, le système utilisera le nom de variable par défaut.

list-endpoint : Cet attribut (facultatif) est utile si la requête doit retourner une "liste" d'éléments et que l'injection des données ne se fera qu'une fois l'utilisateur ayant sélectionné manuellement un élément de cette liste. Similaire à l'attribut "endpoint" cet attribut permet d'indiquer la "source de donnée" impliquée pour obtenir la liste des éléments. Les valeurs possibles sont disponibles ci-dessous.

list-template-vars : Cet attribut est complémentaire de l'attribut précédent (cas où la requête doit retourner une "liste" d'éléments). Il est utile pour indiquer à l'interface dans quel ordre afficher les valeurs de chaque élément de la liste. Il est donc attendu un tableau ordonné de clé. Exemple de valeur attendue : [SIREN, DENOMINATION, SIREN, GEO_NAME, LIBELLE_ACTIVITE] (les crochets sont importants pour indiquer que c'est un tableau ordonné). Le premier élément du tableau correspond à la clé qui devra être utilisée pour contacter le endpoint principal une fois que l'utilisateur a fait son choix dans la liste, il ne sera pas affiché. Les autres éléments permettent d'organiser les valeurs dans l'interface (ce qui est affiché) : la 2ème clé fournie, correspond au titre de l'élément dans la liste, la 3ème à une information complémentaire du titre, la 4ème au sous-titre, et la 5ème à un texte secondaire (affiché en italique).


Endpoints disponibles

  • '"/pappers/siren"' : ce endpoint permet de récupérer les informations d'une entreprise depuis le service [Pappers.fr] à partir d'un numéro SIREN fournie par le champ d'appel. Les variables retournées par ce endpoint sont :
DENOMINATION : La dénomination sociale de l'entreprise correspondante au numéro SIREN fourni ;
CATEGORIE_JURIDIQUE : Le code de la catégorie juridique (consultables ici) ;
FORME_JURIDIQUE : Le nom de la forme juridique sous sa forme complète. Exemple : "SARL, société à responsabilité limitée"
ASSOCIE_UNIQUE : Renvoie une valeur booléenne afin d'indiquer si la structure est unipersonnelle ;
TVA_INTRA : Le numéro de TVA intracommunautaire de l'entreprise correspondante au numéro SIREN fourni ;
SIREN : Le numéro SIREN fourni (et remis en forme si besoin, ou tronqué si le SIRET a été fourni au lieu du SIREN) ;
SIEGE_ADR : L'adresse du siège (numéro de voie + répétition + nom de la voie) ;
SIEGE_ADR_COMPL : Le complément d'adresse, s'il est connu ;
SIEGE_ADR_CP : Le code postal de la commune ;
SIEGE_ADR_COMMUNE : Le nom de la commune ;
SIEGE_SIRET : Le numéro SIRET du siège de l'entreprise correspondante au numéro SIREN fourni ;
ACTIVITE_CODE : le code d'activité principale exercée (code APE /NAF). Ex : "73.11Z" ;
CAPITAL_SOCIAL_EUR : le montant (numérique) du capital social de l'entreprise concernée. Ex: 4000
DATE_IMMATRICULATION : la date d'immatriculation de la société (la dernière immatriculation). Format : aaaa-mm-jj, compatible avec un champ date-input du SmartForm ;
DATE_CLOTURE_EXERCICE : la date de clôture annuelle. Format : aaaa-mm-jj, compatible avec un champ date-input du SmartForm. Dans ce format, l'année 'aaaa' correspond à l'année courante si la date de clôture est passée, sinon ce sera la date de l'année N-1 ;
NOM_GREFFE : le nom du greffe assigné à cette société. Le format renvoyé est en majuscule, avec accent (ex: ORLÉANS).
  • '"/entreprise-data-gouv-sirene/siren"' : ce endpoint permet de récupérer les informations d'une entreprise depuis la base de données SIRENE (data.gouv) à partir d'un numéro SIREN fournie par le champ d'appel. Les variables retournées par ce endpoint sont :
DENOMINATION : La dénomination sociale de l'entreprise correspondante au numéro SIREN fourni ;
CATEGORIE_JURIDIQUE : Le code de la catégorie juridique (consultables ici) ;
TVA_INTRA : Le numéro de TVA intracommunautaire de l'entreprise correspondante au numéro SIREN fourni ;
SIREN : Le numéro SIREN fourni (et remis en forme si besoin, ou tronqué si le SIRET a été fourni au lieu du SIREN) ;
SIEGE_ADR : L'adresse du siège (numéro de voie + répétition + nom de la voie) ;
SIEGE_ADR_COMPL : Le complément d'adresse, s'il est connu ;
SIEGE_ADR_CP : Le code postal de la commune ;
SIEGE_ADR_COMMUNE : Le nom de la commune ;
SIEGE_SIRET : Le numéro SIRET du siège de l'entreprise correspondante au numéro SIREN fourni ;
SIEGE_PAYS : Si le siège est à l'étranger, le nom du pays ;
PP_NOM : Dans le cas où l'entreprise est une personne physique, le nom de cette personne ;
PP_PRENOM : Dans le cas où l'entreprise est une personne physique, le prénom de cette personne ;
ACTIVITE_CODE : le code d'activité principale exercée (code APE /NAF). Ex : "73.11Z"


  • '"/entreprise-data-gouv-sirene/rncs"' : ce endpoint permet de récupérer les informations via l'API RNCS qui offre les informations publiques sur les sociétés françaises immatriculées dans les registres locaux des greffes des tribunaux, et cela à partir d'un numéro SIREN fournie par le champ d'appel. Les variables retournées par ce endpoint sont :
DENOMINATION : La dénomination sociale de l'entreprise correspondante au numéro SIREN fourni ;
FORME_JURIDIQUE : Le nom de la forme juridique dans le format propre au RNCS. Exemple : "Société par actions simplifiée"
ASSOCIE_UNIQUE : Renvoie une valeur booléenne afin d'indiquer si la structure est unipersonnelle ;
TVA_INTRA : Le numéro de TVA intracommunautaire de l'entreprise correspondante au numéro SIREN fourni ;
SIREN : Le numéro SIREN fourni (et remis en forme si besoin, ou tronqué si le SIRET a été fourni au lieu du SIREN) ;
SIEGE_ADR : L'adresse du siège (numéro de voie + répétition + nom de la voie) ;
SIEGE_ADR_COMPL : Le complément d'adresse, s'il est connu ;
SIEGE_ADR_CP : Le code postal de la commune ;
SIEGE_ADR_COMMUNE : Le nom de la commune ;
SIEGE_PAYS : Si le siège est à l'étranger, le nom du pays ;
CAPITAL_SOCIAL_EUR : le montant (numérique) du capital social de l'entreprise concernée. Ex: 4000
DATE_IMMATRICULATION : la date d'immatriculation de la société (la dernière immatriculation). Format : aaaa-mm-jj, compatible avec un champ date-input du SmartForm ;
DATE_CLOTURE_EXERCICE : la date de clôture annuelle. Format : aaaa-mm-jj, compatible avec un champ date-input du SmartForm. Dans ce format, l'année 'aaaa' correspond à l'année courante si la date de clôture est passée, sinon ce sera la date de l'année N-1 ;
CODE_GREFFE : le code correspondant à ce greffe. Ex: 6202…
NOM_GREFFE : le nom du greffe assigné à cette société. Le format renvoyé est en majuscule, avec accent (ex: ORLÉANS).

List-Endpoints disponibles

  • '"/pappers/suggestions-list"' : ce end-point permet de récupérer (gratuitement) depuis Pappers.fr une liste de sociétés dont la dénomination contient au moins le terme fourni par le champ d'appel. Chacun des éléments de la liste retournée répond à la nomenclature suivante :
DENOMINATION : la dénomination de la société listée (ex: 'DUPONT & FRÈRES')
SIREN : le SIREN correspondant à la société listée (ex: '123 456 789')
GEO_NAME : le code postal et la commune. Ex: (ex: "34090 MONTPELLIER")
LIBELLE_ACTIVITE : le libellé de l'activité principale. Ex : "Activités des agences de publicité"


  • '"/pappers/list"' : ce end-point est identique au précédent, mais il permet de récupérer depuis Pappers.fr (coût : 0.1 jeton) une liste de sociétés dont la dénomination contient au moins le terme fourni par le champ d'appel. Chacun des éléments de la liste retournée répond à la nomenclature suivante :
DENOMINATION : la dénomination de la société listée (ex: 'DUPONT & FRÈRES')
SIREN : le SIREN correspondant à la société listée (ex: '123 456 789')
GEO_NAME : le code postal et la commune. Ex: (ex: "34090 MONTPELLIER")
LIBELLE_ACTIVITE : le libellé de l'activité principale. Ex : "Activités des agences de publicité"


  • '"/entreprise-data-gouv-sirene/sirene-list"' : ce endpoint permet de récupérer une liste de société dont la dénomination contient au moins le terme fourni par le champ d'appel. Chacun des éléments de la liste retournée répond à la même nomenclature que celle du "list-endpoint" précédent, mais retrouvés par rapport à [la base SIRENE de data.gouv|https://entreprise.data.gouv.fr/api_doc/sirene].

Exemples de paramétrage

L'exemple suivant correspond aux Options (attribut "api") d'un champ du SmartForm dans lequel un utilisateur peut saisir une dénomination, cliquer sur un bouton "Rechercher" (dans le champ) pour voir s'ouvrir une pop-in lui permettant de choisir une société parmi celles correspondantes à la dénomination saisie d'après la base de données de Pappers.fr. De plus, le "endpoint" principal va permettre, une fois un élément de la liste choisi d'injecter les données dans le formulaire en respectant une correspondance spécifique (sous-attribut 'mapping') entre le nom de la variable renvoyée par l'API et celle du formulaire de l'utilisateur. 

blockclasses: mid-size nobreak
api: 
  button-icon: "fa fa-search"
  button-label: Rechercher
  tooltip-text: "Rechercher les entreprises correspondantes sur une base de données publique."
  list-endpoint: "/pappers/suggestions-list/" 
  list-template-vars: [SIREN, DENOMINATION, SIREN, GEO_NAME, LIBELLE_ACTIVITE]
  endpoint: "/pappers/siren/"
  mapping: 
    SIREN: SOCIETE_SIREN
    DENOMINATION: SOCIETE_DENOMINATION
    FORME_JURIDIQUE: TYPE_SOCIETE
    SIEGE_ADR: SOCIETE_RUE
    SIEGE_ADR_CP: SOCIETE_CP
    SIEGE_ADR_COMMUNE: SOCIETE_VILLE
    ADDRESS: SOCIETE_RUE
    NOM_GREFFE: SOCIETE_GREFFE
    CAPITAL_SOCIAL_EUR: SOCIETE_CAPITAL
    DATE_CLOTURE_EXERCICE: SOCIETE_CLOTURE_EXERCICE
Récupérée de « https://wiki.hercule.co/index.php?title=SmartForm_-_Injection_depuis_une_API&oldid=1074 »