Saltar al contenido principal

Cómo habilitar y usar los campos dinámicos en la Información Adicional de tu credencial POK

Los campos dinámicos te permiten personalizar la Información Adicional de una credencial de POK Proof of Knowledge para cada destinatario, en lugar de usar el mismo valor para todos. Se habilitan en el editor de diseños y se completan al momento de la emisión (manual, masiva o por API). Esta guía cubre ambas partes: configurar los campos dinámicos en un diseño y emitir credenciales con ellos a través de la API.

Parte 1: Configurar campos dinámicos en un diseño​

1. Abrir el editor de diseños​

  1. Inicia sesión en tu panel de POK a través del selector de región, con tu usuario y contraseña.
  2. En el menú lateral, selecciona Diseños.
  3. Haz clic en Nuevo diseño para construir un template desde cero.

Desde aquí puedes editar tanto el diseño visual como la información estructural que forma tu credencial.

2. Abrir la sección Información Adicional​

  1. Dentro del editor del template, selecciona Información Adicional en el menú lateral izquierdo. En esta sección se agrega el contenido extra que acompaña a cada credencial.
  2. En la sección Información General, haz clic en Agregar para configurar los campos que describen la credencial a emitir.

3. Habilitar opciones avanzadas (opcional)​

Dentro del diálogo de Información General encontrarás una opción adicional:

  • Activa el toggle "Mejorar la calidad de mi credencial OpenBadge" para habilitar más campos opcionales. Estos campos aportan detalle, transparencia y contexto al destinatario, y elevan la calidad de tu credencial dentro del estándar OpenBadge.

Esta configuración no es obligatoria, pero es muy recomendable si quieres entregar credenciales más completas y alineadas con las buenas prácticas internacionales.

4. Activar los campos dinámicos​

  1. Dentro del acordeón Detalles, marca el checkbox Habilitar campos dinámicos.

  2. Al habilitar esta opción, cada campo de información general muestra un nuevo checkbox: Habilitar campo dinámico.

Así puedes definir qué información será fija para todos los destinatarios y cuál será personalizada en cada caso.

¿Qué significa habilitar un campo dinámico?​

  • Si marcas la opción, el campo se vuelve dinámico: su valor se completa con información personalizada para cada destinatario al momento de la emisión (manual, masiva o por API).
  • Si no la marcas, el valor será el mismo para todos los destinatarios y se tomará directamente del diseño.

Identificador del campo dinámico​

Cuando activas un campo dinámico, aparece un nombre entre corchetes, por ejemplo: [nota final].

Guarda este identificador: lo usarás en la emisión para asignar un valor distinto a cada destinatario.

5. Guardar el diseño​

Una vez configurada la Información Adicional y definidos los campos dinámicos que necesitas:

  • Haz clic en Guardar Diseño para conservar los cambios y habilitar el template para emisiones.

Parte 2: Emitir credenciales con campos dinámicos vía API​

La emisión por API te permite emitir credenciales de forma automatizada, integrando tus sistemas externos con POK.

1. Obtener tu API Key​

  1. En POK, abre el menú superior derecho y entra en Integrations.

  2. Haz clic en Nueva integración.

  3. Asigna un nombre descriptivo (por ejemplo, "Integración Sistema Interno").

  4. Selecciona Integración por API Key.

  5. Copia tu API Key y guárdala en un lugar seguro. Solo se muestra una vez.

  6. Marca el toggle "Ya copié la API Key..." y confirma para cerrar el diálogo.

2. Obtener el ID del template con campos dinámicos​

Antes de emitir credenciales con campos dinámicos, identifica el ID del template que los contiene. Llama al endpoint de listado de templates para obtener la lista completa de templates disponibles en tu organización. Para más detalles de la solicitud, consulta la documentación del endpoint de listado de templates.

La respuesta lista todos los templates con su nombre e ID. Busca el template que configuraste con información adicional dinámica y copia su ID: lo usarás en los siguientes pasos.

Ejemplo de respuesta

{
    "pagination": {
        "next": "string"
    },
    "data": [
        {
            "id": "Qmx1ZQ==",
            "name": "Certified Frontend OB v2"
        }
    ]
}

3. Consultar los detalles del template​

Con el ID del template, consulta sus detalles para extraer los campos dinámicos definidos en él. En el parámetro id, usa el ID del template copiado en el paso anterior. Para más detalles de la solicitud, consulta la documentación del endpoint para obtener un template.

La respuesta incluye la estructura completa del template, donde puedes identificar:

  • El objeto customParameters, que contiene los campos dinámicos creados.
  • El ID y la etiqueta de cada uno de esos campos.

Necesitarás estos IDs para armar el cuerpo de la solicitud del siguiente paso, ya que cada campo dinámico debe enviarse dentro del objeto customParameters.

Ejemplo de respuesta

{
    "id": "Qmx1ZQ==",
    "name": "Certified Frontend OB v2",
    "version": "2",
    "customParameters": [
        {
            "id": "achievement_description",
            "label": "achievement_description"
        },
        {
            "id": "37c53975-c57c-4f3b-a894-238ed118f7b7",
            "label": "final grade"
        }
    ]
}

4. Emitir una credencial usando campos dinámicos​

Para emitir la credencial con tus campos dinámicos, usa el endpoint de emisión de credenciales. Para más detalles de la solicitud, consulta la documentación del endpoint de emisión de credenciales.

Dentro del cuerpo de la solicitud:

  • En el objeto customization template, incluye el objeto customParameters. Dentro de él, agrega cada uno de los IDs identificados en el paso 3, junto con el valor que quieres asignar a cada campo dinámico.
  • En el campo id del objeto template, ingresa el ID del template obtenido en el paso 2.

Con estos pasos, tu credencial se emite con todos los valores dinámicos que definiste.

Ejemplo de cuerpo

{
    "credential": {
        "tags": ["StudentId:65989", "#SALE", "Q1"],
        "skipAcceptance": false,
        "emissionType": "pok",
        "dateFormat": "dd/MM/yyyy",
        "emissionDate": "2022-10-09T00:00:00.000Z",
        "title": "Frontend developer",
        "emitter": "The World University"
    },
    "receiver": {
        "languageTag": "es-AR",
        "identification": "12345678",
        "email": "john.doe@pok.tech",
        "lastName": "Doe",
        "firstName": "John"
    },
    "customization": {
        "learningPath": {
            "stepId": "01J4MM0KYVR71D7VSCAN09TYW4",
            "id": "01J4MM0KYTAW0MJDJVGCG7XDBE"
        },
        "page": "48a975cd-be42-48b4-967a-84c1c09b730e",
        "template": {
            "customParameters": {
                "achievement_description": "Este certificado acredita que John Doe ha completado exitosamente el programa de estudios y ha cumplido con todos los requisitos académicos establecidos por The World University para obtener el título de Desarrollador Frontend.",
                "37c53975-c57c-4f3b-a894-238ed118f7b7": "+A"
            },
            "id": "Qmx1ZQ=="
        }
    }
}

Personalizaciones adicionales (opcional)​

Además de los campos dinámicos, puedes sumar otros elementos a la emisión:

Estas opciones enriquecen aún más el contexto que recibe el alumno.

Respuesta exitosa​

Cuando la credencial se emite correctamente, la respuesta incluye:

  • El ID de la credencial.
  • El state de la emisión.
  • La viewUrl, desde donde se podrá ver la credencial una vez que el destinatario la acepte.

Ejemplo de respuesta

{
    "id": "cf0a0360-85f7-494f-86bd-dba8c1b86893",
    "state": "waitingForApproval"
}

Con estos pasos, los campos dinámicos quedan completamente configurados y puedes crear experiencias más personalizadas y flexibles para cada destinatario dentro del ecosistema POK.