API de credenciales

Gestiona plantillas de credenciales — las que entregas a los destinatarios.

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

Crear credencial

Crea una credencial bajo un emisor verificado.

POST /badges

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
name	string	Sí	Título de la credencial
description	string	Sí	Qué representa la credencial
criteria	string	Sí	Qué hizo el destinatario para ganarla
image	string	Sí	Imagen codificada en Base64 (PNG o JPG)
issuerId	string	Sí	El 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 credenciales.
• La imagen se sube a IPFS para su almacenamiento perenne.

---

Listar credenciales

Recupera todas las credenciales que has 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 credencial

Actualiza una credencial existente. Solo cambian los campos que envíes.

PUT /badges/{badgeId}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	El ID de la credencial (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 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 difusión

Fija el texto personalizado que aparecerá cuando los destinatarios difundan esta credencial en redes sociales.

PUT /badges/{badgeId}/share-text

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	El ID de la credencial (parámetro de ruta)
text	string	Sí	Texto de difusión (sin HTML permitido)

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 credencial

Elimina una credencial. No puede 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 credencial tiene otorgamientos y no puede eliminarse
• 404 — credencial no encontrada