Tham chiếu API huy hiệu: Tạo, xác minh và truy xuất huy hiệu

Quản lý các mẫu huy hiệu — những chứng chỉ bạn cấp cho người nhận.

Để cấp huy hiệu này cho nhiều người nhận cùng lúc bằng cách tải lên CSV thay vì dùng API, xem Chứng chỉ hàng loạt.

Tất cả endpoint đều yêu cầu xác thực qua header X-Api-Key. Xem Xác thực.

Tạo huy hiệu

Tạo một huy hiệu mới thuộc một tổ chức cấp đã được xác minh.

POST /badges

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tiêu đề huy hiệu
description	string	Có	Huy hiệu đại diện cho điều gì
criteria	string	Có	Người nhận đã làm gì để đạt huy hiệu này
image	string	Có	Ảnh mã hóa Base64 (PNG hoặc JPG)
issuerId	string	Có	ID của tổ chức cấp đã được xác minh
shareText	string	Không	Văn bản chia sẻ mạng xã hội mặc định cho huy hiệu này. Hỗ trợ các trình giữ chỗ , và . Nếu bỏ qua sẽ dùng mặc định có sẵn.
designJson	string	Không	Tài liệu trình thiết kế huy hiệu đã tuần tự hóa, được lưu để sau này có thể chỉnh sửa lại huy hiệu theo từng lớp.

Ví dụ

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

Phản hồi

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

Ghi chú

• Tổ chức cấp phải được xác minh trước khi tạo huy hiệu.
• Ảnh được lưu trên Amazon S3 và phân phối qua CDN toàn cầu của chúng tôi dưới một URL bất biến, định danh theo nội dung.
• Khi lớp huy hiệu đã tồn tại, hãy cấp nó cho người nhận bằng API Chứng chỉ.

---

Liệt kê huy hiệu

Truy xuất tất cả huy hiệu bạn đã tạo.

GET /badges

Ví dụ

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

Phản hồi

[
  {
    "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"
  }
]

---

Lấy huy hiệu

Truy xuất một huy hiệu, bao gồm văn bản chia sẻ và tài liệu trình thiết kế huy hiệu đã tuần tự hóa (designJson). Đây là endpoint mà hộp thoại Chỉnh sửa huy hiệu dùng để khôi phục từng lớp; endpoint liệt kê bỏ qua designJson để phản hồi gọn nhẹ.

GET /badges/{badgeId}

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
badgeId	string	Có	ID huy hiệu (tham số đường dẫn)

Ví dụ

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

Phản hồi

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

Văn bản chia sẻ luôn được đưa vào. Biến thể liệt kê nhẹ hơn GET /badges?badgeId={id} trả về cùng tài liệu nhưng không có designJson, và chỉ bao gồm văn bản chia sẻ khi được gọi với includeShareText=true.

---

Cập nhật huy hiệu

Cập nhật một huy hiệu hiện có. Chỉ các trường bạn cung cấp mới bị thay đổi.

PUT /badges/{badgeId}

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
badgeId	string	Có	ID huy hiệu (tham số đường dẫn)
name	string	Không	Tiêu đề huy hiệu mới
description	string	Không	Mô tả mới
criteria	string	Không	Tiêu chí mới
image	string	Không	Ảnh mã hóa Base64 mới
designJson	string	Không	Tài liệu trình thiết kế huy hiệu đã tuần tự hóa mới.

Ví dụ

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

Phản hồi

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

---

Cập nhật văn bản chia sẻ

Đặt văn bản tùy chỉnh hiển thị khi người nhận chia sẻ huy hiệu này lên mạng xã hội.

PUT /badges/{badgeId}/share-text

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
badgeId	string	Có	ID huy hiệu (tham số đường dẫn)
text	string	Có	Văn bản chia sẻ (không cho phép HTML)

Ví dụ

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

Phản hồi

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

---

Xóa huy hiệu

Xóa một huy hiệu. Huy hiệu phải không có chứng chỉ nào.

DELETE /badges/{badgeId}

Ví dụ

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

Phản hồi

Trả về một chuỗi xác nhận thuần:

"badge has been deleted"

Lỗi

• 400 — huy hiệu vẫn còn chứng chỉ đã cấp: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — không tìm thấy huy hiệu