Gestión de plantillas

Recuperar la lista de plantillas

Esta API permite recuperar la lista de plantillas de un emisor en formato JSON. Se accede a ella mediante una llamada GET al endpoint [API-URL]/issuer/XXX/templates, donde XXX es el identificador del emisor. Puede obtener su identificador de emisor aquí.

Parámetros opcionales:

• template-name: filtra la respuesta para devolver únicamente las plantillas de certificado cuyo nombre contiene la cadena indicada como parámetro (sin distinguir entre mayúsculas y minúsculas)

Ejemplo: https://api.bcdiploma.com/issuer/2/templates?template-name=en

Recuperar la definición de una plantilla

Esta API permite recuperar la definición de una plantilla de un emisor. Se accede a ella mediante una llamada GET al endpoint [API-URL]/issuer/XXX/template/YYY/json, donde XXX es el identificador del emisor y YYY es el identificador de la plantilla.

Ejemplo de llamada: https://api.bcdiploma.com/issuer/2/template/1x04/json

Recuperar la lista de campos variables de una plantilla

Esta API permite recuperar los campos variables de una plantilla de un emisor. Se accede a ella mediante una llamada GET al endpoint [API-URL]/issuer/XXX/template/YYY/fields, donde XXX es el identificador del emisor y YYY es el identificador de la plantilla.

De forma predeterminada, la respuesta se devuelve como texto, con los campos variables separados por ;. Si se añade ?Content-Type=application%2Fjson a la llamada GET, el resultado se devolverá en formato JSON.

Ejemplo de llamada: https://api.bcdiploma.com/issuer/2/template/1x04/fields?Content-Type=application%2Fjson

Creación y actualización de una plantilla de microcertificación

Las plantillas de microcertificación se pueden añadir o actualizar mediante una llamada POST al endpoint [API-URL]/template/mc.

El cuerpo de la solicitud es un formulario multipart que contiene las siguientes partes:

• json: el JSON que contiene la definición de la plantilla. Obligatorio tanto en la creación como en la actualización.

• badgeImage: un archivo que contiene la imagen principal de la microcertificación. Obligatorio en la creación y opcional en la actualización. Formatos admitidos: png, svg. Tamaño óptimo para el PNG: 240px * 240px.

• partnerImage: un archivo que contiene el logotipo del socio. Formato admitido: png. Opcional.

• issuerImage: un archivo que contiene el logotipo del emisor. Formato admitido: png. Opcional.

Creación de una plantilla de microcertificación

El cuerpo de una solicitud de creación de plantilla de microcertificado es un formulario multipart que incluye obligatoriamente una parte badgeImage y una parte json. Esta parte json, que contiene la definición de la plantilla, es un JSON que contiene los siguientes elementos:

Obligatorios:

• mode: en modo “creación”, debe tener el valor add
• label: el título de la plantilla. Puede ser una cadena de caracteres simple o un JSON con el título en diferentes idiomas.
• json: los textos y los campos dinámicos de la plantilla. Para reducir la carga útil, los campos de la plantilla están codificados (A, B, C, etc.). La tabla de correspondencia entre los campos y su código se proporciona más adelante.
• DefaultLanguage: el idioma predeterminado de la plantilla en formato ISO-2. Debe ser coherente con los códigos de idioma presentes en el elemento json.
• badge: un JSON que contiene los códigos de idioma como claves y el nombre o los nombres de archivo indicados en la parte badgeImage del formulario multipart, para cada idioma de la plantilla (incluso si la imagen es la misma sea cual sea el idioma).

Opcionales:

• partnerLogo: un JSON que contiene los códigos de idioma como claves y el nombre o los nombres de archivo indicados en la parte partnerImage del formulario multipart, para cada idioma de la plantilla.
• issuerLogo: un JSON que contiene los códigos de idioma como claves y el nombre o los nombres de archivo indicados en la parte issuerImage del formulario multipart, para cada idioma de la plantilla.
• notification: lista de las direcciones de correo electrónico a las que se debe notificar tras la creación de la plantilla, separadas por el carácter ,.
• cstyle: describe la disposición y el estilo deseados para la plantilla. El funcionamiento de este elemento se describe en un apartado específico más adelante.

Si la operación se realiza correctamente, el endpoint devolverá el identificador de la nueva plantilla en forma de cadena de caracteres, por ejemplo 1x49.

Ejemplo de contenido válido de una parte json de un formulario multipart de creación de plantilla de microcertificado:

• Con un título bilingüe
• Bilingüe, con en como idioma predeterminado
• Que permite tener una imagen de insignia y una imagen de socio diferentes según el idioma
• Con una disposición en 3 columnas, con un estilo inspirado en el tema “Midnight Vision” disponible en el backoffice.
• Con una notificación por correo electrónico de la creación de la plantilla cuando esta sea efectiva

{
  "mode": "add",
  "label": {
    "en": "BCdiploma Expert",
    "fr": "Expert BCdiploma"
  },
  "json": {
    "A": {
      "en": "Issuing body:",
      "fr": "Émetteur :"
    },
    "T": "Leaston University",
    "B": {
      "en": "Partner endorsement:",
      "fr": "Partenaire :"
    },
    "E": {
      "en": "Other partners:",
      "fr": "Autres partenaires :"
    },
    "F": "Blockchain Certified Data",
    "G": {
      "en": "Micro-certification issued to",
      "fr": "Micro-certification délivrée à"
    },
    "I": {
      "en": "on:",
      "fr": "le :"
    },
    "K": {
      "en": "Expiration date:",
      "fr": "Date d'expiration :"
    },
    "M": {
      "en": "Outcomes",
      "fr": "Résultats"
    },
    "description": {
      "en": "Holders of this micro-certification have a thorough knowledge of the world of digital credentials and associated open standards such as Open Badges. Micro-credential holders also understand the concept of the BCdiploma templates and know how to implement it to build customized micro-credentials for any institution.",
      "fr": "Les titulaires de cette micro-certification ont une connaissance approfondie du monde des attestations numériques et des normes ouvertes associées, telles que les Open Badges. Les titulaires de cette micro-certification comprennent également le concept des modèles BCdiploma et savent comment les mettre en œuvre pour créer des micro-credentials personnalisés pour n'importe quelle institution."
    },
    "N": {
      "en": "Competency / Skills",
      "fr": "Compétences / Aptitudes"
    },
    "skills": {
      "en": "Blockchain basics;Micro-Credentials;Digital Credentials;Open Badges",
      "fr": "Blockchain basics;Digital Credentials;Micro-Credentials;Open Badges"
    },
    "O": {
      "en": "Assessment",
      "fr": "Évaluation"
    },
    "criteria": {
      "en": "Completion of the BCdiploma backoffice training session including issuing and sharing micro-credentials on the blockchain.",
      "fr": "Participation à la session de formation au backoffice de BCdiploma, incluant l'émission et le partage de micro-credentials sur la blockchain."
    },
    "Q": {
      "en": "Component of",
      "fr": "Composant de"
    }
  },
  "DefaultLanguage": "en",
  "badge": {
    "en": "badge_en.svg",
    "fr": "badge_fr.svg"
  },
  "partnerLogo": {
    "en": "partner.png",
    "fr": "partner.png"
  },
  "issuerLogo": {
    "en": "issuer.png",
    "fr": "issuer.png"
  },
  "cstyle": "{l:'threeCol',R:{f:'Raleway',g:'#25225BFF'},T:{w:500,s:'32px',g:'#FFFFFF00',c:'#FFFFFFFF'},I:{c:'#D1D4D5'},U:{w:700,s:'16px',c:'#6259F4FF'},P:{w:400,s:'16px',c:'#FFFFFFFF'},N:{w:700,s:'24px',c:'#FFFFFFFF'},K:{w:400,s:'16px',g:'#FFFFFF00',c:'#FFFFFFFF',b:'1px #6259F4FF',r:'5px'},L:{w:400,s:'16px',c:'#6259F4FF'},S:{g:'#000000FF'}}",
  "notification": "support@bcdiploma.com"
}

Actualización de una plantilla de microcertificado

El cuerpo de una solicitud de actualización de plantilla de microcertificado es un formulario multipart que incluye obligatoriamente una parte json. Esta parte json, que contiene la definición de la plantilla, es un JSON que contiene los siguientes elementos:

Obligatorios:

• mode: en modo actualización, debe tener el valor update
• id: el ID de la plantilla que se va a modificar
• json: los textos y los campos dinámicos de la plantilla. Tenga en cuenta que, para reducir la carga útil, pueden incluirse únicamente los textos y los campos dinámicos de la plantilla que se deban actualizar.
• DefaultLanguage: el idioma predeterminado de la plantilla en formato ISO-2. Debe ser coherente con los códigos de idioma presentes en el elemento json.

Opcionales: label, badge, partnerLogo, notification, cstyle

Ejemplo de contenido válido de una parte json de un formulario multipart de actualización de plantilla de microcertificado:

• Con una actualización del título de la microcertificación
• Sin actualización de la definición de la plantilla

{
  "mode": "update",
  "id": "1x49",
  "label": "BCdiploma Expert",
  "json": {},
  "DefaultLanguage": "en"
}

Tabla de correspondencia código/campo utilizada en la descripción del modelo de datos de los microcertificados

Para reducir la carga útil, los nombres de los campos que componen la plantilla de un microcertificado se sustituyen por un código (una letra o una palabra) en el json esperado durante la creación o la actualización de una plantilla de microcertificado. A continuación se ofrece una tabla de referencia de estos códigos. La mayoría de los campos son obligatorios. El endpoint devolverá un error 400 si faltan campos obligatorios.

Personalización de la disposición y del estilo de las plantillas mediante “cstyle”

La disposición (elección del número de columnas de la plantilla o elección de la plantilla a medida proporcionada por BCdiploma, si cuenta con una) y el estilo (fuente, color, tamaño, etc. de los elementos gráficos que componen su plantilla) pueden controlarse mediante la API a través del elemento cstyle contenido en la parte json del formulario multipart.

El elemento cstyle se compone de un elemento layout, que describe la disposición elegida, y de elementos de estilo que permiten modificar la presentación de los componentes. El elemento layout puede tomar uno de los siguientes valores:

• oneCol: disposición en 1 sola columna
• legacy: disposición en 2 columnas
• threeCol: disposición en 3 columnas
• CUSTOM_LAYOUT: disposición a medida facilitada por los equipos de BCdiploma, si cuenta con una. Esta disposición no admite la modificación de los elementos de estilo.

En el elemento cstyle puede especificar únicamente los elementos que desee sobrescribir con respecto a la configuración predeterminada.

A continuación se muestran la presentación y el estilo predeterminados que se utilizan al crear una plantilla de microcertificado desde el backoffice. En ellos se representa el conjunto de los componentes y atributos css que se pueden modificar mediante la API:

{
  "layout": "legacy",
  "root": {
    "fontFamily": "Roboto",
    "background": "#f7f7f7"
  },
  "title": {
    "fontWeight": 300,
    "fontSize": "32px",
    "background": "#FFF",
    "color": "#005E7A"
  },
  "splitter": {
    "color": "#D1D4D5"
  },
  "subTitle": {
    "fontWeight": 700,
    "fontSize": "16px",
    "color": "#005E7A"
  },
  "paragraph": {
    "fontWeight": 400,
    "fontSize": "16px",
    "color": "#002432"
  },
  "graduateName": {
    "fontWeight": 700,
    "fontSize": "24px",
    "color": "#002432"
  },
  "skill": {
    "fontWeight": 400,
    "fontSize": "18px",
    "background": "#fff",
    "color": "#005E7A",
    "border": "1px #005E7A",
    "borderRadius": "0px"
  },
  "link": {
    "fontWeight": 400,
    "fontSize": "16px",
    "color": "#005E7A"
  },
  "section": {
    "background": "#FFF"
  }
}

Para reducir la carga útil, el elemento cstyle utiliza una sintaxis JSON5 comprimida con códigos cortos que corresponden a los elementos gráficos de la plantilla y a sus atributos CSS. Esta es la tabla de correspondencia de estos códigos. Tenga en cuenta que los códigos en mayúsculas corresponden a los componentes de la plantilla y los códigos en minúsculas corresponden a los atributos CSS de dichos componentes.

El equivalente en formato “cstyle” de la presentación y del estilo predeterminados es el siguiente:

{l:'legacy',R:{f:'Roboto',g:'#f7f7f7'},T:{w:300,s:'32px',g:'#FFF',c:'#005E7A'},I:{c:'#D1D4D5'},U:{w:700,s:'16px',c:'#005E7A'},P:{w:400,s:'16px',c:'#002432'},N:{w:700,s:'24px',c:'#002432'},K:{w:400,s:'18px',g:'#fff',c:'#005E7A',b:'1px #005E7A',r:'0px'},L:{w:400,s:'16px',c:'#005E7A'},S:{g:'#FFF'}}

Nota sobre las fuentes que se pueden utilizar en los estilos de las plantillas

La lista de las fuentes que se pueden utilizar en los estilos de una plantilla está disponible en esta dirección.

Duplicación de plantillas de origen

Las plantillas personalizadas se pueden duplicar para crear variantes basadas en la misma plantilla de origen (seed). Esta funcionalidad permite disponer de un gran número de certificados diferentes que comparten el mismo diseño y la misma estructura de datos, con contenidos, logotipos y firmas distintos.

Paso 1: recuperar el JSON de la plantilla de origen

Comience por recuperar la definición completa de la plantilla de origen:

GET [API-URL]/issuer/:issuerId/template/:seedId/json

Parámetros:

• issuerId: su identificador de emisor
• seedId: identificador de la plantilla de origen

Ejemplo:

GET https://api.bcdiploma.com/issuer/253/template/0x13/json

Paso 2: modificar y desplegar el duplicado

Eliminar el identificador de la plantilla de origen

Debe eliminar la clave id del JSON recuperado antes de utilizarlo para crear un nuevo duplicado.

{
  "id": "0x13",           // ← Se debe eliminar
  "label": "Seed Certificate",
  "template": {
    "img_logo_1": "QmW1LwvJxWsuszWyGhiCzeM7HZj11SmY4wpbpvhvtZ5trs",
    "img_logo_2": "",
    ...
  }
}

Añadir la vinculación con la plantilla de origen

Inserte la clave meta_alias en el JSON con el identificador de la plantilla de origen:

{
  "label": "Seed Certificate (Duplicate 1)",
  "template": {
    "img_logo_1": "QmW1LwvJxWsuszWyGhiCzeM7HZj11SmY4wpbpvhvtZ5trs",
    ...
    "meta_attributed_to": "^FirstName¤ ^LastName¤",
    "meta_alias": "0x13" // ← Se debe añadir
  },
  "DataTech": "ID;Email",
  ...
}

Adaptar los contenidos

Puede modificar los textos y los campos según sus necesidades.

Actualizar las imágenes (opcional)

Para modificar un logotipo o una firma:

• img_*: imágenes (logotipos, etc.)
• sign_*: firmas digitales

Sustituya el valor por el nombre del archivo que desea adjuntar, por ejemplo:

"img_logo_1": "new_logo.png",

Enviar la solicitud

Para crear una plantilla duplicada:

POST [API-URL]/issuer/:issuerId/template

Para actualizar una plantilla:

PUT [API-URL]/issuer/:issuerId/template/:templateId

Cuerpo (multipart/form-data):

Ejemplo completo

Archivo template.json, ejemplo sin cambio de logotipo:

{
  "label": "Seed Certificate (Duplicate 1)",
  "template": {
    "img_logo_1": "QmW1LwvJxWsuszWyGhiCzeM7HZj11SmY4wpbpvhvtZ5trs",
    ...
    "meta_attributed_to": "^FirstName¤ ^LastName¤",
    "meta_alias": "0x13"
  },
  "DataTech": "ID;Email",
  ...
}

Archivo template.json, ejemplo con cambio de logotipo:

{
  "label": "Seed Certificate (Duplicate 1)",
  "template": {
    "img_logo_1": "new_logo.png",
    "meta_attributed_to": "^FirstName¤ ^LastName¤",
    "meta_alias": "0x13"
  },
  "DataTech": "ID;Email"
}

Respuesta:

El identificador del nuevo duplicado o del duplicado modificado, por ejemplo 3x02.