Intégrer un outil de vérification des certificats à votre site
Vue d'ensemble
Pour maximiser la chaine de confiance autour de la validité des certificats que vous émettez, vous avez la possibilité d'intégrer à votre site institutionnel un outil de vérification en ligne de vos certificats. Un point de terminaison et un exemple de code source dédiés sont fournis pour faciliter au maximum cette intégration.
API de vérification
La fonctionnalité de vérification est accessible via un appel POST au point de terminaison suivant : [API-URL]/v2/verifier.
Entête HTTP obligatoire : Content-Type: application/json
Le corps de la requête doit être un objet JSON valide avec la structure suivante :
- issuer : votre identifiant émetteur (entier), ou un tableau d'identifiants si vous en avez plusieurs (ex. :
253ou[2, 253]) - url : L'URL complète du certificat à vérifier
{
"issuer": integer | [integer, ...],
"url": "string"
}
Exemple de corps de la requête:
{
"issuer": [2, 253],
"url":"https://www.leaston.org/certificates/certificate.html?env=prod&key=756CF1818595DBED0045749D10DA231CE9BE48E67288B1553598F5F8D848C389cFZuL1JmT1EvOG5ZY09LM3c0YXprY2ZTMXRaeURvU3NpZk8vUW5oN00zWTVKVkpX"
}
Réponse
Le point de terminaison /v2/verifier retourne un objet JSON contenant un code de réponse, un message de réponse, ainsi que tous les champs publics du certificat, accompagnés du code HTTP approprié. Les codes de réponse de cette API v2 sont indiqués entre parenthèses avant le message textuel. (ex. : (IS_OK) Url is valid).
Exemple de réponse :
{
"code": "IS_OK",
"message": "Url is valid",
"templateId": "1x0C",
"templateLabel": {
"en": "Strategic Artificial Intelligence for Business Applications",
"fr": "Intelligence Artificielle Stratégique pour les Applications Business"
},
"data": {
"ID": "1",
"Email": "support@bcdiploma.com",
"firstName": "Jane",
"lastName": "Doe",
"obtentionDate": "2025-10-02",
"ExpirationDate": "2125-01-03",
"assessment": "",
"linkLabel": "",
"linkURL": ""
},
"attributedTo": "Jane Doe"
}
Succès (Code HTTP : 200)
L'URL est reconnue comme étant authentique et comme ayant été émise via BCdiploma. Cependant, le certificat peut être dans un état le rendant inaccessible temporairement ou définitivement. Cet état est détaillé dans le message textuel associé au code de retour.
IS_OK Url is valid
IS_EXPIRED Url is valid but certificate has expired
IS_DISABLED Url is valid but certificate has been disabled
IS_DELETED Url is valid but certificate has been subject to the right of oblivion
NON_VERIFIED_ISSUER Url is valid, but the certificate's issuer has not been verified yet
Échecs
Code HTTP : 400
INVALID_URL Given url is invalid
NO_KEY_IN_URL Given url does not contain key
Code HTTP : 403
UNAUTHORIZED_DOMAIN Domain is invalid
INCORRECT_ISSUER Url is valid but not issued by given issuer
Code HTTP : 404
UNKNOWN_KEY The key is unknown
Exemple d'utilisation
Exemple cURL
curl -X POST https://api.bcdiploma.com/v2/verifier \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.leaston.org/certificates/certificate.html?env=prod&key=756CF1818595DBED0045749D10DA231CE9BE48E67288B1553598F5F8D848C389cFZuL1JmT1EvOG5ZY09LM3c0YXprY2ZTMXRaeURvU3NpZk8vUW5oN00zWTVKVkpX",
"issuer": 253
}'
Algorithme
- La validité de l'URL fournie est vérifiée. Si l'URL n'est pas une URL valide, alors erreur 400.
- La clé est extraite de l'URL (recherche du motif
\b[a-zA-Z0-9]{128}\b). Si aucune clé n'est trouvée, alors erreur 400. - L'existence de la clé dans notre registre est vérifiée. Si la clé n'est pas trouvée, alors erreur 404.
- Le domaine de l'URL fournie est vérifié parmi les différentes possibilités (bcdiploma.com, evidenz.io, 3videnz.com, ou le domaine de l'émetteur tel que défini dans le template). Si le domaine n'est pas valide, alors erreur 403.
- Si l'émetteur est précisé dans la requête, il est comparé à l'émetteur réel du document. S'il est différent de l'émetteur réel du certificat, alors erreur 403.
- Le statut du document est vérifié. À ce stade le code de retour est 200, mais le message peut varier en fonction du statut du document.
- Si la vérification est un succès, tous les champs publics du certificat sont retournés en plus du code de retour et du message
Exemple d'intégration sur un site web
Cet exemple basique est composé de 3 fichiers. Créez les 3 fichiers dans un répertoire de votre choix en copiant leurs contenus ci-dessous pour le tester.
- Un fichier HTML
index.htmlcontenant la structure de la page de vérification
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>BCdiploma Verifier</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>
<main>
<div class="container">
<input type="text" id="inputField" placeholder="Copy the URL to verify">
<button id="submitButton">Verify</button>
<div id="result"></div>
</div>
</main>
<script src="script.js"></script>
</body>
</html>
- Un fichier de javascript
script.jscontenant l'appel API
// Override this map to customize messages displayed for each return code.
const VERIFIER_MESSAGES = {
IS_OK: null, // null = use the message from the API response
IS_EXPIRED: null,
IS_DISABLED: null,
IS_DELETED: null,
NON_VERIFIED_ISSUER: null,
INVALID_URL: null,
NO_KEY_IN_URL: null,
UNKNOWN_KEY: null,
UNAUTHORIZED_DOMAIN: null,
INCORRECT_ISSUER: null,
};
function getDisplayMessage(responseBody) {
const customMessage = VERIFIER_MESSAGES[responseBody.code];
return customMessage !== null && customMessage !== undefined
? customMessage
: responseBody.message;
}
document.getElementById('submitButton').addEventListener('click', function() {
var inputValue = document.getElementById('inputField').value;
fetch('https://api.bcdiploma.com/v2/verifier', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({url: inputValue, issuer: 253}) // Replace this value with your own issuer ID
})
.then(response => response.json())
.then(data => {
var resultDiv = document.getElementById('result');
resultDiv.textContent = getDisplayMessage(data);
})
.catch(error => console.error('Error :', error));
});
- Une feuille de style pour la mise en forme.
body {
font-family: Arial, sans-serif;
margin: 0;
padding: 0;
}
header {
background-color: #2E3B4E;
padding: 20px;
text-align: center;
}
header img {
max-width: 100%;
}
main {
display: flex;
justify-content: center;
align-items: center;
height: 100vh;
background-color: #F6F8F9;
}
.container {
text-align: center;
}
input {
padding: 10px;
margin-right: 10px;
border: 1px solid #ccc;
border-radius: 4px;
font-size: 16px;
}
button {
padding: 10px 20px;
background-color: #2E3B4E;
color: #fff;
border: none;
border-radius: 4px;
font-size: 16px;
cursor: pointer;
}
button:hover {
background-color: #1E2736;
}
FAQ
Je reçois une erreur indiquant que le certificat est invalide alors qu'il existe bien dans BCdiploma
Si la réponse de l'API retourne le code INCORRECT_ISSUER (HTTP 403), cela signifie que l'URL du certificat est valide mais qu'elle n'a pas été émise par l'émetteur renseigné dans votre appel API.
Vérifiez que la valeur du paramètre issuer correspond bien à votre identifiant émetteur dans BCdiploma. Cet identifiant est disponible dans la section Administration de votre back-office BCdiploma. Remplacez la valeur utilisée dans l'exemple (253) par votre propre identifiant émetteur.
Comment personnaliser les messages affichés à l'utilisateur ?
Les messages retournés par l'API peuvent être surchargés par les votres. Pour les adapter à votre charte éditoriale, modifiez la map VERIFIER_MESSAGES dans le fichier script.js. Remplacez la valeur null d'un code par le message de votre choix : si la valeur est null, le message par défaut retourné par l'API est affiché ; sinon, c'est votre message personnalisé qui est utilisé.
Comment tester l'intégration sur l'environnement de staging ?
Pour pointer vers l'environnement de staging BCdiploma, remplacez l'URL de l'API dans script.js :
fetch('https://api-staging.bcdiploma.com/v2/verifier', {
à la place de :
fetch('https://api.bcdiploma.com/v2/verifier', {