Automatiser le processus d'émission

Cette documentation décrit l'automatisation du processus de certification par les API REST de BCdiploma, composée de plusieurs points de terminaison.

L'interface permettant la publication d'attestations peut être exécutée de la manière suivante :

  1. L'émetteur envoie les données à certifier à l'API BCdiploma. Optionnellement, les certificats peuvent être envoyés automatiquement par courriel
  2. Optionnellement, la plateforme BCdiploma pousse vers l'API de l'émetteur une notification indiquant que la certification a été effectué
  3. L'émetteur récupère les URL certifiées par BCdiploma
  4. Optionnellement, l'émetteur envoie les certificats générés par courriel
  5. Optionnellement, l'émetteur supprime les données d'historique ayant servi à certifier

Dans la plupart des interfaces entre BCdiploma et un outil tiers, seules les étapes 1 et 3 sont nécessaires.

Diagramme de flux d'une interface BCdiploma

Détails des différents méthodes d'API, asynchrones les unes par rapport aux autres :

1- Demande de certification des données: Le programme de l'émetteur appelle le point de terminaison "Push" de BCdiploma avec les paramètres suivants

  • une ou plusieurs " lignes " de données à certifier, y compris un identifiant unique par ligne (ID Data)
  • un identifiant de modèle à utiliser
  • le jeton d'authentification obtenu préalablement
  • optionnellement, les informations permettant d'envoyer les certificats automatiquement par courriel
  • optionnellement, un fichier ZIP contenant les documents à certifier

Le point de terminaison renvoie un identifiant de campagne (lot) pour identifier le traitement.

2- Notification du traitement effectué (optionnel): Une fois le processus de certification terminé, BCdiploma appelle le point de terminaison de notification de l'émetteur avec l'ID de campagne correspondant comme paramètre. Cette notification est optionnelle. Dans le cas où elle n'est pas mise en place, assurez-vous simplement que la récupération des liens certifiés (étape 3) ne soit faite que 30 secondes après la demande de certification des données (le processus est en effet asynchrone).

3- Récupération des liens certifiés: Le programme de l'émetteur appelle le point de terminaison "Pull" avec les paramètres suivants :

  • l'identifiant de la campagne à partir de laquelle le ou les liens certifiés doivent être récupérés

  • le jeton d'authentification préalablement obtenu Le point de terminaison renvoie alors les paires ID-URL de la campagne correspondante, qui pourront être par exemple stockées dans la base de données de l'émetteur.

4- Envoi des certificats générés par courriel: Le programme de l'émetteur appelle le point de terminaison d'envoi de courriels avec les paramètres suivants :

  • l'identifiant de la campagne contenant les certificats à envoyer
  • l'identifiant du modèle utilisé pour cette campagne
  • les identifiants des lignes de données pour lesquelles les certificats doivent être envoyés
  • l'objet du courriel
  • l'adresse de réponse au courriel
  • le nom "From" du courriel

Conseil

Cette opération peut être effectuée automatiquement lors de l'étape 1

5- Suppression de l'historique des données: Le programme de l'émetteur appelle le point de terminaison "Delete Data" de BCdiploma pour supprimer les données utilisées pour la certification, avec les éléments suivants en paramètre:

  • l'identifiant de la campagne dont les données doivent être supprimées

  • le jeton d'authentification préalablement obtenu

Demande de certification des données "Push" (1)

Le service "Push" est accessible par un appel POST au point de terminaison [API-URL]/admin/data.

Entête HTTP obligatoire : Content-Type: application/json

Le corps de la requête est une chaîne de caractères JSON : 3 champs sont obligatoires :

  • templateId : l'identifiant du modèle à utiliser pour la publication. Il peut être récupéré dans le backoffice, en cliquant sur l'image d'un modèle de certificat. L'identifiant se trouve après le & en fin d'URL. Exemple: pour le modèle https://certificate-staging.bcdiploma.com/template/2&0x13, il s'agit de 0x13
  • contentType : "application/json" ou "text/csv" selon le format choisi (application/json à privilégier)
  • data : les données d'un ou plusieurs certificats en JSON ou CSV selon le format choisi (JSON à privilégier)

Avertissement

Attention, l'injection de HTML dans les données certifiées est proscrite pour des raisons de sécurité. Les requêtes comportant du HTML seront rejetées automatiquement le firewall de BCdiploma.

Plusieurs champs optionnels sont disponibles:

  • notification : l'adresse de courriel à laquelle les rapports de publication et d'envoi de courriel seront transmis
  • notes : une note qui sera ajoutée dans les informations de la campagne
  • automated-emailing : déclenche l'envoi automatique des certificats par courriel dès que leur publication est effectuée. Dans l'exemple suivant, il est suffixé par -deactivated pour éviter toute erreur de manipulation. Les champs object, reply_to et from_name doivent être présents pour que la requête soit valide. Néanmoins, si vous spécifiez une valeur chaine vide "" pour ces champs, alors les valeurs par défaut disponibles seront utilisées. 2 champs optionnels et mutuellement exclusifs permettent de spécifier un modèle de courriel à utiliser lorsque plusieurs sont disponibles :
    • Le champ mailingTemplateId permet de spécifier un modèle de courriel par son identifiant
    • Le champ mailingTemplateLabel permet de spécifier un modèle de courriel par son label (un alias)

Enfin, vous pouvez spécifier une ou plusieurs adresses à mettre en copie ou en copie cachée via des champs optionnels cc (Carbon Copy) et bcc (Blind Carbon Copy), comme indiqué dans l'exemple ci dessous.

Conseil

Bonne pratique : les API de BCdiploma ont été optimisées pour des publications "en lot" : c'est à dire qu'un appel à l'API contenant plusieurs certificats doit être privilégié à de multiples appels ne contenant qu'un seul certificat. Cette dernière approche peut entrainer des problèmes de performances lors de vos publications. Sauf si vous avez des contraintes métiers ou techniques le justifiant, elle est déconseillée.

Exemple d'envoi des données au format JSON

Attention

Attention, la présence de l'élément "automated-emailing" dans l'entête de la structure JSON déclenchera l'envoi automatique des certificats par courriel une fois la campagne publiée. Dans l'exemple suivant, il est suffixé par -deactivated pour éviter toute erreur de manipulation.

Conseil

L'intégralité des champs doivent être nommément indiqués dans les données à certifier. Donnez leur une valeur chaine vide "" si vous ne souhaitez pas les valoriser.

{
  "templateId": "0x01",
  "contentType": "application/json",
  "notes": "Ceci est une note relative à la campagne",
  "notification": "your_address@your_domain.com",
  // Enlevez le suffixe -deactivated pour envoyer automatiquement par courriel les certificats
  "automated-emailing-deactivated": {
    // Les champs "object", "reply_to" et "from_name" sont obligatoires
    // Le champ "object" ne peut pas être une chaine vide "", sauf si une valeur par défaut
    // a été mise en place sur votre environnement (sur demande)
    "object": "Votre attestation numérique est arrivée !",
    // Le champ "reply_to" peut être une chaine vide "" : dans ce cas c'est l'adresse
    // de courriel par défaut noreply-bcd@bcdiploma.com qui sera utilisée
    "reply_to": "",
    // Le champ "from_name" peut être une chaine vide "" : dans ce cas c'est votre nom d'émetteur
    // qui sera utilisé
    "from_name": "BCdiploma",

    // Les champ suivants sont optionnels et mutuellement exlusifs.
    // Ils sont utilisés pour spécifier le modèle de courriel à utiliser lorsque
    // plusieurs modèles de courriel sont disponibles
    // "mailingTemplateId": "10115920"
    // "mailingTemplateLabel": "SCPD"
    "cc": [
      {
        "email": "email-to-cc1@yourdomain.com",
        "name": "1ère adresse en copie"
      },
      "email-to-cc2@yourdomain.com"
    ],
    "bcc": [
      {
        "email": "email-to-bcc@yourdomain.com",
        "name": "1ère adresse en copie cachée"
      },
      "email-to-bcc2@yourdomain.com"
    ]
  },
  "data": [
    {
      "ID": "1234",
      "Email": "john.doe@bcdiploma.com",
      "language": "en",
      "firstName": "John",
      "lastName": "DOE",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2025-03-27",
      "assessment": "",
      "linkLabel": "",
      "linkURL": ""
    },
    {
      "ID": "4567",
      "Email": "bob.die@bcdiploma.com",
      "language": "en",
      "firstName": "Bob",
      "lastName": "DIE",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2025-03-27",
      "assessment": "",
      "linkLabel": "",
      "linkURL": ""
    }
  ]
}

Réponse

La réponse aura le statut 200 si tout s'est bien passé. Elle contiendra également un JSON avec un champ campaignId : c'est l'ID de la campagne, nécessaire pour pouvoir récupérer les données ultérieurement.

Association de fichiers à certifier (optionnel)

Si votre modèle de certificat le prévoit, vous aurez la possibilité d'associer un fichier (photo, archive ZIP, PDF) à chaque certificat lors d'une publication. Notons que ce processus utilise le même niveau de chiffrement que les données des certificats.

Le principe est le suivant:

  • Dans votre modèle de certificat, identifiez le champ "Cfile" censé contenir le nom de fichier (ex: "Photo", "Document"...);
  • Lors de la publication, indiquez, pour chaque certificat, dans ce champ "Cfile" un nom de fichier, par exemple "MonDocumentaCertifier1.pdf", "MonDocumentaCertifier2.pdf". Notez qu'actuellement seuls les formats png/svg/jpg, PDF et ZIP sont supportés;
  • Lors de la publication, joignez une archive compressée (.zip) contenant l'ensemble des fichiers à associer aux certificats générés, en respectant les noms de fichiers indiqués dans le champ "Cfile".

Techniquement, la demande de certification de données avec des documents diffère de la demande de certification de données classique sur les points suivants :

  • le contentType doit être "multipart/form-data"
  • le JSON contenant les données à certifier doivent être placée dans le champ "body" du multipart
  • l'archive compressée zip contenant les fichiers à associer aux certificats doit être placée dans un champ "file" du multipart

Chaque certificat sera généré en association avec son fichier sur la base de la correspondance entre la valeur de "Cfile" et le nom du fichier dans l'archive.

Exemple d'appel avec cURL :

curl --request POST \
  --url https://api-staging.bcdiploma.com/admin/data \
  --header 'Authorization: Bearer eyJ[...]QWQ' \
  --header 'Content-Type: multipart/form-data' \
  --form 'body={
    "templateId":"0x01",
    "contentType":"application/json",
    "notes":"Ceci est une note relative à la campagne",
    "notification": "your_address@your_domain.com",
    // Enlevez le suffixe -deactivated pour envoyer automatiquement par courriel les certificats
    "automated-emailing-deactivated": {
      "object": "Test emailing from API",
      "reply_to": "support@bcdiploma.com",
      "from_name": "API robot"
	},
    "data": [
    {
      "ID":"1234",
      "Email":"john.doe@bcdiploma.com",
      "language":"en",
      "firstName":"John",
      "lastName":"DOE",
      "obtentionDate":"2020-03-27",
      "expirationDate":"2025-03-27",
      "assessment":"",
	  "Document":"MonDocumentaCertifier1.pdf",
      "linkLabel":"",
      "linkURL":""
    },
    {
      "ID":"4567",
      "Email":"bob.die@bcdiploma.com",
      "language":"en",
      "firstName":"Bob",
      "lastName":"DIE",
      "obtentionDate":"2020-03-27",
      "expirationDate":"2025-03-27",
      "assessment":"",
	  "Document":"MonDocumentaCertifier2.pdf",
      "linkLabel":"",
      "linkURL":""
    }
	]
}' \
  --form 'file=@/home/Work/Documents/data/file_to_certified.zip'

Notification du traitement effectué (2) (optionnel)

Une fois que le processus de certification est terminé pour une campagne, l'API BCdiploma est capable d'appeler un point de terminaison REST de votre choix, en utilisant indifféremment une instruction GET ou POST et en passant l'identifiant campagneId de la campagne terminée comme paramètre de la requête.

Exemple: Si le point de terminaison spécifié par l'émetteur est https://api.issuer.com?campaignId=${campaignId}, alors l'API appellera https://api.issuer.com?campaignId=XXX où XXX est l'identifiant de la campagne terminée. De manière générale, ${campaignId} sera remplacé dans l'URL par l'identifiant de la campagne terminée et dans le body pour un appel de type POST.

Pour mettre en place ce point de terminaison, vous pouvez contacter le support ou utiliser les API ci-dessous. Ces API permettent de configurer, récupérer et tester un point de terminaison pour l'API de notification.

Configurer un point de terminaison pour l'API de notification

Le service de configuration d'un point de terminaison est accessible par un appel POST au point de terminaison [API-URL]/issuer/XXX/notif où XXX est l'ID émetteur.

Entête HTTP obligatoire : Content-Type: application/json

Le corps de la requête est une chaîne de caractères JSON composée de champs obligatoires :

  • url : l'URL du point de terminaison à appeler ;
  • method : le type d'appel, soit GET, soit POST
  • content : dans le cas d'un POST, le body qui sera transmis lors de l'appel

Exemple pour un point de terminaison de type GET:

{
  "url": "https://api.issuer.com?campaignId=${campaignId}",
  "method": "GET"
}

Exemple pour un point de terminaison de type POST:

{
  "url": "https://api.issuer.com?notification",
  "method": "POST",
  "content": {
    "id": "${campaignId}",
    "from": "BCdiploma",
    "operation": "CAMPAIGN-NOTIFICATION"
  }
}

Récupérer le point de terminaison en cours pour l'API de notification

Le service de récupération du point de terminaison en cours pour l'API de notification est accessible par un appel GET au point de terminaison [API-URL]/issuer/XXX/notif où XXX est l'ID émetteur.

Tester le point de terminaison en cours pour l'API de notification

Le service de test du point de terminaison en cours pour l'API de notification est accessible par un appel GET au point de terminaison [API-URL]/issuer/XXX/testnotif où XXX est l'ID émetteur.

Récupération des liens certifiés (3)

La récupération des liens certifiés est possible par un appel de type GET. Il permet de récupérer les liens des certificats et de nombreuses autres informations. Il est accessible au point de terminaison [API-URL]/admin/data?campaignId=XXX où XXX est l'identifiant de la campagne donné en réponse au service "Pull". La réponse contiendra les certificats au format JSON, en incluant :

  • L'ensemble des champs techniques et les champs ayant servis à la certification, si les données n'ont pas été supprimées
  • La clé unique identifiant la certification key, son URL de consultation url
  • Son statut d'émission StatusID (1=Publié ; 3=Supprimé ; 6=Expiré ; 9=Désactivé)
  • L'état mail et l'éventuel date d'un envoi de courriel pour le certificat LastActivity
  • L'url du badge correspondant si elle existe badge

Exemple de réponse :

{
  "data": [
    {
      "EvidenzId": 282253,
      "ID": "1234",
      "Email": "john.doe@bcdiploma.com",
      "firstName": "John",
      "lastName": "DOE",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2025-03-27",
      "StatusID": 1,
      "available": true,
      "key": "3145612112FF7EE4FB5F3BC564D2B25002E9960A59A2F1C255419925663345FAWzIbDb2ewSNEQV8RXoyDCr4pbh6Ith6EYfLEFVccRXWBts40",
      "Language": "en",
      "LastActivity": null,
      "mail": false,
      "StartDate": null,
      "EndDate": "2025-03-27",
      "PublicationDate": "2020-03-27T14:04:52.277Z",
      "url": "https://certificate-demo.bcdiploma.com/check/3145612112FF7EE4FB5F3BC564D2B25002E9960A59A2F1C255419925663345FAWzIbDb2ewSNEQV8RXoyDCr4pbh6Ith6EYfLEFVccRXWBts40",
      "badge": "https://api-demo.bcdiploma.com/badges/assert/3145612112FF7EE4FB5F3BC564D2B25002E9960A59A2F1C255419925663345FAWzIbDb2ewSNEQV8RXoyDCr4pbh6Ith6EYfLEFVccRXWBts40"
    },
    {
      "EvidenzId": 282254,
      "ID": "4567",
      "Email": "bob.die@bcdiploma.com",
      "firstName": "Bob",
      "lastName": "Die",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2025-03-27",
      "StatusID": 3,
      "available": false,
      "key": "B7B263810A47B75841872910721EE07DA574C103CEBC9CB115754DFCB91A4EB8qV2GWHI2ZTTystVlzesdxlYLNwBDjCIX%2BvhdVkyd3WQMXvOi",
      "Language": "en",
      "LastActivity": null,
      "mail": false,
      "StartDate": null,
      "EndDate": "2025-03-27",
      "PublicationDate": "2020-03-27T14:04:52.277Z",
      "url": "https://certificate-demo.bcdiploma.com/check/B7B263810A47B75841872910721EE07DA574C103CEBC9CB115754DFCB91A4EB8qV2GWHI2ZTTystVlzesdxlYLNwBDjCIX%252BvhdVkyd3WQMXvOi",
      "badge": "https://api-demo.bcdiploma.com/badges/assert/B7B263810A47B75841872910721EE07DA574C103CEBC9CB115754DFCB91A4EB8qV2GWHI2ZTTystVlzesdxlYLNwBDjCIX%252BvhdVkyd3WQMXvOi"
    }
  ]
}

Envoi des certificats par courriel (4) (optionnel)

Le service d'envoi de courriel est accessible par un appel POST au point de terminaison [API-URL]/admin/emails.

Entête HTTP obligatoire : Content-Type: application/json

Le corps de la requête est une chaîne de caractères JSON composée de champs obligatoires :

  • campaignId : l'identifiant de la campagne contenant les certificats à envoyer ;
  • ids : les identifiants des lignes de données pour lesquelles les certificats doivent être envoyés, séparés par des ;. Ces identifiants de données ont été renvoyés dans le champ EvidenzId de la requête de récupération des liens certifiés ;
  • object : l'objet du courriel. Si une valeur chaine vide "" est spécifiée, alors c'est la valeur par défaut disponible qui sera utilisée ;
  • reply_to : l'adresse d'expéditeur et de réponse au courriel. Si une valeur chaine vide "" est spécifiée, alors c'est la valeur par défaut disponible qui sera utilisée ;
  • from_name : le nom à afficher comme expéditeur du courriel. Si une valeur chaine vide "" est spécifiée, alors c'est la valeur par défaut disponible qui sera utilisée. Attention ce champ ne peut pas contenir une adresse de courriel ;

et de champs optionnels :

  • notification : l'adresse à laquelle le rapport de réussite de la campagne d'envoi de courriels est envoyé.
  • Le champ mailingTemplateId permet de spécifier un modèle de courriel par son identifiant
  • Le champ mailingTemplateLabel permet de spécifier un modèle de courriel par son label (qui est un alias).

Enfin, vous pouvez spécifier une ou plusieurs adresses à mettre en copie ou en copie cachée via des champs optionnels cc (Carbon Copy) et bcc (Blind Carbon Copy), comme indiqué dans l'exemple ci dessous.

Exemple :

{
  "campaignId": "959",
  "ids": "19123;19124",
  "object": "Mail de démo",
  "reply_to": "noreply-bcd@bcdiploma.com",
  "from_name": "BCdiploma robot",
  "notification": "you@yourdomain.com",
  // "mailingTemplateId": "10115920"
  // "mailingTemplateLabel": "SCPD"
  "cc": [
    {
      "email": "email-to-cc1@yourdomain.com",
      "name": "1ère adresse en copie"
    },
    "email-to-cc2@yourdomain.com"
  ],
  "bcc": [
    {
      "email": "email-to-bcc@yourdomain.com",
      "name": "1ère adresse en copie cachée"
    },
    "email-to-bcc2@yourdomain.com"
  ]
}

campaignId peut être remplacé dans le corps de la requête par templateId. Dans ce cas, on pourra envoyer par courriel les certificats de la vue "Voir tous les certificats" du modèle correspondant. templateId : l'identifiant du modèle des certificats à envoyer. Il peut être récupéré dans le backoffice, en cliquant sur l'image d'un modèle de certificat. L'identifiant se trouve après le & en fin d'URL. Exemple: pour le modèle https://certificate-staging.bcdiploma.com/template/2&0x13, il s'agit de 0x13.

Exemple :

{
  "templateId": "0x13",
  "ids": "19123;19124;56478;78451",
  "object": "Mail de démo",
  "reply_to": "noreply-bcd@bcdiploma.com",
  "from_name": "BCdiploma robot",
  "notification": "your_address@your_domain.com"
}