Loading....
Print Friendly, PDF & Email

DESCRIPTION

The ESPD Service’s APIs enable publishers to integrate all of the ESPD Service’s functionalities to the buyer profiles that they administer.

The offered functionalities enable buyers and economic operators to conduct ESPD data entry, completion and consultation. Each functionality is carried out by an operation which depends on one of the following APIs:

  • API DUME A (for Buyers ESPDs)
  • API DUME OE (for Economic Operators ESPDs)
  • API Métadonnées (to only intervene on an ESPD’s metadata)
  • API Attestations (to retrieve certificates)
  • API Données (to retrieve data from third party sources such as API Entreprises)
  • API Référentiels (to obtain the ESPD Service’s referentials)
  • API eCertis (to obtain eCertis referentials)

This page presents the ESPD Service’s operations, listed by API.

Please note that it is up to each publisher to design its ergonomics and kinematics of use of the ESPD for its buyer profile, as the ESPD Service’s operations simply enable the exchange of the ESPD’s constituent data, without prejudice to the human-computer interaction implemented by the various marketplaces.

Operating principles of the ESPD Service's presented services

The presented services are organized by field and type of operation.

The use of global URIs enables the identification of which field the requested operations apply to. As a reminder, URI stands for Uniform Resource Identifier; it is a string of characters designed for the identification of a physical or abstract resource over a network (for example a Web resource), and whose syntax meets an Internet standard that was implemented for the World Wide Web.

List of the ESPD Service’s API URIs

FieldCorresponding URI
Données (Data)https://chorus-pro.gouv.fr:5443/service/dume/donnees
DUME Acheteur (Buyer ESPD)https://chorus-pro.gouv.fr:5443/service/dume/dumeA
DUME Opérateur économique (Economic operator ESPD)https://chorus-pro.gouv.fr:5443/service/dume/dumeOE
Métadonnées (Metadata)https://chorus-pro.gouv.fr:5443/service/dume/metadonnees
Attestations (Certificates)https://chorus-pro.gouv.fr:5443/service/dume/attestations
Référentiels (Referentials)https://chorus-pro.gouv.fr:5443/service/dume/referentiels

An input parameter called operation enables to determine which functionalities you wish to activate (example: rechercherDume, enregistrerDume, fusionnerDume, recupererModelDume…). Please note that a single operation can be applied to one or multiple fields.

Thus, for cases of similar uses between DUME A and DUME OE, the same operation name will be used. The differentiation will be made at the level of the URI under which the operation is carried out. For example, if you enter « opération=enregistrerDume » whilst using URI “../dumes/dumeA”, a DUME A (Buyer ESPD) will be recorded.

The table below illustrates some cases when operations can be carried out on one or multiple URIs:

OperationApplicable field(s)
rechercherDume (search ESPD)DUME A ; DUME OE (Buyer ESPD ; Economic Operator ESPD)
enregistrerDume (record ESPD)DUME A ; DUME OE (Buyer ESPD ; Economic Operator ESPD)
fusionnerDume (merge ESPD)DUME OE (Economic Operator ESPD)
recupererModelDume (retrieve ESPD)DUME A ; DUME OE (Buyer ESPD ; Economic Operator ESPD)
etc.etc.

The input parameter “operation” is always complemented by other parameters (for example, the identification of the buyer profile) enabling the execution of the request. In the case when multiple identical parameters are specified, then only the last one is considered by the solution.

As a reminder, APIs enable the use of the ESPD Service’s referential. Their implementation also requires design work on the publisher’s part in order to offer simpler and more user-adapted functionalities.

Calls formalism:

Service calls are structured around a JSON feed which encapsulates the XML file that contains the ESPD. Please note that the only dematerialized ESPDs recognized by regulations are XML format ESPDs, thus complying with formalism as it is defined by the European Union. Any other format for an ESPD (example: PDF) only counts as a copy, and wouldn’t constitute an original of probative value.

The JSON feed contains the name of the operation to execute, input parameters enabling the call to be executed as well as complementary data to the ESPD called “metadata”. They allow either the assurance of good ESPD technical management, either to provide additional information that is not in the XML file. In order to know the exact content of the metadata, it is necessary to consult the API list.

Replies given to the calls made to the ESPD Service follow the same rules. However, JSONs sent by the ESPD Service send back “output parameters” by way of data. Input and output parameters, specific to each call, will be presented in each API’s description later in this document.

The JSON’s formalism is standardized:

  • a request is enclosed in brackets: {}
  • each parameter or operation is defined by a title put between quotation marks: “ ”
  • each data is enclosed in quotation marks: “ ”
  • each set of title and data is separated from the next by a comma: ,
  • the last field of the call must not be followed by a comma, the comma being interpreted as a prelude to the entry of a new field,
  • the XML is entered encoded in base 64 in the JSON.

Malformed requests lead to error messages which specify the nature of the identified issue.

You will find the most frequent error codes below:

ERROR CODEDescriptionAPI output
PARAM_MISSINGThe parameter is in the request, but is not expected by the API {
"type": "ERREUR",
"code": "PARAM_MISSING",
"message": "Le champs 'xxx' n'existe pas et ne doit pas être renseigné"
},
PARAM_REQUIREDThe parameter is not in the request, but is expected by the API{
"type": "ERREUR",
"code": "PARAM_REQUIRED",
"message": "Le champs 'xxx' est manquant"
},
PARAM_MAXLENGTHThe length of the expected parameter's value is higher than the expected value{
"type": "ERREUR",
"code": "PARAM_MAXLENGTH",
"message": "Le champs 'xxx' est mal formaté : longueur maximale 18"
},
PARAM_FORMATThe value of the input parameter's format does not comply with the expected format {
"type": "ERREUR",
"code": "PARAM_FORMAT",
"message": "Le champs 'xxx' est mal formaté"
},
PARAM_MINLENGTHThe length of the expected parameter's value is lower than the expected value{
"type": "ERREUR",
"code": "PARAM_MINLENGTH",
"message": "Le champs 'xxx' est mal formaté : longueur minimale 1"
}
InternalErrorSystem error{
"type": "ERREUR",
"code": "InternalError",
"message": "Erreur Interne serveur"
}

The request below enables the recording of a buyer ESPD with validated status in the ESPD Service referential. If the DUME A (Buyer ESPD) has never been recorded in the referential before, there is no need to enter an ID number in the input JSON.

Once the API call is done, the ESPD Service stores the recorded ESPD’s XML into the ESPD Service base and sends a unique identification number back to the buyer.

List of operations by API

The APIs presented below have been available since April 3rd 2018. They are open to publishers in connection with the ESPD Service. For more information about connecting in production or in qualification, please check the following page: https://communaute.chorus-pro.gouv.fr/documentation/acces-aux-api-du-service-dume/.

As a reminder, the operations carried out on the DUME A (Buyer ESPD) are carried out at the following URI: https://chorus-pro.gouv.fr:5443/service/dume/dumeA

  • recupererModelDume: enables to retrieve a blank Buyer ESPD template.
  • recupererDumeFormate: enables to retrieve an existing Buyer ESPD at the requested format.
  • enregistrerDume: enables to record a Buyer ESPD in the ESPD Service and, if appropriate, to obtain an identifier.
  • rechercherDumes: enables to search for ESPDs in the ESPD Service.
  • creerDumeSimple: enables to request the creation of a « simple » ESPD, matching the criteria of procedures that are carried out within the framework of simplified procurement procedures.

The URI for the Economic Operator ESPD API is the following: https://chorus-pro.gouv.fr:5443/service/dume/dumeOE

  • recupererModelDume : enables to retrieve a blank Economic Operator ESPD template.
  • recupererDumeFormate: enables to retrieve an existing Economic Operator ESPD at the requested format.
  • enregistrerDume: enables to record an Economic Operator ESPD in the ESPD Service and, if appropriate, to obtain an identifier.
  • fusionnerDumeAvecDonneesEntreprise: enables to merge an Economic Operator ESPD with a Buyer ESPD and/or with the company’s public or private data.
  • creerdumeOEavecSiretOE: enables to retrieve an Economic Operator ESPD XML with an identifier, complemented with the economic operator’s public or private data.
  • fusionnerDume: enables to retrieve the merging of an Economic Operator ESPD and a Buyer ESPD whose numbers or XML it has, complemented with BOAMP (Bulletin Officiel des Annonces de Marchés Publics, “Official Journal of Public Procurement Notices”) data.
  • rechercherDUME: enables to retrieve ESPD IDs that meet a number of criteria (ID_consultation, SIRET OE, …).
  • telechargerDUMEAvecPJ: enables to retrieve the ESPD with attached files and certificates.

The URI for the ESPD Metadata API is the following: https://chorus-pro.gouv.fr:5443/service/dume/métadonnées

  • mettreAJourDume: enables to update the metadata related to a Buyer ESPD or an Economic Operator ESPD.

The URI for the certificates API is the following: https://chorus-pro.gouv.fr:5443/service/dume/donnees

  • recupererDonneesOE: enables to retrieve an Economic Operator’s public or private data.

The URI for the referential API is the following: https://chorus-pro.gouv.fr:5443/service/dume/Referentiel

Last Update: June 4, 2019  

752    ESPD  
Back To Top