Patvirtinimų API

Kurkite ir valdykite patvirtinimus (assertions) — konkretiems gavėjams išduotus ženklelius.

Visiems galiniams taškams reikalingas autentifikavimas per antraštę X-Api-Key. Žr. Autentifikavimas.

Sukurti patvirtinimą

Išduokite ženklelį gavėjui.

Reikia vienu metu išduoti šimtams ar tūkstančiams gavėjų, o ne kviesti API po kartą kiekvienam? Naudokite Masiniai patvirtinimai naudotojo sąsajos funkciją, kuri priima CSV failą.

POST /awards

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
badgeId	string	Taip	Išduotino ženklelio ID
recipient	object	Taip	Gavėjo duomenys (žr. toliau)
recipient.name	string	Taip	Pilnas gavėjo vardas (mažiausiai 5 simboliai)
recipient.email	string	Taip	Gavėjo el. pašto adresas
issuedOn	string	Taip	Išdavimo data ISO 8601 formatu (pvz., 2025-01-15)
expires	string	Ne	Galiojimo pabaigos data ISO 8601 formatu

Pavyzdys

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

Atsakas

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

Pastabos

• Skaičiuojamas kaip vienas patvirtinimas jūsų metiniame patvirtinimų limite (Free: 1 200 per metus, Starter: 12 000 per metus, Pro: 120 000 per metus). Limitas yra lankstus metinis kiekis — išnaudokite jį bet kada per metus, taip pat ir dideliais kiekiais — ir atsinaujina jūsų paskyros registracijos metinių dieną. Atsiskaitymas lieka mėnesinis; tik patvirtinimų kvota yra metinė. Daugiau informacijos žr. Planai ir atsiskaitymas.

---

Patvirtinimų sąrašas

Gaukite patvirtinimus su pasirenkamu filtravimu ir puslapiavimu.

GET /awards

Užklausos parametrai

Parametras	Tipas	Privalomas	Aprašymas
filter	JSON string	Ne	Filtro objektas (žr. toliau)
lastEvaluatedKey	string	Ne	Puslapiavimo žetonas iš ankstesnio atsakymo

Filtro objektas

Parametras filter priima JSON eilutę su šiais laukais:

Laukas	Tipas	Aprašymas
badgeId	string	Filtruoti pagal ženklelio ID.
search	string	Požymis, ieškomas gavėjų vardų arba el. pašto adresų dalyje (žr. searchField).
searchField	string	Arba name (numatytasis), arba email — kuriame stulpelyje ieškoti.

Puslapiavimas per lastEvaluatedKey veikia su filtrais ir be jų. Puslapio dydis — 50.

Pavyzdys — visų patvirtinimų sąrašas

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

Pavyzdys — filtravimas pagal ženklelį

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"

Atsakas

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

Jei atsakyme yra lastEvaluatedKey, rezultatų yra daugiau. Perduokite jį kaip užklausos parametrą kitoje užklausoje, kad gautumėte kitą puslapį.

---

Siųsti patvirtinimo el. laišką

Išsiųskite gavėjui el. pašto pranešimą apie jo patvirtinimą.

POST /awards/{awardId}/send

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Apdovanojimo ID (kelio parametras ir turinys)
email	string	Taip	Gavėjo el. pašto adresas

Pavyzdys

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

Atsakas

Grąžinama paprasta patvirtinimo eilutė:

"email sent"

---

Dalytis patvirtinimu

Pasidalykite patvirtinimu su keliais gavėjais el. paštu.

POST /awards/{awardId}/share

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Apdovanojimo ID (kelio parametras ir turinys)
recipients	string	Taip	El. pašto adresų sąrašas, atskirtas kableliais
subject	string	Taip	El. laiško tema
message	string	Taip	El. laiško tekstas

Pavyzdys

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

Atsakas

Grąžinama paprasta patvirtinimo eilutė:

"email sent"

---

Atšaukti patvirtinimą

Atšaukite jūsų išduotą patvirtinimą. Talpinamas Open Badges v2.0 assertion pažymimas revoked: true (su pasirenkama priežastimi), kad bet kuris tikrintuvas matytų, jog ženklelis nebegalioja. Patvirtinimo įrašas saugomas audito tikslais, o kreditas negrąžinamas.

Atšaukimas taip pat perduodamas patvirtinimo Open Badges 3.0 Verifiable Credential: apdovanojimo bitas perjungiamas W3C Bitstring Status List, į kurį nurodo VC credentialStatus, todėl atšaukimą aptinka ir VC piniginės. Žr. Atšaukimas (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Apdovanojimo ID (kelio parametras)
reason	string	Ne	Atšaukimo priežastis. Sutrumpinama iki 500 simbolių.
notify	boolean	Ne	Kai true, el. paštu praneša gavėjui, kad jo patvirtinimas buvo atšauktas. Numatytoji reikšmė false.

Pavyzdys

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

Atsakas

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

Jau atšaukto patvirtinimo atšaukimas yra idempotentiškas — grąžinamas tas pats atsakas ir pranešimas nesiunčiamas iš naujo.

Atšaukimas masiškai

Norėdami atšaukti daug patvirtinimų vienu metu, vietoj šio galinio taško kvietimo kiekvienam apdovanojimui naudokite patvarų masinį galinį tašką su 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 } }'

Grąžina { "jobId", "total" }; užduotis serveryje atšaukia visus ID (praleisdama jau atšauktus) ir gali būti tęsiama. Jau atšaukti ir neegzistuojantys ID pateikiami kaip praleisti.

---

Ištrinti patvirtinimą

Visam laikui ištrinkite jūsų išduotą patvirtinimą. Skirtingai nei atšaukimas, tai visiškai pašalina įrašą, o viešas patvirtinimo puslapis grąžins 404. Naudokite tai tik tikroms klaidoms (pvz., išduota ne tam asmeniui); tikriems patvirtinimams rinkitės atšaukimą, kad assertion liktų patikrinamas kaip atšauktas. Kreditas negrąžinamas.

DELETE /awards/{awardId}

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Apdovanojimo ID (kelio parametras)

Pavyzdys

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

Atsakas

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

---

Atsisiųsti PDF sertifikatą

Sugeneruokite spausdinimui paruoštą A4 PDF patvirtinimo sertifikatą.

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

Autentifikavimo nereikia — šis galinis taškas viešas, todėl gavėjai gali patys atsisiųsti savo sertifikatą.

Pavyzdys

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

Atsakas yra dvejetainis PDF su antrašte Content-Type: application/pdf.

---

Sekti patvirtinimo įvykį

Užregistruokite įsitraukimo įvykį. Naudojamas viešame patvirtinimo puslapyje įsitraukimo statistikai kaupti. Autentifikavimo nereikia.

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

Parametrai

Šis galinis taškas skaito turinį tiesiogiai (be parameters apvalkalo).

Parametras	Tipas	Privalomas	Aprašymas
event	string	Taip	Viena iš view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ne	Kai event=share, socialinis tinklas: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Dublikatų slopinimas pagal IP: tas pats įvykis iš to paties IP skaičiuojamas vieną kartą per 24 valandas.

Pavyzdys

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

Atsakas

{
  "ok": true
}

---

Gauti patvirtinimo statistiką

Gaukite kaupiamuosius patvirtinimo įsitraukimo skaitiklius.

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

Autentifikavimo nereikia.

Atsakas

Skaitikliai grąžinami pagal neapdorotą įvykio tipą. totals talpina bendrą kiekvieno įvykio skaičių; networks išskaido pasiskirstymą pagal tinklus įvykiams, turintiems network (šiuo metu share). Įvykiai be užfiksuotos veiklos tiesiog nerodomi.

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