API d'atorgaments

Crea i gestiona atorgaments (assertions) — credencials lliurades a destinataris concrets.

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

Crear atorgament

Lliura una credencial a un destinatari.

POST /awards

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
badgeId	string	Sí	L'ID de la credencial a atorgar
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
blockchain	string	No	Blockchain per a la verificació on-chain. Només s'admet matchain. Disponible al pla Pro.

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ó.
• El paràmetre blockchain només està disponible al pla Pro.

---

Llistar atorgaments

Recupera atorgaments 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 tots els atorgaments

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 d'atorgament

Envia un correu al destinatari sobre el seu atorgament.

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 atorgament

Difon un atorgament 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'un atorgament.

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 l'atorgament

Registra un esdeveniment d'interacció (visita, difusió, descàrrega, afegit a LinkedIn). L'utilitza la pàgina pública de l'atorgament 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 l'atorgament

Recupera comptadors acumulatius d'interacció d'un atorgament.

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