Pag-issue ng Open Badges gamit ang Badges Ninja REST API: Quickstart

Karamihan sa mga credential program ay hindi nangangailangan ng API. Kung nagpapatakbo ka ng course na may ilang daang graduate kada taon, kaya na ng dashboard ang lahat: magdidisenyo ka ng badge sa visual designer, mag-a-upload ng CSV, at makakakuha ang bawat recipient ng verification page at PDF certificate. Kung ito ang sitwasyon mo, magsimula sa kung paano mag-issue ng Open Badges mula sa CSV at bumalik ka na lang mamaya.

Nagiging sulit ang API kapag ang mga credential ay dapat i-issue ng ibang system: minarkahan ng learning platform mo na tapos na ang isang course, isinara ng registration tool mo ang isang event, itinala ng HR system mo ang natapos na compliance module. Sa mga ganitong kaso, walang gustong mag-export ng spreadsheet tuwing katapusan ng linggo. Mas simple ang isang HTTP call sa mismong sandali ng pagkumpleto, at nakukuha ng recipient ang badge niya habang sariwa pa ang achievement.

Tinatahak ng quickstart na ito ang buong daan sa apat na call: kumuha ng key, gumawa ng issuer, gumawa ng badge, i-award ito. Pagkatapos, titingnan natin kung paano ibibigay ang verification link sa recipient at i-check ang resulta. Ang bawat request shape sa ibaba ay galing sa mga naka-deploy na handler, kaya puwede mo itong i-paste at patakbuhin.

Ano ang kailangan mo bago magsimula

• Isang libreng account sa badges.ninja. Sapat na ang Free plan para sa tutorial na ito: kasama rito ang 2 issuers, 5 badges, 2 seats at 1 API key.
• Isang API key, na ginawa mula sa dashboard.
• Isang PNG o JPG para sa badge image, o badge na dinisenyo mo sa visual designer.

Ang base URL para sa lahat ay https://api.badges.ninja.

Step 1: Gumawa ng API key

Mag-sign in, buksan ang API Keys sa sidebar, at i-click ang Create API Key. Bigyan ito ng pangalang nagsasabi kung saan ito gagamitin, gaya ng “LMS integration”, para mapag-iba mo ang mga key kapag nag-rotate ka mamaya.

Isang beses lang ipinapakita ang key. Kopyahin ito agad sa secrets manager o environment variable mo. Ang mga key ay mukhang bws_ na sinusundan ng 32 hex character, at ipinapadala mo ang mga ito sa X-Api-Key header sa bawat request. Ang pag-revoke ng key mula sa parehong screen ay may bisa agad.

Ilang gawi na makakaiwas sa gulo mamaya:

• Huwag na huwag ilagay ang key sa front-end code o sa public repository. Tawagin ang API mula sa server, serverless function, o automation tool.
• Gumamit ng isang key kada integration. Kapag may na-leak, isang integration lang ang ire-revoke mo, hindi lahat.
• Tumatanggap din ang dashboard ng signed-in session mo (isang Cognito JWT na ipinapadala bilang Authorization: Bearer), pero para sa mga script at integration, ang API key ang tamang gamit.

Lahat ng halimbawa sa ibaba ay kumukuha ng key mula sa environment variable na pinangalanang BADGES_API_KEY.

Step 2: Gumawa ng issuer

Ang issuer ang organisasyong nasa likod ng badge. Lumalabas ito sa bawat verification page at sa loob ng Open Badge v2.0 data, kaya gamitin ang pangalang talagang kilala ng mga tao.

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

Ang mga kinakailangang field ay name (hindi bababa sa 3 character), url (valid na http o https address) at email. Ang mga opsyonal na field ay logo (base64-encoded na image) at linkedinOrganizationId, na nagpapagana ng Add to LinkedIn Profile button sa mga public credential page mo.

Naglalaman ang response ng issuer identifier:

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

Panatilihin ang value na iyon nang eksakto kung paano ito ibinalik. Ito ang input sa susunod na step.

Issuer verification

Makakagawa lang ng badges sa ilalim ng verified na issuer. Ganito gumagana ang verification:

• Kung ang email ng issuer ay tugma sa email ng account mo, awtomatikong na-ve-verify ang issuer. Ito ang pinakamabilis na daan para sa unang test.
• Kung iba ang email, may ipapadalang verification email na may code sa address na iyon. Kukumpirmahin mo ang code sa dashboard (o sa issuers API) bago gumawa ng badges.

Kaya para sa tutorial na ito, gamitin ang parehong email na ginamit mo sa pag-sign up.

Step 3: Gumawa ng badge

Ang badge ang reusable na template: pangalan, description, criteria at image. Bawat award na i-i-issue mo mamaya ay tumutukoy pabalik dito.

Plain JSON lang ang request. Ang image ay ipinapasok bilang base64 string, kaya walang multipart upload na pagtitiisan. Tinatanggap at inaalis ang data URL prefix gaya ng data:image/png;base64,.

JavaScript (Node 18 o mas bago):

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)

Required ang lahat ng limang field (name, description, criteria, image, issuerId). May dalawang opsyonal na dapat mong malaman: ang shareText, ang default na text na nakikita ng mga recipient kapag nag-share sila sa social networks (sinusuportahan nito ang mga placeholder na {{badge_name}}, {{issuer_name}} at {{award_url}}), at ang designJson, na nagse-save ng visual-designer document para ma-edit ang badge layer by layer mamaya.

Ang success ay nagbabalik ng HTTP 200 na may { "badgeId": "<id>" }. Permanenteng nase-save ang image, at ang badge ay isa nang Open Badge v2.0 BadgeClass na puwedeng kunin ng sinuman.

Dapat ka bang gumawa ng badges sa code?

Kadalasan, hindi. Creative task ang pagdidisenyo ng badge, at mas magandang lugar para rito ang visual designer (80+ templates, shapes, icons, 11 fonts at custom uploads) kaysa sa script. Karaniwang pattern ang idisenyo ang bawat badge nang isang beses sa dashboard, tapos ang integration mo ay mag-i-issue na lang ng awards laban dito. Puwede mong i-list ang mga badge mo gamit ang GET /badges at kopyahin ang id ng gusto mo.

Gumawa ng badges sa pamamagitan ng API kapag ginagawa mo ang mga ito programmatically, halimbawa isa kada course sa catalog na daan-daan, o kapag nag-seseed ka ng test environment.

Step 4: I-award ang badge

Ito ang call na gagawin ng integration mo nang libu-libong beses. Ipadala ang badge, ang recipient, at ang petsa.

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"]

Ang mga rule na madalas ikatisod ng mga tao:

• Ang recipient ay nested object na may name at email. Tinatanggihan ang mga flat field gaya ng recipientEmail.
• Ang recipient.name ay dapat hindi bababa sa 5 character.
• Required ang issuedOn. Magpadala ng epoch milliseconds o ISO date string gaya ng 2026-09-28.
• Opsyonal ang expires at tumatanggap ng parehong format.

Ang success ay HTTP 200 na may body na naglalaman ng awardId. Ang email ng recipient ay naka-store bilang SHA-256 hash sa Open Badge data, kaya hindi ito kailanman inilalantad ng public JSON.

Step 5: Hanapin ang verification page at ang Open Badge JSON

Identifier ang ibinibigay ng award response, hindi handa nang link. Nagtatapos sa GUID ang identifier, at doon binubuo ang mga public page:

• Human-readable na verification page: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Kung ang awardId mo ay bumalik bilang buong URL, gamitin ang huling path segment bilang GUID.

Pareho silang public. Kahit sino na may link ay puwedeng mag-verify ng credential nang hindi gumagawa ng account, at iyon ang punto: dapat makapag-check ang employer o admissions officer ng badge sa loob ng sampung segundo.

I-fetch ang JSON para makita kung ano ang nakikita ng mundo:

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

Makakakuha ka ng Open Badge v2.0 Assertion: ang badge na tinutukoy nito, ang hashed na identity ng recipient, ang issue date, at isang verification block na nakaturo pabalik sa naka-host na assertion. Dahil standard na Open Badges data ito, mababasa ito ng anumang tool na nakakaintindi ng format. Ang portability na iyon ang dahilan para piliin ang Open Badges kaysa sa proprietary na PDF; mas malalim itong tinatalakay ng Open Badges vs PDF certificates.

Paano natatanggap ng mga recipient ang credential

Magkaiba ang paggawa ng award at ang pagsasabi sa recipient tungkol dito. Mabubuksan ng mga recipient ang kanilang credentials sa recipient portal sa badges.ninja/me, na gumagamit ng magic-link sign-in na walang password, at puwede silang mag-publish ng public profile sa badges.ninja/u/<handle>. Mula sa verification page, puwede nilang idagdag ang badge sa LinkedIn, i-download ang PDF certificate, o i-share ang link.

Para sa unang ilang test, magpadala ng award sa sarili mo gamit ang sarili mong email address at daanan ang karanasan ng recipient. Ito ang pinakamabilis na paraan para mapansin ang mga bagay na gaya ng badge description na pangit basahin.

Error handling na hindi masakit

Gumagamit ang API ng ordinaryong HTTP status code. Ito ang mga makakaharap mo:

Dalawang praktikal na tip. Una, ituring ang 400 bilang problema sa data at i-log ang response body, dahil binabanggit nito ang field na pumalpak. Pangalawa, gawing idempotent ang integration mo sa panig mo: i-store ang awardId katabi ng completion record sa sarili mong database, at i-check ito bago tumawag ulit sa API. Sa ganoon, ang na-retry na webhook o na-rerun na job ay hindi kailanman mag-i-issue ng dalawang credential sa iisang tao.

Pagsasama-sama sa totoong integration

Ganito karaniwan ang wiring:

1. Mag-design ng badges sa dashboard, isa kada course o milestone, at itala ang ID ng bawat badge.
2. Mag-store ng mapping sa system mo mula course papunta sa badge ID.
3. Kapag natapos ng learner ang course, tatawag ang server mo ng POST /awards kasama ang pangalan, email at completion date nila.
4. I-save ang ibinalik na awardId sa completion record.
5. Ipakita ang verification link sa loob ng sarili mong product, para makita ito ng learner nang hindi umaalis.

Kung ayaw mong magsulat ng code, gumagana ang parehong call mula sa anumang automation tool na kayang magpadala ng HTTP request na may JSON body at custom header. Ituro ito sa https://api.badges.ninja/awards at i-map ang mga field ng form o spreadsheet mo sa badgeId, recipient.name, recipient.email at issuedOn.

Mga plan at limit na dapat malaman

Available ang API sa bawat plan; hindi ka nagbabayad ng dagdag para i-unlock ito. Sakop ng Free plan ($0) ang 2 issuers, 5 badges, 2 seats, 1 API key at 1,200 credentials kada taon. Ang Starter ay $9 kada buwan at ang Pro ay $29 kada buwan, na may mas mataas na limit. Tingnan ang pricing page para sa kasalukuyang numero bago mo sukatin ang rollout. Kung inihahambing mo ang singil ng ibang platform para sa API access, inilalatag ng Credly alternative ang mga gastos nang magkatabi.

Saan susunod

• Nasa API documentation ang buong endpoint reference, na available sa 40 wika.
• Para sa detalye ng authentication at paghawak ng key, tingnan ang authentication guide.
• Para sa mas malalim na error codes, tingnan ang errors reference.
• Kapag lumampas ka na sa isang call kada pagkakataon, gamitin ang bulk awards sa dashboard: mag-upload ng CSV, at i-pause o i-resume ang run kung kailangan.

Ang unang matagumpay na award ang mahirap na bahagi. Pagkatapos noon, ang natitira na lang ay isaksak ang parehong call sa mga lugar kung saan naitatala na ang mga achievement.

Handa ka na bang mag-issue ng una mong verifiable credential? Magsimula nang libre sa badges.ninja — visual designer, public verification page, PDF certificate, Open Badge v2.0 output. Walang kailangang credit card.