Members API

จัดการที่นั่งทีมและบทบาท — บุคคลที่ใช้ผู้ออก เหรียญ และการมอบของบัญชีคุณร่วมกัน

เอนด์พอยต์ทั้งหมดต้องมีการยืนยันตัวตน ดู การยืนยันตัวตน ทุกคำขอถูกจำกัดขอบเขตอยู่ภายในบัญชีของเจ้าของที่ได้รับการยืนยันตัวตน

บทบาทที่สามารถกำหนดได้ผ่าน API คือ admin, editor และ viewer บทบาท owner สงวนไว้สำหรับผู้ถือบัญชีและไม่สามารถกำหนดหรือลบได้

แสดงรายการสมาชิก

ดึงข้อมูลสมาชิกทั้งหมดและคำเชิญที่รอดำเนินการในบัญชีของคุณ

GET /members

ตัวอย่าง

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

การตอบกลับ

{
  "items": [
    {
      "memberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "owner@acme.example.com",
      "role": "owner",
      "status": "active"
    },
    {
      "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "email": "editor@acme.example.com",
      "role": "editor",
      "status": "pending"
    }
  ]
}

status เป็น active สำหรับสมาชิกที่ยอมรับแล้ว หรือ pending สำหรับคำเชิญที่ยังไม่ได้ยอมรับ

---

เชิญสมาชิก

เชิญบุคคลเข้าสู่บัญชีด้วยอีเมล อีเมลคำเชิญพร้อมลิงก์ยอมรับจะถูกส่งไปยังที่อยู่นั้น

POST /members

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
email	string	ใช่	ที่อยู่อีเมลที่จะเชิญ (ต้องเป็นอีเมลที่ถูกต้อง)
role	string	ใช่	บทบาทที่จะกำหนด — หนึ่งใน admin, editor, viewer

ตัวอย่าง

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

การตอบกลับ

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "pending"
}

ข้อผิดพลาด

• 400 — role must be one of admin, editor, viewer
• 400 — ที่อยู่อีเมลไม่ถูกต้องหรือขาดหายไป
• 400 — seat limit reached — บัญชีไม่มีที่นั่งว่างสำหรับแผน (ฟรี: 2, Starter: 5, Pro: 20, รวมเจ้าของ) ลบสมาชิกหรืออัปเกรดแผน
• 400 — อีเมลนี้เป็นสมาชิกอยู่แล้วหรือมีคำเชิญที่รอดำเนินการในบัญชีนี้

---

ยอมรับคำเชิญ

ยอมรับคำเชิญที่รอดำเนินการ อีเมลของผู้ใช้ที่ได้รับการยืนยันตัวตนต้องตรงกับที่อยู่ที่ส่งคำเชิญไป

POST /members/accept

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
inviteId	string	ใช่	รหัสคำเชิญจากอีเมลลิงก์ยอมรับ

ตัวอย่าง

curl -X POST https://api.badges.ninja/members/accept \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  }'

การตอบกลับ

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "active"
}

ข้อผิดพลาด

• 400 — email does not match invitation — อีเมลที่ลงชื่อเข้าใช้แตกต่างจากอีเมลที่ถูกเชิญ
• 404 — ไม่พบคำเชิญ (ยอมรับแล้ว ยกเลิกแล้ว หรือ inviteId ไม่ถูกต้อง)

---

อัปเดตบทบาทสมาชิก

เปลี่ยนบทบาทของสมาชิกที่มีอยู่ ต้องมีสิทธิ์เจ้าของหรือผู้ดูแล

POST /members/{memberId}/role

พารามิเตอร์

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
memberId	string	ใช่	รหัสสมาชิก (พารามิเตอร์เส้นทาง)
role	string	ใช่	บทบาทใหม่ — หนึ่งใน admin, editor, viewer

ตัวอย่าง

curl -X POST https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901/role \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "role": "admin"
    }
  }'

การตอบกลับ

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "role": "admin",
  "updated": true
}

ข้อผิดพลาด

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — ไม่พบสมาชิก

---

ลบสมาชิก

ลบสมาชิกออกจากบัญชี หรือยกเลิกคำเชิญที่รอดำเนินการ สมาชิกจะสูญเสียการเข้าถึงทันทีและที่นั่งของพวกเขาจะถูกปลดออก

DELETE /members/{memberId}

ตัวอย่าง

curl -X DELETE https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

การตอบกลับ

สตริงเปล่า:

"member has been removed"

ข้อผิดพลาด

• 400 — the owner cannot be removed
• 404 — ไม่พบสมาชิก