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

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

{
  "statusCode": 200,
  "info": {
    "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

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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"
      }
    ]
  }
}

---

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

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

{
  "statusCode": 200,
  "info": {
    "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

{
  "statusCode": 200,
  "info": {
    "updated": true
  }
}

---

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

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Errores

• 400 — la insignia tiene otorgamientos y no se puede eliminar
• 404 — insignia no encontrada