API de otorgamientos

Crea y gestiona otorgamientos de insignias (assertions) — insignias emitidas a destinatarios concretos.

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

Crear otorgamiento

Emite una insignia a un destinatario.

POST /awards

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	ID de la insignia a otorgar
recipient	object	Sí	Datos del destinatario (ver abajo)
recipient.name	string	Sí	Nombre completo del destinatario (mínimo 5 caracteres)
recipient.email	string	Sí	Correo 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
blockchain	string	No	Blockchain para verificación on-chain. Solo se admite matchain. Disponible en el plan Pro.

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 un otorgamiento contra tu cuota mensual (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). La cuota se mide sobre los otorgamientos creados desde las 00:00 UTC del día 1 del mes natural en curso — se reinicia en el límite del mes natural UTC, no en tu aniversario de facturación.
• El parámetro blockchain solo está disponible en el plan Pro, y solo acepta matchain.
• El anclaje en blockchain aún no está activo. Pasar blockchain: "matchain" se acepta y se registra como una solicitud, pero todavía no se escribe ninguna prueba on-chain — por ahora los otorgamientos no llevan ningún registro on-chain verificable.

---

Listar otorgamientos

Recupera otorgamientos con filtrado y paginación opcionales.

GET /awards

Parámetros de query

Parámetro	Tipo	Obligatorio	Descripción
filter	JSON string	No	Objeto de filtro (ver 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 a buscar en nombres o correos de destinatarios (ver searchField).
searchField	string	Bien name (predeterminado) o email — qué columna buscar.

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

Ejemplo — listar todos los otorgamientos

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://ipfs.ninja/ipfs/Qm..."
      },
      "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 query parameter en la próxima solicitud para obtener la página siguiente.

---

Enviar correo de otorgamiento

Envía una notificación por correo al destinatario sobre su otorgamiento.

POST /awards/{awardId}/send

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	ID del otorgamiento (parámetro de ruta y cuerpo)
email	string	Sí	Correo 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 otorgamiento

Comparte un otorgamiento con varios destinatarios por correo.

POST /awards/{awardId}/share

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	ID del otorgamiento (parámetro de ruta y cuerpo)
recipients	string	Sí	Lista de correos separados por comas
subject	string	Sí	Asunto del correo
message	string	Sí	Cuerpo del mensaje

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 otorgamiento

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

POST /awards/{awardId}/revoke

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
awardId	string	Sí	ID del otorgamiento (parámetro de ruta)
reason	string	No	Motivo de la revocación. Se trunca a 500 caracteres.
notify	boolean	No	Cuando es true, envía un correo al destinatario informándole de que su otorgamiento fue revocado. 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 un otorgamiento ya revocado es idempotente — devuelve la misma respuesta sin reenviar una notificación.

---

Eliminar otorgamiento

Elimina de forma permanente un otorgamiento que hayas emitido. A diferencia de la revocación, esto elimina el registro por completo y la página pública del otorgamiento devolverá 404. Usa esto para errores genuinos (p. ej. otorgado a la persona equivocada); para credenciales reales prefiere revocar, de modo que la assertion 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í	ID del otorgamiento (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 PDF

Genera un certificado PDF A4 listo para imprimir para un otorgamiento.

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 cabecera Content-Type: application/pdf.

---

Registrar evento de otorgamiento

Registra un evento de interacción. Lo usa la página pública de otorgamiento para alimentar 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 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 event 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 del otorgamiento

Recupera contadores acumulados de interacción para un otorgamiento.

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

No requiere autenticación.

Respuesta

Los contadores se devuelven indexados por el tipo de evento en bruto. totals contiene el recuento total por evento; networks desglosa el reparto por red para los eventos que llevan un 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 }
  }
}