< Descriptif des entités

< API Partenaires

API Partenaires GRU : Mise à disposition des tiers, de leurs demandes de financement et des téléservices publiés dans Aiden

Présentation des APIs Partenaires GRU

MGDIS met à disposition des applications de Gestion de la Relation Usager partenaires une API dédiée à la récupération des tiers, de leurs demandes de financement et des téléservices publiés dans Aiden.

Ces APIs ont pour but de permettre aux applications GRU de restituer aux usagers les tiers auxquels ils sont rattachés dans Aiden, de leur permettre un accès facilité à chacune des demandes de financement associées à ces tiers et de lister les téléservices publiés dans Aiden.

Note : Ces APIs étant en cours d’implémentation, cette documentation est susceptible d’évoluer.

APIs disponibles

Les données sont mises à disposition via des APIs semi-publiques. Les appels sont à réaliser en POST sous format GraphQL. L’API est basée sur le langage de requête pour API GraphQL. Si GraphQL ne vous est pas familier, nous vous recommandons de consulter les liens suivants :
Les APIs permettent de récupérer tous les tiers associés à un compte OIDC donné, ainsi que les demandes de financement associées à chaque tiers. Des filtres sur les tiers et les demandes de financement peuvent être appliqués afin de récupérer uniquement les données pertinentes pour les cas d’usages (statut du tiers ou des demandes, téléservice…). De plus, une pagination est systématiquement présente et modifiable par le consommateur.

Documentation technique

L’url est de la forme :

https://{{fqdn}}/pda-semi-public-api/api/graphql

L’interface pour la documentation technique et pour tester unitairement est également disponible à cette URL. Il faut être authentifié avec un utilisateur connu de la GRU pour pouvoir la consulter.

Pour tous les appels, les informations suivantes sont nécessaires dans les entêtes :

  • X-Tenant-Id : identifiant du tenant client
  • X-Request-Id : UUID au format v4 pour tracer les appels corrélés
  • Authorization : de type basic avec l’utilisateur autorisé sur l’API GRU
Exemple de headers :
 
{

"X-Tenant-Id": "portaildesaides",

"X-Request-Id": "5baa0d80-697e-4bda-92d6-49348dfba529",

"Authorization": "Basic Z3J1LW1nZGlzOmdydS1tZ2Rpcw=="

}
 

Query tiersDemandes

Cette requête permet de récupérer les tiers liés au comptes usager et leurs demandes associés.
Le filtre obligatoire à appliquer définit le compte usager OIDC dont on souhaite récupérer les tiers et demandes (providerOIDC et identifiant subOIDC).

Lister les tiers

Cette opération permet de récupérer les tiers associés à un compte donné.

Les filtres possibles sur les tiers sont :

  • Référence technique du tiers (tiersReference) : égalité stricte (equals) sur la référence technique du tiers.
  • Statut (tiersStatus), le filtre se fait sur le statut des tiers :
    • Inclus dans une liste (in) : pour récupérer les tiers qui ont un statut inclus dans la liste donnée (e.g. [« TRANSMITTED », « SUPPORTED »])
Exemple d’appel

Données en sortie de tiers :

Une liste de tiers est renvoyée par l’opération tiersDemandes. Cette liste peut être paginée et contient les tiers correspondant aux filtres définies en entrée de la Query. Chaque tiers peut contenir les données suivantes :

  • id : référence technique du tiers (format GraphQL Relay Node API – voir section Query Node)
  • libelle : libellé du tiers
  • referenceAdministrative : administrative du tiers
  • statut : statut du tiers
    • id : code technique du statut
    • libelle : libellé du statut
  • famille : famille du tiers
    • id : code technique de la famille
    • libelle : libellé de la famille
  • raisonSociale : raison sociale du tiers
  • personnaliteJuridique : personnalité juridique du tiers (« MORALE » ou « PHYSIQUE »)
  • SIRET : SIRET d’un tiers de personnalité juridique
  • RNA : RNA d’un tiers « Association »
  • adresse : adresse principale du tiers
  • mail : adresse mail du tiers
  • site : site web du tiers
  • telephone : telephone principal du tiers
  • demandes : demandes de financement du tiers

Lister les demandes de financement d’un tiers

Cette opération permet de récupérer les demandes de financement d’un tiers donné. Les filtres possibles en entrée de tiersDemandes sont :

  • teleserviceReferences, le filtre se fait sur le téléservice des demandes de financement
    • Inclus dans une liste (in) : pour récupérer les demandes de financement qui ont un téléservice avec la référence technique inclue dans la liste donnée (e.g. [« F_DEMOTEST », « BRMIE »])
Exemple d’appel

Données en sortie de demandes

Une liste des demandes de financement est renvoyée par la Query tiersDemandes si le champs « demandes » est sélectionné. Cette liste peut être paginée et contient les demandes correspondantes aux filtres définis en entrée de la Query. Chaque demande de financement peut contenir les données suivantes :

  • id : référence technique de la demande (format GraphQL Relay Node API – voir section Query Node)
  • libelle : libellé de la demande
  • referenceAdministrative : référence administrative de la demande
  • dateCreation : date de création de la demande
  • dateModification : date de modification de la demande
  • actionUsager : Vrai si la demande nécessite une action de l’usager
  • demandePartagee : Vrai si la demande a été partagée au compte usager
  • tiersBeneficiaire : Vrai si le tiers est le bénéficiaire de la demande de financement 
  • tiersDemandeur : Vrai si le tiers est le demandeur de la demande de financement
  • cloture : Vrai si la demande est clôturée
  • statut : statut de la demande de financement
    • id : code technique du statut
    • libelle : libellé du statut
  • demarche :
    • id : code technique du téléservice
    • libelle : libellé du téléservice
  • url : URL d’accès à la demande de financement

Les demandes retournées par cette requête sont les demandes où le tiers est :

  • Demandeur, c’est à dire qu’il a déposé la demande de financement dans Aiden. Dans ce cas, le booléen tiersDemandeur est à « Vrai » 

et/ou

  • Bénéficiaire, c’est à dire que le tiers est le bénéficiaire de cette subvention. Dans ce cas, le booléen tiersBeneficiaire est à « Vrai »

Un usager peut également être « destinataire du partage » d’une demande de financement en cours de création. Les demandes partagées à l’usager sont rattachées à son compte et non à un tiers en particulier, c’est pourquoi elles seront renvoyées pour tous les tiers associés à ce compte. Lorsqu’une demande est partagée à l’usager, le booléen demandePartagee est à « Vrai ».

Le booléen actionUsager est valorisé à « Vrai » s’il existe une sollicitation en attente de réponse. Les sollicitations concernées sont :

  • une demande de compléments sur pièce en attente de réponse sur la demande de financement
  • une contribution pour modification ou redirection adressée au compte en attente de réponse

Query teleservices

Cette requête permet de rechercher dans la liste des téléservices publiés sur Aiden. À partir du filtre obligatoire de recherche (search), la liste des téléservices publiés est filtrée et paginée. Il existe des filtres optionnels pour le type de workflow (SIMPLE par défaut), le statut du téléservice (PUBLIE par défaut) et le providerOIDC (url différente avec OIDC). Chaque téléservice peut contenir les données suivantes :

  • id : référence technique du téléservice (format GraphQL Relay Node API – voir section Query Node)
  • libelle : libellé du téléservice
  • famillesTiers : liste des familles de tiers autorisées à déposer une demande sur ce téléservice
    • id : code technique de la famille de tiers
    • libelle : libellé de la famille de tiers
  • motsCles : liste des mots-clés associés au téléservice
    • id : code technique du mot-clé
    • libelle : libellé du mot-clé
  • statut : statut du téléservice
    • id : code technique du statut
    • libelle : libellé du statut
  • url : URL de dépôt d’une nouvelle démarche sur ce téléservice
  • dateOuvertureDepot : date d’ouverture des dépôts sur l’espace usager
  • dateFermetureDepot : date de fermeture des dépôts sur l’espace usager

Si aucune famille de tiers n’est associée au téléservice, cela veut dire qu’il est accessible pour tous les usagers, indépendamment de la famille du tiers.

Exemple d’appel

Query node

Cette requête permet de récupérer un objet compatible avec l’API Node GraphQL Relay grâce à son id. Cet objet peut être un tiers, une demande de financement ou un téléservice.

Dans le cas des tiers et des demandes, ces objets contenant des données confidentielles, elle nécessitera des permissions additionnelles à votre compte partenaire pour y accéder.
L’id a considérer est présent en retour des queries tiersDemandes et teleservices. Il servira de paramètre d’entrée à l’API Query Node. Dans l’exemple suivant, vous trouverez l’id des téléservices publiés.

Cet id représente un codage Base64 sous la forme :
<type GraphQL>:<référence technique>

Exemple de contenu d’un identifiant de téléservice

"id": "VGVsZXNlcnZpY2VHUlU6UF90ZXN0ZGF0"

TeleserviceGRU:P_testdat

Exemple d’appel de l’API GraphQL

Avec cet identifiant, il sera possible d’utiliser la query node en spécifiant également le type GraphQL cible. Cela permettra de donner précisément les champs souhaités en retour.

Aide à l'utilisation de GraphQL

Comment renommer les champs dans la réponse GraphQL ? 

Il est possible avec GraphQL de renommer des champs afin de faciliter le mapping propre à chaque GRU. Pour cela nous allons utiliser la technologie « Field Aliasing » implémentée dans GraphQL (cf la spécification https://spec.graphql.org/draft/#sec-Field-Alias).

Comme vous pouvez le voir dans l’exemple suivant, les champs natifs : « id », « libelle », « demandePartagee », « tiersBeneficiaire » et « tiersDemandeur » ont respectivement été renommés « code », « titre », « estPartagee », « jeSuisUnBeneficiaire » et « jeSuisDemandeur ».
Cette technique consiste à préfixer le nom du champ natif par le vôtre suivi du caractère « : » afin de séparer les deux : NouveauNom:nomNatif