Saltar al contenido principal

Cómo emitir una credencial por API y filtrarla por tags

Para emitir una credencial con la API de POK Proof of Knowledge, primero creas un template, generas una API key y llamas al endpoint de emisión con el ID del template. Si agregas tags a la solicitud, luego puedes filtrar las credenciales emitidas con el parámetro de consulta tags. Esta guía te muestra el flujo completo.

Parte 1: Preparación inicial​

Crear un template​

Necesitas un template antes de poder emitir cualquier credencial.

  1. Inicia sesión en tu panel de POK a través del selector de región.
  2. Ve a la sección Diseños.
  3. Crea un nuevo template.

Para instrucciones detalladas, consulta cómo diseñar un certificado.

Crear una 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.

Parte 2: Emitir una credencial por API​

Paso 1: Obtener el ID del template​

Primero identifica el ID del template que creaste. Llama al endpoint de listado de templates para obtener todos los templates disponibles en tu organización. Para ver el detalle completo de la solicitud, consulta la referencia de la API.

La respuesta incluye cada template con su nombre y su ID. Busca el template que configuraste previamente y copia su ID. Lo usarás en el siguiente paso.

Ejemplo de respuesta:

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

Datos opcionales​

Paso 2: Emitir la credencial​

Llama al endpoint de emisión de credenciales. Para ver el detalle completo del body de la solicitud, consulta la referencia de la API.

Hay dos campos clave en el body:

  • id dentro del objeto template: ingresa el ID del template que obtuviste en el Paso 1.
  • tags dentro del objeto credential: los tags son valores arbitrarios asociados a la credencial que te permiten filtrar tus emisiones más adelante.

Ejemplo de tags:

"tags": ["StudentId:65989", "#SALE", "Q1"]

Una vez que completes los valores del body, podrás emitir credenciales vinculadas a tags.

Ejemplo de body:

{
    "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": "",
            "id": ""
        },
        "page": "",
        "template": {
            "customParameters": {},
            "id": "Qmx1ZQ=="
        }
    }
}

Parte 3: Obtener y filtrar credenciales emitidas​

Listar credenciales emitidas​

Después de emitir, obtén el listado completo de credenciales emitidas con el endpoint de listado de credenciales. Para ver el detalle completo de la solicitud, consulta la referencia de la API.

Filtrar por tags​

Para filtrar los resultados, usa el parámetro de consulta tags. El valor debe coincidir exactamente con el tag que usaste al momento de la emisión.

Ejemplo de solicitud:

GET /credential?tags=Q1

La API devuelve únicamente las credenciales que contienen ese tag.

Qué puedes hacer ahora​

Con estos pasos puedes:

  • Emitir credenciales digitales por API.
  • Asociarlas a identificadores personalizados (tags).
  • Filtrar tus emisiones fácilmente.
  • Gestionar grandes volúmenes de credenciales con segmentación avanzada.