< Descriptif des entités

< API Partenaires

API Partenaires : Interfaçage avec un outil de délibération externe

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 Basic ou Bearer. Un token Basic correspond à la chaîne utilisateur:motdepasse encodé en base64 tandis qu’un token Bearer est 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 instance. 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
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
  • 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
        • 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
            • 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
 
Pagination des résultats :

Il est possible de filtrer et paginer la liste des dossiers retournés pour chaque instance délibérante.
Pour cela, il est nécessaire de renseigner les paramètres souhaités au niveau des dossiers :

Exemple :
				
					query MaRequete {
  deliberationRecupererInfosDossiers(
    identifiantOutilDeliberation: AIRSDELIB
    referenceExterneInstance: "ABC123"
  ) {
    totalCount
    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
          edges {
            node {
              idAvenant
              informationsComplementaires
              montantCalcule
              montantPropose
              referenceAdministrative
              referenceTechnique
              libelleDossierFinancement
              taux
              baseEligible {
                montant
                typeMontant
              }
              coutProjet {
                montant
                typeMontant
              }
              demandeFinancement {
                exercice
                referenceAdministrativeDemande
                referenceTechniqueDemande
              }
              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
              }
            }
          }
        }
      }
    }
  }
}

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
    }
  }
}