API de credencials

Crea i gestiona credencials (assertions) — insígnies lliurades a destinataris concrets.

Tots els endpoints requereixen autenticació amb la capçalera X-Api-Key. Consulta Autenticació.

Crear credencial

Lliura una credencial a un destinatari.

POST /awards

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la credencial a emetre
recipient	object	Sí	Dades del destinatari (vegeu més avall)
recipient.name	string	Sí	Nom complet del destinatari (mínim 5 caràcters)
recipient.email	string	Sí	Correu del destinatari
issuedOn	string	Sí	Data d'emissió en format ISO 8601 (p. ex. 2025-01-15)
expires	string	No	Data de caducitat en format ISO 8601

Exemple

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"
    }
  }'

Resposta

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

Notes

• Descompta un de la teva bossa mensual (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). La bossa es reinicia cada període de facturació.

---

Llistar credencials

Recupera credencials amb filtres i paginació opcionals.

GET /awards

Paràmetres de consulta

Paràmetre	Tipus	Obligatori	Descripció
filter	JSON string	No	Objecte de filtre (vegeu més avall)
lastEvaluatedKey	string	No	Token de paginació d'una resposta anterior

Objecte de filtre

El paràmetre filter accepta un JSON string amb aquests camps:

Camp	Tipus	Descripció
badgeId	string	Filtra per ID de credencial.
search	string	Subcadena a cercar en noms o correus de destinataris (mira searchField).
searchField	string	O name (per defecte) o email — quina columna cercar.

La paginació amb lastEvaluatedKey funciona amb o sense filtres. La mida de pàgina és 50.

Exemple — Llistar totes les credencials

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

Exemple — Filtrar per credencial

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"

Resposta

{
  "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 resposta inclou lastEvaluatedKey, hi ha més resultats. Passa'l com a paràmetre de consulta a la següent sol·licitud per obtenir la pàgina següent.

---

Enviar correu de credencial

Envia un correu al destinatari sobre la seva credencial.

POST /awards/{awardId}/send

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
awardId	string	Sí	L'ID de l'atorgament (paràmetre de ruta i cos)
email	string	Sí	Correu del destinatari

Exemple

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"
    }
  }'

Resposta

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

---

Difondre credencial

Difon una credencial a diversos destinataris per correu.

POST /awards/{awardId}/share

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
awardId	string	Sí	L'ID de l'atorgament (paràmetre de ruta i cos)
recipients	string	Sí	Llista de correus separada per comes
subject	string	Sí	Assumpte del correu
message	string	Sí	Cos del missatge

Exemple

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."
    }
  }'

Resposta

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

---

Baixar certificat PDF

Genera un PDF A4 a punt per imprimir d'una credencial.

GET /awards/{awardGuid}/pdf

No requereix autenticació — aquest endpoint és públic perquè els destinataris puguin baixar el seu propi certificat.

Exemple

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

La resposta és el PDF binari amb capçalera Content-Type: application/pdf.

---

Registrar esdeveniment de la credencial

Registra un esdeveniment d'interacció (visita, difusió, descàrrega, afegit a LinkedIn). L'utilitza la pàgina pública de la credencial per alimentar estadístiques d'interacció. No requereix autenticació.

POST /awards/{awardGuid}/event

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
kind	string	Sí	Un de view, share, download, linkedin_add.
network	string	No	Si kind=share, la xarxa social: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Supressió de duplicats per IP: el mateix tipus des de la mateixa IP es compta una sola vegada cada 24 hores.

Exemple

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ístiques de la credencial

Recupera comptadors acumulatius d'interacció d'una credencial.

GET /awards/{awardGuid}/stats

No requereix autenticació.

Resposta

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