API Đơn vị cấp

Quản lý các đơn vị cấp huy hiệu — các tổ chức hoặc cá nhân cấp huy hiệu.

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 đơn vị cấp

Tạo một đơn vị cấp huy hiệu mới.

POST /issuers

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tên tổ chức (tối thiểu 3 ký tự)
url	string	Có	Website của tổ chức (phải là URL HTTP/HTTPS hợp lệ)
email	string	Có	Email liên hệ của đơn vị cấp
logo	string	Không	Hình ảnh mã hóa Base64 (PNG hoặc JPG)
linkedinOrganizationId	string	Không	ID số của trang công ty trên LinkedIn. Khi được đặt, mọi trang chứng chỉ công khai của đơn vị cấp này đều hiển thị nút Add to LinkedIn Profile.

Ví dụ

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

Phản hồi

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

Ghi chú

• Được tính vào giới hạn đơn vị cấp của gói (Free: 2, Starter: 5, Pro: 10). Không trừ hạn mức.
• Nếu email của đơn vị cấp trùng với email tài khoản của bạn, đơn vị cấp sẽ được tự động xác minh.
• Nếu email khác, một email xác minh sẽ được gửi đến email của đơn vị cấp.
• Sau khi cấu hình đơn vị cấp, hãy dùng API Chứng chỉ để bắt đầu cấp chứng chỉ dưới đơn vị cấp đó.

---

Liệt kê đơn vị cấp

Lấy tất cả đơn vị cấp mà bạn đã tạo.

GET /issuers

Ví dụ

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

Phản hồi

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp là Unix epoch tính bằng mili giây. Khi có nhiều đơn vị cấp hơn mức vừa một trang, lastEvaluatedKey cũng được trả về để phân trang.

---

Xác minh đơn vị cấp

Xác minh một đơn vị cấp bằng mã xác minh được gửi đến email của đơn vị đó.

POST /issuers/{issuerId}/verify

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
issuerId	string	Có	ID đơn vị cấp (tham số đường dẫn)
code	string	Có	Mã xác minh trong email

Ví dụ

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Phản hồi

Một chuỗi thuần:

"issuer has been verified"

---

Xóa đơn vị cấp

Xóa một đơn vị cấp. Đơn vị cấp không được có huy hiệu nào liên kết với nó.

DELETE /issuers/{issuerId}

Ví dụ

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Phản hồi

Một chuỗi thuần:

"issuer has been deleted"

Lỗi

• 400 — đơn vị cấp vẫn còn huy hiệu liên kết: issuer has {n} badge(s) linked — delete the badges first. Việc xóa chỉ bị chặn bởi huy hiệu liên kết — chứng chỉ không chặn việc xóa.
• 404 — không tìm thấy đơn vị cấp

---

Cập nhật đơn vị cấp

Cập nhật các trường của một đơn vị cấp. Chỉ có thể chỉnh sửa các đơn vị cấp chưa được xác minh — khi một đơn vị cấp đã được xác minh, điểm cuối này trả về 400 verified issuers cannot be edited để giữ tính ổn định của chứng chỉ. Việc chỉnh sửa đơn vị cấp sẽ tạo lại mã xác minh của nó: nếu email trùng với email tài khoản của bạn thì đơn vị cấp được xác minh lại tự động, nếu không một email xác minh mới sẽ được gửi đến địa chỉ đó.

PUT /issuers/{issuerId}

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
issuerId	string	Có	ID đơn vị cấp (tham số đường dẫn)
name	string	Không	Tên mới
url	string	Không	URL mới
email	string	Không	Email mới (gửi email xác minh mới trừ khi trùng với email tài khoản của bạn)
logo	string	Không	Logo mới mã hóa Base64
linkedinOrganizationId	string	Không	ID tổ chức LinkedIn mới (hoặc chuỗi rỗng để xóa)

Phản hồi

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Lỗi

• 400 — verified issuers cannot be edited (đơn vị cấp đã được xác minh)
• 400 — not authorized (đơn vị cấp thuộc về tài khoản khác)
• 404 — không tìm thấy đơn vị cấp