Dématérialisation des cautions de marché
-
Vue d'ensemble
Consommer l'API
La description des services proposés ci-après n’est que purement fonctionnelle. Les aspects techniques sont répertoriés dans les sections « Cas d’usage » qui sont plus détaillées.
Prérequis
- Le client doit avoir un contrat caution de marché valide avec la CEGC.
- Le client doit délivrer deux certificats (client assertion et user assertion) qu’il aura demandés et obtenus préalablement à une autorité de certification reconnue ; lors de la demande de GO-LIVE (validation technique faite par BPCE-IT).
Cinématique globale de consommation de l’API
Création d’une caution
Etape 1 : Le client doit s’identifier.
Etape 2 : Le client récupère la liste des agences via le web service GET /v1/clientBranches/search/bySiren afin de choisir l’agence pour laquelle il souhaiterait créer la caution. Un client peut ne pas avoir d’agence.
Etape 3 : Le client récupère la liste des contrats via le web service GET /v1/marketBondContracts/search/bysiren afin de choisir le contrat concerné par son besoin.
Etape 4 : Le client récupère la liste des modèles de texte rattachés au contrat via le web service GET /v1/bondTemplateTexts/search/byMarketBondContract afin de choisir le modèle correspondant à son besoin.
Etape 5 : Le client renseigne toutes les informations nécessaires à la création d’une caution et appelle le web service POST /v1/marketBonds/marketBondInitiate afin de créer sa caution.
Etape 6 : Le client reçoit un lien afin de télécharger son acte de garantie en temps réel.
Récupération d’une caution
Etape 1 : Le client doit s’identifier.
Etape 2 : Le client récupère la caution via le web service GET /v1/marketBonds/{marketBondId}.
Récupération d’un acte de garantie
Etape 1 : Le client doit s’identifier.
Etape 2 : Le client récupère une URL afin de télécharger l’acte de garantie via le web service POST /v1/marketBonds/{marketBondId}/prepareDownload.
Récupérer votre jeton
Principe
L’application cliente appelle le serveur d’authentification afin de récupérer un jeton.
Les éléments à envoyer au serveur d’autorisation sont les jetons Client_Assertion et User_Assertion. Ces deux jetons sont construits par le client à l’aide de ces deux certificats.
La partie sécurité entre le client et la CEGC est implémentée comme suit :
le client demande un jeton d’accès à l’API par l’intermédiaire d’un serveur d’authentification. Pour s’authentifier, le client devra adresser à ce serveur 2 jetons JWT distincts :
- Un jeton permettant d’identifier l’application à l’origine de l’appel : client_assertion
- Un jeton permettant d’identifier l’utilisateur à l’origine de la demande : user_assertion
Ces 2 jetons sont construits à partir de 2 certificats client (ou par le même certificat pour les 2 jetons). Il faudra donc au préalable fournir à la CEGC la ou les clé(s) publique(s).
Catégories
-
Vue d'ensemble
Obtenir la liste des agences
Obtenir la liste des agences rattachées à un client.
Cas d’usage
Ce service renvoie la liste des agences utilisables au sein de la demande de caution pour un client.
Le SIREN passé en paramètre devra faire partie de la structure du SIREN de l’entreprise à l’origine de cet appel.
Ce service prend en paramètre le SIREN du client et renvoie en réponse une liste contenant les informations suivantes :
- Id technique de l’agence.
- Description courte de l’agence.
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès (voir la rubrique « Vue d’ensemble » > « Récupération d’un jeton« ).
Exemple
Requête
GET /v1/clientBranches/search/bySiren
Résultat
Status code : 200
Description : La liste des agences répertoriées pour le SIREN passé en paramètre de la requête. L’élément identification.clientBranchId sera à utiliser au sein de la demande de caution pour indiquer l’agence pour laquelle sera faite la demande.
Body
« items »: [
{
« identification »: {
« clientBranchId »: « string »
},
« identity »: {
« clientBranchLabel »: « string »
}
}
]
}
Status code : 400
Description : l’erreur 400 « Bad request » sera retournée si le paramètre SIREN n’est pas
correct dans la requête.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 500
Description : Internal Server Error.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 503
Description : Internal Unavailable.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Obtenir la liste des contrats
Obtenir la liste des contrats éligibles à une demande de caution.
Cas d’usage
Ce service renvoie la liste des contrats éligibles à une demande de caution.
Il prend en paramètre un numéro de SIREN client CEGC et renvoie en réponse une liste contenant les informations suivantes :
- Identifiant du contrat.
- Numéro de contrat.
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès (voir la rubrique « Vue d’ensemble » > « Récupération d’un jeton« ).
Exemple
Requête
GET /v1/marketBondContracts/search/bySiren
Résultat
Status code : 200
Description : La liste des agences répertoriées pour le SIREN passé en paramètre de la requête. L’élément identification.clientBranchId sera à utiliser au sein de la demande de caution pour indiquer l’agence pour laquelle sera faite la demande.
Body
« items »: [
{
« identification »: {
« marketBondContractId« : « string »
},
« identity »: {
« customerReference« : « string »
}
}
]
}
Status code : 500
Description : Internal Server Error.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 503
Description : Internal Unavailable.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Obtenir la liste des modèles de texte
Obtenir la liste des modèles de texte rattachés à un contrat.
Cas d’usage
Ce service renvoie la liste des modèles de texte rattachés à un contrat d’un client.
Il prend en paramètre un numéro de contrat CEGC et renvoie en réponse une liste contenant les informations suivantes :
- Identifiant du modèle de texte.
- Description courte du modèle.
- Description longue du modèle.
- Identifiant du type de garantie.
- Description courte du type de la garantie.
- Type de Marché.
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès (voir la rubrique « Vue d’ensemble » > « Récupération d’un jeton« ).
Exemple
Requête
GET /v1/bondTemplateTexts/search/byMarketBondContract
Résultat
Status code : 200
Description : La réponse contient un ensemble de modèles de texte utilisables sur le contrat demandé en entrée. L’élément identification.marketBondTextId contient la valeur à utiliser lors de la demande de caution. Il s’agit de l’identifiant du texte qui sera utilisé pour la caution lors de la demande de caution.
Body
{
« items »: [
{
« identification »: {
« marketBondTextId »: « string »
},
« identity »: {
« textLabel »: « RESTITUTION D’ACOMPTE MARCHE PUBLIC GARANTIE A PREMIERE DEMANDE AVEC ECHEANCE »,
« textShortLabel« : « RA – PUB GAPD AVEC ECH« ,
« warrantTypeId« : « string »,
« warrantTypeShortLabel« : « string »,
« marketType« : « string »
}
]
}
Status code : 400
Description : l’erreur 400 « Bad request » pourra se produire en cas d’absence du paramètre query marketBondContractId. Ou si la valeur de ce paramètre n’est pas renseignée.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 500
Description : Internal Server Error.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 503
Description : Internal Unavailable.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Créer une caution
Créer une caution pour un client ou une agence d’un client.
Cas d’usage
Ce service permet d’effectuer une demande de caution de marché à la CEGC.
La réponse contient l’ensemble des éléments demandés pour la caution ainsi qu’un lien pour télécharger le document généré par la CEGC. Le lien à récupérer est : marketBond.characteristics.marketBondDownloadLink.href.
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès (voir la rubrique « Vue d’ensemble » > « Récupération d’un jeton« ).
Exemple
Requête
POST /v1/marketBonds/marketBondInitiate
Résultat
Status code : 201
Description : Le code retour 201 signifie que la demande de caution est prise en compte et que le document relatif à cette caution est disponible pour téléchargement.
Body
{« marketBond »:
{« characteristics »: {
« marketBondContractId »: « string »,
« siren »: « string »,
« marketBondId »: « string »,
« marketBondDownloadLink »: {
« href »: « string »
},
« bondDetail »: {
« effectiveBondDate »: « string »,
« bondDueDate »: « string »,
« marketBondTextId »: « string »,
« warrantType »: « string »,
« bondAmount »: {
« value »: 0,
« currencyCode »: « string »
},
« provisionnalReleaseDate »: « string »,
« clientBondId »: « string »,
« clientComment »: « string »,
« clientBranchId »: « string »,
« additionalOption »: « string »,
« optionReference »: « string »
},
« marketDetail »: {
« type »: « string »,
« amount »: {
« value »: 0,
« currencyCode »: « string »
},
« date »: « string »,
« dueDate »: « string »,
« workNature »: « string »,
« reference »: « string »
},
« recipientDetail »: {
« siren »: « string »,
« companyName »: « string »,
« nationality »: « string »,
« rCSPlace »: « string »,
« juridicCategory »: « string »,
« shareCapital »: « string »,
« postAddress »: {
« location »: [
« string »
],
« postalCode »: « string »,
« countrylso2 »: « string »
},
« headOfficeTown »: « string »
},« addressee »: {
« legalSituation »: « string »,
« physicalAddressee »: {
« nationality »: « string »,
« livingCountry »: « string »,
« name »: « string »,
« surname »: « string »,
« civility »: « string »,
« postAddress »: {
« location »: [
« string »
],
« postalCode »: « string »,
« countrylso2 »: « string »
}
},
« companyAddressee »: {
« siren »: « string »,
« companyName »: « string »,
« nationality »: « string »,
« postAddress »: {
« location »: [
« string »
],
« postalCode »: « string »,
« countrylso2 »: « string »
},
« town »: « string »
}
}
},
« response »: {
« interactionId »: « string »,
« code »: « string »,
« label »: « string »
}
}
}
Status code : 400
Description : L’erreur 400 « Bad request » pourra être renvoyée dans le cas où la demande de caution ne respecte pas la définition.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 500
Description : Internal Server Error.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 503
Description : Internal Unavailable.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Récupérer un acte de caution
Demander l’URL de téléchargement d’une caution.
Cas d’usage
Ce service permet de préparer une caution (le texte) au téléchargement. Le texte mis à disposition est le même que celui proposé lors de la création de la caution.
Il prend en paramètre un numéro de caution CEGC et renvoie en réponse les informations suivantes :
- Numéro de la caution de marché.
- Lien permettant de télécharger la caution.
- Date de création de la caution.
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès (voir la rubrique « Vue d’ensemble » > « Récupération d’un jeton« ).
Exemple
Requête
POST /v1/marketBonds/{marketBondId}/prepareDownload
Résultat
Status code : 200
Body
{
« prepareDownload »: {
« characteristics »: {
« marketBondId »: « string »,
« marketBondDownloadLink »: « string »
},
« response »: {
« interactionId »: « string »,
« code »: « string »,
« label »: « string »
}
}
}
Status code : 500
Description : Internal Server Error.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 503
Description : Internal Unavailable.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Récupérer une caution
Récupérer le détail d’une caution.
Cas d’usage
Ce service renvoie les informations d’une caution. Il prend en paramètre le numéro de la caution CEGC et renvoie la liste des informations suivantes :
- Numéro de la caution de marché.
- Numéro du contrat.
- SIREN du client.
- Date d’effet de la garantie.
- Date d’échéance de la caution.
- Description courte du modèle utilisé.
- Id Ged de l’acte de garantie.
- Code type de garantie (RA, RG, GBF etc..).
- Montant cautionné.
- Date prévisionnelle de mainlevée.
- Référence de la caution chez le client.
- Id agence Client.
- Libellé long de l’agence.
- Option complémentaire/périmètre.
- Référence du document objet de l’option complémentaire (tranche/commande/avenant).
- Statut de la caution.
- Référence marché.
- Nature travaux.
- Montant du marché.
- Date de réception des travaux.
- Raison sociale client.
- Type de marché : public ou privé.
- SIREN bénéficiaire.
- Date du marché.
- Date de création de la caution.
Prérequis
Pour procéder à cette requête, il est nécessaire de remplir les prérequis d’éligibilité et d’avoir récupéré le jeton d’accès (voir la rubrique « Vue d’ensemble » > « Récupération d’un jeton« ).
Exemple
Requête
GET /v1/marketBonds/{marketBondId}
Résultat
Status code : 200
Description : Le code retour 201 signifie que la demande de caution est prise en compte et que le document relatif à cette caution est disponible pour téléchargement.
Body
{
« marketBond »: {
« identification »: {
« marketBondId »: « string »
},
« bondDetail »: {
« effectiveBondDate »: « string »,
« bondDueDate »: « string »,
« marketBondTextId »: « string »,
« warrantType »: « string »,
« bondAmount »: {
« value »: 0,
« currencyCode »: « string »
},
« provisionnalReleaseDate »: « string »,
« clientBondId »: « string »,
« clientComment »: « string »,
« clientBranchId »: « string »,
« additionalOption »: « string »,
« optionReference »: « string »,
« marketBondContractId »: « string »,
« siren »: « string »,
« bondStatus »: « string »
}
}
}
Status code : 404
Description :No market bond found.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 500
Description : Internal Server Error.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Status code : 503
Description : Internal Unavailable.
Body
{
« errors« : [
{
« code »: « string »,
« message »: « string »,
« attribute »: « string »,
« additionalInformation »: « string »
}
]
}
Console Try-it
Cette section sera prochainement disponible.