Automatizar el proceso de emisión

Esta documentación describe la automatización del proceso de certificación mediante las API REST de BCdiploma, compuestas por varios endpoints.

La interfaz que permite la publicación de certificados puede ejecutarse de la siguiente manera:

  1. El emisor envía a la API de BCdiploma los datos que se van a certificar. Opcionalmente, los certificados pueden enviarse automáticamente por correo electrónico
  2. Opcionalmente, la plataforma BCdiploma envía a la API del emisor una notificación que indica que la certificación se ha realizado
  3. El emisor recupera las URL certificadas por BCdiploma
  4. Opcionalmente, el emisor envía por correo electrónico los certificados generados
  5. Opcionalmente, el emisor borra los datos de historial que se utilizaron para certificar

En la mayoría de las interfaces entre BCdiploma y una herramienta de terceros, solo son necesarios los pasos 1 y 3.

Diagrama de flujo de una interfaz BCdiploma

Detalles de los distintos métodos de la API, asíncronos entre sí:

1- Solicitud de certificación de datos: El programa del emisor llama al endpoint “Push” de BCdiploma con los siguientes parámetros

  • una o varias “filas” de datos que se van a certificar, incluido un identificador único por fila (ID Data)
  • un identificador de la plantilla que se va a utilizar
  • el token de autenticación obtenido previamente
  • opcionalmente, la información que permite enviar los certificados automáticamente por correo electrónico
  • opcionalmente, un archivo ZIP que contiene los documentos que se van a certificar

El endpoint devuelve un identificador de campaña (lote) para identificar el procesamiento.

2- Notificación del procesamiento realizado (opcional): Una vez finalizado el proceso de certificación, BCdiploma llama al endpoint de notificación del emisor con el ID de campaña correspondiente como parámetro. Esta notificación es opcional. Si no se implementa, simplemente asegúrese de que la recuperación de los enlaces certificados (paso 3) no se realice hasta 30 segundos después de la solicitud de certificación de datos (el proceso es, en efecto, asíncrono).

3- Recuperación de los enlaces certificados: El programa del emisor llama al endpoint “Pull” con los siguientes parámetros:

  • el identificador de la campaña de la que deben recuperarse el enlace o los enlaces certificados

  • el token de autenticación obtenido previamente El endpoint devuelve entonces los pares ID-URL de la campaña correspondiente, que podrán, por ejemplo, almacenarse en la base de datos del emisor.

4- Envío de los certificados generados por correo electrónico: El programa del emisor llama al endpoint de envío de correos electrónicos con los siguientes parámetros:

  • el identificador de la campaña que contiene los certificados que se van a enviar
  • el identificador de la plantilla utilizada para esta campaña
  • los identificadores de las filas de datos cuyos certificados deben enviarse
  • el asunto del correo electrónico
  • la dirección de respuesta del correo electrónico
  • el nombre “From” del correo electrónico

Consejos

Esta operación puede realizarse automáticamente en el paso 1

5- Borrado del historial de datos: El programa del emisor llama al endpoint “Delete Data” de BCdiploma para borrar los datos utilizados para la certificación, con los siguientes elementos como parámetros:

  • el identificador de la campaña cuyos datos deben borrarse

  • el token de autenticación obtenido previamente

Solicitud de certificación de datos “Push” (1)

Se accede al servicio “Push” mediante una llamada POST al endpoint [API-URL]/admin/data.

Encabezado HTTP obligatorio: Content-Type: application/json

El cuerpo de la solicitud es una cadena de caracteres JSON: Hay 3 campos obligatorios:

  • templateId: el identificador de la plantilla que se va a utilizar para la publicación. Puede obtenerse en el backoffice haciendo clic en la imagen de una plantilla de certificado. El identificador se encuentra después del & al final de la URL. Ejemplo: para la plantilla https://certificate-staging.bcdiploma.com/template/2&0x13, se trata de 0x13
  • contentType: "application/json" o "text/csv" según el formato elegido (se recomienda application/json)
  • data: los datos de uno o varios certificados en JSON o CSV según el formato elegido (se recomienda JSON)

Aviso

Atención: la inyección de HTML en los datos certificados está prohibida por motivos de seguridad. Las solicitudes que contengan HTML serán rechazadas automáticamente por el firewall de BCdiploma.

Hay varios campos opcionales disponibles:

  • notification: la dirección de correo electrónico a la que se enviarán los informes de publicación y de envío de correos electrónicos
  • notes: una nota que se añadirá a la información de la campaña
  • automated-emailing: activa el envío automático de los certificados por correo electrónico en cuanto se publican. En el ejemplo siguiente, lleva el sufijo -deactivated para evitar cualquier error de manipulación. Los campos object, reply_to y from_name deben estar presentes para que la solicitud sea válida. No obstante, si especifica una cadena vacía "" como valor de estos campos, se utilizarán los valores predeterminados disponibles. Hay 2 campos opcionales y mutuamente excluyentes que permiten especificar la plantilla de correo electrónico que se va a utilizar cuando hay varias disponibles:
    • El campo mailingTemplateId permite especificar una plantilla de correo electrónico por su identificador
    • El campo mailingTemplateLabel permite especificar una plantilla de correo electrónico por su label (un alias)

Por último, puede especificar una o varias direcciones para poner en copia o en copia oculta mediante los campos opcionales cc (Carbon Copy) y bcc (Blind Carbon Copy), como se indica en el ejemplo siguiente.

Consejos

Buena práctica: las API de BCdiploma se han optimizado para publicaciones “por lotes”, es decir, debe preferirse una llamada a la API que contenga varios certificados antes que múltiples llamadas que contengan un solo certificado. Este último enfoque puede provocar problemas de rendimiento durante sus publicaciones. Salvo que tenga restricciones de negocio o técnicas que lo justifiquen, se desaconseja.

Ejemplo de envío de datos en formato JSON

Advertencia

Atención: la presencia del elemento "automated-emailing" en el encabezado de la estructura JSON activará el envío automático de los certificados por correo electrónico una vez publicada la campaña. En el ejemplo siguiente, lleva el sufijo -deactivated para evitar cualquier error de manipulación.

Consejos

Todos los campos deben indicarse por su nombre en los datos que se van a certificar. Asígneles una cadena vacía "" si no desea darles un valor.

{
  "templateId": "0x01",
  "contentType": "application/json",
  "notes": "Esta es una nota relativa a la campaña",
  "notification": "your_address@your_domain.com",
  // Elimine el sufijo -deactivated para enviar automáticamente los certificados por correo electrónico
  "automated-emailing-deactivated": {
    // Los campos "object", "reply_to" y "from_name" son obligatorios
    // El campo "object" no puede ser una cadena vacía "", salvo que se haya configurado
    // un valor predeterminado en su entorno (previa solicitud)
    "object": "¡Su certificado digital ha llegado!",
    // El campo "reply_to" puede ser una cadena vacía "": en ese caso se utilizará la dirección
    // de correo electrónico predeterminada noreply-bcd@bcdiploma.com
    "reply_to": "",
    // El campo "from_name" puede ser una cadena vacía "": en ese caso se utilizará
    // su nombre de emisor
    "from_name": "BCdiploma",

    // Los campos siguientes son opcionales y mutuamente excluyentes.
    // Se utilizan para especificar la plantilla de correo electrónico que se va a utilizar
    // cuando hay varias plantillas de correo electrónico disponibles
    // "mailingTemplateId": "10115920"
    // "mailingTemplateLabel": "SCPD"
    "cc": [
      {
        "email": "email-to-cc1@yourdomain.com",
        "name": "Primera dirección en copia"
      },
      "email-to-cc2@yourdomain.com"
    ],
    "bcc": [
      {
        "email": "email-to-bcc@yourdomain.com",
        "name": "Primera dirección en copia oculta"
      },
      "email-to-bcc2@yourdomain.com"
    ]
  },
  "data": [
    {
      "ID": "1234",
      "Email": "john.doe@bcdiploma.com",
      "language": "en",
      "firstName": "John",
      "lastName": "DOE",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2035-03-27",
      "assessment": "",
      "linkLabel": "",
      "linkURL": ""
    },
    {
      "ID": "4567",
      "Email": "bob.die@bcdiploma.com",
      "language": "en",
      "firstName": "Bob",
      "lastName": "DIE",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2035-03-27",
      "assessment": "",
      "linkLabel": "",
      "linkURL": ""
    }
  ]
}

Respuesta

La respuesta tendrá el estado 200 si todo ha funcionado correctamente. También contendrá un JSON con un campo campaignId: es el ID de la campaña, necesario para poder recuperar los datos posteriormente.

Asociación de archivos para certificar (opcional)

Si su plantilla de certificado lo prevé, podrá asociar un archivo (foto, archivo ZIP, PDF) a cada certificado durante una publicación. Cabe señalar que este proceso utiliza el mismo nivel de cifrado que los datos de los certificados.

El principio es el siguiente:

  • En su plantilla de certificado, identifique el campo "Cfile" destinado a contener el nombre del archivo (p. ej.: "Photo", "Document"...);
  • Durante la publicación, indique para cada certificado, en este campo "Cfile", un nombre de archivo, por ejemplo "MiDocumentoACertificar1.pdf", "MiDocumentoACertificar2.pdf". Tenga en cuenta que actualmente solo se admiten los formatos png/svg/jpg, PDF y ZIP;
  • Durante la publicación, adjunte un archivo comprimido (.zip) que contenga todos los archivos que se van a asociar a los certificados generados, respetando los nombres de archivo indicados en el campo "Cfile".

Técnicamente, la solicitud de certificación de datos con documentos difiere de la solicitud de certificación de datos clásica en los siguientes puntos:

  • el contentType debe ser "multipart/form-data"
  • el JSON que contiene los datos que se van a certificar debe colocarse en el campo "body" del multipart
  • el archivo comprimido zip que contiene los archivos que se van a asociar a los certificados debe colocarse en un campo "file" del multipart

Cada certificado se generará en asociación con su archivo a partir de la correspondencia entre el valor de "Cfile" y el nombre del archivo dentro del archivo comprimido.

Ejemplo de llamada con 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":"Esta es una nota relativa a la campaña",
    "notification": "your_address@your_domain.com",
    // Elimine el sufijo -deactivated para enviar automáticamente los certificados por correo electrónico
    "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":"2035-03-27",
      "assessment":"",
	  "Document":"MiDocumentoACertificar1.pdf",
      "linkLabel":"",
      "linkURL":""
    },
    {
      "ID":"4567",
      "Email":"bob.die@bcdiploma.com",
      "language":"en",
      "firstName":"Bob",
      "lastName":"DIE",
      "obtentionDate":"2020-03-27",
      "expirationDate":"2035-03-27",
      "assessment":"",
	  "Document":"MiDocumentoACertificar2.pdf",
      "linkLabel":"",
      "linkURL":""
    }
	]
}' \
  --form 'file=@/home/Work/Documents/data/file_to_certified.zip'

Notificación del procesamiento realizado (2) (opcional)

Una vez finalizado el proceso de certificación de una campaña, la API de BCdiploma puede llamar a un endpoint REST de su elección, utilizando indistintamente una instrucción GET o POST y pasando el identificador campaignId de la campaña finalizada como parámetro de la solicitud.

Ejemplo: Si el endpoint especificado por el emisor es https://api.issuer.com?campaignId=${campaignId}, la API llamará a https://api.issuer.com?campaignId=XXX, donde XXX es el identificador de la campaña finalizada. De manera general, ${campaignId} se sustituirá por el identificador de la campaña finalizada en la URL y, en el caso de una llamada de tipo POST, en el body.

Para configurar este endpoint, puede ponerse en contacto con el soporte o utilizar las API que se indican a continuación. Estas API permiten configurar, recuperar y probar un endpoint para la API de notificación.

Configurar un endpoint para la API de notificación

Se accede al servicio de configuración de un endpoint mediante una llamada POST al endpoint [API-URL]/issuer/XXX/notif, donde XXX es el ID del emisor.

Encabezado HTTP obligatorio: Content-Type: application/json

El cuerpo de la solicitud es una cadena de caracteres JSON compuesta por campos obligatorios:

  • url: la URL del endpoint al que se va a llamar;
  • method: el tipo de llamada, ya sea GET o POST
  • content: en el caso de un POST, el body que se transmitirá durante la llamada

Ejemplo para un endpoint de tipo GET:

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

Ejemplo para un endpoint de tipo POST:

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

Recuperar el endpoint actual para la API de notificación

Se accede al servicio de recuperación del endpoint actual para la API de notificación mediante una llamada GET al endpoint [API-URL]/issuer/XXX/notif, donde XXX es el ID del emisor.

Probar el endpoint actual para la API de notificación

Se accede al servicio de prueba del endpoint actual para la API de notificación mediante una llamada GET al endpoint [API-URL]/issuer/XXX/testnotif, donde XXX es el ID del emisor.

Recuperación de los enlaces certificados (3)

La recuperación de los enlaces certificados es posible mediante una llamada de tipo GET. Permite recuperar los enlaces de los certificados y mucha otra información. Está disponible en el endpoint [API-URL]/admin/data?campaignId=XXX, donde XXX es el identificador de la campaña proporcionado en la respuesta del servicio “Push”. La respuesta contendrá los certificados en formato JSON, e incluirá:

  • Todos los campos técnicos y los campos utilizados para la certificación, si los datos no se han borrado
  • La clave única que identifica la certificación key, su URL de consulta url
  • Su estado de emisión StatusID (1=Publicado; 3=Eliminado; 6=Vencido; 9=Desactivado)
  • El estado mail y la fecha, si la hay, de un envío de correo electrónico para el certificado LastActivity
  • La URL de la insignia correspondiente, si existe, badge

Ejemplo de respuesta:

{
  "data": [
    {
      "EvidenzId": 282253,
      "ID": "1234",
      "Email": "john.doe@bcdiploma.com",
      "firstName": "John",
      "lastName": "DOE",
      "obtentionDate": "2020-03-27",
      "expirationDate": "2035-03-27",
      "StatusID": 1,
      "available": true,
      "key": "3145612112FF7EE4FB5F3BC564D2B25002E9960A59A2F1C255419925663345FAWzIbDb2ewSNEQV8RXoyDCr4pbh6Ith6EYfLEFVccRXWBts40",
      "Language": "en",
      "LastActivity": null,
      "mail": false,
      "StartDate": null,
      "EndDate": "2035-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": "2035-03-27",
      "StatusID": 3,
      "available": false,
      "key": "B7B263810A47B75841872910721EE07DA574C103CEBC9CB115754DFCB91A4EB8qV2GWHI2ZTTystVlzesdxlYLNwBDjCIX%2BvhdVkyd3WQMXvOi",
      "Language": "en",
      "LastActivity": null,
      "mail": false,
      "StartDate": null,
      "EndDate": "2035-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"
    }
  ]
}

Envío de los certificados por correo electrónico (4) (opcional)

Se accede al servicio de envío de correos electrónicos mediante una llamada POST al endpoint [API-URL]/admin/emails.

Encabezado HTTP obligatorio: Content-Type: application/json

El cuerpo de la solicitud es una cadena de caracteres JSON compuesta por campos obligatorios:

  • campaignId: el identificador de la campaña que contiene los certificados que se van a enviar;
  • ids: los identificadores de las filas de datos cuyos certificados deben enviarse, separados por ;. Estos identificadores de datos se devolvieron en el campo EvidenzId de la solicitud de recuperación de los enlaces certificados;
  • object: el asunto del correo electrónico. Si se especifica una cadena vacía "" como valor, se utilizará el valor predeterminado disponible;
  • reply_to: la dirección del remitente y de respuesta del correo electrónico. Si se especifica una cadena vacía "" como valor, se utilizará el valor predeterminado disponible;
  • from_name: el nombre que se mostrará como remitente del correo electrónico. Si se especifica una cadena vacía "" como valor, se utilizará el valor predeterminado disponible. Atención: este campo no puede contener una dirección de correo electrónico;

y por campos opcionales:

  • notification: la dirección a la que se envía el informe de éxito de la campaña de envío de correos electrónicos.
  • El campo mailingTemplateId permite especificar una plantilla de correo electrónico por su identificador
  • El campo mailingTemplateLabel permite especificar una plantilla de correo electrónico por su label (que es un alias).

Por último, puede especificar una o varias direcciones para poner en copia o en copia oculta mediante los campos opcionales cc (Carbon Copy) y bcc (Blind Carbon Copy), como se indica en el ejemplo siguiente.

Ejemplo:

{
  "campaignId": "959",
  "ids": "19123;19124",
  "object": "Correo de demostración",
  "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": "Primera dirección en copia"
    },
    "email-to-cc2@yourdomain.com"
  ],
  "bcc": [
    {
      "email": "email-to-bcc@yourdomain.com",
      "name": "Primera dirección en copia oculta"
    },
    "email-to-bcc2@yourdomain.com"
  ]
}

campaignId puede sustituirse en el cuerpo de la solicitud por templateId. En ese caso, se podrán enviar por correo electrónico los certificados de la vista “Ver todos los certificados” de la plantilla correspondiente. templateId: el identificador de la plantilla de los certificados que se van a enviar. Puede obtenerse en el backoffice haciendo clic en la imagen de una plantilla de certificado. El identificador se encuentra después del & al final de la URL. Ejemplo: para la plantilla https://certificate-staging.bcdiploma.com/template/2&0x13, se trata de 0x13.

Ejemplo:

{
  "templateId": "0x13",
  "ids": "19123;19124;56478;78451",
  "object": "Correo de demostración",
  "reply_to": "noreply-bcd@bcdiploma.com",
  "from_name": "BCdiploma robot",
  "notification": "your_address@your_domain.com"
}