API de insignias

Gestiona plantillas de insignia — las credenciales que otorgas a los destinatarios.

Todos los endpoints requieren autenticación vía la cabecera X-Api-Key. Consulta Autenticación.

Crear insignia

Crea una nueva insignia bajo un emisor verificado.

POST /badges

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
name	string	Sí	Título de la insignia
description	string	Sí	Lo que representa la insignia
criteria	string	Sí	Qué hizo el destinatario para obtenerla
image	string	Sí	Imagen codificada en Base64 (PNG o JPG)
issuerId	string	Sí	ID del emisor verificado
shareText	string	No	Texto predeterminado para compartir esta insignia en redes sociales. Admite los marcadores , y . Si se omite, se usa un valor predeterminado integrado.
designJson	string	No	Documento serializado del diseñador de insignias, guardado para que la insignia pueda reeditarse capa por capa más adelante.

Ejemplo

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Respuesta

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

Notas

• El emisor debe estar verificado antes de crear insignias.
• La imagen se sube a IPFS para almacenamiento permanente.

---

Listar insignias

Recupera todas las insignias que hayas creado.

GET /badges

Ejemplo

curl -X GET https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://ipfs.ninja/ipfs/Qm...",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Obtener insignia

Recupera una única insignia, incluido su texto de compartición y el documento serializado del diseñador de insignias (designJson). Este es el endpoint que usa el modal de Editar insignia para rehidratar las capas individuales; el endpoint de listado omite designJson para mantener las respuestas ligeras.

GET /badges/{badgeId}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	ID de la insignia (parámetro de ruta)

Ejemplo

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://ipfs.ninja/ipfs/Qm...",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

El texto de compartición siempre se incluye. La variante de listado más ligera GET /badges?badgeId={id} devuelve el mismo documento sin designJson, e incluye el texto de compartición solo cuando se llama con includeShareText=true.

---

Actualizar insignia

Actualiza una insignia existente. Solo se cambian los campos que indiques.

PUT /badges/{badgeId}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	ID de la insignia (parámetro de ruta)
name	string	No	Nuevo título
description	string	No	Nueva descripción
criteria	string	No	Nuevos criterios
image	string	No	Nueva imagen codificada en Base64
designJson	string	No	Nuevo documento serializado del diseñador de insignias.

Ejemplo

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Respuesta

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

Actualizar texto de compartición

Establece el texto personalizado que se muestra cuando los destinatarios comparten esta insignia en redes sociales.

PUT /badges/{badgeId}/share-text

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	ID de la insignia (parámetro de ruta)
text	string	Sí	Texto de compartición (sin HTML)

Ejemplo

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Respuesta

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Eliminar insignia

Elimina una insignia. La insignia no debe tener otorgamientos.

DELETE /badges/{badgeId}

Ejemplo

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta

Devuelve una cadena de confirmación simple:

"badge has been deleted"

Errores

• 400 — la insignia aún tiene otorgamientos emitidos: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — insignia no encontrada