Akreditācijas datu API

Izveidojiet un pārvaldiet akreditācijas datus (assertions) — nozīmes, kas izdotas konkrētiem saņēmējiem.

Visiem galapunktiem nepieciešama autentifikācija, izmantojot galveni X-Api-Key. Skatiet Autentifikācija.

Izveidot akreditācijas datus

Izdodiet nozīmi saņēmējam.

Vai jāizdod simtiem vai tūkstošiem saņēmēju vienlaikus, nevis viens API izsaukums katrai personai? Izmantojiet lietotāja saskarnes funkciju Masveida akreditācijas dati, kas pieņem CSV augšupielādi.

POST /awards

Parametri

Parametrs	Tips	Obligāts	Apraksts
badgeId	string	Jā	Izdodamās nozīmes ID
recipient	object	Jā	Saņēmēja dati (skatiet tālāk)
recipient.name	string	Jā	Saņēmēja pilnais vārds (vismaz 5 rakstzīmes)
recipient.email	string	Jā	Saņēmēja e-pasta adrese
issuedOn	string	Jā	Izdošanas datums ISO 8601 formātā (piem., 2025-01-15)
expires	string	Nē	Derīguma termiņš ISO 8601 formātā

Piemērs

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

Atbilde

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

Piezīmes

• Tiek ieskaitīts kā viens akreditācijas datu ieraksts jūsu gada akreditācijas datu limitā (Free: 1 200 gadā, Starter: 12 000 gadā, Pro: 120 000 gadā). Limits ir elastīgs gada apjoms — izmantojiet to jebkurā laikā gada garumā, tostarp lielos apjomos — un tiek atiestatīts jūsu konta reģistrācijas gadadienā. Norēķini paliek mēneša, tikai akreditācijas datu kvota ir gada. Sīkāku informāciju skatiet sadaļā Plāni un norēķini.

---

Akreditācijas datu saraksts

Iegūstiet akreditācijas datus ar neobligātu filtrēšanu un lappušu dalījumu.

GET /awards

Vaicājuma parametri

Parametrs	Tips	Obligāts	Apraksts
filter	JSON string	Nē	Filtra objekts (skatiet tālāk)
lastEvaluatedKey	string	Nē	Lappušu dalījuma marķieris no iepriekšējās atbildes

Filtra objekts

Parametrs filter pieņem JSON virkni ar šādiem laukiem:

Lauks	Tips	Apraksts
badgeId	string	Filtrēt pēc nozīmes ID.
search	string	Apakšvirkne, ko meklēt saņēmēju vārdos vai e-pasta adresēs (skatiet searchField).
searchField	string	Vai nu name (noklusējums), vai email — kurā kolonnā meklēt.

Lappušu dalījums ar lastEvaluatedKey darbojas gan ar filtriem, gan bez tiem. Lappuses izmērs ir 50.

Piemērs — visu akreditācijas datu saraksts

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

Piemērs — filtrēšana pēc nozīmes

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"

Atbilde

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

Ja atbildē ir lastEvaluatedKey, ir vēl rezultāti. Nododiet to kā vaicājuma parametru nākamajā pieprasījumā, lai iegūtu nākamo lappusi.

---

Nosūtīt akreditācijas datu e-pastu

Nosūtiet saņēmējam e-pasta paziņojumu par viņa akreditācijas datiem.

POST /awards/{awardId}/send

Parametri

Parametrs	Tips	Obligāts	Apraksts
awardId	string	Jā	Apbalvojuma ID (ceļa parametrs un pieprasījuma pamatteksts)
email	string	Jā	Saņēmēja e-pasta adrese

Piemērs

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

Atbilde

Atgriež vienkāršu apstiprinājuma virkni:

"email sent"

---

Kopīgot akreditācijas datus

Kopīgojiet akreditācijas datus ar vairākiem saņēmējiem pa e-pastu.

POST /awards/{awardId}/share

Parametri

Parametrs	Tips	Obligāts	Apraksts
awardId	string	Jā	Apbalvojuma ID (ceļa parametrs un pieprasījuma pamatteksts)
recipients	string	Jā	Ar komatiem atdalīts e-pasta adrešu saraksts
subject	string	Jā	E-pasta tēma
message	string	Jā	E-pasta ziņojuma teksts

Piemērs

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

Atbilde

Atgriež vienkāršu apstiprinājuma virkni:

"email sent"

---

Atsaukt akreditācijas datus

Atsauciet jūsu izdotos akreditācijas datus. Mitinātais Open Badges v2.0 assertion tiek atzīmēts ar revoked: true (ar neobligātu iemeslu), lai ikviens verifikators redzētu, ka nozīme vairs nav derīga. Akreditācijas datu ieraksts tiek saglabāts audita nolūkos, un kredīts netiek atmaksāts.

Atsaukšana tiek pārnesta arī uz akreditācijas datu Open Badges 3.0 Verifiable Credential: apbalvojuma bits tiek apgriezts W3C Bitstring Status List, uz ko norāda VC credentialStatus, tāpēc atsaukumu konstatē arī VC maki. Skatiet Atsaukšana (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametri

Parametrs	Tips	Obligāts	Apraksts
awardId	string	Jā	Apbalvojuma ID (ceļa parametrs)
reason	string	Nē	Atsaukšanas iemesls. Tiek saīsināts līdz 500 rakstzīmēm.
notify	boolean	Nē	Ja true, nosūta saņēmējam e-pastu, ka viņa akreditācijas dati ir atsaukti. Noklusējums ir false.

Piemērs

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

Atbilde

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

Jau atsauktu akreditācijas datu atsaukšana ir idempotenta — tiek atgriezta tā pati atbilde, paziņojums netiek sūtīts atkārtoti.

Masveida atsaukšana

Lai atsauktu daudzus akreditācijas datu ierakstus vienlaikus, tā vietā, lai izsauktu šo galapunktu katram apbalvojumam, izmantojiet izturīgo masveida galapunktu ar action: "revoke":

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

Tas atgriež { "jobId", "total" }; uzdevums servera pusē atsauc visus ID (izlaižot jau atsauktos) un ir atsākams. Jau atsauktie un neesošie ID tiek ziņoti kā izlaisti.

---

Dzēst akreditācijas datus

Neatgriezeniski izdzēsiet jūsu izdotos akreditācijas datus. Atšķirībā no atsaukšanas, tas pilnībā noņem ierakstu, un publiskā akreditācijas datu lapa atgriezīs 404. Izmantojiet to patiesām kļūdām (piem., izdots nepareizai personai); īstiem akreditācijas datiem dodiet priekšroku atsaukšanai, lai assertion paliktu verificējams kā atsaukts. Kredīts netiek atmaksāts.

DELETE /awards/{awardId}

Parametri

Parametrs	Tips	Obligāts	Apraksts
awardId	string	Jā	Apbalvojuma ID (ceļa parametrs)

Piemērs

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

Atbilde

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

---

Lejupielādēt PDF sertifikātu

Ģenerējiet drukai gatavu A4 PDF sertifikātu akreditācijas datiem.

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

Autentifikācija nav nepieciešama — šis galapunkts ir publisks, lai saņēmēji varētu paši lejupielādēt savu sertifikātu.

Piemērs

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

Atbilde ir binārs PDF ar galveni Content-Type: application/pdf.

---

Izsekot akreditācijas datu notikumu

Reģistrējiet iesaistes notikumu. Publiskā akreditācijas datu lapa to izmanto, lai papildinātu iesaistes statistiku. Autentifikācija nav nepieciešama.

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

Parametri

Šis galapunkts nolasa pamattekstu tieši (bez parameters ietinuma).

Parametrs	Tips	Obligāts	Apraksts
event	string	Jā	Viena no vērtībām view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nē	Kad event=share, sociālais tīkls: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Dublikātu nomākšana pēc IP: viens un tas pats notikums no vienas IP tiek skaitīts vienreiz 24 stundu laikā.

Piemērs

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

Atbilde

{
  "ok": true
}

---

Iegūt akreditācijas datu statistiku

Iegūstiet akreditācijas datu kumulatīvos iesaistes skaitītājus.

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

Autentifikācija nav nepieciešama.

Atbilde

Skaitītāji tiek atgriezti pēc neapstrādāta notikuma tipa. totals satur kopējo skaitu katram notikumam; networks sadala sadalījumu pa tīkliem notikumiem, kuriem ir network (pašlaik share). Notikumi bez reģistrētas darbības vienkārši nav iekļauti.

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