API Huy hiệu

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

Tất cả các điểm cuối cần 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 dưới một đơn vị cấp đã 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ó	Ý nghĩa của huy hiệu
criteria	string	Có	Điều người nhận đã làm để đạt được huy hiệu
image	string	Có	Hình ảnh mã hóa Base64 (PNG hoặc JPG)
issuerId	string	Có	ID của đơn vị cấp đã xác minh

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

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

Ghi chú

• Đơn vị cấp phải được xác minh trước khi tạo huy hiệu.
• Hình ảnh được tải lên IPFS để lưu trữ vĩnh viễn.

---

Liệt kê huy hiệu

Lấy mọi 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

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Cập nhật huy hiệu

Cập nhật một huy hiệu hiện có. Chỉ những trường bạn cung cấp mới được 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	Hình ảnh mã hóa Base64 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

{
  "statusCode": 200,
  "info": {
    "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 trê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

{
  "statusCode": 200,
  "info": {
    "updated": true
  }
}

---

Xóa huy hiệu

Xóa một huy hiệu. Huy hiệu phải không có lần cấp 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

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

Lỗi

• 400 — huy hiệu có lần cấp và không thể xóa
• 404 — không tìm thấy huy hiệu