Badges API atsauce: nozīmju izveide, verifikācija un iegūšana

Pārvaldiet nozīmju veidnes – apliecinājumus, ko izsniedzat saņēmējiem.

Lai šo nozīmi izsniegtu daudziem saņēmējiem vienlaikus, augšupielādējot CSV, nevis izmantojot API, skatiet Masveida apliecinājumi.

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

Izveidot nozīmi

Izveidojiet jaunu nozīmi zem verificēta izdevēja.

POST /badges

Parametri

Parametrs	Tips	Obligāts	Apraksts
name	string	Jā	Nozīmes nosaukums
description	string	Jā	Ko nozīme apliecina
criteria	string	Jā	Ko saņēmējs izdarīja, lai nopelnītu šo nozīmi
image	string	Jā	Base64 kodēts attēls (PNG vai JPG)
issuerId	string	Jā	Verificētā izdevēja ID
shareText	string	Nē	Šīs nozīmes noklusējuma kopīgošanas teksts sociālajos tīklos. Atbalsta vietturus , un . Ja izlaists, tiek izmantota iebūvēta noklusējuma vērtība.
designJson	string	Nē	Serializēts nozīmju dizainera dokuments, kas tiek saglabāts, lai nozīmi vēlāk varētu rediģēt slāni pa slānim.

Piemērs

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Atbilde

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

Piezīmes

• Pirms nozīmju izveides izdevējam jābūt verificētam.
• Attēls tiek glabāts Amazon S3 un tiek piegādāts, izmantojot mūsu globālo CDN, ar nemainīgu, uz saturu balstītu URL.
• Kad nozīmes klase ir izveidota, izsniedziet to saņēmējiem, izmantojot Apliecinājumu API.

---

Uzskaitīt nozīmes

Iegūstiet visas jūsu izveidotās nozīmes.

GET /badges

Piemērs

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

Atbilde

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Iegūt nozīmi

Iegūstiet vienu nozīmi, ieskaitot tās kopīgošanas tekstu un serializēto nozīmju dizainera dokumentu (designJson). Šo galapunktu izmanto nozīmes rediģēšanas logs, lai atjaunotu atsevišķus slāņus; saraksta galapunkts designJson izlaiž, lai atbildes būtu vieglas.

GET /badges/{badgeId}

Parametri

Parametrs	Tips	Obligāts	Apraksts
badgeId	string	Jā	Nozīmes ID (ceļa parametrs)

Piemērs

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Atbilde

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Kopīgošanas teksts vienmēr tiek iekļauts. Vieglāks saraksta variants GET /badges?badgeId={id} atgriež to pašu dokumentu bez designJson, un kopīgošanas tekstu iekļauj tikai tad, ja izsaukts ar includeShareText=true.

---

Atjaunināt nozīmi

Atjauniniet esošu nozīmi. Tiek mainīti tikai jūsu norādītie lauki.

PUT /badges/{badgeId}

Parametri

Parametrs	Tips	Obligāts	Apraksts
badgeId	string	Jā	Nozīmes ID (ceļa parametrs)
name	string	Nē	Jauns nozīmes nosaukums
description	string	Nē	Jauns apraksts
criteria	string	Nē	Jauni kritēriji
image	string	Nē	Jauns Base64 kodēts attēls
designJson	string	Nē	Jauns serializēts nozīmju dizainera dokuments.

Piemērs

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Atbilde

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

Atjaunināt kopīgošanas tekstu

Iestatiet pielāgoto tekstu, kas tiek rādīts, kad saņēmēji kopīgo šo nozīmi sociālajos medijos.

PUT /badges/{badgeId}/share-text

Parametri

Parametrs	Tips	Obligāts	Apraksts
badgeId	string	Jā	Nozīmes ID (ceļa parametrs)
text	string	Jā	Kopīgošanas teksts (HTML nav atļauts)

Piemērs

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Atbilde

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Dzēst nozīmi

Dzēsiet nozīmi. Nozīmei nedrīkst būt apliecinājumu.

DELETE /badges/{badgeId}

Piemērs

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Atbilde

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

"badge has been deleted"

Kļūdas

• 400 — nozīmei joprojām ir izsniegti apliecinājumi: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — nozīme nav atrasta