Referencia de la API de insignias: crear, verificar y obtener insignias

Gestiona las plantillas de insignias, las credenciales que emites a los destinatarios.

Para emitir esta insignia a muchos destinatarios a la vez mediante la carga de un CSV en lugar de usar la API, consulta Credenciales masivas.

Todos los endpoints requieren autenticación mediante 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í	Qué representa la insignia
criteria	string	Sí	Qué hizo el destinatario para obtener esta insignia
image	string	Sí	Imagen codificada en Base64 (PNG o JPG)
issuerId	string	Sí	El ID del emisor verificado
shareText	string	No	Texto predeterminado para compartir en redes sociales para esta insignia. 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 poder volver a editar la insignia 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 almacena en Amazon S3 y se sirve a través de nuestra CDN global bajo una URL inmutable direccionada por contenido.
• Una vez que existe una clase de insignia, emítela a los destinatarios con la API de credenciales.

---

Listar insignias

Obtén todas las insignias que has 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://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Obtener insignia

Obtén una sola insignia, incluido su texto para compartir y el documento serializado del diseñador de insignias (designJson). Este es el endpoint que usa el modal de edición de insignias para rehidratar cada capa; 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í	El 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://badges.ninja/images/{sha256}.png",
  "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 para compartir siempre se incluye. La variante de listado más ligera GET /badges?badgeId={id} devuelve el mismo documento sin designJson, y solo incluye el texto para compartir cuando se llama con includeShareText=true.

---

Actualizar insignia

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

PUT /badges/{badgeId}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	El ID de la insignia (parámetro de ruta)
name	string	No	Nuevo título de la insignia
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 para compartir

Define 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í	El ID de la insignia (parámetro de ruta)
text	string	Sí	Texto para compartir (no se permite 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 credenciales.

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 credenciales emitidas: "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