Contrats d’interfaces API – Communauté Chorus Pro

DESCRIPTION

Les API du Service Dume permettent aux éditeurs d'intégrer toutes les fonctionnalités du Service DUME aux profils d'acheteurs qu'ils administrent.

Les fonctionnalités proposées permettent aux acheteurs et opérateurs économiques de réaliser toutes les étapes de saisie, complétion et consultation des DUME. Chaque fonctionnalité est portée par une opération relevant d'une des API suivantes :

API DUME A (pour les DUME Acheteurs)
API DUME OE (pour les DUME Opérateurs Economiques)
API Métadonnées (pour intervenir uniquement sur les métadonnées d'un DUME)
API Données (pour récupérer des données issues de sources tierces comme API Entreprises)
API Référentiel (pour interroger les référentiels du service DUME)
API E-Certis (pour récupérer la transcription française de la réglementation européenne)
API Attestations (pour récupérer les attestations via API Entreprises)

Cette page présente les opérations due Service DUME, classées par API.

Veuillez noter qu'il appartient à chaque éditeur de concevoir pour son profil d'acheteur l'ergonomie et les cinématiques d'utilisation du DUME, les opérations du Service DUME permettant simplement l'échange des données constitutives du DUME, sans préjuger de l'interface homme machine mise en œuvre par les différentes places de marché.

Le guide des bonnes pratiques d'implémentation des API de l'AIFE conseillent fortement l'implémentation pour les API proposées par l'AIFE d'une opération permettant de consulter l'état de santé des applications. Chaque API DUME a été dotée d'une opération "healthCheck" permettant de consulter l'état de santé de l'application.

Opération "healthCheck" commune à toutes les API

Ces opérations sont consultables par les consommateurs des API DUME.

Objet	Description
URI	N’importe quelle API DUME
Exemple de requête JSON (IN)	{ "operation": "healthCheck", "plateforme": { "typeIdPlateforme": "1", "idPlateforme": "12345678901011", "idTechniquePlateforme": "AAA001" }, "rsDemandeur": "AIFE", "idDemandeur": "12345698765445" }
Exemple de réponse JSON (OUT) si application UP	{ "response": { "messageList": [ { "type": "INFO", "code": "HEALTH_CHECK", "message": "{\"status\":\"UP\"}" } ] } }
Exemple de réponse JSON (OUT) si application DOWN	{ "response": { "messageList": [ { "type": "INFO", "code": "HEALTH_CHECK", "message": "{\"status\":\DOWN\"}" } ] } }
Exemple de réponse JSON (OUT) si service HealthCheck non accessible	{ "response": { "messageList": [ { "type": "ERREUR", "code": "HEALTH_CHECK", "message": "Pas de réponse du service HealthCheck" } ] } }

Paramètre d’entrée	Obligatoire (O) / Facultatif (F)	Règle de gestion
operation	O	O Constante =healthCheck
idPlateforme	O	1/ Id fonctionnel du profil d'acheteur ayant sollicité le raccordement 2/ Le format de l’ID de la plateforme est contrôlé : - Si « type identifiant » est « 1 » : 14 caractères - Si « type identifiant » est « 2 » : 18 caractères maximum (soit 1 à 18 caractères) - Si « type identifiant » est « 3 » : 3 à 18 caractères - Si « type identifiant » est « 4 » : 9 ou 10 caractères - Si « type identifiant » est « 5 » : « 9 » caractères - Si « type identifiant » n’est pas renseigné, il est réputé s’agir d’un SIRET : 14 caractères 3/ L’ID technique de la plateforme et l’ID de la plateforme doivent exister en base de données et être positionnés sur la même ligne de cette base de données
idTechniquePlateforme	O	1/ ID disponible sur l'espace "raccordement" de Chorus Pro. L'id technique correspond au code application partenaire contenu dans la fiche de raccordement 2/ L’ID technique de la plateforme et l’ID de la plateforme doivent exister en base de données et être positionnés sur la même ligne de cette base de données
typeIdPlateforme	O	Les valeurs pour « type d’ID plateforme demandeuse » sont - « 1 » (Tiers avec SIRET) - « 2 » (Structure Européenne hors France) – TVA intracommunautaire - « 3 » (Structure hors UE) – Code pays + 16 premiers caractères raison sociale - « 4 » (RIDET) - « 5 » (Numéro Tahiti)
idDemandeur	O	L'idDemandeur correspond au SIRET ou l'identifiant fonctionnel de l'entité qui fait la demande sur la place de marché.
rsDemandeur	O	Nom de l'entité qui fait la demande sur la place (Raison sociale)

Fonctionnement des services exposés du Service DUME

Principes de fonctionnement des services exposés (API)

Les services exposés sont organisés par domaine et par type d’opération.

L’utilisation d’URI globaux permet de distinguer à quel domaine s’adressent les opérations demandées. Pour rappel, une URI de l'anglais Uniform Resource Identifier, soit "identifiant uniforme de ressource", est une courte chaîne de caractères identifiant une ressource sur un réseau (par exemple une ressource Web) physique ou abstraite, et dont la syntaxe respecte une norme d'Internet mise en place pour le World Wide Web.

Liste des URI des référentiels du Service DUME en mode PISTE

Domaine	URI correspondante
Données	https://api.piste.gouv.fr/dume/donnees
DUME acheteur	https://api.piste.gouv.fr/dume/dumeA
DUME Opérateur Economique	https://api.piste.gouv.fr/dume/dumeOE
Métadonnées	https://api.piste.gouv.fr/dume/metadonnees
Référentiels	https://api.piste.gouv.fr/dume/referentiels
Attestations	https://api.piste.gouv.fr/dume/attestations

Un paramètre d’entrée intitulé opération permet de déterminer la fonctionnalité qu’on souhaite activer (ex: rechercherDume, enregistrerDume, fusionnerDume, recupererModelDume,...). On note qu’une même opération peut être appliquée à un ou plusieurs domaine(s).

Ainsi, pour les cas d'utilisation similaires entre dume A et dume OE, on utilisera le même nom d'opération. La différentiation s’effectuera au niveau de l'URI sous laquelle l’opération est réalisée. Par exemple, si on effectue « opération=enregistrerDume » avec utilisation de l'URI "../dumes/dumeA", on réalisera l’enregistrement d'un DUME A.

Le tableau ci-dessous illustre quelques-uns des cas d’opérations réalisables sur une ou plusieurs URI :

Opération	Domaine(s) applicable(s)
rechercherDume	DUME A ; DUME OE
enregistrerDume	DUME A ; DUME OE
fusionnerDume	DUME OE
recupererModelDume	DUME A ; DUME OE
etc.	etc.

Le paramètre d'entrée "opération" est toujours complété par d'autres paramètres (par exemple, l'identifiant du profil d'acheteur concerné) permettant d'exécuter la requête. Dans le cas où plusieurs paramètres identiques sont indiqués, alors seul le dernier est considéré par la solution.

Pour rappel, les API permettent l’utilisation du référentiel Service DUME. Leur implémentation demande également à l’éditeur un travail de conception afin de proposer des fonctionnalités plus simples et plus adaptées à l’utilisateur.

Format des appels (JSON)

Formalisme des appels :

Les appels de service sont structurés autour d’un flux JSON encapsulant le fichier XML qui contient le DUME proprement dit. Veuillez noter à ce propos que les seuls DUME dématérialisés reconnus par la réglementation sont des DUME de format XML, respectant un formalisme défini par l’Union Européenne. Tout autre format donné à un DUME (ex : PDF) ne vaut que copie, et ne saurait constituer un original à valeur probante.

Le flux JSON contient le nom de l’opération à exécuter, des paramètres d’entrée permettant d’exécuter l’appel ainsi que des données complémentaires au DUME appelées « métadonnées ». Celles-ci permettent soit d’assurer la bonne gestion technique du DUME soit d’apporter des informations complémentaires non présentes dans le fichier XML. Afin de connaître le contenu exact des métadonnées, il est nécessaire de consulter la liste des API.

Les réponses apportées aux appels passés à destination du service DUME obéissent aux mêmes règles. Cependant, les JSON émis par le service DUME retournent en guise de données des « paramètres de sortie ». Les paramètres d’entrée et de sortie propres à chaque appel vous seront présentés dans le descriptif de chaque API, plus loins dans le présent document.

Le formalisme du JSON est standardisé :

une requête est encadrée par des crochets : {}
chaque paramètre ou opération est défini par un titre entre guillemets : “ ”
chaque donnée est encadrée par des guillemets : “ ”
chaque ensemble titre et données est séparé du suivant par une virgule : ,
le dernier champ de l’appel ne doit pas être suivi d’une virgule, cette dernière étant interprétée comme prélude au renseignement d’un nouveau champ,
le XML est saisi encodé en base 64 dans le JSON.

Liste des codes erreurs fournis suite à un appel erroné

Les requêtes mal formulées donnent lieu à des messages d’erreur précisant la nature du problème identifié.

Vous trouverez ci-dessous les codes erreurs les plus fréquents :

CODE ERREUR	Description	Sortie API
PARAM_MISSING	Paramètre présent dans la requête, mais pas attendu par l'API	{ "type": "ERREUR", "code": "PARAM_MISSING", "message": "Le champs 'xxx' n'existe pas et ne doit pas être renseigné" },
PARAM_REQUIRED	Paramètre non présent dans la requête, mais attendu par l'API	{ "type": "ERREUR", "code": "PARAM_REQUIRED", "message": "Le champs 'xxx' est manquant" },
PARAM_MAXLENGTH	La valeur du paramètre attendu a une longueur supérieure à la valeur attendue	{ "type": "ERREUR", "code": "PARAM_MAXLENGTH", "message": "Le champs 'xxx' est mal formaté : longueur maximale 18" },
PARAM_FORMAT	La valeur du format du paramètre en entrée n'est pas conforme au format attendu	{ "type": "ERREUR", "code": "PARAM_FORMAT", "message": "Le champs 'xxx' est mal formaté" },
PARAM_MINLENGTH	La valeur du paramètre attendu a une longueur inférieure à la valeur attendue	{ "type": "ERREUR", "code": "PARAM_MINLENGTH", "message": "Le champs 'xxx' est mal formaté : longueur minimale 1" }
InternalError	Erreur système	{ "type": "ERREUR", "code": "InternalError", "message": "Erreur Interne serveur" }

Illustration : exemples de JSON commentés

La requête ci-dessous permet l’enregistrement d’un DUME acheteur au statut validé dans le référentiel Service DUME. Si le DUME A n’a jamais été enregistré dans le référentiel auparavant, il est inutile de renseigner un numéro d’ID dans le JSON d’entrée.

Une fois l’appel API effectué, le Service DUME stocke le XML du DUME enregistré dans la base Service DUME et retourne un numéro d’identification unique à l’acheteur.

Liste des opérations par API

Les API présentées ci-dessous sont disponibles depuis le 3 avril 2018. Elles sont ouvertes aux éditeurs raccordés au Service DUME. Pour plus d'information au sujet du raccordement en production ou en qualification, merci de consulter la page suivante : https://communaute.chorus-pro.gouv.fr/documentation/acces-aux-api-du-service-dume/.

API DUME Acheteur

Pour rappel, les opérations effectuées sur les DUME A (DUME Acheteur) s’effectuent à l’URI suivante : https://api.piste.gouv.fr/dume/dumeA

Pour mémoire l'URI utilisée lors des anciens raccordements, effectués sur Chorus Pro (plutôt que sur PISTE) était : https://chorus-pro.gouv.fr:5443/service/dume/dumeA

recupererModelDume : permet de récupérer un modèle de DUME A vierge.
recupererDumeFormate : permet de récupérer un DUME A dans un format donné (ex : PDF, HTML, ...).
enregistrerDume : permet d'enregistrer un DUME A dans le Service DUME et, le cas échéant, d'obtenir son identifiant.
rechercherDumes : permet de lancer une recherche de DUMEs dans Service DUME.
creerDumeSimple : permet de solliciter la création d’un DUME « simple », correspondant aux critères des procédures réalisées dans le cadre des marchés publics simplifiés.
supprimer DUME : permet de supprimer un DUME

API DUME Opérateur Economique

L'URL pour l'API DUME OE est la suivante : https://api.piste.gouv.fr/dume/dumeOE

Pour mémoire l'URI utilisée lors des anciens raccordements, effectués sur Chorus Pro (plutôt que sur PISTE) était : https://chorus-pro.gouv.fr:5443/dumes/dumeOE

recupererModelDume : permet au profil d'acheteurs de récupérer un DUME totalement vide.
recupererDumeFormate : permet de récupérer un DUME au format PDF, HTML ou XML ainsi que les métadonnées associées, sur la base de l'identifiant ou bien du XML de ce DUME.
CreerdumeOEavecSiretOE : permet de récupérer un XML DUME OE à partir d'un identifiant, complété par les informations publiques ou privées de l'opérateur économique.
fusionnerDumeavecDonneesEntreprise : permet de récupérer un DUME OE issu d'un DUME Acheteur dont elle a le numéro ou le XML, complété des données publiques ou privées de l'OE.
fusionnerDume : La place de marché souhaite récupérer la fusion d'un DUME OE et d'un DUME Acheteur dont elle a les numéros ou les XML
enregistrerDume : permet au profil d'acheteur d'enregistrer un DUME OE pour lequel il dispose d'un identifiant ou d'un XML.
telechargerDumeAvecPJ :La place de marché souhaite récupérer le DUME avec les PJ éventuellement ajoutées par l’opérateur économique ou encore avec les attestations récupérées via les API entreprise
rechercherDumes : La place de marché souhaite récupérer les ID des DUMES répondant à un certain nombre de critères (ID_consultation, SIRET OE, …)
AjouterPJ : La place de marché souhaite ajouter une PJ à un DUME.
supprimer un DUME - DUME OE. : permet de supprimer un DUME
Analyser réponses : permet ainsi à un acheteur de savoir facilement si les répondants respectent les critères d’exclusion, de sélection et de restriction sollicités par l’acheteur dans son DUME.

API Métadonnées

L’URI pour l’API Métadonnées DUME est la suivante : https://api.piste.gouv.fr/dume/metadonnees

Pour mémoire l'URI utilisée lors des anciens raccordements, effectués sur Chorus Pro (plutôt que sur PISTE) était : https://chorus-pro.gouv.fr:5443/service/dume/métadonnées

mettreAJourDume : permet de mettre à jour les métadonnées associées à un DUME Acheteur ou Opérateur Economique.

API Données

L’URI pour l’API attestations est la suivante : https://api.piste.gouv.fr/dume/donnees

Pour mémoire l'URI utilisée lors des anciens raccordements, effectués sur Chorus Pro (plutôt que sur PISTE) était : https://chorus-pro.gouv.fr:5443/service/dume/donnees

recupererDonneesOE : permet de récupérer les données publiques ou privées d'un OE.

API Référentiel

L’URI pour l’API Référentiel est la suivante : https://api.piste.gouv.fr/dume/referentiels

Pour mémoire l'URI utilisée lors des anciens raccordements, effectués sur Chorus Pro (plutôt que sur PISTE) était : https://chorus-pro.gouv.fr:5443/dumes/Referentiel

Listerréférentiel: permet au profil d’acheteur de connaitre la liste des référentiels présents dans le service DUME.
listerValeursDeReferentiel : permet au profil d’acheteur de connaitre la liste des valeurs d'un des référentiels présent dans le service DUME.
RecupererLibelles : permet au profil d’acheteur de récupérer les libellés du formulaire DUME

API E-Certis

L’URI pour l’API eCertis est la suivante : https://api.piste.gouv.fr/dume/ecertis

recupererEvidence : Permet de récupérer les déclinaisons nationales et les évidences associées aux critères européens d’exclusion et de sélection

API Attestations

L'URL pour l'API Attestations est la suivante : https://api.piste.gouv.fr/dume/attestations

Pour mémoire l'URI utilisée lors des anciens raccordements, effectués sur Chorus Pro (plutôt que sur PISTE) était : https://chorus-pro.gouv.fr:5443/service/dume/Attestations

récupererAttestations : Le profil d'acheteur souhaite récupérer les attestations connues de la solution DUME pour un opérateur économique.
demanderMiseAjour : Le profil d'acheteur souhaite mettre à jour la liste des attestations connues de la solution DUME.

Dernière mise à jour : mai 23, 2024

15004 DUME