INSIGNIA UNED

Crear el Emisor de la Insignia (Issuer): El primer paso, si no ha sido realizado aún, es crear la entidad que se encargará de generar y emitir las insignias, por ejemplo: una empresa, facultad, escuela, departamento, curso específico o persona individual. Los atributos mínimos que el estándar solicita para un emisor son: una imagen con el identificador gráfico o logotipo, nombre de la entidad, correo electrónico, sitio web y una descripción.
Crear la Insignia (Badge): Una vez creado el emisor, se procede con la insignia, la cual es la imagen base representativa que se podrá adjudicar posteriormente a una o muchas personas. La información mínima que se almacena de una insignia corresponde a: un archivo de la imagen (debe ser en el formato SVG), una descripción, el criterio general de premiación y el ente emisor al que pertenece.
Generar la Adjudicación (Assertion): Es el proceso de asignar, entregar o premiar a una persona con una insignia determinada. La adjudicación se realiza mediante la inserción de los datos correspondientes al correo electrónico y nombre real de la persona receptora dentro del archivo de la insignia, además de los datos del evento dónde se obtuvo, la evidencia (dirección pública de un sitio o recurso disponible en la web), y la respectiva fecha de emisión. El dato del correo electrónico se utiliza como identificador único para la persona receptora y además como medio para enviarle la insignia obtenida.

Las rutas de aprendizaje corresponden a una secuencia de insignias que representa el progreso de una persona a través de diferentes niveles de conocimiento, habilidades o experiencias. Las rutas de aprendizaje permiten que las insignias pasen de ser reconocimientos aislados a representar trayectorias de aprendizaje o desarrollo de competencias.

Para crear una ruta de aprendizaje, es necesario generar una o varias insignias digitales y luego organizarlas en una secuencia lógica, estableciendo relaciones de dependencia entre ellas. Por ejemplo, se podría crear una ruta de aprendizaje para un curso de Liderazgo y Gestión de Proyectos, la cual incluya insignias para cada módulo o tema, y luego establecer que la obtención de una insignia específica es un requisito para obtener la siguiente insignia en la secuencia. De esta manera, las rutas de aprendizaje permiten a las personas visualizar su progreso y logros a lo largo del tiempo, y también pueden ser utilizadas por los empleadores o instituciones educativas para evaluar las habilidades y competencias de una persona en función de su trayectoria de aprendizaje.

Ejemplo ilustrativo de una ruta de aprendizaje

2 / 3 insignias obtenidas 67%

✓ Obtenida

Introducción a liderazgo

→

✓ Obtenida

Liderazgo en equipos

→

Paso 3

Gestión de proyectos

Personas receptoras (Recipients): Son las personas que reciben o son premiadas con una insignia digital. Para que una persona pueda recibir una insignia, es necesario que el correo electrónico de la persona receptora sea válido y esté registrado dentro del archivo de la insignia. Esto se realiza durante el proceso de adjudicación.
Hospedaje (Host): Corresponde a la entidad que proporciona el servicio de almacenamiento, gestión, control y operación de la información de los emisores, las insignias y su respectiva adjudicación a las personas receptoras.
Verificadores o validadores (Validator & Verifiers): Existen sitios web que nos permiten verificar si una insignia es válida, si cumple correctamente con el estándar de Open Badges y si está acreditada a un correo electrónico específico.

Sitios web validadores:

Validador propio de INSIGNIA UNED [↗]
Validador IMS Global [↗]
Validador BADGR [↗]

Permisos Institucionales: Esta sección permite gestionar la asignación de permisos entre cuentas institucionales verificadas para facilitar el trabajo colaborativo sobre recursos autorizados dentro de la plataforma. Desde aquí se pueden consultar permisos activos y administrar quién puede operar determinados elementos institucionales. Esta opción se muestra para cuentas emisoras o administradoras que estén verificadas.
Mi Reporte General: Reúne un resumen ejecutivo de la actividad de emisión, incluyendo estadísticas clave como insignias emitidas, revocadas y adjudicaciones recientes. Sirve como un punto de consulta rápido para monitorear el comportamiento general de los emisores asociados a la cuenta.
Catálogo General: Corresponde al catálogo institucional de insignias y emisores disponibles para consulta. Facilita explorar de forma ordenada la oferta general publicada en el sistema y conocer qué insignias están disponibles, así como las entidades responsables de emitirlas.

La issuer_api_key necesaria para autenticar las peticiones se obtiene desde el formulario de edición del Emisor correspondiente (botón «Ver API KEY»).

Nota para integraciones externas: la API recomendada es v2 y autentica por encabezado Authorization. Este endpoint no utiliza token CSRF porque está diseñado para consumo externo controlado por issuer_api_key, rate limit y reglas CORS.

Condiciones operativas actuales de la API

Límite de solicitudes

100 solicitudes por 3600 segundos (aprox. 1 hora(s)) por combinación token+IP.

Si se supera el límite

La API responde HTTP 429, con encabezado Retry-After y campo JSON retry_after.

Orígenes permitidos para solicitudes web (CORS)

https://insignia.uned.ac.cr
https://*.uned.ac.cr

Nota: la lista CORS es útil para clientes web (navegador). Las apps móviles nativas suelen autenticarse por token y no dependen de CORS.

¿Cómo implementar Adjudicaciones desde una aplicación externa?

Especificación de la API:

POST /assertion/api/v2/award

Permite crear una nueva Adjudicación [assertion] — v2

Autenticación: use el encabezado Authorization con formato Bearer ISSUER_API_KEY. También se acepta el token en formato plano por compatibilidad. Este endpoint no requiere token CSRF porque está orientado a integraciones externas autenticadas por API key. El rate limit actual es de 100 solicitudes por 3600 segundos (aprox. 1 hora(s)) por combinación token + IP. Si se excede el límite, la API responde HTTP 429 con encabezado Retry-After.

Código de ejemplo en JavaScript para utilizar la API:


    // Codigo JS para ejecutar Adjudicaciones externas desde la API: https://insignia.uned.ac.cr/assertion/api/v2/award

    const url = "https://insignia.uned.ac.cr/assertion/api/v2/award"; // URL de la API v2 para realizar la adjudicación externa de una insignia

    let headersList = {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer ISSUER_API_KEY" // Aquí se coloca la issuer_api_key (64 caracteres hex). Se obtiene en INSIGNIA UNED [Formulario de edición de Emisores].
    }

    let bodyContent = JSON.stringify({
        "identity" : "", // Correo de la persona receptora de la insignia [max_length 255]
        "name" : "", // Nombre completo real de la persona receptora de la insignia [max_length 64]
        "narrative" : "", // Descripción breve del evento [max_length 256]
        "evidence" : "", // Opcional: (puede ir vacío) | URI -> Dirección web de un recurso o página que presente evidencia y detalle del logro obtenido [max_length 256]
        "issued_date" : "", // Fecha de adjudicación en el formato [dd/mm/YYYY] -> Día/Mes/Año [max_length 10]
        "badge_uid" : "", // UID de la Insignia, el cual se obtiene en INSIGNIA UNED [Formulario de edición de Insignias] [max_length 64]
        "send_mail" : "", // Se coloca un '1' si se desea enviar un correo de notificación a la persona receptora de la insignia, de lo contrario se coloca un '0'
        "email_body" : "" // Opcional: (puede ir vacío) | Texto opcional que se visualizará en el cuerpo del correo enviado a la persona receptora de la insignia [max_length 512]
    });

    // Función asíncrona para realizar la petición POST a la API de adjudicación de insignias

    async function assertion() {
        let response = await fetch(url, { 
            method: "POST",
            body: bodyContent,
            headers: headersList
        });

        let result = await response.json();

        console.log(result);
        // Respuesta exitosa (HTTP 201): { awarded: true, status: "success", assertion_uid: "...", assertion_url: "..." }
        // Error de validación (HTTP 400): { awarded: false, status: "error", errors: { campo: "mensaje" } }
        // Error de autenticación / not found (HTTP 401/404): { awarded: false, status: "error", message: "..." }
        // Límite de solicitudes (HTTP 429): { awarded: false, status: "error", message: "...", retry_after: N }
        // En HTTP 429, revise también el encabezado Retry-After para reintentar.
    }

    // Llamado a la función para realizar la petición POST a la API de adjudicación de insignias

    assertion();

Código de ejemplo en PHP para utilizar la API:


    // Codigo PHP para ejecutar Adjudicaciones externas desde la API: https://insignia.uned.ac.cr/assertion/api/v2/award

    $url = 'https://insignia.uned.ac.cr/assertion/api/v2/award'; // URL de la API v2 para realizar la adjudicación externa de una insignia

    $bodyContent = 
        array(
            "identity" => "", // Correo de la persona receptora de la insignia [max_length 255]
            "name" => "", // Nombre completo real de la persona receptora de la insignia [max_length 64]
            "narrative" => "", // Descripción breve del evento [max_length 256]
            "evidence" => "", // Opcional: (puede ir vacío) | URI -> Dirección web de un recurso o página que presente evidencia y detalle del logro obtenido [max_length 256]
            "issued_date" => "", // Fecha de adjudicación en el formato [dd/mm/YYYY] -> Día/Mes/Año [max_length 10]
            "badge_uid" => "", // UID de la Insignia, el cual se obtiene en INSIGNIA UNED [Formulario de edición de Insignias] [max_length 64]
            "send_mail" => "", // Se coloca un '1' si se desea enviar un correo de notificación a la persona receptora de la insignia, de lo contrario se coloca un '0'
            "email_body" => "" // Opcional: (puede ir vacío) | Texto opcional que se visualizará en el cuerpo del correo enviado a la persona receptora de la insignia [max_length 512]
        );

    $headersList = array(
        'http' => array(
            'method' => 'POST',
            'header' =>
                'Accept: application/json'."\r\n".
                'Content-type: application/json'."\r\n".
                'Authorization: Bearer ISSUER_API_KEY'."\r\n", // Aquí se coloca la issuer_api_key (64 caracteres hex). También se acepta en formato plano por compatibilidad.
            'content' => json_encode($bodyContent)
        )
    );

    $context = stream_context_create($headersList);

    $result = file_get_contents($url, false, $context);

    $result = json_decode($result);
    var_dump($result); // Respuesta exitosa (HTTP 201): awarded=true + assertion_uid + assertion_url | Error (400/401/404): awarded=false + errors/message | Límite (429): awarded=false + retry_after

Resumen

Esta versión incorpora delegación institucional completa para que las cuentas institucionales autoricen a funcionarios a gestionar recursos en su nombre sin compartir credenciales. Además, mejora la auditoría, aclara la propiedad visual de los recursos y corrige comportamientos de filtrado y eliminación en insignias.

Detalle de cambios

Delegación institucional

Nuevo módulo Permisos institucionales para que cuentas institucionales verificadas asignen o revoquen permisos a funcionarios activos.
La delegación aplica a emisores, insignias, rutas de aprendizaje y adjudicaciones, permitiendo crear, ver, editar y eliminar recursos institucionales sin compartir credenciales.
Los recursos creados mediante delegación conservan como propiedad real la cuenta institucional de origen.

Interfaz y claridad operativa

Se mejoró la señalización visual para distinguir recursos Propios de recursos Institucional delegada en formularios y listados.
Los mensajes de pertenencia ahora muestran explícitamente el nombre de la cuenta institucional propietaria cuando corresponde.
Los avisos y la columna Propiedad se ocultan automáticamente cuando el funcionario no tiene delegaciones activas, reduciendo ruido y confusión.

Auditoría y consistencia

La auditoría ahora registra de forma más clara las concesiones y revocaciones de permisos institucionales, identificando mejor la cuenta funcionaria afectada.
Se corrigió el filtrado por emisor en el listado de insignias (`badge/index/{id}`) para que aplique correctamente el filtro solicitado.
Se mejoró el mensaje al eliminar insignias para distinguir entre bloqueo por adjudicaciones existentes y bloqueo por asociación a rutas de aprendizaje.
Se aplicó un parche de compatibilidad para rutas antiguas de insignias que usaban un punto (`.`) como parte de la entropía del identificador, evitando bloqueos o lecturas inconsistentes de recursos públicos heredados.

Resumen

Esta versión fortalece la seguridad general del sistema, permite cargar insignias en formato PNG, habilita un nuevo flujo de acceso temporal al portafolio para personas con correos externos, permite compartir insignias vía código QR desde el perfil público de adjudicación, mejora la administración interna y refuerza la compatibilidad con Open Badges 2.0.

Detalle de cambios

Administración y operación

Nuevo módulo de registro de acciones para Auditoría en administración, con filtro de acciones predefinidas y carga automática del año actual cuando no se especifica rango.
Nuevo mantenimiento de sesiones internas con clasificación de estados y limpieza de registros anómalos.

Seguridad y hardening

Protección CSRF activada para formularios y solicitudes internas, con exclusiones controladas para la API externa y el flujo interno de Adminer.
Rutas expuestas reducidas: Auto Routing desactivado y publicación solo de endpoints definidos explícitamente.
Consultas sensibles reforzadas con parámetros preparados.
Módulo de configuración del sistema restringido a administradores.
Límite de tasa definido por token+IP para la API externa.
CORS con lista blanca configurable y soporte de patrones de subdominio.
LDAP reforzado con soporte configurable para LDAPS/StartTLS, validación de certificados y timeout de red.
Validación estricta de carga de archivos por MIME real, estructura SVG y saneamiento de contenido SVG antes de persistencia.
Mejoras internas de seguridad en sesiones, cookies, almacenamiento de claves y manejo de errores.

Open Badges 2.0 y verificación

Mejoras de revocación OB 2.0 con /revocationlist/{badge_uid}, revokedOn y revocationReason.
Verificador compatible con assertions revocadas publicadas con HTTP 410 Gone.
Validación de propiedad por correo más explícita en resultados obtenidos en el verificador.
Metadatos públicos con respuestas semánticas application/ld+json.
Hash del receptor reforzado para mayor privacidad.

Portafolio externo y recuperación de acceso

Nuevo flujo público para consultar el portafolio con correos externos, sin autenticación LDAP y sin depender de sesiones o cookies del servidor.
Se incorporaron las rutas /backpack_external/request-access, /backpack_external/verify y /backpack_external/profile/{email_b64}/{view_token} para solicitud, validación y consulta temporal del portafolio.
La verificación externa ahora usa OTP de 6 dígitos de un solo uso y un token temporal de vista en la URL, permitiendo refrescar la página del portafolio durante 10 minutos sin pedir un código nuevo.
Se agregó una nueva tabla de control para tokens de acceso externo, con expiración, límite de intentos fallidos y rate limiting por IP/correo.
La vista del portafolio fue adaptada para modo externo de solo lectura, sin menú interno, sin datos de sesión y ocultando enlaces JSON privados.
La pantalla de login ahora incluye un acceso visible al portafolio externo y el correo de adjudicación incorpora un enlace directo para solicitar este acceso.

Archivos, UX y mejoras generales

Soporte extendido para insignias en formato PNG (carga y verificación), manteniendo SVG como formato canónico interno.
Correcciones del baking SVG y robustez en guardado/estructura.
Flujo de compartir adjudicación optimizado para LinkedIn y ajustes visuales de interfaz. Removidas otras redes sociales.
Se agregó código QR en el modal de compartir de la adjudicación pública para facilitar acceso desde móvil y descarga rápida del QR.
Sidebar con scroll interno automático solo cuando el contenido excede el alto disponible.
Optimizaciones internas de sesiones, caché y plantilla de correo.
La insignia obtenida ahora es visible en la plantilla de correo de adjudicación, con un diseño más claro y profesional.
Mejoras internas y visuales en el verificador de insignias, con mensajes de error más claros y detallados para casos comunes como insignias revocadas, expiradas o con datos faltantes.
Perfil público de adjudicación ahora muestra el nombre real de la persona receptora y la revocación de forma destacada, con fecha y motivo si están disponibles, y un mensaje claro para el receptor sobre la situación de su insignia.
Mejoras generales de interfaz (usabilidad y accesibilidad): íconos actualizados, textos más claros, consistencia en botones y campos del formulario, y correcciones de diseño para una experiencia más fluida.
Mejoras en usabilidad del formulario de adjudicación masiva: textos más descriptivos, validación en tiempo real, mensajes de error detallados, corrección automática de fechas y previsualización de datos antes de confirmar la adjudicación.
Nueva sección para consultar el reporte general de emisión, con estadísticas clave por emisor, como el total de insignias emitidas y revocadas, así como las últimas adjudicaciones.
Nuevo encabezado que muestra el nombre del usuario e incorpora un submenú de acceso rápido al portafolio, los reportes y el cierre de sesión.

Resumen

Esta versión amplía fuertemente las capacidades del sistema: moderniza la adjudicación masiva, agrega validador propio, rutas de aprendizaje, catálogo público de insignias, mejoras de privacidad y una nueva API v2 para integraciones externas.

Detalle de cambios

Adjudicación masiva rediseñada: El proceso de adjudicar insignias a múltiples personas fue completamente mejorado. Ahora se carga un archivo CSV (editable desde Excel), que se previsualiza y edita en una tabla dinámica directamente en el formulario. El sistema resalta errores en los datos en tiempo real e informa con detalle cuáles envíos de correo fallaron.
Validador de insignias propio: Se incorporó un verificador público basado en el estándar Open Badges 2.0, para no depender de herramientas externas que puedan estar caídas o no disponibles.
Rutas de aprendizaje: Nueva funcionalidad que permite crear secuencias ordenadas de insignias por emisor. El progreso del receptor se muestra visualmente tanto en el perfil de la insignia como en el perfil de la adjudicación.
Catálogo público de insignias: Nuevo catálogo que lista todas las insignias creadas por cuentas institucionales, con su respectivo emisor, ordenadas por nombre y disponibles para adjudicar. Accesible desde el menú, el inicio y la pantalla de login.
Perfil público individual de insignias: Cada insignia ahora tiene su propia página pública, incluso si aún no ha sido adjudicada a nadie.
Privacidad de datos mejorada: Los datos personales del receptor (correo y nombre) ya no se muestran en perfiles públicos ni en el portafolio, evitando exposición involuntaria. El portafolio de los funcionarios pasa a ser privado. Los usuarios externos ya no tienen portafolio; en su lugar, pueden descargar o compartir la insignia directamente desde su perfil de adjudicación.
Términos de uso actualizados: Se revisaron y ampliaron los términos, con especial atención a la distinción entre cuentas institucionales (funcionario) y cuentas externas, que reemplaza los conceptos anteriores de Verificado y No Verificado.
Correo de adjudicación mejorado: El email que recibe el acreedor ahora incluye un enlace a los términos de uso y muestra de forma visible el correo del emisor, para que pueda contactarlo directamente ante cualquier consulta.
Compartir y descargar desde el perfil público: Se añadieron opciones para compartir la adjudicación en LinkedIn, Facebook y X (Twitter), copiar la URL, descargar la insignia directamente o generar un código HTML para incrustar en otros sitios.
Modo mantenimiento: Los administradores ahora pueden activar un modo de mantenimiento desde la configuración del sistema. Cuando está activo, solo los administradores pueden acceder a la plataforma.
API v2 para adjudicaciones externas: Nueva versión de la API con mejoras en formato, seguridad y compatibilidad para integración con aplicaciones de terceros.
Identificadores únicos mejorados: Se actualizó la generación de UIDs para emisores, insignias y adjudicaciones, usando una especificación criptográfica más robusta.
URLs y APIs alineadas al estándar OB: Las rutas públicas y de API fueron mejoradas para cumplir con la especificación Open Badges, manteniendo compatibilidad con las URLs anteriores ya generadas.
Actualización del núcleo: Se actualizó el framework base, con mejoras de seguridad, manejo de rutas y compatibilidad con PHP 8+. Se realizaron también mejoras generales de interfaz: íconos, textos, claridad en botones y campos del formulario.

Resumen

Esta versión marca la salida a estable del sistema, renueva la interfaz, moderniza la base tecnológica y consolida el cumplimiento práctico del estándar Open Badges 2.0.

Detalle de cambios

Versión estable: El sistema sale oficialmente de la fase BETA y pasa a versión estable.
Rediseño completo de la interfaz: La apariencia y el diseño fueron renovados por completo para adaptarse al estándar visual institucional de la UNED. Se corrigieron enlaces rotos, se mejoraron textos, íconos y la claridad general de los controles.
Actualización del núcleo: Se modernizó el framework base con mejoras de rendimiento y compatibilidad total con PHP 8. Se eliminó por completo la dependencia de jQuery.
Cumplimiento del estándar OB 2.0: Las insignias adjudicadas ahora superan correctamente los validadores externos del estándar Open Badges 2.0, incluyendo IMS Global, OpenBadge Factory y Badgr.
Emisores verificados: Se introdujo una distinción entre emisores normales y emisores con cuenta verificada. Esta condición se refleja visualmente en el portafolio, el perfil público de la insignia y el perfil del emisor mediante una etiqueta de verificación. Solo los administradores pueden cambiar este estado desde el formulario de edición de usuarios.
Términos de uso: Se añadieron términos de uso a modo de descargo de responsabilidad, que el usuario acepta al utilizar la plataforma.
Adjudicación masiva mejorada: Ahora se carga un archivo TXT con separación por tabulación (exportable fácilmente desde Excel) en lugar del formato anterior, simplificando la preparación y carga de datos.
Nuevos campos en adjudicaciones e insignias: Se añadió el campo Evidencia en adjudicaciones (enlace de respaldo opcional, parte del estándar OB), el campo Tags / Etiquetas en insignias, y se amplió el campo Criterio para admitir más texto y formato multilínea.
Estado de revocación visible: Las insignias revocadas y no revocadas ahora se distinguen visualmente tanto en el portafolio del usuario como en las vistas internas.
Correo personalizable: Al adjudicar una insignia, ahora es posible incluir un mensaje de texto opcional en el correo que recibe el acreedor.
API mejorada con nuevos ejemplos: La API para adjudicaciones externas fue mejorada y se añadieron ejemplos de uso en JavaScript y PHP. Se incorporó además una nueva API para consultar el portafolio completo o filtrado por emisor.
Portafolio renombrado: La sección anteriormente llamada "Mochila" ahora se denomina "Portafolio" en la interfaz (la URL interna sigue siendo {backpack} para mantener compatibilidad).

Emisor de Insignias

Dirección de Internacionalización y Cooperación

Resumen

Detalle de cambios

Delegación institucional

Interfaz y claridad operativa

Auditoría y consistencia

Resumen

Detalle de cambios

Administración y operación

Seguridad y hardening

Open Badges 2.0 y verificación

Portafolio externo y recuperación de acceso

Archivos, UX y mejoras generales

Resumen

Detalle de cambios

Resumen

Detalle de cambios