API de emisores

Gestiona los emisores de insignias: las organizaciones o personas que emiten insignias.

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

Crear emisor

Crea un nuevo emisor de insignias.

POST /issuers

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre de la organización (mínimo 3 caracteres)
url	string	Sí	Sitio web de la organización (debe ser una URL HTTP/HTTPS válida)
email	string	Sí	Correo electrónico de contacto del emisor
logo	string	No	Imagen codificada en Base64 (PNG o JPG)
linkedinOrganizationId	string	No	ID numérico de la página de empresa de LinkedIn. Si se define, cada página pública de credencial de este emisor muestra un botón Añadir al perfil de LinkedIn.

Ejemplo

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

Respuesta

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

Notas

• Cuenta para el límite de emisores de tu plan (Free: 2, Starter: 5, Pro: 10). No se descuenta cuota.
• Si el correo del emisor coincide con el de tu cuenta, el emisor se verifica automáticamente.
• Si el correo es distinto, se envía un correo de verificación a la dirección del emisor.
• Tras configurar un emisor, usa la API de credenciales para empezar a emitir credenciales con ese emisor.

---

Listar emisores

Obtiene todos los emisores que has creado.

GET /issuers

Ejemplo

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

Respuesta

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp es una marca de tiempo Unix en milisegundos. Cuando existen más emisores de los que caben en una página, también se devuelve un lastEvaluatedKey para la paginación.

---

Verificar emisor

Verifica un emisor con el código de verificación enviado a su correo electrónico.

POST /issuers/{issuerId}/verify

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
issuerId	string	Sí	El ID del emisor (parámetro de ruta)
code	string	Sí	El código de verificación del correo

Ejemplo

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Respuesta

Una cadena simple:

"issuer has been verified"

---

Eliminar emisor

Elimina un emisor. El emisor no debe tener insignias vinculadas.

DELETE /issuers/{issuerId}

Ejemplo

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta

Una cadena simple:

"issuer has been deleted"

Errores

• 400: el emisor aún tiene insignias vinculadas: issuer has {n} badge(s) linked — delete the badges first. La eliminación depende únicamente de las insignias vinculadas; las credenciales no la bloquean.
• 404: emisor no encontrado

---

Actualizar emisor

Actualiza los campos de un emisor. Solo se pueden editar los emisores no verificados: una vez verificado un emisor, este endpoint devuelve 400 verified issuers cannot be edited para preservar la estabilidad de las credenciales. Al editar un emisor se regenera su código de verificación: si el email coincide con el de tu cuenta, el emisor se vuelve a verificar automáticamente; de lo contrario, se envía un nuevo correo de verificación a esa dirección.

PUT /issuers/{issuerId}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
issuerId	string	Sí	El ID del emisor (parámetro de ruta)
name	string	No	Nuevo nombre
url	string	No	Nueva URL
email	string	No	Nuevo correo (envía un nuevo correo de verificación salvo que coincida con el de tu cuenta)
logo	string	No	Nuevo logotipo codificado en Base64
linkedinOrganizationId	string	No	Nuevo ID de organización de LinkedIn (o cadena vacía para borrarlo)

Respuesta

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Errores

• 400: verified issuers cannot be edited (el emisor ya está verificado)
• 400: not authorized (el emisor pertenece a otra cuenta)
• 404: emisor no encontrado