Open Badges izdošana, izmantojot Badges Ninja REST API: ātrā sākšana

Lielākajai daļai kvalifikāciju programmu API nekad nav vajadzīgs. Ja vadāt kursu ar dažiem simtiem absolventu gadā, informācijas panelis izdara visu: nozīmi izveidojat vizuālajā dizainerī, augšupielādējat CSV failu, un katrs saņēmējs iegūst verifikācijas lapu un PDF sertifikātu. Ja tā ir jūsu situācija, sāciet ar kā izdot Open Badges no CSV faila un atgriezieties vēlāk.

API atmaksājas, kad kvalifikācijas jāizdod citai sistēmai: jūsu mācību platforma atzīmē kursu kā pabeigtu, jūsu reģistrācijas rīks noslēdz pasākumu, jūsu personāla sistēma fiksē pabeigtu atbilstības moduli. Šādos gadījumos neviens nevēlas katras nedēļas beigās eksportēt izklājlapu. Viens HTTP izsaukums pabeigšanas brīdī ir vienkāršāks, un saņēmējs nozīmi iegūst, kamēr sasniegums vēl ir svaigs.

Šī ātrā sākšana jūs izvadīs cauri visam ceļam četros izsaukumos: iegūstiet atslēgu, izveidojiet izdevēju, izveidojiet nozīmi, piešķiriet to. Pēc tam aplūkosim, kā nodot saņēmējam verifikācijas saiti un pārbaudīt rezultātu. Katra tālāk redzamā pieprasījuma forma nāk no izvietotajiem apstrādātājiem, tāpēc varat to ielīmēt un palaist.

Kas jums vajadzīgs, pirms sākat

• Bezmaksas konts vietnē badges.ninja. Šai apmācībai pietiek ar Free plānu: tajā ir 2 izdevēji, 5 nozīmes, 2 vietas un 1 API atslēga.
• Viena API atslēga, izveidota informācijas panelī.
• PNG vai JPG attēls nozīmei vai nozīme, ko izveidojāt vizuālajā dizainerī.

Visa pamata URL ir https://api.badges.ninja.

1. solis: izveidojiet API atslēgu

Pierakstieties, sānjoslā atveriet API Keys un noklikšķiniet uz Create API Key. Dodiet tai nosaukumu, kas norāda, kur tā dzīvos, piemēram, „LMS integration”, lai vēlāk, rotējot atslēgas, tās varētu atšķirt.

Atslēga tiek parādīta tieši vienu reizi. Nekavējoties nokopējiet to savā noslēpumu pārvaldniekā vai vides mainīgajā. Atslēgas izskatās kā bws_, kam seko 32 heksadecimāli simboli, un tās tiek sūtītas galvenē X-Api-Key katrā pieprasījumā. Atslēgas atsaukšana tajā pašā ekrānā stājas spēkā nekavējoties.

Daži ieradumi, kas vēlāk ietaupa nepatikšanas:

• Nekad nelieciet atslēgu priekšgala kodā vai publiskā repozitorijā. Izsauciet API no servera, bezserveru funkcijas vai automatizācijas rīka.
• Katrai integrācijai izmantojiet vienu atslēgu. Ja viena noplūst, jūs atsaucat vienu integrāciju, nevis visas.
• Informācijas panelis pieņem arī jūsu pierakstīto sesiju (Cognito JWT, nosūtīts kā Authorization: Bearer), taču skriptiem un integrācijām pareizais rīks ir API atslēga.

Visi tālāk redzamie piemēri nolasa atslēgu no vides mainīgā BADGES_API_KEY.

2. solis: izveidojiet izdevēju

Izdevējs ir organizācija, kas stāv aiz nozīmes. Tas parādās katrā verifikācijas lapā un Open Badge v2.0 datos, tāpēc izmantojiet nosaukumu, ko cilvēki patiešām pazīst.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

Obligātie lauki ir name (vismaz 3 rakstzīmes), url (derīga http vai https adrese) un email. Neobligātie lauki ir logo (base64 kodēts attēls) un linkedinOrganizationId, kas jūsu publiskajās kvalifikāciju lapās ieslēdz pogu Add to LinkedIn Profile.

Atbilde satur izdevēja identifikatoru:

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Saglabājiet šo vērtību tieši tādu, kāda tā atgriezta. Tā ir nākamā soļa ievade.

Izdevēja verifikācija

Nozīmes var izveidot tikai verificēta izdevēja vārdā. Verifikācija darbojas šādi:

• Ja izdevēja e-pasts sakrīt ar jūsu konta e-pastu, izdevējs tiek verificēts automātiski. Tas ir ātrākais ceļš pirmajam testam.
• Ja e-pasts ir atšķirīgs, uz šo adresi tiek nosūtīta verifikācijas e-pasta vēstule ar kodu. Kodu apstiprināt informācijas panelī (vai ar izdevēju API), pirms veidojat nozīmes.

Tāpēc šai apmācībai izmantojiet to pašu e-pastu, ar kuru reģistrējāties.

3. solis: izveidojiet nozīmi

Nozīme ir atkārtoti izmantojama veidne: nosaukums, apraksts, kritēriji un attēls. Katra vēlāk izdotā piešķiršana norāda atpakaļ uz to.

Pieprasījums ir vienkāršs JSON. Attēls tiek ievietots kā base64 virkne, tāpēc nav jācīnās ar multipart augšupielādi. Datu URL prefikss, piemēram, data:image/png;base64,, tiek pieņemts un noņemts.

JavaScript (Node 18 vai jaunāks):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Visi pieci lauki (name, description, criteria, image, issuerId) ir obligāti. Divus neobligātos ir vērts zināt: shareText – noklusējuma teksts, ko saņēmēji redz, dalīdamies sociālajos tīklos (atbalsta vietturus {{badge_name}}, {{issuer_name}} un {{award_url}}), un designJson, kas saglabā vizuālā dizainera dokumentu, lai nozīmi vēlāk varētu rediģēt slāni pa slānim.

Veiksmes gadījumā tiek atgriezts HTTP 200 ar { "badgeId": "<id>" }. Attēls tiek saglabāts pastāvīgi, un nozīme tagad ir Open Badge v2.0 BadgeClass, ko var iegūt ikviens.

Vai nozīmes vispār jāveido kodā?

Parasti nē. Nozīmes dizains ir radošs uzdevums, un vizuālais dizainers (vairāk nekā 80 veidņu, formas, ikonas, 11 fonti un pašu augšupielādes) tam ir daudz labāka vieta nekā skripts. Izplatīts modelis ir katru nozīmi izveidot informācijas panelī vienu reizi, bet jūsu integrācija pēc tam izdod tikai piešķīrumus tai. Savas nozīmes varat izlistēt ar GET /badges un nokopēt vēlamās id.

Veidojiet nozīmes ar API, ja ģenerējat tās programmatiski, piemēram, vienu katram kursam katalogā ar simtiem kursu, vai ja aizpildāt testa vidi.

4. solis: piešķiriet nozīmi

Šo izsaukumu jūsu integrācija veiks tūkstošiem reižu. Nosūtiet nozīmi, saņēmēju un datumu.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

Noteikumi, kas cilvēkiem sagādā grūtības:

• recipient ir ligzdots objekts ar laukiem name un email. Plakani lauki, piemēram, recipientEmail, tiek noraidīti.
• recipient.name jābūt vismaz 5 rakstzīmju garam.
• issuedOn ir obligāts. Sūtiet epohas milisekundes vai ISO datumu, piemēram, 2026-09-28.
• expires ir neobligāts un pieņem tos pašus formātus.

Veiksme ir HTTP 200 ar pamatni, kurā ir awardId. Saņēmēja e-pasts Open Badge datos tiek glabāts kā SHA-256 jaucējkods, tāpēc publiskais JSON to nekad neatklāj.

5. solis: atrodiet verifikācijas lapu un Open Badge JSON

Piešķiršanas atbilde sniedz identifikatoru, nevis gatavu saiti. Identifikators beidzas ar GUID, un publiskās lapas tiek veidotas no šī GUID:

• Cilvēkam lasāma verifikācijas lapa: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Ja jūsu awardId atnāk kā pilns URL, kā GUID izmantojiet pēdējo ceļa segmentu.

Abas ir publiskas. Ikviens ar saiti var verificēt kvalifikāciju, neveidojot kontu, un tas ir jēga: darba devējam vai uzņemšanas speciālistam jāspēj pārbaudīt nozīmi desmit sekundēs.

Ielādējiet JSON, lai redzētu, ko redz pasaule:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Jūs saņemat Open Badge v2.0 apliecinājumu: nozīmi, uz kuru tas atsaucas, jauktu saņēmēja identitāti, izdošanas datumu un verifikācijas bloku, kas norāda atpakaļ uz mitināto apliecinājumu. Tā kā tie ir standarta Open Badges dati, tos var nolasīt jebkurš rīks, kas formātu saprot. Šī pārnesamība ir iemesls, kāpēc izvēlēties Open Badges, nevis patentētu PDF; Open Badges pret PDF sertifikātiem šo kompromisu aplūko dziļāk.

Kā saņēmēji saņem kvalifikāciju

Piešķiršanas izveide ir atsevišķa no saņēmēja informēšanas. Saņēmēji var atvērt savas kvalifikācijas saņēmēju portālā badges.ninja/me, kas izmanto pieteikšanos ar maģisko saiti bez paroles, un var publicēt publisku profilu adresē badges.ninja/u/<handle>. No verifikācijas lapas viņi var pievienot nozīmi LinkedIn, lejupielādēt PDF sertifikātu vai kopīgot saiti.

Pirmajiem testiem nosūtiet piešķīrumu sev uz savu e-pasta adresi un izejiet cauri saņēmēja pieredzei. Tas ir visātrākais veids, kā pamanīt tādas lietas kā neveikli skanošu nozīmes aprakstu.

Kļūdu apstrāde, kas nesāp

API izmanto parastos HTTP statusa kodus. Tie, ar kuriem sastapsieties:

Divi praktiski padomi. Pirmkārt, 400 uztveriet kā datu problēmu un reģistrējiet atbildes pamattekstu, jo tas nosauc neveiksmīgo lauku. Otrkārt, padariet savu integrāciju idempotentu savā pusē: saglabājiet awardId blakus pabeigšanas ierakstam savā datubāzē un pārbaudiet to, pirms vēlreiz izsaucat API. Tā atkārtots webhook vai atkārtoti palaists darbs nekad neizdod vienai personai divas kvalifikācijas.

Viss kopā reālā integrācijā

Tipisks savienojums izskatās šādi:

1. Izveidojiet nozīmes informācijas panelī, vienu katram kursam vai atskaites punktam, un pierakstiet katras nozīmes ID.
2. Savā sistēmā saglabājiet atbilstību no kursa uz nozīmes ID.
3. Kad izglītojamais pabeidz kursu, jūsu serveris izsauc POST /awards ar viņa vārdu, e-pastu un pabeigšanas datumu.
4. Saglabājiet atgriezto awardId pie pabeigšanas ieraksta.
5. Parādiet verifikācijas saiti savā produktā, lai izglītojamais to redz, to neatstājot.

Ja labāk nerakstāt kodu, tas pats izsaukums darbojas no jebkura automatizācijas rīka, kas spēj nosūtīt HTTP pieprasījumu ar JSON pamattekstu un pielāgotu galveni. Norādiet to uz https://api.badges.ninja/awards un savus veidlapas vai izklājlapas laukus sasaistiet ar badgeId, recipient.name, recipient.email un issuedOn.

Plāni un ierobežojumi, kurus vērts zināt

API ir pieejams katrā plānā; par tā atbloķēšanu nemaksājat papildus. Free plāns ($0) aptver 2 izdevējus, 5 nozīmes, 2 vietas, 1 API atslēgu un 1,200 kvalifikācijas gadā. Starter maksā $9 mēnesī un Pro $29 mēnesī, ar augstākiem ierobežojumiem. Pirms plānojat ieviešanas apjomu, cenu lapā pārbaudiet aktuālos skaitļus. Ja salīdzināt, ko citas platformas prasa par piekļuvi API, Credly alternatīva izmaksas parāda blakus.

Kur iet tālāk

• Pilnu galapunktu atsauci atradīsiet API dokumentācijā, kas ir pieejama 40 valodās.
• Par autentifikācijas un atslēgu apstrādes detaļām skatiet autentifikācijas ceļvedi.
• Par kļūdu kodiem sīkāk skatiet kļūdu atsauci.
• Kad ar vienu izsaukumu reizē vairs nepietiek, informācijas panelī izmantojiet masveida piešķiršanu: augšupielādējiet CSV un vajadzības gadījumā apturiet vai atsāciet izpildi.

Pirmā veiksmīgā piešķiršana ir grūtākā. Pēc tam atliek tikai pieslēgt to pašu izsaukumu vietām, kur sasniegumi jau tiek reģistrēti.

Gatavi izdot savu pirmo pārbaudāmo kvalifikāciju? Sāciet bez maksas platformā badges.ninja – vizuālais dizainers, publiska verifikācijas lapa, PDF sertifikāts, Open Badge v2.0 izvade. Kredītkarte nav nepieciešama.