Présentation des APIS partenaires de délibération
MGDIS met à disposition des APIs partenaires afin de connecter les dossiers Aiden à un outil de délibération externe.
APIS disponibles
Opérations GraphQL
Les données sont mises à disposition via des APIs partenaires. Les appels sont à réaliser en POST sous format GraphQL.
Plusieurs APIs sont mises à disposition :
- Récupération des informations d’un dossier à partir d’une instance délibérante externe
- Récupération des documents d’un dossier
- Rattachement d’un dossier à un numéro de délibération
- Détachement d’un dossier à un numéro de délibération
- Mise à jour des informations de délibération
L’accès à ces API est sécurisé avec la création d’un compte de service personnalisé (une demande est à soumettre auprès de votre chef de projet MGDIS).
L’url est de la forme :
https://{fqdn}/pda-semi-public-api/api/graphql où {fqdn} correspond à l’url de base de l’environnement.
L’interface pour la documentation technique et pour tester unitairement est également disponible à cette URL. Il faut être authentifié avec un utilisateur connu pour pouvoir la consulter.
Pour tous les appels, les informations suivantes sont nécessaires dans le Header :
- Authorization: Correspond au token d’identification de l’appelant, peut être de type
BasicouBearer. Un tokenBasiccorrespond à la chaîneutilisateur:motdepasseencodé en base64 tandis qu’un tokenBearerest celui renvoyé par le serveur lors de l’authentification. - X-Tenant-Id: Correspond à l’identifiant du tenant
Exemple de header :
{
"Authorization": "Basic dXRpbGlzYXRldXI6bW90ZGVwYXNzZQ==",
"X-Tenant-Id": "myTenant"
}
Query 1 : Récupération des informations d'un dossier à partir d'une instance délibérante externe (deliberationRecupererInfosDossiers)
Cette API permet la récupération des informations sur les dossiers rattachés à une instance délibérante externe à Aiden.
A partir d’une référence externe d’instance délibérante, il est possible de récupérer les informations des instances correspondantes dans Aiden, ainsi que les informations des dossiers associés à cette instance. Ainsi, il est possible de récupérer :
- les informations des instances délibérantes correspondantes dans Aiden
- certaines informations des dossiers rattachés à ces instances. Les dossiers doivent avoir le statut Instruction terminée ou Prêt à voter, et être non clôturés.
- certaines informations de la demande de financement associé au dossier
- les informations des documents des dossiers et demandes ci-dessus étant éligibles à cette API
Il est donc possible de filtrer les résultats de sortie pour :
- une liste de dossiers (via leurs références techniques)
- la division du gestionnaire des dossiers
- le département du gestionnaire des dossiers
Paramètres d’entrée :
- identifiantOutilDeliberation : Paramètre obligatoire permettant de spécifier l’identifiant de la gestion des délibérations associée, de type chaîne de caractères.
- referenceExterneInstance : Paramètre obligatoire permettant de spécifier la référence externe de l’instance délibérante, de type chaîne de caractères.
- dossiersReferences : Paramètre facultatif permettant de spécifier la liste de références des dossiers, sous la forme d’un tableau de chaînes de caractères.
- gestionnaireDivision : Paramètre optionnel permettant de spécifier le code de la division du gestionnaire du dossier, de type chaîne de caractères. Ce paramètre permet de filtrer les dossiers selon la division du gestionnaire : seuls les dossiers dont le gestionnaire appartient à la division donnée seront retournés.
- gestionnaireDepartement : Paramètre optionnel permettant de spécifier le code du département du gestionnaire dossier, de type chaîne de caractères. Ce paramètre permet de filtrer les dossiers selon le département du gestionnaire : seuls les dossiers dont le gestionnaire appartient au département donné seront retournés.
Structure de sortie :
- totalCount : Nombre total d’instances délibérantes récupérées, de type nombre
- pageInfo : Donne des informations sur la pagination
- hasNextPage : Indique s’il y a encore des instances à récupérer après (de type booléen)
- hasPreviousPage : Indique s’il y a des instances à récupérer avant (de type booléen)
- edges : Liste des instances délibérantes sous forme de tableau d’objets. Un « edge » correspond à un objet dont l’attribut « node » représente l’instance délibérante.
- node : Représentation de l’instance délibérante de type objet
- dateHeureDebut : Date et heure de début, de type chaîne de caractères. Exemple : 2022-03-21T23:00:00.000Z
- dateHeureFin : Date et heure de fin, de type chaîne de caractères. Exemple : 2022-03-21T23:00:00.000Z
- dateLimiteEnrolement : Date limite d’enrolement, de type chaîne de caractères. Exemple : 2022-03-21T23:00:00.000Z
- libelle : Libellé de l’instance délibérante, de type chaîne de caractères
- lieu : Lieu, de type chaîne de caractères
- referenceExterne : Référence externe, de type chaîne de caractères
- referenceTechnique : Référence technique (interne à AIDEN) de l’instance délibérante, de type chaîne de caractères
- statut : Statut de l’instance délibérante, de type chaîne de caractères. Valeurs possibles : « OUVERTE », « PREVISIONNELLE », « FIN_ENROLEMENT », « TERMINEE »
- type : Type d’instance délibérante, de type chaîne de caractères
- dossiersFinancement : Liste des dossiers associés à l’instance délibérante sous forme de tableau d’objets
- totalCount : Nombre total de dossiers pour l’instance délibérante, de type nombre
- pageInfo : Donne des informations sur la pagination
- hasNextPage : Indique s’il y a encore des dossiers à récupérer après (de type booléen)
- hasPreviousPage : Indique s’il y a des dossiers à récupérer avant (de type booléen)
- edges : Liste des dossiers sous forme de tableau d’objets. Un « edge » correspond à un objet dont l’attribut « node » représente le dossier
- node : Représentation du dossier de type objet
- idAvenant : Identifiant de l’avenant (0 si décision initiale), de type nombre
- informationsComplementaires : Informations complémentaires du dossier, sous forme d’un objet libre
- montantCalcule : Montant calculé TTC du dossier, de type nombre
- montantPropose : Montant proposé TTC du dossier, de type nombre
- referenceAdministrative : Référence administrative du dossier, de type chaîne de caractères
- referenceTechnique : Référence technique (interne à AIDEN) du dossier, de type chaîne de caractères
- libelleDossierFinancement : Libellé du dossier, de type chaîne de caractères
- taux : Taux de l’aide, de type nombre entre 0 et 100
- baseEligible : Base éligible de type objet
- montant : Montant de la base éligible en euros, de type nombre
- typeMontant : Type de montant de la base éligible. Valeurs possibles : HT ou TTC, de type chaîne de caractères
- coutProjet : Coût du projet de type objet
- montant : Montant du cout du projet en euros, de type nombre
- typeMontant : Type de montant du cout du projet. Valeurs possibles : HT ou TTC, de type chaîne de caractères
- demandeFinancement : Informations concernant la demande de financement associée au dossier de type objet
- exercice : Exercice de la demande, année sous forme de nombre
- referenceAdministrativeDemande : Référence administrative de la demande, de type chaîne de caractères
- referenceTechniqueDemande : Référence technique (interne à AIDEN) de la demande, de type chaîne de caractères
- hierarchies : Le nœud contenant les hiérarchies et les critères analytiques pour chaque hiérarchie (A venir dans une prochaine version)
- dispositif : Informations concernant le dispositif du dossier
- libelle : Libellé du dispositif
- reference : Référence du dispositif
- documents : Documents de délibération liés au dossier sous forme de tableau d’objets
- codePiece : Référence technique de la pièce liée au document, de type chaîne de caractères
- description : Description du document, de type chaîne de caractères
- idcmis : Identifiant CMIS du document, de type chaîne de caractères
- libelle : Libellé du document, de type chaîne de caractères
- libellePiece : Libellé de la pièce liée au document, de type chaîne de caractères
- gestionnaire : Informations concernant l’agent gestionnaire du dossier de type objet
- codeDepartement : Code du département de l’agent gestionnaire du dossier, de type chaîne de caractères
- codeDivision : Code de la division de l’agent gestionnaire du dossier, de type chaîne de caractères
- libelleDepartement : Libellé du département de l’agent gestionnaire du dossier, de type chaîne de caractères
- libelleDivision : Libellé de la division de l’agent gestionnaire du dossier, de type chaîne de caractères
- tiersBeneficiaire : Informations concernant le tiers bénéficiaire du dossier de type objet
- codePostal : Code postal du tiers bénéficiaire du dossier, de type chaîne de caractères
- commune : Commune du tiers bénéficiaire du dossier, de type chaîne de caractères
- dateNaissance : Date de naissance du tiers bénéficiaire du dossier, de type chaîne de caractères. Exemple : « 1990-02-12 »
- nom : Nom du tiers bénéficiaire du dossier, de type chaîne de caractères
- prenom : Prénom du tiers bénéficiaire du dossier, de type chaîne de caractères
- raisonSociale : Raison sociale du tiers bénéficiaire du dossier, de type chaîne de caractères
- siret : SIRET du tiers bénéficiaire du dossier (concaténation du SIREN et du NIC), de type chaîne de caractères. Exemple : « 43xxx1 00xxx9 »
- ventilations : Informations concernant les ventilations liées au dossier sous forme de tableau d’objets
- codeBudget : Code budget de la ventilation, de type chaîne de caractères
- codeCollectivite : Code collectivité de la ventilation, de type chaîne de caractères
- exercice : Exercice de la ventilation, de type nombre
- identifiantGestionFinanciere : Identifiant de la gestion financière liée à la ventilation, de type chaîne de caractères
- libelleBudget : Libellé du budget de la ventilation, de type chaîne de caractères
- libelleCollectivite : Libellé de la collectivité de la ventilation, de type chaîne de caractères
- libelleImputation : Libellé de l’imputation de la ventilation, de type chaîne de caractères
- ligneCredit : Ligne de crédit de la ventilation, de type chaîne de caractères
- montantPropose : Montant proposé TTC de la ventilation, de type nombre
- referenceExterne : Référence externe de la ventilation, de type chaîne de caractères
- node : Représentation du dossier de type objet
- node : Représentation de l’instance délibérante de type objet
Pagination des résultats :
L’API est paginée : par défaut, seuls les 50 premiers dossiers sont renvoyés. Cette pagination peut être personnalisée en ajoutant les paramètres (optionnels) « limit » et « offset ».
Le paramètre « limit » permet d’indiquer le nombre maximal de dossier retournés par l’API, pour l’instance délibérante.
Le paramètre « offset » permet de définir l’index de début pour les dossiers.
Le champ « totalCount » retourne le nombre total de dossiers pour l’instance délibérante.
Exemple : Si totalCount=200 et limit=100, alors il faut faire 2 appels avec :
- offset=0
- offset=100
Exemple :
query MaRequete {
deliberationRecupererInfosDossiers(
identifiantOutilDeliberation: AIRSDELIB
referenceExterneInstance: "ABC123"
) {
totalCount
pageInfo {
hasNextPage
hasPreviousPage
}
edges {
node {
dateHeureDebut
dateHeureFin
dateLimiteEnrolement
libelle
lieu
referenceExterne
referenceTechnique
statut
type
dossiersFinancement(
dossiersReferences: ["REF_DOSSIER_1", "REF_DOSSIER_2"]
gestionnaireDepartment: "departement-exemple"
gestionnaireDivision: "division-exemple"
limit: 10
offset: 10
) {
totalCount
pageInfo {
hasNextPage
hasPreviousPage
}
edges {
node {
idAvenant
informationsComplementaires
montantCalcule
montantPropose
referenceAdministrative
referenceTechnique
libelleDossierFinancement
taux
baseEligible {
montant
typeMontant
}
coutProjet {
montant
typeMontant
}
demandeFinancement {
exercice
referenceAdministrativeDemande
referenceTechniqueDemande
hierarchies
}
dispositif {
libelle
reference
}
documents {
codePiece
description
idcmis
libelle
libellePiece
}
gestionnaire {
codeDepartement
codeDivision
libelleDepartement
libelleDivision
}
tiersBeneficiaire {
codePostal
commune
dateNaissance
nom
prenom
raisonSociale
siret
}
ventilations {
codeBudget
codeCollectivite
exercice
identifiantGestionFinanciere
libelleBudget
libelleCollectivite
libelleImputation
ligneCredit
montantPropose
referenceExterne
}
}
}
}
}
}
}
}
Hiérarchies (Disponible à partir de la version 312):
Les critères analytiques de la demande de financement sont disponibles dans : hierarchies/criteresAnalytiques/values ». Les critères analytiques sont rangés par niveau hiérarchique (niveau 1 puis 2, etc.)
Exemple :
"hierarchies": [
{
"href": "/referentiel-hierarchies/api/tenants/portaildesaides/hierarchies/TESTPFE3",
"title": "TESTPFE3",
"reference": "TESTPFE3",
"modificationByAgent": false,
"selectable": {
"levels": [
"ACTION"
],
"multiple": {
"active": true
}
},
"criteresAnalytiques": [
{
"href": "/referentiel-hierarchies/api/tenants/portaildesaides/hierarchies/TESTPFE3/root/PRIORITE~PRIORITE_1/OBJECTIF~OBJSPEC_12/ACTION~ACTION_121",
"libelle": "Priorité 1 > Objectif 1.2 > Action 1.2.1",
"values": {
"PRIORITE": {
"reference": "PRIORITE_1",
"title": "Priorité 1",
"referenceAdministrative": "PR01",
"referenceExterne": "Ref1"
},
"OBJECTIF": {
"reference": "OBJSPEC_12",
"title": "Objectif 1.2",
"referenceAdministrative": "OS1.2",
"referenceExterne": "Ref012"
},
"ACTION": {
"reference": "ACTION_121",
"title": "Action 1.2.1",
"referenceAdministrative": "1.2.1",
"referenceExterne": "Ref121"
}
}
},
{
"href": "/referentiel-hierarchies/api/tenants/portaildesaides/hierarchies/TESTPFE3/root/PRIORITE~PRIORITE_1/OBJECTIF~OBJSPEC_12/ACTION~ACTION_122",
"libelle": "Priorité 1 > Objectif 1.2 > Action 1.2.2",
"values": {
"PRIORITE": {
"reference": "PRIORITE_1",
"title": "Priorité 1",
"referenceAdministrative": "PR01",
"referenceExterne": "Ref1"
},
"OBJECTIF": {
"reference": "OBJSPEC_12",
"title": "Objectif 1.2",
"referenceAdministrative": "OS1.2",
"referenceExterne": "Ref12"
},
"ACTION": {
"reference": "ACTION_122",
"title": "Action 1.2.2",
"referenceAdministrative": "1.2.2",
"referenceExterne": "Ref122"
}
}
},
{
"href": "/referentiel-hierarchies/api/tenants/portaildesaides/hierarchies/TESTPFE3/root/PRIORITE~PRIORITE_1/OBJECTIF~OBJSPEC_11/ACTION~ACTION_111",
"libelle": "Priorité 1 > Objectif 1.1 > Action 1.1.1",
"values": {
"PRIORITE": {
"reference": "PRIORITE_1",
"title": "Priorité 1",
"referenceAdministrative": "PR01",
"referenceExterne": "Ref1"
},
"OBJECTIF": {
"reference": "OBJSPEC_11",
"title": "Objectif 1.1",
"referenceAdministrative": "OS1.1",
"referenceExterne": "Ref11"
},
"ACTION": {
"reference": "ACTION_111",
"title": "Action 1.1.1",
"referenceAdministrative": "1.1.1",
"referenceExterne": "Ref111"
}
}
},
{
"href": "/referentiel-hierarchies/api/tenants/portaildesaides/hierarchies/TESTPFE3/root/PRIORITE~PRIORITE_2/OBJECTIF~OBJSPEC_21/ACTION~ACTION_211",
"libelle": "Priorité 2 > Objectif 2.1 > Action 2.1.1",
"values": {
"PRIORITE": {
"reference": "PRIORITE_2",
"title": "Priorité 2",
"referenceAdministrative": "PR02",
"referenceExterne": "Ref2"
},
"OBJECTIF": {
"reference": "OBJSPEC_21",
"title": "Objectif 2.1",
"referenceAdministrative": "OS2.1",
"referenceExterne": "Ref21"
},
"ACTION": {
"reference": "ACTION_211",
"title": "Action 2.1.1",
"referenceAdministrative": "2.1.1",
"referenceExterne": "Ref211"
}
}
},
{
"href": "/referentiel-hierarchies/api/tenants/portaildesaides/hierarchies/TESTPFE3/root/PRIORITE~PRIORITE_2/OBJECTIF~OBJSPEC_21/ACTION~ACTION_213",
"libelle": "Priorité 2 > Objectif 2.1 > Action 2.1.3",
"values": {
"PRIORITE": {
"reference": "PRIORITE_2",
"title": "Priorité 2",
"referenceAdministrative": "PR02",
"referenceExterne": "Ref2"
},
"OBJECTIF": {
"reference": "OBJSPEC_21",
"title": "Objectif 2.1",
"referenceAdministrative": "OS2.1",
"referenceExterne": "Ref21"
},
"ACTION": {
"reference": "ACTION_213",
"title": "Action 2.1.3",
"referenceAdministrative": "2.1.3",
"referenceExterne": "Ref213"
}
}
}
],
"referenceExterne": "REFEXT"
}
]
Query 2 : Récupération des documents d'un dossier
⚠️Attention, cette route uniquement n’est pas en GraphQL et est définie en tant qu’API REST standard.
Cette API permet de récupérer les binaires des documents d’un dossier à partir de leur id. Les id des documents sont récupérés via la query 1.
| Récupérer les documents de délibérations liés à un dossier | Entité | Documents | ||
| URL | https://{{fqdn}}/pda-semi-public-api/api/tenants/{{tenant}}/deliberation/recuperer-documents-lies-a-dossier-et-demande | |||
| Verbe | POST | |||
| Headers | Content-Type | Application/json | ||
| Authorization | Basic | Identifiant | ||
| Mot de passe | ||||
| Bearer | JWT | |||
| Exemple de body |
{
"idDocuments": ["idDoc1", "idDoc2", "idDoc3"],
"dossier": "1234567ABCD"
}
|
|||
Structure de sortie :
1 fichier contenant :
- Les documents du dossier et de la demande de financement associée. Ces documents sont nommés avec leur idcmis suivi de leur extension
- Un fichier .json reprenant, pour chaque idcmis demandé lors de l’appel :
- l’idcmis du document
- file_name : `<idcmis>.<extension>` (correspond au nom complet du fichier incluant l’extension du fichier)
- status : le statut de la récupération : « OK » ou « KO »
- document_name : le nom du document avec son extension, valorisé si le document a été trouvé
- error : la description de l’erreur de récupération du document lorsque celui-ci n’a pu être ajouté dans l’archive
Query 3 : Rattachement d'un dossier à un numéro de délibération (deliberationRattacherRapport)
Cette API permet de mettre à jour le numéro de délibération ainsi que le code de délibération sur une liste de dossiers.
Le numéro de délibération est affiché sur la page décision du dossier, dans la section « Délibération et engagement juridique ». Le code de délibération correspond à la référence technique du numéro de délibération : il n’est pas affiché sur le dossier (uniquement stocké sur l’entité du dossier).
Ces dossiers doivent avoir le statut : Instruction terminée ou Prêt à voter, et être non clôturés.
Paramètres d’entrée :
- identifiantOutilDeliberation : Paramètre obligatoire permettant de spécifier l’identifiant de la gestion des délibérations associée, de type chaîne de caractères.
- dossiers : Paramètre obligatoire permettant de spécifier la liste des dossiers à mettre à jour. Cette liste contient les références techniques des dossiers cibles. De type tableau de chaînes de caractères.
- numeroRapport : Paramètre obligatoire permettant de spécifier le numéro du rapport, de type chaîne de caractères.
- codeTechniqueRapport : Paramètre obligatoire permettant de spécifier le code technique du rapport, de type chaîne de caractères.
Structure de sortie :
Un tableau d’objets, dont chaque élément possède les propriétés suivantes :
- referenceDossier : Référence technique du dossier concerné, de type chaîne de caractères
- updated : Valeur indiquant si le dossier a été mis à jour ou non. True si le dossier a bien été mis à jour, false sinon, de type booleen
- error : Représentation de l’erreur (si erreur) de type objet
- code : Code d’erreur, de type nombre
- message : Message d’erreur, de type chaîne de caractères
Exemple :
query MaRequete {
deliberationRattacherRapport(
identifiantOutilDeliberation: AIRSDELIB
numeroRapport: "1"
codeTechniqueRapport: "dee215d"
dossiers: ["1234567ABCD", "987654NBVCXW"]
) {
referenceDossier
updated
error {
code
message
}
}
}
Query 4 : Détachement d'un dossier à un numéro de délibération (deliberationDetacherRapport)
Cette API permet de supprimer le numéro de délibération ainsi que le code de délibération sur une liste de dossiers.
Si la date et/ou la date de délibération étaient renseignées sur les dossiers, ces informations sont également supprimées des dossiers lors du détachement.
Les dossiers doivent avoir le statut : Instruction terminée ou Prêt à voter, et être non clôturés.
Paramètres d’entrée :
- identifiantOutilDeliberation : Paramètre obligatoire permettant de spécifier l’identifiant de la gestion des délibérations associée, de type chaîne de caractères.
- codeTechniqueRapport : Paramètre obligatoire permettant de spécifier le code technique du rapport, de type chaîne de caractères.
- dossiers : Paramètre obligatoire permettant de spécifier la liste des dossiers à mettre à jour. Cette liste contient les références techniques des dossiers cibles, de type tableau de chaînes de caractères.
Structure de sortie :
Un tableau d’objets, dont chaque élément possède les propriétés suivantes :
- referenceDossier : Référence technique du dossier concerné, de type chaîne de caractères
- updated : Valeur indiquant si le dossier a été mis à jour ou non. True si le dossier a bien été mis à jour, false sinon, de type booleen
- error : Représentation de l’erreur (si erreur) de type objet
- code : Code d’erreur, de type nombre
- message : Message d’erreur, de type chaîne de caractères
Exemple :
query MaRequete {
deliberationDetacherRapport(
identifiantOutilDeliberation: AIRSDELIB
codeTechniqueRapport: "dee215d"
dossiers: ["1234567ABCD", "987654NBVCXW"]
) {
referenceDossier
updated
error {
code
message
}
}
}
Query 5 : Mise à jour des informations de délibération sur un dossier (deliberationMettreAJourInformations)
Cette API permet de mettre à jour les informations de délibération d’une liste de dossiers :
- Date de délibération
- Référence de délibération
- Numéro de rapport de délibération
Ces informations sont affichées sur la page de décision des dossiers, dans la section « Délibération et engagement juridique ».
Ces dossiers doivent avoir le statut : Instruction terminée ou Prêt à voter, et être non clôturés.
Paramètres d’entrée :
- identifiantOutilDeliberation : Paramètre obligatoire permettant de spécifier l’identifiant de la gestion des délibérations associée.
- dossiers : Paramètre obligatoire permettant de spécifier la liste des dossiers à mettre à jour. Cette liste contient les références techniques des dossiers cibles.
- dateDeliberation : Paramètre obligatoire permettant de spécifier la date de délibération à renseigner au niveau des dossiers.
- referenceDeliberation : Paramètre obligatoire permettant de spécifier la référence de délibération à renseigner au niveau des dossiers.
- numeroRapport : Paramètre obligatoire permettant de spécifier le numéro du rapport.
- codeTechniqueRapport : Paramètre obligatoire permettant de spécifier le code technique du rapport.
Doit correspondre au code de rapport déjà présent sur chaque dossier de la liste (cf. paramètre « dossiers »).
Structure de sortie :
Un tableau d’objets, dont chaque élément possède les propriétés suivantes :
- referenceDossier : Référence technique du dossier concerné, de type chaîne de caractères
- updated : Valeur indiquant si le dossier a été mis à jour ou non. True si le dossier a bien été mis à jour, false sinon, de type booleen
- error : Représentation de l’erreur (si erreur) de type objet
- code : Code d’erreur, de type nombre
- message : Message d’erreur, de type chaîne de caractères
Exemple :
query MaRequete {
deliberationMettreAJourInformations(
dateDeliberation: "2023-06-16T11:21:00.000Z"
identifiantOutilDeliberation: AIRSDELIB
referenceDeliberation: "dbe211e5d"
dossiers: ["1234567ABCD", "987654NBVCXW"]
numeroRapport: "1"
codeTechniqueRapport: "dee215d"
) {
referenceDossier
updated
error {
code
message
}
}
}