Emite Open Badges con la API REST de Badges Ninja: guía de inicio rápido

La mayoría de los programas de credenciales no necesitan una API. Si impartes un curso con unos cientos de graduados al año, el panel de control lo hace todo: diseñas una insignia en el diseñador visual, subes un CSV y cada destinatario recibe una página de verificación y un certificado en PDF. Si ese es tu caso, empieza por cómo emitir Open Badges desde un CSV y vuelve más tarde.

La API se gana su lugar cuando otro sistema debe emitir las credenciales: tu plataforma de aprendizaje marca un curso como completado, tu herramienta de inscripciones cierra un evento, tu sistema de RR. HH. registra un módulo de cumplimiento terminado. En esos casos nadie quiere exportar una hoja de cálculo al final de cada semana. Una sola llamada HTTP en el momento de la finalización es más sencilla, y el destinatario recibe su insignia mientras el logro sigue fresco.

Esta guía recorre todo el camino en cuatro llamadas: obtener una clave, crear un emisor, crear una insignia y otorgarla. Después vemos cómo entregar el enlace de verificación al destinatario y comprobar el resultado. Cada formato de petición que verás sale de los handlers desplegados, así que puedes copiarlo, pegarlo y ejecutarlo.

Qué necesitas antes de empezar

Una cuenta gratuita en badges.ninja. El plan Free basta para este tutorial: incluye 2 emisores, 5 insignias, 2 puestos y 1 clave de API.
Una clave de API, creada desde el panel.
Un PNG o JPG para la imagen de la insignia, o una insignia que hayas diseñado en el diseñador visual.

La URL base para todo es https://api.badges.ninja.

Paso 1: Crea una clave de API

Inicia sesión, abre API Keys en la barra lateral y haz clic en Create API Key. Ponle un nombre que indique dónde va a vivir, como “LMS integration”, para distinguir las claves cuando las rotes más adelante.

Newly created key revealed once

La clave se muestra una sola vez. Cópiala de inmediato en tu gestor de secretos o en una variable de entorno. Las claves tienen la forma bws_ seguida de 32 caracteres hexadecimales, y se envían en la cabecera X-Api-Key en cada petición. Revocar una clave desde la misma pantalla surte efecto al instante.

Unos hábitos que te ahorrarán problemas:

Nunca pongas la clave en código de front-end ni en un repositorio público. Llama a la API desde un servidor, una función serverless o una herramienta de automatización.
Usa una clave por integración. Si una se filtra, revocas una integración en lugar de todas.
El panel también acepta tu sesión iniciada (un JWT de Cognito enviado como Authorization: Bearer), pero para scripts e integraciones la herramienta adecuada es la clave de API.

Todos los ejemplos siguientes leen la clave de una variable de entorno llamada BADGES_API_KEY.

Paso 2: Crea un emisor

Un emisor es la organización que respalda la insignia. Aparece en cada página de verificación y dentro de los datos de Open Badge v2.0, así que usa el nombre que la gente realmente conoce.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

Los campos obligatorios son name (al menos 3 caracteres), url (una dirección http o https válida) y email. Los campos opcionales son logo (una imagen codificada en base64) y linkedinOrganizationId, que activa el botón Add to LinkedIn Profile en tus páginas públicas de credenciales.

La respuesta contiene el identificador del emisor:

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Guarda ese valor exactamente como lo devuelve la API. Es la entrada del siguiente paso.

Verificación del emisor

Las insignias solo se pueden crear bajo un emisor verificado. La verificación funciona así:

Si el correo del emisor coincide con el correo de tu cuenta, el emisor se verifica automáticamente. Es el camino más rápido para una primera prueba.
Si el correo es distinto, se envía a esa dirección un correo de verificación con un código. Confirmas el código en el panel (o a través de la API de emisores) antes de crear insignias.

Así que, para este tutorial, usa el mismo correo con el que te registraste.

Paso 3: Crea una insignia

Una insignia es la plantilla reutilizable: nombre, descripción, criterios e imagen. Cada otorgamiento que emitas después apunta a ella.

La petición es JSON plano. La imagen va como cadena en base64, así que no hay que pelearse con subidas multipart. Se acepta un prefijo de data URL como data:image/png;base64, y se elimina.

JavaScript (Node 18 o posterior):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Los cinco campos (name, description, criteria, image, issuerId) son obligatorios. Vale la pena conocer dos opcionales: shareText, el texto predeterminado que ven los destinatarios al compartir en redes sociales (admite los marcadores {{badge_name}}, {{issuer_name}} y {{award_url}}), y designJson, que guarda un documento del diseñador visual para poder editar la insignia capa por capa más adelante.

Un éxito devuelve HTTP 200 con { "badgeId": "<id>" }. La imagen se almacena de forma permanente, y la insignia ya es una BadgeClass de Open Badge v2.0 que cualquiera puede consultar.

¿Deberías crear insignias desde código?

Normalmente no. El diseño de insignias es una tarea creativa, y el diseñador visual (más de 80 plantillas, formas, iconos, 11 fuentes y subidas personalizadas) es un lugar mucho mejor para ello que un script. Un patrón habitual es diseñar cada insignia una vez en el panel y hacer que tu integración solo emita otorgamientos contra ella. Puedes listar tus insignias con GET /badges y copiar el id de la que quieras.

Crea insignias mediante la API cuando las generes de forma programática, por ejemplo una por curso en un catálogo de cientos, o cuando estés preparando un entorno de pruebas.

Paso 4: Otorga la insignia

Esta es la llamada que tu integración hará miles de veces. Envía la insignia, el destinatario y la fecha.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

Las reglas que suelen hacer tropezar:

recipient es un objeto anidado con name y email. Los campos planos como recipientEmail se rechazan.
recipient.name debe tener al menos 5 caracteres.
issuedOn es obligatorio. Envía milisegundos de epoch o una fecha ISO como 2026-09-28.
expires es opcional y admite los mismos formatos.

Un éxito es un HTTP 200 con un cuerpo que contiene el awardId. El correo del destinatario se almacena como hash SHA-256 en los datos de Open Badge, de modo que el JSON público nunca lo expone.

Paso 5: Encuentra la página de verificación y el JSON de Open Badge

La respuesta del otorgamiento te da un identificador, no un enlace listo para usar. El identificador termina en un GUID, y las páginas públicas se construyen a partir de ese GUID:

Página de verificación legible para personas: https://badges.ninja/awards/<awardId>
JSON-LD de Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Si tu awardId llega como una URL completa, usa el último segmento de la ruta como GUID.

Ambas son públicas. Cualquiera con el enlace puede verificar la credencial sin crear una cuenta, que es precisamente la idea: un empleador o un responsable de admisiones debería poder comprobar una insignia en diez segundos.

Descarga el JSON para ver lo que ve el mundo:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Obtienes una Assertion de Open Badge v2.0: la insignia a la que hace referencia, la identidad del destinatario con hash, la fecha de emisión y un bloque de verificación que apunta a la assertion alojada. Como son datos estándar de Open Badges, cualquier herramienta que entienda el formato puede leerlos. Esa portabilidad es la razón para elegir Open Badges frente a un PDF propietario; Open Badges vs PDF certificates profundiza en el equilibrio entre ambos.

Cómo reciben la credencial los destinatarios

Crear un otorgamiento es independiente de avisar al destinatario. Los destinatarios pueden abrir sus credenciales desde el portal de destinatarios en badges.ninja/me, que usa inicio de sesión con enlace mágico, sin contraseña, y pueden publicar un perfil público en badges.ninja/u/<handle>. Desde la página de verificación pueden añadir la insignia a LinkedIn, descargar el certificado en PDF o compartir el enlace.

En tus primeras pruebas, envíate un otorgamiento a tu propio correo y recorre la experiencia del destinatario. Es la forma más rápida de detectar cosas como una descripción de insignia que suena torpe.

Gestión de errores sin dolores de cabeza

La API usa códigos de estado HTTP normales. Los que te encontrarás:

Status	Significado	Qué hacer
200	Éxito	Lee el cuerpo JSON
400	Falta un campo o no es válido, incluido un nombre de destinatario de menos de 5 caracteres	Corrige el payload; reintentar la misma petición volverá a fallar
401	Clave de API ausente o incorrecta	Revisa la cabecera `X-Api-Key` y que la clave no se haya revocado
402	Sin créditos o sin cuota del plan	Mejora el plan o espera al siguiente periodo de cuota
404	No se encontró la insignia	Revisa el `badgeId` que enviaste

Dos consejos prácticos. Primero, trata el 400 como un problema de datos y registra el cuerpo de la respuesta, ya que nombra el campo que falla. Segundo, haz tu integración idempotente por tu lado: guarda el awardId junto al registro de finalización en tu propia base de datos y compruébalo antes de volver a llamar a la API. Así, un webhook reintentado o un job que se ejecuta de nuevo nunca emitirá dos credenciales a la misma persona.

Juntándolo todo en una integración real

Un montaje típico se ve así:

Diseña las insignias en el panel, una por curso o hito, y anota el ID de cada una.
Guarda en tu sistema una correspondencia entre curso e ID de insignia.
Cuando un alumno completa un curso, tu servidor llama a POST /awards con su nombre, correo y fecha de finalización.
Guarda el awardId devuelto junto al registro de finalización.
Muestra el enlace de verificación dentro de tu propio producto, para que el alumno lo vea sin salir de él.

Si prefieres no escribir código, la misma llamada funciona desde cualquier herramienta de automatización que pueda enviar una petición HTTP con cuerpo JSON y una cabecera personalizada. Apúntala a https://api.badges.ninja/awards y mapea los campos de tu formulario u hoja de cálculo a badgeId, recipient.name, recipient.email e issuedOn.

Planes y límites que conviene conocer

La API está disponible en todos los planes; no pagas extra para desbloquearla. El plan Free ($0) cubre 2 emisores, 5 insignias, 2 puestos, 1 clave de API y 1,200 credenciales al año. Starter cuesta $9 al mes y Pro $29 al mes, con límites más altos. Consulta la página de precios para ver las cifras actuales antes de dimensionar un despliegue. Si estás comparando lo que cobran otras plataformas por acceder a su API, Credly alternative expone los costes lado a lado.

Siguientes pasos

La referencia completa de endpoints está en la documentación de la API, disponible en 40 idiomas.
Para detalles de autenticación y manejo de claves, consulta la guía de autenticación.
Para los códigos de error en profundidad, consulta la referencia de errores.
Cuando una llamada a la vez se te quede corta, usa los otorgamientos masivos del panel: sube un CSV y pausa o reanuda la ejecución si lo necesitas.

Lo difícil es el primer otorgamiento exitoso. Después, todo consiste en conectar la misma llamada a los lugares donde ya se registran los logros.

¿Listo para emitir tu primera credencial digital verificable? Empieza gratis en badges.ninja — diseñador visual, página pública de verificación, certificado en PDF, salida Open Badge v2.0. Sin tarjeta de crédito.