API de credenciales

Crea y gestiona credenciales (assertions) — 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.

POST /awards

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
badgeId	string	Sí	El ID de la insignia a emitir
recipient	object	Sí	Datos del destinatario (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

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

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

Notas

• Descuenta uno de tu bolsa mensual (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). La bolsa se reinicia cada periodo de facturación.

---

Listar credenciales

Recupera credenciales con filtros y paginación opcionales.

GET /awards

Parámetros de consulta

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

Objeto de filtro

El parámetro filter admite un JSON string con estos campos:

Campo	Tipo	Descripción
badgeId	string	Filtrar por ID de insignia.
search	string	Subcadena a buscar en nombres o correos de destinatarios (mira searchField).
searchField	string	O name (por defecto) o email — qué columna buscar.

La paginación por 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

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "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 la respuesta incluye lastEvaluatedKey, hay más resultados. Pásalo como parámetro de consulta en la siguiente solicitud para obtener la próxima página.

---

Enviar correo de credencial

Envía un correo al 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 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

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

Difundir credencial

Difunde una credencial a varios destinatarios por correo.

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 cuerpo)
recipients	string	Sí	Lista de correos separada 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

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

Descargar certificado PDF

Genera un PDF A4 listo para imprimir de una credencial.

GET /awards/{awardGuid}/pdf

No requiere autenticación — este endpoint es público para que los destinatarios descarguen su propio certificado.

Ejemplo

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

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

---

Registrar evento de la credencial

Registra un evento de interacción (visita, difusión, descarga, agregación a LinkedIn). Lo utiliza la página pública de la credencial para alimentar estadísticas de interacción. No requiere autenticación.

POST /awards/{awardGuid}/event

Parámetros

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

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

Ejemplo

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

---

Estadísticas de la credencial

Recupera contadores acumulativos de interacción de una credencial.

GET /awards/{awardGuid}/stats

No requiere autenticación.

Respuesta

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}