Gestion des modèles de certificats

Récupérer la liste des modèles de certificat

Cette API de récupération de la liste des modèles d'un émetteur au format JSON est accessible via un appel GET au point de terminaison [API-URL]/issuer/XXX/templates où XXX est l'identifiant de l'émetteur. Vous pouvez récupérer votre identifiant émetteur ici.

Paramètres optionnels :

• template-name: Filtre la réponse en retournant uniquement les modèles de certificat dont le nom contient la chaîne passée en paramètre (non sensible à la casse)

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

Récupérer la définition d'un modèle de certificat

Cette API de récupération de la définition d'un modèle pour un émetteur est accessible via un appel GET au point de terminaison [API-URL]/issuer/XXX/template/YYY/json où XXX est l'identifiant de l'émetteur et YYY est l'identifiant du modèle.

Exemple d'appel: https://api.bcdiploma.com/issuer/2/template/1x04/json

Récupérer la liste des champs variables d'un modèle de certificat

Cette API de récupération des champs variables d'un modèle pour un émetteur est accessible via un appel GET au point de terminaison [API-URL]/issuer/XXX/template/YYY/fields où XXX est l'identifiant de l'émetteur et YYY est l'identifiant du modèle.

Par défaut, la réponse est renvoyée sous forme de texte, où les champs variables sont séparés par des ; En ajoutant ?Content-Type=application%2Fjson à l'appel GET, le résultat sera renvoyé au format JSON.

Exemple d'appel: https://api.bcdiploma.com/issuer/2/template/1x04/fields?Content-Type=application%2Fjson

Création et mise à jour d'un modèle de microcertification

Les modèles de microcertification peuvent être ajoutés ou mis à jour via un appel POST au point de terminaison [API-URL]/template/mc.

Le corps de la requête est un formulaire multipart contenant les parties suivantes :

• json : le JSON contenant la définition du modèle. Obligatoire à la création et à la mise à jour.

• badgeImage : un fichier contenant l'image principale de la micro-certification. Obligatoire à la création et optionnelle en mise à jour. Formats supportés : png, svg. Taille optimale pour le PNG : 240px * 240px.

• partnerImage : un fichier contenant le logo du partenaire. Format supporté : png. Optionnelle.

• issuerImage : un fichier contenant le logo de l'émetteur. Format supporté : png. Optionnelle.

Création d'un modèle de microcertification

Le corps d'une requête de création de modèle de microcertificat est un formulaire multipart comprenant obligatoirement une partie badgeImage et une partie json. Cette partie json, qui contient la définition du modèle, est un JSON contenant les éléments suivants :

Obligatoires :

• mode : en mode "création", doit avoir la valeur add
• label : le titre du modèle. Il peut s'agir d'une chaîne de caractères simple ou d'un JSON avec le titre dans différentes langues.
• json : les textes et les champs dynamiques pour le modèle. Pour réduire la charge utile, les champs du modèle sont codées (A, B, C etc.). La table de correspondance entre les champs et leur code est fournie ci-après.
• DefaultLanguage : la langue par défaut du modèle au format ISO-2. Doit être cohérente avec les codes langues présents dans l'élément json.
• badge : un JSON contenant les codes langue en tant que clés, et le(s) nom(s) de fichier indiqué(s) dans la partie badgeImage du formulaire multipart, pour chaque langue du modèle (et ce même si l'image est la même quelle que soit la langue).

Optionnels :

• partnerLogo : un JSON contenant les codes langue en tant que clés, et le(s) nom(s) de fichier indiqué(s) dans la partie partnerImage du formulaire multipart, pour chaque langue du modèle.
• issuerLogo : un JSON contenant les codes langue en tant que clés, et le(s) nom(s) de fichier indiqué(s) dans la partie issuerImage du formulaire multipart, pour chaque langue du modèle.
• notification : liste des adresses de courriel à notifier à l'issue de la création du modèle, séparées par le caractère ,.
• cstyle : décrit la mise en page et le style souhaité pour le modèle. Le fonctionnement de cet élément est décrit dans un paragraphe dédié ci-dessous.

Le point de terminaison renverra l'identifiant du nouveau modèle en cas de succès, sous forme d'une chaîne de caractères, par exemple 1x49.

Exemple de contenu valide d'une partie json d'un formulaire multipart de création de modèle de microcertificat :

• Avec un titre bilingue
• Bilingue, avec en en tant que langue par défaut
• Permettant d'avoir une image de badge et une image de partenaire différentes en fonction de la langue
• Avec une mise en page sur 3 colonnes, avec style inspiré du thème "Midnight Vision" disponible dans le backoffice.
• Avec une notification par courriel de création du modèle lorsqu'elle sera effective

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

Mise à jour d'un modèle de microcertificat

Le corps d'une requête de mise à jour de modèle de microcertificat est un formulaire multipart comprenant obligatoirement une partie json. Cette partie json, qui contient la définition du modèle, est un JSON contenant les éléments suivants :

Obligatoires :

• mode : en mode mise à jour, doit avoir la valeurupdate
• id : l'id du modèle à modifier
• json : les textes et les champs dynamiques pour le modèle. A noter que pour réduire la charge utile, seuls les textes et les champs dynamiques à mettre à jour pour le modèle peuvent être présents.
• DefaultLanguage : la langue par défaut du modèle au format ISO-2. Doit être cohérente avec les codes langues présents dans l'élément json.

Optionnels : label, badge, partnerLogo, notification, cstyle

Exemple de contenu valide d'une partie json d'un formulaire multipart de mise à jour de modèle de microcertificat :

• Avec une mise à jour du titre de la microcertificat
• Sans mise à jour de la définition du modèle

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

Table de correspondance code/champ utilisée dans la description du modèle de données des microcertificats

Pour réduire la charge utile, les noms des champs constituant le modèle d'un microcertificat sont substitués par un code (une lettre ou un mot) dans le json attendu lors de la création ou la mise à jour d'un modèle de microcertificat. Voici une table de référence pour ces codes. La plupart des champs sont obligatoires. Le point de terminaison renverra une erreur 400 si des champs obligatoires sont manquants.

Personnalisation de la mise en page et du style des modèles via "cstyle"

La mise en page (choix du nombre de colonnes du modèle ou choix du modèle sur mesure fourni par BCdiploma si vous en disposez) et le style (font, couleur, taille etc. des éléments graphiques composant votre modèle) peuvent être pilotés via API via l'élément cstyle contenu dans la partie json du formulaire multipart.

L'élément cstyle est composé d'un élément décrivant la mise en page retenue layout et d'éléments de styles permettant de modifier la mise en forme des composants. L'élément layout peut prendre l'une des valeurs suivantes :

• oneCol : mise en page sur 1 seule colonne
• legacy : mise en page sur 2 colonnes
• threeCol : mise en page sur 3 colonnes
• CUSTOM_LAYOUT : mise en page sur mesure mise à disposition par les équipes de BCdiploma, si vous en disposez. Cette mise en page ne supporte pas la modification des éléments de style.

Vous pouvez spécifier dans l'élément cstyle uniquement les éléments que vous souhaitez surcharger par rapport à la configuration par défaut.

Voici la mise en forme et le style par défaut utilisés lors de la création d'un modèle de microcertificat via le backoffice. L'ensemble des composants et attributs css disponibles pour modification via API y est représenté :

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

Pour réduire la charge utile, l'élément cstyle utilise une syntaxe JSON5 compressée avec des codes courts correspondant aux éléments graphiques du modèle et à leurs attributs CSS. Voici la table de correspondance pour ces codes. A noter que les codes en majuscules correspondent aux composants du modèle et ceux en minuscules correspondent aux attributs CSS de ces composants.

L'équivalent au format "cstyle" de la mise en forme et du style par défaut est le suivant :

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

Note sur les polices de caractères utilisables dans les styles des modèles

La liste des polices utilisable dans les styles d'un modèle est disponible à cette adresse.