API Credențiale

Creează și gestionează credențiale (aserțiuni) — insigne emise unor destinatari anume.

Toate endpointurile necesită autentificare prin antetul X-Api-Key. Vezi Autentificare.

Creare credențial

Emite o insignă unui destinatar.

Trebuie să emiți către sute sau mii de destinatari deodată, în loc de un apel API pentru fiecare persoană? Folosește funcția din interfață Credențiale în masă, care acceptă încărcarea unui fișier CSV.

POST /awards

Parametri

Parametru	Tip	Obligatoriu	Descriere
badgeId	string	Da	ID-ul insignei de emis
recipient	object	Da	Detaliile destinatarului (vezi mai jos)
recipient.name	string	Da	Numele complet al destinatarului (minimum 5 caractere)
recipient.email	string	Da	Adresa de e-mail a destinatarului
issuedOn	string	Da	Data emiterii în format ISO 8601 (de ex. 2025-01-15)
expires	string	Nu	Data expirării în format ISO 8601

Exemplu

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

Răspuns

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

Note

• Se consumă un credențial din fondul tău anual de credențiale (Free: 1.200/an, Starter: 12.000/an, Pro: 120.000/an). Fondul este o alocare anuală flexibilă — îl poți cheltui oricând pe parcursul anului, inclusiv în rafale — și se reînnoiește la aniversarea înregistrării contului tău. Facturarea rămâne lunară; doar cota de credențiale este anuală. Vezi Planuri și facturare pentru detalii.

---

Listare credențiale

Obține credențiale, cu filtrare și paginare opționale.

GET /awards

Parametri de interogare

Parametru	Tip	Obligatoriu	Descriere
filter	șir JSON	Nu	Obiect de filtrare (vezi mai jos)
lastEvaluatedKey	string	Nu	Token de paginare dintr-un răspuns anterior

Obiectul de filtrare

Parametrul filter acceptă un șir JSON cu aceste câmpuri:

Câmp	Tip	Descriere
badgeId	string	Filtrează după ID-ul insignei.
search	string	Subșir de căutat în numele sau în adresele de e-mail ale destinatarilor (vezi searchField).
searchField	string	Fie name (implicit), fie email — coloana în care se caută.

Paginarea prin lastEvaluatedKey funcționează cu sau fără filtre. Dimensiunea paginii este 50.

Exemplu — listarea tuturor credențialelor

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

Exemplu — filtrare după insignă

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"

Răspuns

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

Dacă lastEvaluatedKey este prezent în răspuns, există mai multe rezultate. Transmite-l ca parametru de interogare în cererea următoare pentru a obține pagina următoare.

---

Trimitere e-mail pentru credențial

Trimite unui destinatar o notificare prin e-mail despre credențialul său.

POST /awards/{awardId}/send

Parametri

Parametru	Tip	Obligatoriu	Descriere
awardId	string	Da	ID-ul credențialului (parametru de cale și în corp)
email	string	Da	Adresa de e-mail a destinatarului

Exemplu

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

Răspuns

Returnează un simplu șir de confirmare:

"email sent"

---

Partajare credențial

Partajează un credențial prin e-mail cu mai mulți destinatari.

POST /awards/{awardId}/share

Parametri

Parametru	Tip	Obligatoriu	Descriere
awardId	string	Da	ID-ul credențialului (parametru de cale și în corp)
recipients	string	Da	Listă de adrese de e-mail separate prin virgulă
subject	string	Da	Subiectul e-mailului
message	string	Da	Corpul mesajului e-mail

Exemplu

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

Răspuns

Returnează un simplu șir de confirmare:

"email sent"

---

Revocare credențial

Revocă un credențial emis de tine. Aserțiunea Open Badges v2.0 găzduită este marcată cu revoked: true (cu un motiv opțional), astfel încât orice verificator vede că insigna nu mai este valabilă. Înregistrarea credențialului este păstrată în scop de audit, iar niciun credit nu este rambursat.

Revocarea se propagă și la Verifiable Credential Open Badges 3.0 al credențialului: bitul credențialului este comutat în Bitstring Status List W3C la care face referire credentialStatus din VC, astfel încât și portofelele VC o detectează. Vezi Revocare (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametri

Parametru	Tip	Obligatoriu	Descriere
awardId	string	Da	ID-ul credențialului (parametru de cale)
reason	string	Nu	Motivul revocării. Trunchiat la 500 de caractere.
notify	boolean	Nu	Când este true, trimite destinatarului un e-mail că credențialul său a fost revocat. Implicit false.

Exemplu

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

Răspuns

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

Revocarea unui credențial deja revocat este idempotentă — returnează același răspuns fără a retrimite o notificare.

Revocare în masă

Pentru a revoca multe credențiale deodată, folosește endpointul durabil de masă cu action: "revoke", în loc să apelezi acest endpoint pentru fiecare credențial:

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

Returnează { "jobId", "total" }; jobul revocă pe server fiecare ID (sărind peste cele deja revocate) și poate fi reluat. ID-urile deja revocate și cele inexistente sunt raportate ca omise.

---

Ștergere credențial

Șterge definitiv un credențial emis de tine. Spre deosebire de revocare, aceasta elimină complet înregistrarea, iar pagina publică a credențialului va returna 404. Folosește această opțiune pentru greșeli reale (de ex. emis persoanei greșite); pentru credențiale reale preferă revocarea, astfel încât aserțiunea să rămână verificabilă ca revocată. Niciun credit nu este rambursat.

DELETE /awards/{awardId}

Parametri

Parametru	Tip	Obligatoriu	Descriere
awardId	string	Da	ID-ul credențialului (parametru de cale)

Exemplu

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

Răspuns

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

---

Descărcare certificat PDF

Generează un certificat PDF A4 gata de tipărit pentru un credențial.

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

Nu necesită autentificare — acest endpoint este public, astfel încât destinatarii să își poată descărca propriul certificat.

Exemplu

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

Răspunsul este PDF-ul binar, cu antetul Content-Type: application/pdf.

---

Urmărire eveniment credențial

Înregistrează un eveniment de interacțiune. Este folosit de pagina publică a credențialului pentru a alimenta statisticile de interacțiune. Nu necesită autentificare.

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

Parametri

Acest endpoint își citește direct corpul (fără învelișul parameters).

Parametru	Tip	Obligatoriu	Descriere
event	string	Da	Unul dintre view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nu	Când event=share, rețeaua socială: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Suprimarea duplicatelor per IP: același eveniment de la aceeași adresă IP este contorizat o singură dată la 24 de ore.

Exemplu

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

Răspuns

{
  "ok": true
}

---

Obținere statistici credențial

Obține contoarele cumulative de interacțiune pentru un credențial.

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

Nu necesită autentificare.

Răspuns

Contoarele sunt returnate după tipul brut al evenimentului. totals conține numărul total pentru fiecare eveniment; networks detaliază împărțirea pe rețele pentru evenimentele care au un network (în prezent share). Evenimentele fără activitate înregistrată sunt pur și simplu absente.

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