API de emisores

Gestiona los emisores de insignias — las organizaciones o personas que otorgan insignias.

Todos los endpoints requieren autenticación vía 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 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 en LinkedIn. Si está establecido, cada página pública de otorgamiento 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 contra el límite de emisores de tu plan (Free: 1, Starter: 5, Pro: ilimitado). No descuenta cuota.
• Si el correo del emisor coincide con el correo de tu cuenta, el emisor queda verificado automáticamente.
• Si el correo es distinto, se envía un correo de verificación al correo del emisor.

---

Listar emisores

Recupera todos los emisores que hayas 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 un tiempo Unix epoch 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 usando el código de verificación enviado a su correo.

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 todavía tiene insignias vinculadas: issuer has {n} badge(s) linked — delete the badges first. La eliminación depende únicamente de las insignias vinculadas — los otorgamientos 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 que un emisor está verificado, este endpoint devuelve 400 verified issuers cannot be edited para preservar la estabilidad de las credenciales. Editar un emisor regenera su código de verificación: si el email coincide con el correo 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 correo de tu cuenta)
logo	string	No	Nuevo logo 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