API de credenciales

Crea y gestiona credenciales (aserciones): insignias emitidas a destinatarios concretos.

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

Crear credencial

Emite una insignia a un destinatario.

¿Necesitas emitir a cientos o miles de destinatarios a la vez en lugar de una llamada a la API por persona? Usa la función de la interfaz Credenciales masivas, que acepta una carga de CSV.

POST /awards

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	El ID de la insignia que se va a emitir
recipient	object	Sí	Datos del destinatario (ver más abajo)
recipient.name	string	Sí	Nombre completo del destinatario (mínimo 5 caracteres)
recipient.email	string	Sí	Dirección de correo electrónico del destinatario
issuedOn	string	Sí	Fecha de emisión en formato ISO 8601 (p. ej., 2025-01-15)
expires	string	No	Fecha de caducidad en formato ISO 8601

Ejemplo

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Respuesta

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Notas

• Cuenta como una credencial de tu reserva anual de credenciales (Free: 1,200/año, Starter: 12,000/año, Pro: 120,000/año). La reserva es una asignación anual flexible: úsala cuando quieras a lo largo del año, incluso en ráfagas, y se restablece en el aniversario del registro de tu cuenta. La facturación sigue siendo mensual; solo la cuota de credenciales es anual. Consulta Planes y facturación para más detalles.

---

Listar credenciales

Obtén credenciales con filtrado y paginación opcionales.

GET /awards

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
filter	JSON string	No	Objeto de filtro (ver más abajo)
lastEvaluatedKey	string	No	Token de paginación de una respuesta anterior

Objeto de filtro

El parámetro filter acepta una cadena JSON con estos campos:

Campo	Tipo	Descripción
badgeId	string	Filtra por ID de insignia.
search	string	Subcadena que se busca en los nombres o en los correos de los destinatarios (ver searchField).
searchField	string	name (predeterminado) o email: la columna en la que se busca.

La paginación mediante lastEvaluatedKey funciona con o sin filtros. El tamaño de página es 50.

Ejemplo — Listar todas las credenciales

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

Ejemplo — Filtrar por insignia

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Si lastEvaluatedKey está presente en la respuesta, hay más resultados. Pásalo como parámetro de consulta en la siguiente solicitud para obtener la página siguiente.

---

Enviar correo de la credencial

Envía una notificación por correo electrónico a un destinatario sobre su credencial.

POST /awards/{awardId}/send

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	El ID de la credencial (parámetro de ruta y de cuerpo)
email	string	Sí	Dirección de correo electrónico del destinatario

Ejemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Respuesta

Devuelve una cadena de confirmación simple:

"email sent"

---

Compartir credencial

Comparte una credencial con varios destinatarios por correo electrónico.

POST /awards/{awardId}/share

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	El ID de la credencial (parámetro de ruta y de cuerpo)
recipients	string	Sí	Lista de direcciones de correo separadas por comas
subject	string	Sí	Asunto del correo
message	string	Sí	Cuerpo del mensaje del correo

Ejemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Respuesta

Devuelve una cadena de confirmación simple:

"email sent"

---

Revocar credencial

Revoca una credencial que hayas emitido. La aserción alojada de Open Badges v2.0 se marca con revoked: true (con un motivo opcional) para que cualquier verificador vea que la insignia ya no es válida. El registro de la credencial se conserva con fines de auditoría y no se reembolsa ningún crédito.

La revocación también se propaga al Verifiable Credential de Open Badges 3.0 de la credencial: se cambia el bit de la credencial en la Bitstring Status List de W3C a la que hace referencia el credentialStatus del VC, de modo que las carteras de VC también lo detectan. Consulta Revocación (Bitstring Status List).

POST /awards/{awardId}/revoke

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	El ID de la credencial (parámetro de ruta)
reason	string	No	Motivo de la revocación. Se trunca a 500 caracteres.
notify	boolean	No	Si es true, envía un correo al destinatario avisándole de que su credencial fue revocada. Por defecto es false.

Ejemplo

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Respuesta

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Revocar una credencial ya revocada es idempotente: devuelve la misma respuesta sin volver a enviar una notificación.

Revocar de forma masiva

Para revocar muchas credenciales a la vez, usa el endpoint masivo duradero con action: "revoke" en lugar de llamar a este endpoint por cada credencial:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Devuelve { "jobId", "total" }; el trabajo revoca cada ID en el servidor (omitiendo las ya revocadas) y se puede reanudar. Los ID ya revocados y los inexistentes se notifican como omitidos.

---

Eliminar credencial

Elimina definitivamente una credencial que hayas emitido. A diferencia de revocar, esto borra el registro por completo y la página pública de la credencial devolverá 404. Úsalo para errores genuinos (p. ej., emitida a la persona equivocada); para credenciales reales, prefiere revocar para que la aserción siga siendo verificable como revocada. No se reembolsa ningún crédito.

DELETE /awards/{awardId}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	El ID de la credencial (parámetro de ruta)

Ejemplo

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Respuesta

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Descargar certificado en PDF

Genera un certificado PDF A4 listo para imprimir para una credencial.

GET /certify-badge/award/{awardGuid}/pdf

No requiere autenticación: este endpoint es público para que los destinatarios puedan descargar su propio certificado.

Ejemplo

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

La respuesta es el PDF binario con la cabecera Content-Type: application/pdf.

---

Registrar evento de la credencial

Registra un evento de interacción. Lo usa la página pública de la credencial para rellenar las estadísticas de interacción. No requiere autenticación.

POST /certify-badge/award/{awardGuid}/event

Parámetros

Este endpoint lee su cuerpo directamente (sin el envoltorio parameters).

Parámetro	Tipo	Obligatorio	Descripción
event	string	Sí	Uno de view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	No	Cuando event=share, la red social: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Supresión de duplicados por IP: el mismo evento desde la misma IP se cuenta una vez cada 24 horas.

Ejemplo

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Respuesta

{
  "ok": true
}

---

Obtener estadísticas de la credencial

Obtén los contadores acumulados de interacción de una credencial.

GET /certify-badge/award/{awardGuid}/stats

No requiere autenticación.

Respuesta

Los contadores se devuelven indexados por el tipo de evento sin procesar. totals contiene el recuento total por evento; networks desglosa el reparto por red para los eventos que llevan network (actualmente share). Los eventos sin actividad registrada simplemente no aparecen.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}