Integrar una herramienta de verificación de certificados en su sitio web

Descripción general

Para reforzar al máximo la cadena de confianza en torno a la validez de los certificados que emite, tiene la posibilidad de integrar en su sitio web institucional una herramienta de verificación en línea de sus certificados. Se proporcionan un endpoint y un ejemplo de código fuente específicos para facilitar al máximo esta integración.

API de verificación

La funcionalidad de verificación es accesible mediante una llamada POST al siguiente endpoint: [API-URL]/v2/verifier.

Encabezado HTTP obligatorio: Content-Type: application/json

El cuerpo de la solicitud debe ser un objeto JSON válido con la siguiente estructura:

  • issuer: su ID del emisor (entero), o un array de identificadores si tiene varios (p. ej.: 253 o [2, 253])
  • url: La URL completa del certificado que se va a verificar
{
    "issuer": integer | [integer, ...],
    "url": "string"
}

Ejemplo de cuerpo de la solicitud:

{
	"issuer": [2, 253], 
    "url":"https://www.leaston.org/certificates/certificate.html?env=prod&key=756CF1818595DBED0045749D10DA231CE9BE48E67288B1553598F5F8D848C389cFZuL1JmT1EvOG5ZY09LM3c0YXprY2ZTMXRaeURvU3NpZk8vUW5oN00zWTVKVkpX"
}

Respuesta

El endpoint /v2/verifier devuelve un objeto JSON que contiene un código de respuesta, un mensaje de respuesta y todos los campos públicos del certificado, junto con el código HTTP correspondiente. Los códigos de respuesta de esta API v2 se indican entre paréntesis antes del mensaje de texto (p. ej.: (IS_OK) Url is valid).

Ejemplo de respuesta:

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

Éxito (código HTTP: 200)

La URL se reconoce como auténtica y como emitida a través de BCdiploma. Sin embargo, el certificado puede encontrarse en un estado que lo haga inaccesible de forma temporal o definitiva. Este estado se detalla en el mensaje de texto asociado al código de retorno.

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

Errores

Código HTTP: 400

INVALID_URL Given url is invalid
NO_KEY_IN_URL Given url does not contain key

Código HTTP: 403

UNAUTHORIZED_DOMAIN Domain is invalid
INCORRECT_ISSUER Url is valid but not issued by given issuer

Código HTTP: 404

UNKNOWN_KEY The key is unknown

Ejemplo de uso

Ejemplo con 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

         }'

Algoritmo

  1. Se verifica la validez de la URL proporcionada. Si la URL no es una URL válida, se devuelve un error 400.
  2. Se extrae la clave de la URL (búsqueda del patrón \b[a-zA-Z0-9]{128}\b). Si no se encuentra ninguna clave, se devuelve un error 400.
  3. Se verifica la existencia de la clave en nuestro registro. Si no se encuentra la clave, se devuelve un error 404.
  4. Se verifica el dominio de la URL proporcionada entre las distintas posibilidades (bcdiploma.com, evidenz.io, 3videnz.com o el dominio del emisor tal como está definido en la plantilla). Si el dominio no es válido, se devuelve un error 403.
  5. Si el emisor se especifica en la solicitud, se compara con el emisor real del documento. Si es diferente del emisor real del certificado, se devuelve un error 403.
  6. Se verifica el estado del documento. En esta fase el código de retorno es 200, pero el mensaje puede variar en función del estado del documento.
  7. Si la verificación se realiza correctamente, se devuelven todos los campos públicos del certificado, además del código de retorno y del mensaje

Ejemplo de integración en un sitio web

Este ejemplo básico se compone de 3 archivos. Para probarlo, cree los 3 archivos en un directorio de su elección copiando el contenido que figura a continuación.

  1. Un archivo HTML index.html que contiene la estructura de la página de verificación
index.html
<!DOCTYPE html>
<html lang="es">
<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>
  1. Un archivo JavaScript script.js que contiene la llamada a la API
script.js
// 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));
});
  1. Una hoja de estilos para dar formato a la página.
styles.css
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;
}

Preguntas frecuentes

Recibo un error que indica que el certificado no es válido, aunque sí existe en BCdiploma

Si la respuesta de la API devuelve el código INCORRECT_ISSUER (HTTP 403), significa que la URL del certificado es válida, pero que no fue emitida por el emisor indicado en su llamada a la API.

Compruebe que el valor del parámetro issuer corresponde a su ID del emisor en BCdiploma. Este identificador está disponible en la sección Administración de su backoffice de BCdiploma. Sustituya el valor utilizado en el ejemplo (253) por su propio ID del emisor.

¿Cómo personalizar los mensajes que se muestran al usuario?

Los mensajes devueltos por la API pueden sustituirse por los suyos. Para adaptarlos a su línea editorial, modifique el mapa VERIFIER_MESSAGES en el archivo script.js. Sustituya el valor null de un código por el mensaje de su elección: si el valor es null, se muestra el mensaje predeterminado devuelto por la API; de lo contrario, se utiliza su mensaje personalizado.

¿Cómo probar la integración en el entorno de pruebas (staging)?

Para apuntar al entorno de pruebas (staging) de BCdiploma, sustituya la URL de la API en script.js:

fetch('https://api-staging.bcdiploma.com/v2/verifier', {

en lugar de:

fetch('https://api.bcdiploma.com/v2/verifier', {