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 trao 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 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ố trang công ty LinkedIn. Khi đặt, mỗi trang cấp công khai từ đơn vị cấp này hiện nút Thêm vào hồ sơ LinkedIn.

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

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

Ghi chú

• Tính vào giới hạn đơn vị cấp của gói (Free: 1, Starter: 5, Pro: không giới hạn). Không trừ hạn mức.
• Nếu email đơn vị cấp trùng với email tài khoản, đơn vị được tự động xác minh.
• Nếu email khác, một email xác minh được gửi đến email đơn vị cấp.

---

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

Lấy mọi đơn vị cấp 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

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "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": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

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

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

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 từ 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

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

---

Xóa đơn vị cấp

Xóa một đơn vị cấp. Đơn vị phải không có huy hiệu nào.

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

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

Lỗi

• 400 — đơn vị cấp có huy hiệu hoặc lần cấp và không thể xóa (xóa chúng trước)
• 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ưa xác minh. Khi đơn vị đã xác minh, chỉ logo và linkedinOrganizationId còn có thể chỉnh sửa để giữ chứng chỉ ổn định.

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 (chỉ khi chưa xác minh)
url	string	Không	URL mới (chỉ khi chưa xác minh)
email	string	Không	Email mới (chỉ khi chưa xác minh — gửi email xác minh mới)
logo	string	Không	Logo mã hóa Base64 mới
linkedinOrganizationId	string	Không	ID tổ chức LinkedIn mới (hoặc chuỗi rỗng để xóa)

---

Tạo lại mã xác minh

Vô hiệu liên kết xác minh trước đó và gửi email một mã mới. Chỉ hợp lệ khi đơn vị cấp vẫn chưa xác minh.

POST /issuers/{issuerId}/rotate-code

Phản hồi

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