API de credencials

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

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

Crear credencial

Emet una insígnia a un destinatari.

Necessites emetre a centenars o milers de destinataris alhora, en lloc d'una crida a l'API per persona? Utilitza la funcionalitat d'interfície Credencials en massa, que accepta una càrrega de CSV.

POST /awards

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
`badgeId`	string	Sí	L'ID de la insígnia que s'ha d'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í	Adreça electrònica 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

bash

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

json

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

Notes

Compta com una credencial del teu conjunt anual de credencials (Free: 1.200/any, Starter: 12.000/any, Pro: 120.000/any). El conjunt és una assignació anual flexible — gasta-la quan vulguis al llarg de l'any, també en ràfegues — i es reinicia en l'aniversari del registre del teu compte. La facturació continua sent mensual; només la quota de credencials és anual. Consulta Plans i facturació per a més detalls.

Llistar credencials

Obtén credencials amb filtratge 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	Testimoni de paginació d'una resposta anterior

Objecte de filtre

El paràmetre filter accepta una cadena JSON amb aquests camps:

Camp	Tipus	Descripció
`badgeId`	string	Filtra per ID de la insígnia.
`search`	string	Subcadena que es cerca als noms o als correus dels destinataris (vegeu `searchField`).
`searchField`	string	`name` (per defecte) o `email` — quina columna es cerca.

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

Exemple — Llistar totes les credencials

bash

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

Exemple — Filtrar per insígnia

bash

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

json

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

Enviar el correu de la credencial

Envia una notificació per correu electrònic a un destinatari sobre la seva credencial.

POST /awards/{awardId}/send

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
`awardId`	string	Sí	L'ID de la credencial (paràmetre de ruta i del cos)
`email`	string	Sí	Adreça electrònica del destinatari

Exemple

bash

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

Retorna una cadena de confirmació simple:

json

"email sent"

Compartir credencial

Comparteix una credencial per correu electrònic amb diversos destinataris.

POST /awards/{awardId}/share

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
`awardId`	string	Sí	L'ID de la credencial (paràmetre de ruta i del cos)
`recipients`	string	Sí	Llista d'adreces electròniques separades per comes
`subject`	string	Sí	Assumpte del correu
`message`	string	Sí	Cos del missatge del correu

Exemple

bash

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

Retorna una cadena de confirmació simple:

json

"email sent"

Revocar credencial

Revoca una credencial que hagis emès. L'assertion allotjada d'Open Badges v2.0 es marca amb revoked: true (amb un motiu opcional) perquè qualsevol verificador vegi que la insígnia ja no és vàlida. El registre de la credencial es conserva per a fins d'auditoria i no es reemborsa cap crèdit.

La revocació es propaga també al Verifiable Credential d'Open Badges 3.0 de la credencial: el bit de la credencial es canvia a la Bitstring Status List de W3C a què fa referència el credentialStatus del VC, de manera que les carteres de VC també ho detecten. Consulta Revocació (Bitstring Status List).

POST /awards/{awardId}/revoke

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
`awardId`	string	Sí	L'ID de la credencial (paràmetre de ruta)
`reason`	string	No	Motiu de la revocació. Es trunca a 500 caràcters.
`notify`	boolean	No	Si és `true`, avisa per correu el destinatari que la seva credencial ha estat revocada. Per defecte, `false`.

Exemple

bash

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

Resposta

json

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

Revocar una credencial que ja està revocada és idempotent — retorna la mateixa resposta sense tornar a enviar cap notificació.

Revocar en massa

Per revocar moltes credencials alhora, utilitza el punt d'accés durable en massa amb action: "revoke" en lloc de cridar aquest endpoint per cada credencial:

bash

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

Retorna { "jobId", "total" }; la tasca revoca tots els ID al servidor (ometent els que ja estan revocats) i es pot reprendre. Els ID ja revocats i els inexistents es reporten com a omesos.

Eliminar credencial

Elimina definitivament una credencial que hagis emès. A diferència de revocar, això suprimeix el registre del tot i la pàgina pública de la credencial retornarà 404. Fes-ho servir per a errors genuïns (p. ex. emesa a una persona equivocada); per a credencials reals, prefereix revocar perquè l'assertion continuï sent verificable com a revocada. No es reemborsa cap crèdit.

DELETE /awards/{awardId}

Paràmetres

Paràmetre	Tipus	Obligatori	Descripció
`awardId`	string	Sí	L'ID de la credencial (paràmetre de ruta)

Exemple

bash

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

Resposta

json

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

Baixar el certificat en PDF

Genera un certificat PDF A4 llest per imprimir d'una credencial.

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

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

Exemple

bash

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

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

Registrar un esdeveniment de la credencial

Registra un esdeveniment d'interacció. L'utilitza la pàgina pública de la credencial per alimentar les estadístiques d'interacció. No requereix autenticació.

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

Paràmetres

Aquest endpoint llegeix el cos directament (sense l'embolcall parameters).

Paràmetre	Tipus	Obligatori	Descripció
`event`	string	Sí	Un de `view`, `share`, `download`, `click_linkedin_addtoprofile`, `click_pdf`, `click_verify`.
`network`	string	No	Quan `event=share`, la xarxa social: `linkedin`, `twitter`, `facebook`, `whatsapp`, `telegram`, `email`, `copy`.

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

Exemple

bash

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

Resposta

json

{
  "ok": true
}

Obtenir les estadístiques de la credencial

Obtén els comptadors acumulats d'interacció d'una credencial.

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

No requereix autenticació.

Resposta

Els comptadors es retornen indexats pel tipus d'esdeveniment en brut. totals conté el recompte total per esdeveniment; networks desglossa el repartiment per xarxa dels esdeveniments que porten un network (actualment share). Els esdeveniments sense activitat registrada simplement no hi són.

json

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

API de credencials ​

Crear credencial ​

Paràmetres ​

Exemple ​

Resposta ​

Notes ​

Llistar credencials ​

Paràmetres de consulta ​

Objecte de filtre ​

Exemple — Llistar totes les credencials ​

Exemple — Filtrar per insígnia ​

Resposta ​

Enviar el correu de la credencial ​

Paràmetres ​

Exemple ​

Resposta ​

Compartir credencial ​

Paràmetres ​

Exemple ​

Resposta ​

Revocar credencial ​

Paràmetres ​

Exemple ​

Resposta ​

Revocar en massa ​

Eliminar credencial ​

Paràmetres ​

Exemple ​

Resposta ​

Baixar el certificat en PDF ​

Exemple ​

Registrar un esdeveniment de la credencial ​

Paràmetres ​

Exemple ​

Resposta ​

Obtenir les estadístiques de la credencial ​

Resposta ​

API de credencials

Crear credencial

Paràmetres

Exemple

Resposta

Notes

Llistar credencials

Paràmetres de consulta

Objecte de filtre

Exemple — Llistar totes les credencials

Exemple — Filtrar per insígnia

Resposta

Enviar el correu de la credencial

Paràmetres

Exemple

Resposta

Compartir credencial

Paràmetres

Exemple

Resposta

Revocar credencial

Paràmetres

Exemple

Resposta

Revocar en massa

Eliminar credencial

Paràmetres

Exemple

Resposta

Baixar el certificat en PDF

Exemple

Registrar un esdeveniment de la credencial

Paràmetres

Exemple

Resposta

Obtenir les estadístiques de la credencial

Resposta