บทนำ

Partner API ของ Performance Hub ช่วยให้แพลตฟอร์มของพาร์ทเนอร์ภายนอกผสานรวมกับโมดูลหลักของ Performance Hub ได้อย่างราบรื่น API นี้รองรับคอมพิวเตอร์วิทัศน์ การวิเคราะห์ การบันทึกการเข้าถึงของสมาชิก และข้อมูลเชิงลึกของสถานที่

รูปแบบคำขอ

API รองรับเนื้อหาคำขอที่เข้ารหัสแบบ JSON และส่งคืนการตอบกลับที่เข้ารหัสแบบ JSON

การจำกัดอัตราการเรียกใช้

เพื่อให้การใช้งานเป็นธรรมและระบบมีเสถียรภาพ บัญชี Partner API จะเริ่มต้นด้วยขีดจำกัดเริ่มต้นดังนี้:

5 คำขอต่อวินาที ต่อปลายทาง
แนะนำ: สูงสุด 1000 รายการ ต่อคำขอแบบกลุ่มเพื่อประสิทธิภาพสูงสุด
ขนาดเพย์โหลดสูงสุด 10MB

ขีดจำกัดอัตราการเรียกใช้สามารถปรับได้ และผู้จัดการบัญชีพาร์ทเนอร์ของ Performance Hub สามารถกำหนดค่าเป็นรายกรณีได้ หากการผสานรวมของคุณต้องการปริมาณงานที่สูงขึ้นสำหรับการเปิดตัว การย้ายข้อมูล การเติมข้อมูลรายงานย้อนหลัง หรือสถานที่ที่มีปริมาณการใช้งานสูง ให้แจ้งเรื่องนี้ระหว่างการเริ่มต้นใช้งานหรือก่อนช่วงเวลาการเปลี่ยนแปลงที่วางแผนไว้

Base URL

https://partner-api.performancehub.co/partner/v1/

การยืนยันตัวตน

การเข้าถึง Partner API ต้องยืนยันตัวตนด้วยคีย์ลับของ API สร้างและจัดการคีย์ของคุณได้ผ่าน Partner Console

คีย์ API ทำหน้าที่เป็นข้อมูลประจำตัวของคุณในการเข้าถึงทรัพยากรของพาร์ทเนอร์ คีย์แต่ละรายการมีสิทธิ์เข้าถึงจำกัดเฉพาะข้อมูลขององค์กรที่กำหนด และสามารถปิดใช้งานได้ทันทีเมื่อจำเป็น

จัดการคีย์ API ของคุณอย่างระมัดระวัง เนื่องจากคีย์ให้สิทธิ์เข้าถึงบัญชีของคุณได้เต็มรูปแบบ อย่าเปิดเผยคีย์เหล่านี้ในที่เก็บโค้ดสาธารณะ แอปพลิเคชันฝั่งไคลเอนต์ หรือที่ใดก็ตามที่คีย์อาจถูกเข้าถึงโดยไม่ได้รับอนุญาต

ยืนยันตัวตนของคำขอโดยใช้ HTTP Basic Auth โดยส่งคีย์ API ของคุณเป็นชื่อผู้ใช้ และเว้นรหัสผ่านว่างไว้

API รองรับเฉพาะการเชื่อมต่อ HTTPS ที่ปลอดภัยเท่านั้น คำขอผ่าน HTTP ธรรมดาจะถูกปฏิเสธ เช่นเดียวกับคำขอใด ๆ ที่ไม่มีข้อมูลประจำตัวสำหรับการยืนยันตัวตนที่ถูกต้อง

ตัวอย่างคำขอ

curl https://partner-api.performancehub.co/partner/v1/organisations \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:
# The colon prevents curl from asking for a password.

ตรวจสอบคีย์ลับ

curl https://partner-api.performancehub.co/partner/v1/auth/ping \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:
# Returns { "message": "You are successfully authorised as <PartnerName>" }

รายการตรวจสอบก่อนเปิดใช้งานจริง

ใช้รายการตรวจสอบนี้ก่อนเปิดใช้การผสานรวมพาร์ทเนอร์สำหรับสถานที่ที่ใช้งานจริง

การตั้งค่า Partner Console

โปรไฟล์พาร์ทเนอร์ของคุณสมบูรณ์แล้ว
URL โลโก้ เว็บไซต์ หมวดหมู่ และคำอธิบายของคุณถูกต้อง
กำหนดค่าวิธีการเชื่อมโยงข้อมูลแล้ว: Direct Link หรือ Linking Identifier
ทดสอบการเชื่อมโยงสถานที่กับสถานที่จริงอย่างน้อยหนึ่งแห่งแล้ว
ใช้ประเภทคีย์ที่ถูกต้อง:
- Dryrun สำหรับการทดสอบการเขียนที่ไม่ส่งผลเสียหาย
- Read-only สำหรับการใช้ข้อมูลอย่างปลอดภัย
- Live เฉพาะเมื่อคุณพร้อมที่จะส่งผลต่อข้อมูลการใช้งานจริงเท่านั้น

การยืนยันตัวตนและการจัดการคีย์

จัดเก็บคีย์ลับไว้ฝั่งเซิร์ฟเวอร์เท่านั้น
ไม่มีการฝังคีย์ไว้ในแอปพลิเคชันฝั่งไคลเอนต์ แอปบนอุปกรณ์เคลื่อนที่ ที่เก็บโค้ดสาธารณะ หรือตั๋วขอรับการสนับสนุน
ทดสอบการหมุนเวียนและการเพิกถอนคีย์แล้ว
ทีมของคุณทราบว่าแต่ละสภาพแวดล้อมใช้คีย์ใด

การตรวจสอบความถูกต้องของข้อมูล

มีฟิลด์ที่จำเป็นครบสำหรับทุกปลายทางที่คุณเรียกใช้
ตัวระบุสถานที่ตรงกับวิธีการเชื่อมโยงที่คุณกำหนดค่าไว้
ID จากระบบของคุณคงที่และไม่เปลี่ยนแปลงระหว่างการซิงค์
การนำเข้าข้อมูลขนาดใหญ่ถูกแบ่งเป็นกลุ่มที่อยู่ภายในขีดจำกัดที่ระบุไว้ในเอกสาร
สามารถระบุและส่งรายการในกลุ่มที่ล้มเหลวซ้ำได้

การทดสอบปลายทาง

ก่อนเปิดตัว ให้ทดสอบทุกปลายทางที่การผสานรวมของคุณต้องใช้:

อ่านข้อมูลองค์กรและสถานที่ได้
บันทึกและอัปเดตข้อมูลสมาชิกได้
แผนสมาชิก โซนการเข้าถึง และชั่วโมงการเข้าถึงซิงค์อย่างถูกต้อง
ระบบรับการเช็กอินและเชื่อมโยงกลับไปยังระบบของคุณได้
สแนปช็อตรายงานใช้ช่วงเวลาการรายงานและเมตริกตามที่คาดไว้
ทดสอบขั้นตอนของ Door/Gate Controller กับฮาร์ดแวร์จริงในกรณีที่เกี่ยวข้อง

ความพร้อมของ Access Time Window

หากการผสานรวมส่ง Access Time Windows:

ตัวอย่างแบบกำหนดวันเวลาแน่นอนและแบบรายสัปดาห์ผ่านรายการตรวจสอบการรับรองผู้ส่งข้อมูล
ค่า epoch เป็นจำนวนเต็มวินาที Unix ที่ไม่มีเครื่องหมายคำพูด และทดสอบขอบเขต [from, to) ที่แน่นอนแล้ว
ตรวจสอบค่าเริ่มต้น UTC เขตเวลา IANA แบบกำหนดเองของการผสานรวม และการเปลี่ยนเวลาออมแสงที่เกี่ยวข้องแล้ว
มีสตรีมเวอร์ชันของสมาชิก/แหล่งข้อมูลที่คงทนและเพิ่มขึ้นทางเดียวเพียงสตรีมเดียว ที่ประสานการอัปเดตแบบส่วนเพิ่ม การกระทบยอด และการลองใหม่
ผู้ปฏิบัติงานเข้าใจลักษณะการทำงานของการเว้นค่า การแทนที่ทั้งหมด Idempotent ความขัดแย้ง ข้อมูลเก่า และ [] ที่ระบุอย่างชัดเจน
scope_key ทุกรายการ รวมถึง default มีการจับคู่กับ Performance Hub ที่ได้รับอนุมัติ และทดสอบแล้วว่าคีย์ที่ไม่รู้จักจะไม่ให้สิทธิ์เข้าถึง
กำหนดค่ารอบการรีเฟรชที่คาดไว้ อายุสูงสุดของข้อมูลต้นทาง ลักษณะการทำงานเมื่อข้อมูลต้นทางเก่า และการแจ้งเตือนของการผสานรวมแล้ว
พิสูจน์แล้วว่าความล้มเหลวในการดึงข้อมูลจากต้นทางจะไม่ส่งสแนปช็อตที่ว่างเปล่าหรือไม่ครบถ้วนออกไป
การบรรจบกันของสตรีมในแต่ละขั้น การยกเลิก/การเพิกถอนสิทธิ์ และขอบเขตเวลาเริ่มต้น/สิ้นสุดที่ประตูจริงเป็นไปตามเป้าหมายที่ตกลงไว้
ตรวจสอบแล้วว่ากฎปกติและสิทธิ์แบบถาวรทำหน้าที่เป็นเส้นทางสำรอง และช่วงเวลาไม่สามารถข้ามการปิดใช้งานผู้ใช้ blockAllAccess การบำรุงรักษา หรือ Geofence ได้

ความพร้อมของการควบคุมการเข้าถึง

สำหรับการผสานรวมด้านการควบคุมการเข้าถึง:

ระบบของคุณตัดสินใจเรื่องการเข้าถึงก่อนเรียก Performance Hub
การผสานรวมจัดการ device_offline, maintenance_mode_active และ unlock_confirmation_timeout ได้
ผู้ปฏิบัติงานเข้าใจว่าการหมดเวลาหมายความว่าการปลดล็อกไม่ได้รับการยืนยัน
บันทึกของคุณจัดเก็บ event_id และ command_id ที่ส่งคืนมา
คุณมีกระบวนการสำรองแบบดำเนินการด้วยตนเองสำหรับเจ้าหน้าที่ของสถานที่

การจัดการข้อผิดพลาดและการลองใหม่

การตอบกลับ 400, 401, 403, 404, 409 และ 422 จะแจ้งให้ผู้ปฏิบัติงานหรือทีมสนับสนุนทราบ แทนที่จะลองใหม่โดยไม่ไตร่ตรอง
การตอบกลับ 429, 500, 502, 503 และ 504 ใช้ตรรกะการลองใหม่แบบจำกัดจำนวนครั้งพร้อมการเว้นระยะ
ความล้มเหลวซ้ำ ๆ จะสร้างการแจ้งเตือนในระบบของคุณ
การผสานรวมไม่ทิ้งเรคคอร์ดที่ล้มเหลวไปอย่างเงียบ ๆ

การติดตามและตรวจสอบ

บันทึกของคุณมีปลายทาง การประทับเวลา ตัวระบุสถานที่ ID ของเรคคอร์ดต้นทาง ผลลัพธ์ของคำขอ และเนื้อหาการตอบกลับ
ทีมสนับสนุนของคุณค้นหาได้ด้วย ID สมาชิก ID สถานที่ ID การเช็กอิน หรือ ID เหตุการณ์การปลดล็อก
คุณมีวิธีส่งซ้ำหรือกระทบยอดการซิงค์ที่ล้มเหลว

การเปิดใช้งานจริง

Performance Hub ยืนยันสิทธิ์การเข้าถึงสำหรับการใช้งานจริงของคุณแล้ว
มีสถานที่ที่ใช้งานจริงอย่างน้อยหนึ่งแห่งเปิดใช้การผสานรวมของคุณ
คีย์สำหรับการใช้งานจริงของคุณใช้งานได้อยู่
ข้อมูลผู้ติดต่อด้านการดำเนินงานและด้านเทคนิคของคุณเป็นปัจจุบัน
กระบวนการสนับสนุนของคุณมีเอกสารสำหรับลูกค้าแล้ว

หลังจากการตรวจสอบเหล่านี้เสร็จสมบูรณ์ การผสานรวมที่คุณกำหนดค่าไว้จะปรากฏในไดเรกทอรีพาร์ทเนอร์ของ Performance Hub ภายในแพลตฟอร์มหลักของ Performance Hub

แนวทางปฏิบัติที่ดีที่สุด

ใช้รูปแบบเหล่านี้เพื่อให้การผสานรวมของพาร์ทเนอร์คาดการณ์ได้ ตรวจสอบได้ และปลอดภัยสำหรับสถานที่

ระบุสถานที่อย่างสม่ำเสมอ

เลือกวิธีการเชื่อมโยงที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณ และใช้อย่างสม่ำเสมอ:

Direct Link - ใช้ facility_id ของ Performance Hub ที่ส่งคืนจากปลายทางสถานที่
Linking Identifier - ใช้ตัวระบุตำแหน่งที่ตั้งของคุณเอง เช่น ID สาขา รหัสตำแหน่งที่ตั้ง หรือหมายเลขร้านค้า

อย่าส่งตัวระบุทั้งสองแบบในคำขอเดียวกัน Performance Hub จะประมวลผลคำขอโดยใช้วิธีการเชื่อมโยงที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณ

ดูคำแนะนำในการตั้งค่าได้ที่วิธีการเชื่อมโยงของพาร์ทเนอร์

เขียนข้อมูลแบบกลุ่มอย่างระมัดระวัง

Partner API รองรับเนื้อหาคำขอแบบ JSON และออกแบบมาสำหรับขั้นตอนการซิงค์แบบกลุ่มในส่วนที่มีการระบุไว้ในเอกสาร ให้จำกัดขนาดของแต่ละกลุ่มและออกแบบให้ลองใหม่ได้

แนวทางเริ่มต้น:

ใช้ไม่เกิน 1000 รายการต่อคำขอแบบกลุ่ม เพื่อประสิทธิภาพสูงสุด
รักษาขนาดเพย์โหลดให้ต่ำกว่า 10MB
ไม่เกิน 5 คำขอต่อวินาทีต่อปลายทาง

ขีดจำกัดอัตราการเรียกใช้สามารถปรับได้ และผู้จัดการบัญชีพาร์ทเนอร์ของ Performance Hub สามารถกำหนดค่าเป็นรายกรณีได้ หากคุณคาดว่าจะมีการนำเข้าข้อมูลปริมาณมาก ทราฟฟิกช่วงเปิดตัว หรือการเติมข้อมูลรายงานย้อนหลัง ให้ตกลงปริมาณงานที่ต้องการก่อนถึงช่วงเวลาการเปลี่ยนแปลง

หากต้องการซิงค์ชุดข้อมูลขนาดใหญ่ ให้แบ่งออกเป็นส่วนย่อยที่กำหนดแน่นอน และบันทึก ID ของแต่ละส่วนไว้ฝั่งคุณ วิธีนี้ช่วยให้วิเคราะห์การลองใหม่ที่ล้มเหลวได้ง่ายขึ้น

ลองใหม่อย่างปลอดภัย

ใช้การเว้นระยะแบบเอ็กซ์โพเนนเชียล (exponential backoff) สำหรับความล้มเหลวชั่วคราว เช่น 429, 500, 502, 503 และ 504

หลีกเลี่ยงการลองใหม่แบบวนซ้ำถี่ ๆ จุดเริ่มต้นที่ดีคือ:

ลองใหม่หลังจาก 1 วินาที
ลองใหม่หลังจาก 2 วินาที
ลองใหม่หลังจาก 4 วินาที
หยุดและแจ้งเตือนหากการดำเนินการยังคงล้มเหลว

สำหรับความล้มเหลวในการตรวจสอบความถูกต้อง เช่น 400 หรือ 422 ให้แก้ไขคำขอก่อนลองใหม่

ใช้ Idempotency ในส่วนที่รองรับ

ปลายทางปลดล็อก Door/Gate Controller รองรับ idempotency_key แบบไม่บังคับ การใช้คีย์เดิมซ้ำสำหรับพาร์ทเนอร์ สถานที่ และประตูเดียวกันจะส่งคืนผลลัพธ์ที่มีอยู่เมื่อมี

ใช้คีย์ที่คงที่สำหรับการดำเนินการที่ทำอยู่ เช่น ID การเช็กอินหรือ ID เหตุการณ์การเข้าถึงจากระบบของคุณ

อย่าสันนิษฐานว่าปลายทางการเขียนทุกตัวรองรับ Idempotency เว้นแต่จะระบุไว้ในเอกสารของปลายทางนั้น

รักษาข้อมูลต้นทางให้สะอาด

ส่งค่าที่คงที่และเป็นมาตรฐานทุกครั้งที่ทำได้:

ใช้ ID ของสมาชิก แผน สถานที่ และการเช็กอินที่สอดคล้องกันจากระบบต้นทางของคุณ
ใช้การประทับเวลาแบบ ISO 8601 สำหรับวันที่และเวลา
ส่งหมายเลขโทรศัพท์ในรูปแบบสากลหากมี
ส่งสกุลเงินโดยใช้ฟิลด์ที่ระบุไว้ในเอกสารของแต่ละปลายทาง
หลีกเลี่ยงการใส่ข้อมูลที่ควรอยู่ในฟิลด์แบบมีโครงสร้างลงในฟิลด์ข้อความอิสระมากเกินไป

ออกแบบสำหรับการซิงค์แบบส่วนเพิ่มและแบบเต็ม

การผสานรวมของพาร์ทเนอร์ส่วนใหญ่ต้องใช้ทั้งสองแบบ:

การซิงค์แบบส่วนเพิ่ม สำหรับการเปลี่ยนแปลงในแต่ละวัน
การซิงค์เพื่อกระทบยอดแบบเต็ม เพื่อแก้ไขเหตุการณ์ที่ตกหล่น การนำเข้าข้อมูลย้อนหลัง หรือข้อมูลที่คลาดเคลื่อน

การผสานรวมของคุณควรส่งสถานะปัจจุบันของสมาชิก แผนสมาชิก หรือสแนปช็อตรายงานซ้ำได้ โดยไม่ขึ้นอยู่กับว่าคำขอก่อนหน้าสำเร็จหรือไม่

เผยแพร่ Access Time Windows อย่างปลอดภัย

ให้ถือว่าค่า access_time_windows ของสมาชิกแต่ละรายเป็นสแนปช็อตที่สมบูรณ์และมีการกำหนดเวอร์ชันแยกกันอย่างอิสระ:

ประสานสตรีม access_time_windows_revision ที่เพิ่มขึ้นทางเดียวเพียงสตรีมเดียวระหว่างเวิร์กเกอร์แบบส่วนเพิ่มและเวิร์กเกอร์กระทบยอด
ลองส่งใหม่สำหรับการส่งที่ไม่แน่นอนหรือล้มเหลวชั่วคราว โดยใช้เวอร์ชันเดิมและเพย์โหลดที่ปรับให้เป็นมาตรฐานแบบเดิม
เว้น access_time_windows ไว้เมื่อคุณไม่ได้อัปเดตค่านี้
ส่ง [] ก็ต่อเมื่อการดึงข้อมูลจากแหล่งที่เชื่อถือได้สำเร็จและพิสูจน์แล้วว่าไม่มีช่วงเวลาเหลืออยู่เท่านั้น อย่าเปลี่ยนการหมดเวลาของต้นทาง ผลลัพธ์ที่ไม่ครบถ้วน หรือความล้มเหลวในการแยกวิเคราะห์ให้กลายเป็นการเพิกถอนสิทธิ์
รักษา external_id และ scope_key ให้คงที่ และรับรองการจับคู่ขอบเขตทุกรายการก่อนใช้งานจริง
ติดตามอายุของข้อมูลต้นทางเทียบกับนโยบายความเป็นปัจจุบันที่ตกลงไว้สำหรับการผสานรวมนั้น

ดูคู่มือผู้ส่งข้อมูล Access Time Windows ฉบับทางการ สำหรับสแนปช็อตแบบสมบูรณ์ เขตเวลา DST การยกเลิก และเวกเตอร์ทดสอบ

ถือว่าการควบคุมการเข้าถึงมีความสำคัญด้านความปลอดภัย

สำหรับการปลดล็อก Door/Gate Controller:

ระบบของคุณต้องตัดสินว่าบุคคลนั้นได้รับอนุญาตให้เข้าหรือไม่ก่อนเรียก Performance Hub
Performance Hub จะส่งคืน 200 ก็ต่อเมื่อตัวควบคุมในสถานที่ยืนยันว่ารีเลย์ปลดล็อกทางกายภาพแล้วเท่านั้น
การยืนยันส่วนใหญ่เสร็จสิ้นภายใน 3-5 วินาที
การหมดเวลาถือเป็นการปลดล็อกที่ล้มเหลวอย่างชัดเจน ไม่ใช่ความสำเร็จที่เกิดขึ้นเบื้องหลัง
ลองใหม่ตามกฎด้านการเข้าถึงและความปลอดภัยของคุณเองเท่านั้น

บันทึก event_id และ command_id ที่ส่งคืนจากปลายทางปลดล็อกทุกครั้ง

ติดตามการผสานรวมของคุณ

ใช้บันทึกคำขอใน Partner Console ระหว่างการพัฒนาและการเปิดตัว ในการใช้งานจริง ให้เก็บบันทึกของคุณเองด้วย โดยมีข้อมูลต่อไปนี้:

การประทับเวลาของคำขอ
ปลายทาง
ID ของเรคคอร์ดต้นทาง
ตัวระบุสถานที่
รหัสสถานะ HTTP
เนื้อหาการตอบกลับหรือข้อความแสดงข้อผิดพลาดจาก Performance Hub

ฟิลด์เหล่านี้ช่วยให้การสนับสนุนและการกระทบยอดรวดเร็วขึ้นมากเมื่อลูกค้าสอบถามว่าเกิดอะไรขึ้น

องค์กร

แสดงถึงหน่วยธุรกิจระดับบนสุดที่ดำเนินงานสถานที่ตั้งแต่หนึ่งแห่งขึ้นไปซึ่งผสานรวมกับแพลตฟอร์ม Performance Hub

ปลายทาง

GET /partner/v1/organisations - List all organisations

ออบเจ็กต์ Organisation

แอตทริบิวต์

org_id string จำเป็น

ตัวระบุเฉพาะขององค์กร
name string จำเป็น

ชื่อองค์กร

ออบเจ็กต์ Organisation

{
  "org_id": "00000000-0000-0000-0000-000000000050",
  "name": "Harbourside Group"
}

แสดงรายการองค์กรทั้งหมด

ส่งคืนรายการองค์กรที่บัญชีพาร์ทเนอร์ของคุณเข้าถึงได้

ค่าที่ส่งคืน

ส่งคืนออบเจ็กต์ JSON ที่มีพร็อพเพอร์ตี data ซึ่งประกอบด้วยอาร์เรย์ของออบเจ็กต์ Organisation

คำขอ

curl https://partner-api.performancehub.co/partner/v1/organisations \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

การตอบกลับ

{
  "data": [
    {
      "org_id": "00000000-0000-0000-0000-000000000050",
      "name": "Harbourside Group"
    },
    {
      "org_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "name": "Wellness Studios Network"
    }
  ]
}

สถานที่

แสดงถึงตำแหน่งที่ตั้งทางกายภาพ เช่น สำนักงาน ร้านค้า สถานที่จัดงาน วิทยาเขต คลินิก หรือยิม ที่สมาชิกสามารถเข้าใช้บริการได้

ปลายทาง

GET /partner/v1/facilities - List all facilities

ออบเจ็กต์สถานที่

แอตทริบิวต์

facility_id string จำเป็น

ตัวระบุเฉพาะของสถานที่
org_id string จำเป็น

ตัวระบุเฉพาะขององค์กรหลัก
name string จำเป็น

ชื่อสถานที่
brand string ไม่บังคับ

ชื่อแบรนด์ที่สถานที่ใช้
website_url string ไม่บังคับ

URL เว็บไซต์ของสถานที่
place_data object ไม่บังคับ

ข้อมูลตำแหน่งที่ตั้งจาก Google Places API ซึ่งประกอบด้วยประเทศ ที่อยู่ที่จัดรูปแบบแล้ว Google Place ID จังหวัด/รัฐ และเมือง
social_links object ไม่บังคับ

ลิงก์โซเชียลมีเดียของสถานที่
timezone string ไม่บังคับ

ตัวระบุเขตเวลา IANA (เช่น "Australia/Sydney", "America/New_York")

ออบเจ็กต์สถานที่

{
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "org_id": "00000000-0000-0000-0000-000000000050",
  "name": "Harbourside Central",
  "brand": "Harbourside",
  "website_url": "https://example.com/central",
  "social_links": {
    "instagram": {
      "handle": "@harbourside.central"
    },
    "facebook": {
      "handle": "HarboursideCentral"
    }
  },
  "place_data": {
    "country": {
      "iso_code": "AU",
      "full_name": "Australia"
    },
    "formatted_address": "123 Main Street, Suite 100, Sydney NSW 2000, Australia",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "province": {
      "abbreviation": "NSW",
      "full_name": "New South Wales"
    },
    "city": {
      "short_name": "Sydney",
      "full_name": "Sydney"
    }
  },
  "timezone": "Australia/Sydney"
}

แสดงรายการสถานที่ทั้งหมด

ส่งคืนรายการสถานที่ที่บัญชีพาร์ทเนอร์ของคุณเข้าถึงได้

ค่าที่ส่งคืน

ส่งคืนออบเจ็กต์ JSON ที่มีพร็อพเพอร์ตี data ซึ่งประกอบด้วยอาร์เรย์ของออบเจ็กต์สถานที่

คำขอ

curl https://partner-api.performancehub.co/partner/v1/facilities \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

การตอบกลับ

{
  "data": [
    {
      "facility_id": "550e8400-e29b-41d4-a716-446655440000",
      "org_id": "00000000-0000-0000-0000-000000000050",
      "name": "Harbourside Central",
      "brand": "Harbourside",
      "website_url": "https://example.com/central",
      "place_data": {
        "country": {
          "iso_code": "AU",
          "full_name": "Australia"
        },
        "formatted_address": "123 Main Street, Sydney NSW 2000, Australia",
        "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
        "province": {
          "abbreviation": "NSW",
          "full_name": "New South Wales"
        },
        "city": {
          "short_name": "Sydney",
          "full_name": "Sydney"
        }
      },
      "timezone": "Australia/Sydney"
    }
  ]
}

แผนสมาชิก

กำหนดข้อเสนอที่ซื้อได้จากองค์กรหรือสถานที่ ซึ่งรวมถึงบริการ สิทธิประโยชน์ ตารางเวลา และราคา

ปลายทาง

POST /partner/v1/membership-plans - Save a membership plan

ออบเจ็กต์ Membership Plan

แอตทริบิวต์

membership_plan_id string จำเป็น

ตัวระบุเฉพาะของแผนสมาชิก
facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุเฉพาะของสถานที่จาก Performance Hub
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ค่าตัวระบุเฉพาะของแต่ละตำแหน่งที่ตั้งที่พาร์ทเนอร์ใช้ (เช่น "Branch ID", "Location Code", "Store Number") ดูข้อมูลเพิ่มเติม
name string จำเป็น

ชื่อแผนที่มนุษย์อ่านได้ (เช่น "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack")
billing_cycle string ไม่บังคับ

ความถี่ในการเรียกเก็บเงิน เป็นค่าใดค่าหนึ่งต่อไปนี้ weekly, fortnightly, monthly, annually หรือ one_time
price integer ไม่บังคับ

ราคาพื้นฐานในหน่วยสกุลเงินที่เล็กที่สุด (เซนต์สำหรับ USD/AUD)
currency string ไม่บังคับ

รหัสสกุลเงิน ISO 4217 (เช่น "AUD", "USD")
description string ไม่บังคับ

คำอธิบายเพื่อการตลาดหรือใช้ภายใน (ไม่บังคับ)
active_members integer ไม่บังคับ

จำนวนสมาชิกที่ใช้งานอยู่ซึ่งใช้แผนสมาชิกนี้
is_recurring boolean ไม่บังคับ

ระบุว่าแผนต่ออายุอัตโนมัติหรือไม่
is_trial boolean ไม่บังคับ

ระบุว่าเป็นข้อเสนอแบบทดลองใช้หรือไม่
visible_to_public boolean ไม่บังคับ

ระบุว่าแผนนี้เปิดให้ซื้อได้ด้วยตนเองหรือไม่
duration_days integer ไม่บังคับ

จำนวนวันที่แผนสมาชิกมีผลใช้งาน
access_zones array ไม่บังคับ

อาร์เรย์ของโซนการเข้าถึงที่รวมอยู่ในแผนสมาชิก แต่ละโซนสามารถกำหนดชั่วโมงการเข้าถึงของตนเองได้ ดูรายละเอียดได้ที่โซนการเข้าถึง
class_limit integer ไม่บังคับ

จำนวนคลาสสูงสุดที่อนุญาต (null หมายถึงไม่จำกัด)

ออบเจ็กต์ Membership Plan

ตัวอย่างนี้ใช้ facility_id สำหรับการผสานรวมแบบ Linking Identifier ให้ส่ง "linking_identifier": "branch_downtown" แทน

{
  "membership_plan_id": "plan_99999",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Office tenant – business hours",
  "description": "Weekday access to the level 3 tenancy and the end-of-trip facilities",
  "billing_cycle": "monthly",
  "price": 8900,
  "currency": "AUD",
  "duration_days": 30,
  "is_recurring": true,
  "is_trial": false,
  "visible_to_public": false,
  "active_members": 245,
  "access_zones": [
    {
      "name": "Level 3 Tenancy",
      "description": "Lift lobby, offices and meeting rooms on level 3",
      "access_hours": {
        "mon": [["07:00", "19:00"]],
        "tue": [["07:00", "19:00"]],
        "wed": [["07:00", "19:00"]],
        "thu": [["07:00", "19:00"]],
        "fri": [["07:00", "19:00"]]
      }
    },
    {
      "name": "End-of-trip Facilities",
      "description": "Bike storage, lockers and showers",
      "access_hours": {
        "mon": [["06:00", "20:00"]],
        "tue": [["06:00", "20:00"]],
        "wed": [["06:00", "20:00"]],
        "thu": [["06:00", "20:00"]],
        "fri": [["06:00", "20:00"]]
      }
    }
  ],
  "class_limit": null
}

โซนการเข้าถึง

โซนการเข้าถึงกำหนดพื้นที่เฉพาะภายในสถานที่ที่แผนสมาชิกให้สิทธิ์เข้าถึง แต่ละโซนสามารถมีชั่วโมงการเข้าถึงของตนเอง ทำให้กำหนดข้อจำกัดด้านเวลาแตกต่างกันในแต่ละพื้นที่ได้

โครงสร้าง

โซนการเข้าถึงแต่ละโซนประกอบด้วย:

name string จำเป็น

ชื่อของโซน (เช่น "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor")
description string ไม่บังคับ

คำอธิบายสิ่งที่รวมอยู่ในโซนนั้น
access_hours object ไม่บังคับ

ชั่วโมงการเข้าถึงเฉพาะสำหรับโซนนี้ ดูรูปแบบช่วงเวลาได้ที่ชั่วโมงการเข้าถึง

ตัวอย่าง

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

{
  "access_zones": [
    {
      "name": "Level 3 Tenancy",
      "description": "Lift lobby, offices and meeting rooms on level 3",
      "access_hours": {
        "mon": [["07:00", "19:00"]],
        "tue": [["07:00", "19:00"]],
        "wed": [["07:00", "19:00"]],
        "thu": [["07:00", "19:00"]],
        "fri": [["07:00", "19:00"]]
      }
    },
    {
      "name": "Tenant Gym",
      "description": "Ground-floor gym and change rooms for building tenants",
      "access_hours": {
        "mon": [["05:00", "22:00"]],
        "tue": [["05:00", "22:00"]],
        "wed": [["05:00", "22:00"]],
        "thu": [["05:00", "22:00"]],
        "fri": [["05:00", "22:00"]],
        "sat": [["07:00", "18:00"]],
        "sun": [["07:00", "18:00"]]
      }
    }
  ]
}

ชั่วโมงการเข้าถึง

ชั่วโมงการเข้าถึงระบุช่วงเวลาที่สมาชิกเข้าถึงโซนหนึ่ง ๆ ได้ในแต่ละวันของสัปดาห์ ชั่วโมงการเข้าถึงกำหนดแยกตามโซนการเข้าถึง ทำให้กำหนดข้อจำกัดด้านเวลาที่แตกต่างกันสำหรับพื้นที่ต่าง ๆ ของสถานที่ได้

โครงสร้าง

{
  "mon": [["start_time", "end_time"]],
  "tue": [["start_time", "end_time"]],
  "wed": [["start_time", "end_time"]],
  "thu": [["start_time", "end_time"]],
  "fri": [["start_time", "end_time"]],
  "sat": [["start_time", "end_time"]],
  "sun": [["start_time", "end_time"]]
}

แต่ละวันเป็นอาร์เรย์ของช่วงเวลาในรูปแบบ HH:MM (นาฬิกาแบบ 24 ชั่วโมง) อาร์เรย์ว่าง [] หมายถึงไม่มีสิทธิ์เข้าถึงในวันนั้น วันที่ไม่ได้ระบุจะถือเหมือนอาร์เรย์ว่าง

ตัวอย่างกรณีการใช้งาน

ผู้เช่าสำนักงาน – เวลาทำการ: เข้าถึงได้ในเวลาทำการเฉพาะวันธรรมดาเท่านั้น

{
  "access_hours": {
    "mon": [["07:00", "19:00"]],
    "tue": [["07:00", "19:00"]],
    "wed": [["07:00", "19:00"]],
    "thu": [["07:00", "19:00"]],
    "fri": [["07:00", "19:00"]]
  }
}

นักศึกษา – การเข้าถึงในภาคเรียน: ห้องสมุดในวิทยาเขตที่เปิดในวันธรรมดา โดยมีช่วงพักกลางวัน และเปิดในเช้าวันเสาร์

{
  "access_hours": {
    "mon": [["08:00", "12:30"], ["13:30", "21:00"]],
    "tue": [["08:00", "12:30"], ["13:30", "21:00"]],
    "wed": [["08:00", "12:30"], ["13:30", "21:00"]],
    "thu": [["08:00", "12:30"], ["13:30", "21:00"]],
    "fri": [["08:00", "12:30"], ["13:30", "17:00"]],
    "sat": [["09:00", "13:00"]]
  }
}

ยิม – รอบเช้าตรู่: เข้าถึงได้เฉพาะช่วงเช้าในวันธรรมดา

{
  "access_hours": {
    "mon": [["04:00", "12:00"]],
    "tue": [["04:00", "12:00"]],
    "wed": [["04:00", "12:00"]],
    "thu": [["04:00", "12:00"]],
    "fri": [["04:00", "12:00"]]
  }
}

แขกของโรงแรม – ตลอด 24 ชั่วโมงทุกวัน: เข้าถึงได้ตลอดเวลา ซึ่งเป็นกรณีการใช้งานที่พบบ่อยที่สุด

{
  "access_hours": {
    "mon": [["00:00", "23:59"]],
    "tue": [["00:00", "23:59"]],
    "wed": [["00:00", "23:59"]],
    "thu": [["00:00", "23:59"]],
    "fri": [["00:00", "23:59"]],
    "sat": [["00:00", "23:59"]],
    "sun": [["00:00", "23:59"]]
  }
}

ตัวอย่างแยกตามโซน

แผนสำหรับแขกของโรงแรมที่เข้าถึงชั้นห้องพักได้ตลอด 24 ชั่วโมง และเข้าถึงสระว่ายน้ำได้ในช่วงเวลาที่สั้นกว่า:

{
  "access_zones": [
    {
      "name": "Guest Floors",
      "description": "Lifts and corridors on the guest room levels",
      "access_hours": {
        "mon": [["00:00", "23:59"]],
        "tue": [["00:00", "23:59"]],
        "wed": [["00:00", "23:59"]],
        "thu": [["00:00", "23:59"]],
        "fri": [["00:00", "23:59"]],
        "sat": [["00:00", "23:59"]],
        "sun": [["00:00", "23:59"]]
      }
    },
    {
      "name": "Swimming Pool",
      "description": "Access to the swimming pool and change rooms",
      "access_hours": {
        "mon": [["06:00", "20:00"]],
        "tue": [["06:00", "20:00"]],
        "wed": [["06:00", "20:00"]],
        "thu": [["06:00", "20:00"]],
        "fri": [["06:00", "20:00"]],
        "sat": [["08:00", "18:00"]],
        "sun": [["08:00", "18:00"]]
      }
    }
  ]
}

บันทึกแผนสมาชิก

สร้างหรืออัปเดตเรคคอร์ดแผนสมาชิก API จะพิจารณาว่าจะสร้างหรืออัปเดตโดยอิงจาก membership_plan_id

พารามิเตอร์

membership_plans array จำเป็น

อาร์เรย์ของออบเจ็กต์ Membership Plan ที่จะบันทึก จำนวนสูงสุดที่แนะนำ: 1000 รายการต่อคำขอเพื่อประสิทธิภาพสูงสุด API จะแบ่งรายการเป็นกลุ่มเพื่อประมวลผลโดยอัตโนมัติ แต่ละรายการต้องมี facility_id (จำเป็นหากไม่ใช้ linking_identifier) หรือ linking_identifier (จำเป็นหากไม่ใช้ facility_id)

ค่าที่ส่งคืน

ส่งคืนข้อความสั้น ๆ ที่ยืนยันการดำเนินการซิงค์

คำขอ

curl -X POST https://partner-api.performancehub.co/partner/v1/membership-plans \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "membership_plans": [
      {
        "membership_plan_id": "plan_99999",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Student – term access",
        "description": "Library and student hub access for one teaching term",
        "billing_cycle": "one_time",
        "price": 4500,
        "currency": "AUD",
        "duration_days": 84,
        "is_recurring": false,
        "is_trial": false,
        "visible_to_public": true,
        "active_members": 245,
        "access_zones": [
          {
            "name": "Library",
            "description": "Reading rooms, study spaces and bookable rooms",
            "access_hours": {
              "mon": [["08:00", "21:00"]],
              "tue": [["08:00", "21:00"]],
              "wed": [["08:00", "21:00"]],
              "thu": [["08:00", "21:00"]],
              "fri": [["08:00", "17:00"]],
              "sat": [["09:00", "13:00"]]
            }
          },
          {
            "name": "Student Hub",
            "description": "Common room, kitchen and lockers",
            "access_hours": {
              "mon": [["07:00", "22:00"]],
              "tue": [["07:00", "22:00"]],
              "wed": [["07:00", "22:00"]],
              "thu": [["07:00", "22:00"]],
              "fri": [["07:00", "22:00"]]
            }
          }
        ],
        "class_limit": null
      }
    ]
  }'

การตอบกลับ

ส่งคืนข้อความแสดงความสำเร็จพร้อมข้อมูลเมตาเกี่ยวกับการดำเนินการซิงค์

{
  "message": "Membership plan sync successful.",
  "metadata": {
    "success": 98,
    "skipped": 2,
    "skipped_items": [
      {
        "membership_plan_id": "plan_456",
        "facility_id": null,
        "reason": "Missing facility_id"
      }
    ]
  }
}

ฟิลด์ข้อมูลเมตา:

success - จำนวนแผนสมาชิกที่ประมวลผลสำเร็จ
skipped - จำนวนแผนที่ถูกข้าม (ถ้ามี)
skipped_items - อาร์เรย์ของแผนที่ถูกข้ามพร้อมเหตุผล (ถ้ามี)
dry-run - แฟล็กบูลีนเมื่อใช้คีย์ประเภท dryrun (ถ้ามี)

สมาชิก

แสดงถึงลูกค้ารายบุคคลของสถานที่ ซึ่งอาจเป็นลีด ผู้มีแนวโน้มเป็นลูกค้า ลูกค้าประจำ สมาชิกที่หมดอายุ หรือผู้ใช้ที่ถูกบล็อก

การ upsert สมาชิกยังสามารถส่งสแนปช็อต access_time_windows ที่สมบูรณ์และมีการกำหนดเวอร์ชัน ซึ่งประกอบด้วยการเข้าถึงแบบกำหนดวันเวลาแน่นอนและแบบรายสัปดาห์ที่เกิดซ้ำได้ด้วย โปรดอ่าน Access Time Windows ก่อนสร้างฟิลด์เหล่านี้ ฟิลด์เหล่านี้เป็นสิทธิ์แบบเพิ่มเติม และไม่ได้แทนที่กฎปกติหรือสิทธิ์แบบถาวรของสถานที่

ปลายทาง

POST /partner/v1/members - Save a member

ออบเจ็กต์ Member

แอตทริบิวต์

member_id string จำเป็น

ตัวระบุเฉพาะของสมาชิก
facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุเฉพาะของสถานที่จาก Performance Hub
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ค่าตัวระบุเฉพาะของแต่ละตำแหน่งที่ตั้งที่พาร์ทเนอร์ใช้ (เช่น "Branch ID", "Location Code", "Store Number") ดูข้อมูลเพิ่มเติม
first_name string จำเป็น

ชื่อจริงของสมาชิก
last_name string จำเป็น

นามสกุลของสมาชิก
email string ไม่บังคับ

ที่อยู่อีเมล
mobile_phone string ไม่บังคับ

หมายเลขโทรศัพท์มือถือในรูปแบบ E.123 (เช่น "+1 415 555 2671")
address object ไม่บังคับ

ออบเจ็กต์ที่อยู่ทางกายภาพซึ่งมีพร็อพเพอร์ตีต่อไปนี้:
- address_line_1 (string) - ที่อยู่บรรทัดหลัก
- address_line_2 (string, ไม่บังคับ) - ที่อยู่บรรทัดที่สอง
- city (string) - ชื่อเมือง
- state (string) - รหัสรัฐ/จังหวัด
- postal_code (string) - รหัสไปรษณีย์
- country (string) - รหัสประเทศ ISO 3166-1 alpha-2 (เช่น "AU", "US")
- country_name (string, ไม่บังคับ) - ชื่อประเทศแบบเต็ม
date_of_birth string ไม่บังคับ

วันเกิดในรูปแบบ YYYY-MM-DD
gender string ไม่บังคับ

เป็นค่าใดค่าหนึ่งต่อไปนี้ male, female, non_binary, prefer_not_to_say หรือ unknown
type string ไม่บังคับ

ประเภทสมาชิก (เช่น staff, member, prospect)
tags array ไม่บังคับ

สตริงหรือข้อความช่วยเหลือแบบย่อสำหรับจัดหมวดหมู่และระบุสมาชิกบางราย (เช่น ["vip", "personal-training", "student"])
membership_status string ไม่บังคับ

สถานะสมาชิกปัจจุบัน (เช่น active, expired, on_hold)
membership_plans array ไม่บังคับ

อาร์เรย์ของแผนสมาชิกที่เชื่อมโยงกับสมาชิก
profile_picture string ไม่บังคับ

รูปโปรไฟล์ที่เข้ารหัสแบบ Base64 (ไม่บังคับ)
created string ไม่บังคับ

การประทับเวลาแบบ ISO 8601 ของเวลาที่สร้างสมาชิก
updated string ไม่บังคับ

การประทับเวลาแบบ ISO 8601 ของเวลาที่อัปเดตสมาชิกครั้งล่าสุด
access_time_windows array ไม่บังคับ

สแนปช็อตที่สมบูรณ์ซึ่งแหล่งข้อมูลเป็นเจ้าของ ของ Access Time Windows แบบกำหนดวันเวลาแน่นอนและ/หรือแบบรายสัปดาห์ที่เกิดซ้ำ เว้นฟิลด์นี้ไว้เพื่อให้สแนปช็อตไม่เปลี่ยนแปลง หรือส่งอาร์เรย์ว่างพร้อมเวอร์ชันที่ใหม่กว่าเพื่อเพิกถอน ดูรูปแบบ การตรวจสอบความถูกต้อง การจับคู่ขอบเขต และหลักการแทนที่ได้ที่ Access Time Windows
access_time_windows_revision integer จำเป็นเมื่อมี access_time_windows

จำนวนเต็มที่ไม่ติดลบ ปลอดภัยสำหรับ JSON และเพิ่มขึ้นทางเดียว สำหรับสตรีมของสมาชิก/แหล่งข้อมูลนี้ จำเป็นทุกครั้งที่มี access_time_windows

ออบเจ็กต์ Member

{
  "member_id": "member_11111",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  // "linking_identifier": "branch_downtown",  // If using linking identifier
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "mobile_phone": "+61 412 345 678",
  "date_of_birth": "1985-06-15",
  "gender": "male",
  "type": "member",
  "tags": ["vip", "personal-training"],
  "profile_picture": "/9j/4AAQSkZJRgABAQAAAQ...",
  "membership_status": "current",
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-20T14:45:00Z",
  "access_time_windows_revision": 1842,
  "access_time_windows": [
    {
      "external_id": "access-4b1782",
      "kind": "absolute",
      "from": 1792053000,
      "to": 1792058400,
      "timezone": "Australia/Perth",
      "scope_key": "after_hours_entry",
      "label": "Temporary site access"
    }
  ],
  "address": {
    "address_line_1": "456 Bourke Street",
    "address_line_2": "Apt 12",
    "city": "Melbourne",
    "state": "VIC",
    "postal_code": "3000",
    "country": "AU",
    "country_name": "Australia"
  },
  "membership_plans": [
    {
      "membership_plan_id": "plan_99999",
      "name": "Unlimited Monthly",
      "start_date": "2024-01-01T00:00:00Z",
      "status": "current",
      "is_current": true,
      "end_date": null
    }
  ]
}

ช่วงเวลาการเข้าถึง

Access Time Windows ช่วยให้สมาชิกของพาร์ทเนอร์มีสิทธิ์การเข้าถึงชั่วคราวหรือแบบเกิดซ้ำที่ส่งมาจากระบบภายนอก หน้านี้เป็นคู่มือผู้ส่งข้อมูลฉบับทางการสำหรับ access_time_windows และ access_time_windows_revision

Access Time Windows เป็นสิทธิ์แบบเพิ่มเติมที่ใช้อนุญาตเท่านั้น ช่วงเวลาที่ใช้งานอยู่สามารถอนุญาตการเข้าถึงได้ แต่ช่วงเวลาที่ไม่ได้ใช้งาน หมดอายุ ข้อมูลเก่า หรือไม่ได้จับคู่ไว้ จะไม่ปฏิเสธการเข้าถึงที่กฎปกติหรือสิทธิ์แบบถาวรอนุญาตไว้แล้ว การปิดใช้งานผู้ใช้ การบล็อกประตูอย่างชัดเจน โหมดบำรุงรักษา Geofence การจำกัดอัตรา และความพร้อมใช้งานของตัวควบคุมยังคงมีผลอยู่

การพัฒนาสำหรับระบบต้นทางแต่ละระบบเป็นอะแดปเตอร์ที่แยกจากกัน อะแดปเตอร์ต้องแปลงข้อมูลต้นทางให้เป็นไปตามข้อตกลงที่ไม่ผูกกับผู้ให้บริการรายใดนี้ โดยไม่เปลี่ยนความหมายของฟิลด์

ฟิลด์สแนปช็อตของสมาชิก

access_time_windows array ไม่บังคับ

สแนปช็อต Access Time Window ที่สมบูรณ์สำหรับสมาชิกและแหล่งข้อมูลของพาร์ทเนอร์รายนี้ สแนปช็อตหนึ่งสามารถมีทั้งช่วงเวลาแบบ absolute และ weekly ผสมกัน เว้นฟิลด์นี้ไว้เพื่อให้สแนปช็อตที่จัดเก็บไว้ไม่เปลี่ยนแปลง หรือส่ง [] เพื่อเพิกถอนทุกช่วงเวลาที่แหล่งข้อมูลนี้เป็นเจ้าของ
access_time_windows_revision integer จำเป็นเมื่อมี access_time_windows

จำนวนเต็มที่ไม่ติดลบ ปลอดภัยสำหรับ JSON และเพิ่มขึ้นทางเดียว สำหรับสตรีมเวอร์ชันของสมาชิก/แหล่งข้อมูลนี้ จำเป็นทุกครั้งที่มี access_time_windows และต้องไม่เกิน 9007199254740991

แต่ละสแนปช็อตรองรับช่วงเวลาได้สูงสุด 50 รายการ external_id, scope_key และ label รองรับได้สูงสุด 120 อักขระ ช่วงเวลาแบบกำหนดวันเวลาแน่นอนครอบคลุมได้สูงสุด 90 วัน แต่ละวันในช่วงเวลาแบบรายสัปดาห์รองรับบล็อกที่ไม่ทับซ้อนกันได้สูงสุดแปดบล็อก ข้อมูลที่ไม่ถูกต้องจะถูกปฏิเสธ แทนที่จะถูกตัดทอนหรือคาดเดา

รูปแบบของช่วงเวลา

ช่วงเวลาแบบกำหนดวันเวลาแน่นอน (absolute) ระบุช่วงเวลาที่แน่นอนหนึ่งช่วง:

ตัวอย่างคำขอแบบผสมที่สมบูรณ์

คำขอนี้จะแทนที่สแนปช็อตเดิมของสมาชิกที่แหล่งข้อมูลเป็นเจ้าของ ด้วยช่วงเวลาแบบกำหนดวันเวลาแน่นอนหนึ่งช่วงและแบบรายสัปดาห์หนึ่งช่วง:

กฎเกี่ยวกับเวลาและขอบเขต

from, to, active_from และ active_until เป็นจำนวนเต็มวินาที Unix แบบ JSON ที่ระบุเวลา UTC:

ส่งเป็นจำนวนเต็ม JSON ที่ไม่มีเครื่องหมายคำพูด สตริงตัวเลข ทศนิยม สตริง RFC 3339 และมิลลิวินาที Unix จะถูกปฏิเสธ
ทุกช่วงเวลาเป็นแบบครึ่งเปิด: [from, to) การเข้าถึงเริ่มต้นได้ตรงเวลา from พอดี และสิ้นสุดการใช้งานตรงเวลา to พอดี
from ต้องน้อยกว่า to เมื่อมีขอบเขตรายสัปดาห์ทั้งสองค่า active_from ต้องน้อยกว่า active_until
อย่าคำนวณ epoch จากวันที่/เวลาท้องถิ่นที่ไม่มีเขตเวลา ให้แปลงเวลาต้นทางเป็นเวลา UTC ก่อน แล้วจึงหารมิลลิวินาที Unix ด้วย 1000 และตรวจสอบว่าผลลัพธ์เป็นจำนวนเต็ม

เขตเวลาและเวลาออมแสง

timezone ต้องเป็นเขตเวลา IANA ที่ถูกต้อง เช่น UTC, Australia/Perth หรือ America/New_York หากเว้นไว้ ค่าเริ่มต้นคือ UTC

ช่วงเวลาแบบกำหนดวันเวลาแน่นอน: from และ to ระบุเวลา UTC ที่แน่นอนอยู่แล้ว timezone เป็นเพียงข้อมูลเมตาสำหรับการแสดงผลและการตรวจสอบ การเปลี่ยนค่านี้จะไม่เลื่อนเวลาใดเวลาหนึ่ง
ช่วงเวลาแบบรายสัปดาห์: timezone กำหนดนาฬิกาท้องถิ่นและกฎเวลาออมแสงที่ใช้ประเมิน access_hours อย่าแปลงบล็อกรายสัปดาห์เป็น UTC ล่วงหน้า
ระหว่างการปรับเวลาเดินหน้า เวลาท้องถิ่นที่เขตเวลาข้ามไปจะไม่เกิดขึ้น
ระหว่างการปรับเวลาถอยหลัง เวลาจริงทั้งสองช่วงที่มีเวลาท้องถิ่นซ้ำกันจะตรงกับบล็อกรายสัปดาห์
active_from และ active_until ยังคงเป็นเวลา UTC แม้ช่วงเวลาแบบรายสัปดาห์จะใช้เขตเวลาที่ไม่ใช่ UTC

access_hours ใช้ค่าตัวพิมพ์เล็ก sun ถึง sat แต่ละค่าเป็นอาร์เรย์ของคู่ [start, end] ในรูปแบบ HH:mm แบบ 24 ชั่วโมงที่เติมศูนย์ข้างหน้า บล็อกต้องไม่ว่าง เรียงลำดับ และไม่ทับซ้อนกัน end ไม่รวมอยู่ในช่วง บล็อกไม่สามารถข้ามเที่ยงคืนได้ ให้แยกช่วงเวลาข้ามคืนของต้นทางเป็นบล็อกช่วงดึกในวันแรกและบล็อกช่วงเช้าในวันถัดไป

ID ที่คงที่และการจับคู่ขอบเขต

external_id ต้องคงที่ตลอดอายุของช่วงเวลาเชิงตรรกะ และไม่ซ้ำกันภายในสแนปช็อตของสมาชิก รักษาค่าให้คงที่เมื่อเวลาหรือป้ายกำกับเปลี่ยนแปลง เพื่อให้ผู้ปฏิบัติงานและบันทึกการตรวจสอบเชื่อมโยงเวอร์ชันต่าง ๆ ได้ อย่านำกลับมาใช้กับช่วงเวลาที่ไม่เกี่ยวข้อง

scope_key คือเป้าหมายการเข้าถึงเชิงตรรกะที่คงที่ของคุณ ค่าเริ่มต้นคือ default ผู้ดูแลระบบของสถานที่จะจับคู่คีย์ที่อนุญาตแต่ละรายการกับเป้าหมายใน Performance Hub ได้แก่ ทั้งสถานที่ ประตู หรือขอบเขตการเข้าถึง:

สแนปช็อตที่สมบูรณ์และเวอร์ชัน

ให้ถือว่าฟิลด์ทั้งสองเป็นพาร์ทิชันที่กำหนดเวอร์ชันแยกต่างหากภายใน upsert ของสมาชิก:

ข้อมูลนำเข้า	ผลลัพธ์
เว้น `access_time_windows` ไว้	สแนปช็อตที่มีอยู่ไม่เปลี่ยนแปลง ไม่ต้องระบุเวอร์ชัน
มีค่าพร้อมเวอร์ชันที่ใหม่กว่า	สแนปช็อตที่จัดเก็บไว้ทั้งหมดของสมาชิก/แหล่งข้อมูลนี้ถูกแทนที่
เวอร์ชันเดิมและเพย์โหลดที่ปรับให้เป็นมาตรฐานแล้วเหมือนเดิม	การส่งซ้ำแบบ Idempotent สแนปช็อตไม่เปลี่ยนแปลง
เวอร์ชันเดิมแต่เพย์โหลดที่ปรับให้เป็นมาตรฐานแล้วต่างกัน	ความขัดแย้ง ให้จัดสรรเวอร์ชันใหม่หลังจากกระทบยอด
เวอร์ชันที่เก่ากว่า	สแนปช็อตเก่าจะถูกข้าม และไม่สามารถเขียนทับสถานะที่ใหม่กว่าได้
`access_time_windows: []` พร้อมเวอร์ชันที่ใหม่กว่า	เพิกถอนช่วงเวลาทั้งหมดที่แหล่งข้อมูลเป็นเจ้าของอย่างชัดเจน

สแนปช็อตเป็นข้อมูลที่สมบูรณ์ ไม่ใช่การแก้ไขบางส่วน หากเวอร์ชัน 1842 มีช่วงเวลา A และ B แล้วเวอร์ชัน 1843 มีเพียง B ช่วงเวลา A จะถูกนำออก

ดูแลสตรีมเวอร์ชันที่ประสานกันเพียงสตรีมเดียวต่อพาร์ทเนอร์/สมาชิก ครอบคลุมเวิร์กเกอร์ webhook การโพล การส่งซ้ำ และการกระทบยอดแบบเต็ม แนะนำให้ใช้ลำดับเลขในฐานข้อมูลที่คงทน ค่ามิลลิวินาที Unix ใช้เป็นเวอร์ชันได้ก็ต่อเมื่อผู้เขียนทุกรายประสานงานกันและรับประกันลำดับและความไม่ซ้ำกันอย่างเคร่งครัดเท่านั้น ค่านี้เป็นค่าเวอร์ชัน ไม่ใช่ฟิลด์ epoch

เก็บคำขอและเวอร์ชันที่แน่นอนไว้จนกว่าจะทราบผลการตอบกลับของ API ลองส่งสแนปช็อตที่ปรับให้เป็นมาตรฐานเดิมซ้ำด้วยเวอร์ชันเดิมหลังจากหมดเวลาหรือเกิดข้อผิดพลาดชั่วคราว อย่าจัดสรรเวอร์ชันใหม่เพียงเพราะไม่แน่ใจว่าการรับส่งข้อมูลสำเร็จหรือไม่

การยกเลิก การหมดอายุ และความล้มเหลวของต้นทาง

ยกเลิกช่วงเวลาหนึ่งช่วง: ดึงสถานะจากแหล่งข้อมูลที่เชื่อถือได้ให้สำเร็จ นำช่วงเวลานั้นออก แล้วส่งสแนปช็อตที่สมบูรณ์ซึ่งเหลืออยู่พร้อมเวอร์ชันที่ใหม่กว่า
ยกเลิกทุกช่วงเวลา: ส่ง access_time_windows: [] พร้อมเวอร์ชันที่ใหม่กว่า
ปล่อยให้ช่วงเวลาแบบกำหนดวันเวลาแน่นอนหมดอายุ: ช่วงเวลาจะหยุดอนุญาตที่ to ให้ส่งการกระทบยอดในภายหลังโดยไม่มีรายการที่หมดอายุ เพื่อให้สแนปช็อตสะอาด
สิ้นสุดช่วงเวลาแบบรายสัปดาห์: นำออกในสแนปช็อตที่ใหม่กว่า หรือใช้ active_until เมื่อแหล่งข้อมูลทราบเวลาสิ้นสุดที่แน่นอน
การดึงข้อมูลจากต้นทางล้มเหลวหรือไม่ครบถ้วน: อย่าส่ง [] และอย่าเผยแพร่สแนปช็อตที่ไม่ครบถ้วน ให้แจ้งเตือนและลองดึงข้อมูลใหม่ การเปลี่ยนความล้มเหลวของต้นทางให้เป็นสแนปช็อตว่างคือการเพิกถอนสิทธิ์การเข้าถึงโดยไม่ตั้งใจ
คำขอ Partner API ไม่ผ่านการตรวจสอบความถูกต้อง: แก้ไขข้อมูลและส่งเวอร์ชันที่ใหม่กว่าเฉพาะเมื่อสแนปช็อตที่ปรับให้เป็นมาตรฐานเปลี่ยนแปลงเท่านั้น ลองใหม่สำหรับความล้มเหลวชั่วคราวด้วยเวอร์ชันเดิม

ความเป็นปัจจุบันของแหล่งข้อมูลกำหนดค่าแยกตามการผสานรวม ตามรอบการส่งข้อมูลและการกระทบยอดที่สัญญาไว้ ก่อนเปิดใช้งาน ให้ตกลงเรื่องอายุสูงสุดของข้อมูลต้นทาง สิ่งที่จะเกิดขึ้นเมื่อเกินอายุนั้น เกณฑ์การแจ้งเตือน และผู้ปฏิบัติงานจะรับทราบการพึ่งพาเพียงขอบเขตของแต่ละช่วงเวลาได้หรือไม่ ช่วงเวลาจากแหล่งข้อมูลที่เก่าจะไม่กลายเป็นกฎการปฏิเสธ กฎปกติและสิทธิ์แบบถาวรยังคงเป็นเส้นทางสำรอง

อัลกอริทึมของผู้ส่งข้อมูล

ใช้ขั้นตอนการทำงานที่ไม่ขึ้นกับภาษาโปรแกรมนี้สำหรับการอัปเดตสมาชิกทุกครั้ง:

รายการตรวจสอบการรับรอง

ทำการตรวจสอบเหล่านี้ให้ครบในสถานที่ระดับ stage โดยใช้การจับคู่ scope_key ฉบับสุดท้าย:

ช่วงเวลาแบบกำหนดวันเวลาแน่นอนที่ไม่ระบุเขตเวลาได้รับการยอมรับและประเมินเป็น UTC
ช่วงเวลาแบบกำหนดวันเวลาแน่นอนที่ใช้เขตเวลา IANA แบบกำหนดเองคงเวลา from/to เดิมไว้
ช่วงเวลาแบบรายสัปดาห์ที่ใช้เขตเวลา IANA แบบกำหนดเองเป็นไปตามเวลานาฬิกาท้องถิ่นตลอดการปรับเวลาเดินหน้าและถอยหลัง
สแนปช็อตแบบผสมระหว่างกำหนดวันเวลาแน่นอน/รายสัปดาห์แทนที่สแนปช็อตก่อนหน้าทั้งหมด
การเข้าถึงเริ่มต้นตรงเวลา from พอดีและหยุดตรงเวลา to พอดี และเวลาสิ้นสุดของบล็อกรายสัปดาห์ก็ไม่รวมอยู่ในช่วงเช่นกัน
การอัปเดตเวลาภายใต้ external_id เดิมพร้อมเวอร์ชันที่ใหม่กว่ามีผล
การเว้น access_time_windows ไว้จะเปลี่ยนฟิลด์อื่นของสมาชิกโดยไม่เปลี่ยนช่วงเวลา
การส่งเวอร์ชัน/เพย์โหลดเดิมซ้ำเป็นแบบ Idempotent
เวอร์ชันเดิม/เพย์โหลดต่างกันจะส่งคืนความขัดแย้งและไม่เปลี่ยนสแนปช็อต
เวอร์ชันที่เก่ากว่าซึ่งมาไม่ตามลำดับจะถูกรายงานว่าเก่า และไม่สามารถย้อนสถานะกลับได้
[] ที่ใหม่กว่าจะเพิกถอนช่วงเวลาที่แหล่งข้อมูลเป็นเจ้าของ ส่วนความล้มเหลวในการดึงข้อมูลจากต้นทางจะไม่ส่งสิ่งใดออกไป
scope_key ที่ไม่รู้จักหรือไม่ได้จับคู่ไว้จะไม่ให้สิทธิ์เข้าถึง และสร้างคำเตือนที่ผู้ปฏิบัติงานมองเห็นได้
การแจ้งเตือนอายุของข้อมูลต้นทางและนโยบายแหล่งข้อมูลเก่าที่กำหนดค่าไว้ทำงานตามเกณฑ์ที่ตกลงไว้
เส้นทาง webhook และการกระทบยอดแบบเต็มบรรจบกันที่สแนปช็อตและลำดับเวอร์ชันเดียวกัน
การส่งข้อมูลผ่านสตรีมไปถึง Door & Gate Access ภายในเป้าหมายที่ตกลงไว้
ช่วงเวลาที่ใช้งานอยู่สามารถอนุญาตประตูจริงที่จับคู่ไว้ได้ แต่ไม่สามารถข้ามการปิดใช้งานผู้ใช้ blockAllAccess การบำรุงรักษา หรือ Geofence ได้
ก่อน นอก และหลังช่วงเวลา กฎปกติและสิทธิ์แบบถาวรยังคงอนุญาตผู้ใช้ที่มีคุณสมบัติตามปกติ

{
  "external_id": "access-4b1782",
  "kind": "absolute",
  "from": 1792053000,
  "to": 1792058400,
  "timezone": "Australia/Perth",
  "scope_key": "after_hours_entry",
  "label": "Temporary site access"
}

ฟิลด์ที่จำเป็นคือ external_id, kind, from และ to ส่วน timezone, scope_key และ label ไม่บังคับ

ช่วงเวลาแบบรายสัปดาห์ (weekly) ระบุช่วงเวลาตามนาฬิกาท้องถิ่นที่เกิดซ้ำ ซึ่งอาจกำหนดขอบเขตด้วยเวลา UTC ได้:

{
  "external_id": "weekly-early-access",
  "kind": "weekly",
  "timezone": "America/New_York",
  "access_hours": {
    "sun": [],
    "mon": [["06:00", "08:30"]],
    "tue": [["06:00", "08:30"]],
    "wed": [["06:00", "08:30"]],
    "thu": [["06:00", "08:30"]],
    "fri": [["06:00", "08:30"]],
    "sat": []
  },
  "active_from": 1790812800,
  "active_until": 1796083200,
  "scope_key": "main_entry",
  "label": "Weekday early access"
}

ฟิลด์ที่จำเป็นคือ external_id, kind และ access_hours ส่วน timezone, active_from, active_until, scope_key และ label ไม่บังคับ

curl -X POST https://partner-api.performancehub.co/partner/v1/members \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      {
        "member_id": "member_11111",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "John",
        "last_name": "Smith",
        "access_time_windows_revision": 1842,
        "access_time_windows": [
          {
            "external_id": "access-4b1782",
            "kind": "absolute",
            "from": 1792053000,
            "to": 1792058400,
            "timezone": "Australia/Perth",
            "scope_key": "after_hours_entry",
            "label": "Temporary site access"
          },
          {
            "external_id": "weekly-early-access",
            "kind": "weekly",
            "timezone": "America/New_York",
            "access_hours": {
              "sun": [],
              "mon": [["06:00", "08:30"]],
              "tue": [["06:00", "08:30"]],
              "wed": [["06:00", "08:30"]],
              "thu": [["06:00", "08:30"]],
              "fri": [["06:00", "08:30"]],
              "sat": []
            },
            "active_from": 1790812800,
            "active_until": 1796083200,
            "scope_key": "main_entry",
            "label": "Weekday early access"
          }
        ]
      }
    ]
  }'

ใช้ facility_id หรือ linking_identifier อย่างใดอย่างหนึ่งตามวิธีการเชื่อมโยงที่คุณกำหนดค่าไว้ อย่าส่งทั้งสองค่า

การแปลง epoch

2026-10-15T08:30:00Z แปลงเป็น 1792053000:

UTC instant                 Unix milliseconds   Unix seconds sent
2026-10-15T08:30:00Z        1792053000000        1792053000

การแปลงที่ไม่ขึ้นกับภาษาโปรแกรม:

instant = parse_source_timestamp_with_explicit_zone(source_timestamp)
milliseconds = instant.to_unix_milliseconds()
assert milliseconds modulo 1000 equals 0
seconds = milliseconds / 1000
assert seconds is a JSON-safe nonnegative integer

หากแหล่งข้อมูลมีความละเอียดต่ำกว่าวินาที ให้กำหนดนโยบายการปัดเศษเวลาเริ่มต้น/สิ้นสุดอย่างชัดเจนก่อนการทดสอบการผสานรวม อย่าส่งเป็นมิลลิวินาทีแล้วพึ่งพาให้ API อนุมานหน่วยเอง

Partner scope_key           Performance Hub mapping
default                     Facility's configured default target
main_entry                  Access Scope "Main entrances"
after_hours_entry           Doors approved for after-hours entry

พาร์ทเนอร์ไม่ต้องส่ง ID ของสถานที่ ประตู หรือขอบเขตการเข้าถึงของ Performance Hub ภายในช่วงเวลา scope_key ที่ไม่รู้จัก ถูกปิดใช้งาน หรือไม่ได้จับคู่ไว้จะไม่ให้สิทธิ์เข้าถึง สำหรับช่วงเวลานั้น และจะไม่ขยายสิทธิ์การเข้าถึง ตกลงและทดสอบการจับคู่ก่อนเปิดตัว

function publish_member(member_key):
    source_result = fetch_authoritative_access_state(member_key)

    if source_result.failed or source_result.incomplete:
        record_failure(member_key)
        schedule_retry(member_key)
        return without sending access_time_windows

    windows = []
    for source_window in source_result.current_windows:
        if source_window.is_absolute:
            windows.append({
                external_id: stable_window_id(source_window),
                kind: "absolute",
                from: to_integer_unix_seconds(source_window.start_instant),
                to: to_integer_unix_seconds(source_window.end_instant),
                timezone: source_window.display_timezone or "UTC",
                scope_key: stable_scope_key(source_window) or "default",
                label: safe_label(source_window)
            })
        else:
            windows.append({
                external_id: stable_window_id(source_window),
                kind: "weekly",
                timezone: valid_iana_zone(source_window.timezone) or "UTC",
                access_hours: split_validate_and_sort_weekly_blocks(source_window),
                active_from: optional_integer_unix_seconds(source_window.active_start),
                active_until: optional_integer_unix_seconds(source_window.active_end),
                scope_key: stable_scope_key(source_window) or "default",
                label: safe_label(source_window)
            })

    normalized_snapshot = validate_sort_and_deduplicate(windows)
    revision = next_durable_member_revision(member_key)
    request = member_upsert_with(normalized_snapshot, revision)
    persist_for_retry(member_key, request)

    response = post_request(request)
    if response.is_transient_or_unknown:
        retry_exact_request_with_same_revision(request)
    else if response.is_revision_conflict:
        reconcile_with_latest_committed_source_state(member_key)
    else if response.is_stale_skip:
        stop_replaying_this_revision_and_reconcile(member_key)

เวกเตอร์ทดสอบขั้นต่ำ

[
  {
    "name": "absolute-half-open",
    "window": {
      "external_id": "tv-absolute",
      "kind": "absolute",
      "from": 1792053000,
      "to": 1792058400
    },
    "expect": {
      "1792052999": "inactive",
      "1792053000": "active",
      "1792058399": "active",
      "1792058400": "inactive"
    }
  },
  {
    "name": "weekly-dst",
    "window": {
      "external_id": "tv-weekly-dst",
      "kind": "weekly",
      "timezone": "America/New_York",
      "access_hours": {
        "sun": [["01:00", "03:30"]],
        "mon": [],
        "tue": [],
        "wed": [],
        "thu": [],
        "fri": [],
        "sat": []
      }
    },
    "expect": "Evaluate local wall time: skipped times do not occur; both repeated 01:30 instants qualify."
  }
]

ส่งเวกเตอร์เชิงลบสำหรับมิลลิวินาที Unix สตริงตัวเลข ทศนิยม เขตเวลา IANA ที่ไม่ถูกต้อง from >= to external_id ที่ซ้ำกัน บล็อกที่ทับซ้อนกัน บล็อกข้ามคืน บล็อกมากกว่าแปดบล็อกในหนึ่งวัน ช่วงเวลามากกว่า 50 รายการ และคีย์ขอบเขตที่ไม่ได้จับคู่ไว้ด้วย

บันทึกสมาชิก

สร้างหรืออัปเดตเรคคอร์ดสมาชิก API จะพิจารณาว่าจะสร้างหรืออัปเดตโดยอิงจาก member_id

พารามิเตอร์

members array จำเป็น

อาร์เรย์ของออบเจ็กต์ Member ที่จะบันทึก จำนวนสูงสุดที่แนะนำ: 1000 รายการต่อคำขอเพื่อประสิทธิภาพสูงสุด API จะแบ่งรายการเป็นกลุ่มเพื่อประมวลผลโดยอัตโนมัติ แต่ละรายการต้องมี facility_id (จำเป็นหากไม่ใช้ linking_identifier) หรือ linking_identifier (จำเป็นหากไม่ใช้ facility_id)

เมื่อสมาชิกมี access_time_windows ต้องมี access_time_windows_revision ด้วย อาร์เรย์นี้เป็นสแนปช็อตที่สมบูรณ์ของแหล่งข้อมูล ไม่ใช่การแก้ไขบางส่วน เว้นไว้เพื่อคงสแนปช็อตที่มีอยู่ หรือส่ง [] พร้อมเวอร์ชันที่ใหม่กว่าเพื่อเพิกถอนช่วงเวลาทั้งหมดที่แหล่งข้อมูลเป็นเจ้าของ โปรดอ่านคู่มือ Access Time Windows ก่อนเปิดใช้ฟิลด์นี้

ค่าที่ส่งคืน

ส่งคืนข้อความสั้น ๆ ที่ยืนยันการดำเนินการซิงค์

ฟิลด์โปรไฟล์ของสมาชิกยังคงเป็นการ upsert ตามปกติ แม้สแนปช็อตช่วงเวลาจะถูกรายงานว่าเป็นการส่งซ้ำแบบ Idempotent หรือถูกข้ามเพราะเป็นข้อมูลเก่า สแนปช็อตที่ขัดแย้งกัน (เวอร์ชันเดิม/เพย์โหลดต่างกัน) ไม่สามารถลองใหม่โดยไม่เปลี่ยนแปลงได้ ให้กระทบยอดสถานะของแหล่งข้อมูลแล้วส่งเวอร์ชันที่ใหม่กว่า

คำขอ

curl -X POST https://partner-api.performancehub.co/partner/v1/members \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      {
        "member_id": "member_11111",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        // "linking_identifier": "branch_downtown",  // If using linking identifier
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@example.com",
        "mobile_phone": "+61 412 345 678",
        "date_of_birth": "1985-06-15",
        "gender": "male",
        "type": "member",
        "tags": ["vip", "personal-training"],
        "profile_picture": "/9j/4AAQSkZJRgABAQAAAQ...",
        "membership_status": "current",
        "created": "2024-01-15T10:30:00Z",
        "updated": "2024-01-20T14:45:00Z",
        "access_time_windows_revision": 1842,
        "access_time_windows": [
          {
            "external_id": "access-4b1782",
            "kind": "absolute",
            "from": 1792053000,
            "to": 1792058400,
            "timezone": "Australia/Perth",
            "scope_key": "after_hours_entry",
            "label": "Temporary site access"
          }
        ],
        "address": {
          "address_line_1": "456 Bourke Street",
          "address_line_2": "Apt 12",
          "city": "Melbourne",
          "state": "VIC",
          "postal_code": "3000",
          "country": "AU",
          "country_name": "Australia"
        },
        "membership_plans": [
          {
            "membership_plan_id": "plan_99999",
            "name": "Unlimited Monthly",
            "start_date": "2024-01-01T00:00:00Z",
            "status": "current",
            "is_current": true,
            "end_date": null
          }
        ]
      }
    ]
  }'

การตอบกลับ

{
  "message": "Member sync successful.",
  "metadata": {
    "success": 245,
    "skipped": 5,
    "skipped_items": [
      {
        "member_id": "member_123",
        "facility_id": null,
        "reason": "Facility integration is disabled in facility-partner-config"
      }
    ]
  }
}

ฟิลด์ข้อมูลเมตา:

success - จำนวนสมาชิกที่ประมวลผลสำเร็จ
skipped - จำนวนสมาชิกที่ถูกข้าม (ถ้ามี)
skipped_items - อาร์เรย์ของสมาชิกที่ถูกข้ามพร้อมเหตุผล (ถ้ามี)
dry-run - แฟล็กบูลีนเมื่อใช้คีย์ประเภท dryrun (ถ้ามี)

การเช็กอิน

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

ปลายทาง

POST /partner/v1/check-ins - Save check-ins

ออบเจ็กต์ Check-In

แอตทริบิวต์

check_in_id string ไม่บังคับ

ตัวระบุเฉพาะของการเช็กอิน ไม่บังคับ หากไม่ระบุ ระบบจะสร้างให้อัตโนมัติจากคู่ของ member_id และ timestamp
member_id string จำเป็น

ตัวระบุเฉพาะของสมาชิก
facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุเฉพาะของสถานที่จาก Performance Hub
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ค่าตัวระบุเฉพาะของแต่ละตำแหน่งที่ตั้งที่พาร์ทเนอร์ใช้ (เช่น "Branch ID", "Location Code", "Store Number") ดูข้อมูลเพิ่มเติม
check_in_type string ไม่บังคับ

ประเภทของการเข้าใช้ เป็นค่าใดค่าหนึ่งต่อไปนี้ member, class, staff, guest หรือ trial
source string ไม่บังคับ

วิธีที่บันทึกการเช็กอิน ค่าที่ใช้บ่อย ได้แก่ manual, tag, rfid, kiosk, app และอาจใช้ค่าอื่นเพิ่มเติม เช่น door_reader หรือ booking ได้
class_id string ไม่บังคับ

ไม่บังคับ ใช้เมื่อเชื่อมโยงกับการจองหรือการเข้าร่วมคลาส
timestamp string จำเป็น

การประทับเวลาในรูปแบบ ISO 8601 ของเวลาที่เกิดการเช็กอิน

ออบเจ็กต์ Check-In

{
  // "check_in_id": "checkin_abc123",  // Optional - auto-generated from member_id + timestamp if not provided
  "member_id": "mem_12345",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  // "linking_identifier": "branch_downtown",  // If using linking identifier
  "check_in_type": "member",
  "source": "rfid",
  "timestamp": "2025-01-20T08:45:30Z"
}

บันทึกการเช็กอิน

สร้างเรคคอร์ดการเช็กอิน API จะตัดรายการซ้ำโดยอัตโนมัติตามสมาชิก สถานที่ และการประทับเวลา

พารามิเตอร์

check_ins array จำเป็น

อาร์เรย์ของออบเจ็กต์ Check-In ที่จะบันทึก จำนวนสูงสุดที่แนะนำ: 1000 รายการต่อคำขอเพื่อประสิทธิภาพสูงสุด API จะแบ่งรายการเป็นกลุ่มเพื่อประมวลผลโดยอัตโนมัติ แต่ละรายการต้องมี facility_id (จำเป็นหากไม่ใช้ linking_identifier) หรือ linking_identifier (จำเป็นหากไม่ใช้ facility_id)

ค่าที่ส่งคืน

ส่งคืนข้อความสั้น ๆ ที่ยืนยันการดำเนินการซิงค์

คำขอ

curl -X POST https://partner-api.performancehub.co/partner/v1/check-ins \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "check_ins": [
      {
        // "check_in_id": "checkin_abc123",  // Optional - auto-generated from member_id + timestamp if not provided
        "member_id": "mem_12345",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        // "linking_identifier": "branch_downtown",  // If using linking identifier
        "check_in_type": "member",
        "source": "rfid",
        "timestamp": "2025-01-20T08:45:30Z"
      }
    ]
  }'

การตอบกลับ

{
  "message": "Check-in sync successful.",
  "metadata": {
    "success": 523,
    "skipped": 3,
    "skipped_items": [
      {
        "member_id": "member_789",
        "facility_id": null,
        "reason": "No matching facility_id for the linking_identifier"
      }
    ]
  }
}

ฟิลด์ข้อมูลเมตา:

success - จำนวนการเช็กอินที่ประมวลผลสำเร็จ
skipped - จำนวนการเช็กอินที่ถูกข้าม (ถ้ามี)
skipped_items - อาร์เรย์ของการเช็กอินที่ถูกข้ามพร้อมเหตุผล (ถ้ามี)
dry-run - แฟล็กบูลีนเมื่อใช้คีย์ประเภท dryrun (ถ้ามี)

การควบคุมการเข้าถึง

Partner API สามารถสั่งงานฮาร์ดแวร์ Door/Gate Controller ของ Performance Hub สำหรับสถานที่ที่เปิดใช้การผสานรวมของคุณ

ใช้ API นี้เมื่อระบบจัดการสมาชิกของคุณได้ตัดสินแล้วว่าบุคคลนั้นได้รับอนุญาตให้เข้า Performance Hub ไม่ได้ประเมินสถานะสมาชิก ชั่วโมงการเข้าถึง กฎโซนประตู การตรวจสอบการฉ้อโกง หรือตรรกะการระงับสมาชิก ระบบของคุณยังคงเป็นผู้มีอำนาจในการตัดสินใจเหล่านั้น

คำขอปลดล็อกเป็นแบบซิงโครนัส Performance Hub จะส่งคำสั่งไปยังตัวควบคุมในสถานที่แบบเรียลไทม์ และจะส่งคืน 200 ก็ต่อเมื่ออุปกรณ์ยืนยันว่ารีเลย์ปลดล็อกทางกายภาพแล้วเท่านั้น การยืนยันส่วนใหญ่ควรเสร็จสิ้นภายใน 3-5 วินาที หากไม่ได้รับการยืนยันภายในช่วงเวลาหมดเวลา API จะส่งคืนความล้มเหลวอย่างชัดเจน

คุณยังสามารถบันทึกความพยายามในการเข้าถึงหรือการปฏิเสธที่ไม่ได้ไปถึงตัวควบคุมได้ด้วย การเรียกนั้นจะไม่ปลดล็อกประตู แต่จะเขียนเหตุการณ์ลงในบันทึกการเข้าถึงของ Door & Gate Access

ปลายทาง

GET /partner/v1/access-control/doors - List available Door/Gate Controllers
GET /partner/v1/access-control/doors/{door_id} - Get Door/Gate Controller status
POST /partner/v1/access-control/doors/{door_id}/unlock - Unlock a Door/Gate Controller
POST /partner/v1/access-control/doors/{door_id}/access-events - Record an access attempt or denial

ออบเจ็กต์ Door/Gate Controller

แอตทริบิวต์

door_id string จำเป็น

ตัวระบุเฉพาะของ Door/Gate Controller จัดเก็บค่านี้ไว้ในระบบของคุณหลังจากค้นพบ และใช้เมื่อเรียกปลายทางปลดล็อก
facility_id string จำเป็น

ID สถานที่ของ Performance Hub
linking_identifier string ไม่บังคับ

ตัวระบุสถานที่ของพาร์ทเนอร์ เมื่อการผสานรวมของคุณใช้ Linking Identifier ดูข้อมูลเพิ่มเติม
name string จำเป็น

ชื่ออุปกรณ์ที่มนุษย์อ่านได้ซึ่งกำหนดค่าไว้ใน Performance Hub
zone string ไม่บังคับ

โซนหรือตำแหน่งของประตู เช่น Entrance
status string จำเป็น

online หรือ offline
relay_state string ไม่บังคับ

สถานะรีเลย์ล่าสุดที่ทราบ เช่น locked หรือ unlocked
maintenance_mode string จำเป็น

โหมดบำรุงรักษาปัจจุบัน เป็นค่าใดค่าหนึ่งต่อไปนี้ off, force-open หรือ force-closed
hold_time_seconds integer จำเป็น

ระยะเวลาค้างการปลดล็อกเริ่มต้นที่กำหนดค่าไว้สำหรับประตู
last_seen string ไม่บังคับ

การประทับเวลาแบบ ISO ของการอัปเดตข้อมูลเมตาของอุปกรณ์ครั้งล่าสุด

ออบเจ็กต์ Door/Gate Controller

{
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "linking_identifier": "branch_downtown",
  "name": "Front Door",
  "zone": "Entrance",
  "status": "online",
  "online": true,
  "relay_state": "locked",
  "maintenance_mode": "off",
  "hold_time_seconds": 10,
  "last_seen": "2026-05-01T04:30:00.000Z"
}

แสดงรายการ Door/Gate Controller

ส่งคืน Door/Gate Controller ที่การผสานรวมของคุณใช้งานได้

หากไม่ได้ระบุทั้ง facility_id และ linking_identifier API จะส่งคืน Door/Gate Controller จากทุกสถานที่ที่เชื่อมโยงกับบัญชีพาร์ทเนอร์ของคุณ

Recommended: Include a facility identifier whenever possible. Requests without `facility_id` or `linking_identifier` may take longer to load for partners with hundreds or thousands of Door/Gate Controllers.

พารามิเตอร์

facility_id string ไม่บังคับ อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ID สถานที่ของ Performance Hub ใช้สำหรับการผสานรวมแบบ Direct Link
linking_identifier string ไม่บังคับ อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุสถานที่/ตำแหน่งที่ตั้งของคุณเอง ใช้เมื่อการผสานรวมของคุณกำหนดค่าให้ใช้ Linking Identifier

ค่าที่ส่งคืน

ส่งคืนอาร์เรย์ของออบเจ็กต์ Door/Gate Controller

คำขอ

curl -X GET "https://partner-api.performancehub.co/partner/v1/access-control/doors?facility_id=550e8400-e29b-41d4-a716-446655440000" \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

การตอบกลับ

{
  "data": [
    {
      "door_id": "00000000000000000000000000000007",
      "facility_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Front Door",
      "zone": "Entrance",
      "status": "online",
      "relay_state": "locked",
      "maintenance_mode": "off",
      "hold_time_seconds": 10,
      "last_seen": "2026-05-01T04:30:00.000Z"
    }
  ]
}

ดูสถานะของ Door/Gate Controller

ดึงสถานะล่าสุดที่ทราบและการกำหนดค่าพื้นฐานของ Door/Gate Controller หนึ่งตัว

ระบุตัวระบุสถานที่เพื่อให้ Performance Hub ตรวจสอบได้ว่าประตูเป็นของสถานที่ที่การผสานรวมของคุณเข้าถึงได้

พารามิเตอร์

door_id string จำเป็น

ID ของ Door/Gate Controller ที่ส่งคืนจากปลายทางแสดงรายการ
facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ID สถานที่ของ Performance Hub จำเป็นสำหรับการผสานรวมแบบ Direct Link
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุสถานที่ของพาร์ทเนอร์ จำเป็นสำหรับการผสานรวมแบบ Linking Identifier

ค่าที่ส่งคืน

ส่งคืนออบเจ็กต์ Door/Gate Controller

คำขอ

curl -X GET "https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007?facility_id=550e8400-e29b-41d4-a716-446655440000" \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

การตอบกลับ

{
  "data": {
    "door_id": "00000000000000000000000000000007",
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Front Door",
    "zone": "Entrance",
    "status": "online",
    "relay_state": "locked",
    "maintenance_mode": "off",
    "hold_time_seconds": 10,
    "last_seen": "2026-05-01T04:30:00.000Z"
  }
}

ปลดล็อก Door/Gate Controller

ส่งคำสั่งปลดล็อกไปยัง Door/Gate Controller และรอให้รีเลย์ทางกายภาพยืนยันว่าปลดล็อกแล้ว

ระบบของคุณต้องตัดสินว่าบุคคลนั้นได้รับอนุญาตหรือไม่ก่อนเรียกปลายทางนี้ Performance Hub จะตรวจสอบเฉพาะคีย์พาร์ทเนอร์ การเข้าถึงสถานที่ ความเป็นเจ้าของประตู และสถานะของอุปกรณ์เท่านั้น

พารามิเตอร์

door_id string จำเป็น

ID ของ Door/Gate Controller ที่ส่งคืนจากปลายทางแสดงรายการ
facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ID สถานที่ของ Performance Hub จำเป็นสำหรับการผสานรวมแบบ Direct Link
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุสถานที่ของพาร์ทเนอร์ จำเป็นสำหรับการผสานรวมแบบ Linking Identifier
member_id string จำเป็น

ID สมาชิกของพาร์ทเนอร์ ใช้สำหรับการบันทึกเพื่อการตรวจสอบและการเชื่อมโยงข้อมูลในภายหลัง
first_name string จำเป็น

ชื่อจริงของบุคคลที่เปิดประตู
last_name string จำเป็น

นามสกุลของบุคคลที่เปิดประตู
full_name string ไม่บังคับ

ไม่บังคับ หากเว้นไว้ Performance Hub จะรวม first_name และ last_name เข้าด้วยกัน
check_in_id string ไม่บังคับ

ID การเช็กอินจากระบบของคุณ (ไม่บังคับ) สำหรับการเชื่อมโยงข้อมูล
idempotency_key string ไม่บังคับ

คีย์ป้องกันการส่งซ้ำ (ไม่บังคับ) การใช้คีย์เดิมซ้ำสำหรับพาร์ทเนอร์ สถานที่ และประตูเดียวกันจะส่งคืนผลลัพธ์ที่มีอยู่เมื่อมี

ค่าที่ส่งคืน

ส่งคืน 200 ก็ต่อเมื่ออุปกรณ์ยืนยันว่ารีเลย์ปลดล็อกทางกายภาพแล้วเท่านั้น ประตูจะใช้ระยะเวลาค้างการปลดล็อกที่กำหนดค่าไว้ในการจัดการอุปกรณ์ของ Performance Hub พาร์ทเนอร์ไม่สามารถแทนที่ระยะเวลาของรีเลย์ในแต่ละคำขอได้ การยืนยันส่วนใหญ่ควรเสร็จสิ้นภายใน 3-5 วินาที ให้ถือว่าการหมดเวลาที่ระบุในเอกสารเป็นการปลดล็อกที่ล้มเหลวอย่างชัดเจน และลองใหม่ตามกฎด้านความปลอดภัยของคุณเองเท่านั้น

ความล้มเหลวที่พบบ่อย:

403 integration_not_enabled - ยังไม่ได้เปิดใช้การผสานรวมของคุณสำหรับสถานที่นั้น
409 maintenance_mode_active - เจ้าหน้าที่ของสถานที่เปิดใช้โหมดบำรุงรักษาสำหรับประตูนั้น
503 device_offline - Door/Gate Controller ออฟไลน์หรือข้อมูลไม่เป็นปัจจุบัน
504 unlock_confirmation_timeout - ส่งคำสั่งแล้วแต่ไม่ได้รับการยืนยันที่ตรงกันก่อนหมดเวลา

คำขอ

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/unlock \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "member_id": "mem_12345",
    "first_name": "Jane",
    "last_name": "S.",
    "full_name": "Jane S.",
    "source": "door_reader",
    "idempotency_key": "unlock_20260501_0001"
  }'

การตอบกลับ

{
  "status": "unlocked",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "command_id": "00000000-0000-0000-0000-000000000049",
  "hold_time_seconds": 10,
  "confirmed_at": "2026-05-01T04:30:00.000Z"
}

การตอบกลับเมื่อล้มเหลว

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

บันทึกความพยายามในการเข้าถึงหรือการปฏิเสธ

บันทึกความพยายามในการเข้าถึงหรือการปฏิเสธที่ระบบของคุณตัดสินไว้แล้ว ระบบจะไม่ติดต่อ Door/Gate Controller และประตูจะไม่ปลดล็อก

ใช้ปลายทางนี้เมื่อระบบของคุณปฏิเสธการเข้า หรือเมื่อต้องการให้ความพยายามปรากฏในบันทึกการเข้าถึงของ Door & Gate Access โดยไม่มีการปลดล็อก Performance Hub ไม่ได้ประเมินสถานะสมาชิก ชั่วโมงการเข้าถึง หรือกฎการเข้าถึงอื่น ๆ

เหตุการณ์ที่ถูกปฏิเสธจะปรากฏในบันทึกการเข้าถึงของ Door & Gate Access พร้อมผลลัพธ์ Denied ชื่อพาร์ทเนอร์ของคุณ ประตู ตัวระบุสมาชิกเมื่อคุณส่งมา และรหัสเหตุผลในรูปแบบที่อ่านได้ ตัวอย่างเช่น membership_expired จะแสดงเป็น "Membership Expired" ระบบจะจัดเก็บ reason_display_text และ user_email ไว้พร้อมกับเหตุการณ์

พารามิเตอร์

door_id string จำเป็น

ID ของ Door/Gate Controller ที่ส่งคืนจากปลายทางแสดงรายการ
facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ID สถานที่ของ Performance Hub จำเป็นสำหรับการผสานรวมแบบ Direct Link
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุสถานที่ของพาร์ทเนอร์ จำเป็นสำหรับการผสานรวมแบบ Linking Identifier
outcome string จำเป็น

denied หรือ attempted
reason string ไม่บังคับ

รหัสเหตุผลแบบ snake_case ตัวพิมพ์เล็ก ยาวไม่เกิน 64 อักขระ จำเป็นเมื่อ outcome เป็น denied ตัวอย่าง: membership_expired
reason_display_text string ไม่บังคับ

เหตุผลที่มนุษย์อ่านได้ ยาวไม่เกิน 256 อักขระ ตัวอย่าง: Membership expired on 2026-04-01
member_id string ไม่บังคับ

ID สมาชิกของพาร์ทเนอร์ ให้เว้นไว้เมื่อข้อมูลประจำตัวไม่ตรงกับสมาชิกรายใด เช่น บัตรที่ไม่รู้จัก
user_email string ไม่บังคับ

อีเมลของบุคคลที่พยายามเข้าถึง
timestamp string ไม่บังคับ

เวลาที่เกิดความพยายาม ในรูปแบบ ISO 8601 พร้อมเขตเวลา ตัวอย่าง: 2026-05-18T10:15:30Z ค่าเริ่มต้นคือเวลาที่ได้รับคำขอ ต้องไม่เป็นเวลาในอนาคตเกิน 5 นาที หรือย้อนหลังเกิน 30 วัน
idempotency_key string ไม่บังคับ

คีย์ป้องกันการส่งซ้ำ ยาวไม่เกิน 128 อักขระ การใช้คีย์เดิมซ้ำสำหรับพาร์ทเนอร์ สถานที่ และประตูเดียวกันจะส่งคืนผลลัพธ์เดิม

ค่าที่ส่งคืน

ส่งคืน 201 เมื่อบันทึกเหตุการณ์แล้ว การส่ง idempotency_key เดิมซ้ำจะส่งคืน 200 โดยตั้งค่า idempotent เป็น true และไม่สร้างเหตุการณ์ใหม่

คีย์ dry-run จะส่งคืน 200 โดยตั้งค่า dry_run เป็น true และจะไม่มีการบันทึกใด ๆ

ความล้มเหลวที่พบบ่อย:

400 - เนื้อหาคำขอไม่ถูกต้อง การปฏิเสธไม่มี reason การประทับเวลาอยู่นอกช่วง หรือ facility_id / linking_identifier ไม่ตรงกับสถานที่ที่เชื่อมโยงไว้
403 - คีย์เป็นแบบอ่านอย่างเดียว
403 integration_not_enabled - ยังไม่ได้เปิดใช้การผสานรวมของคุณสำหรับสถานที่นั้น message จะระบุเหตุผล
404 - ไม่พบ Door/Gate Controller สำหรับสถานที่ที่เชื่อมโยงไว้

คำขอ

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/access-events \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "outcome": "denied",
    "reason": "membership_expired",
    "reason_display_text": "Membership expired on 2026-04-01",
    "member_id": "mem_12345",
    "user_email": "member@example.com",
    "timestamp": "2026-05-18T10:15:30Z",
    "idempotency_key": "evt_abc12345"
  }'

การตอบกลับ

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z"
}

การส่งซ้ำแบบ Idempotent

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z",
  "idempotent": true
}

รายงานของสถานที่

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

ปลายทาง

POST /partner/v1/report-snapshots - Save report snapshots

ออบเจ็กต์ Report Snapshot

แอตทริบิวต์

facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ตัวระบุเฉพาะของสถานที่จาก Performance Hub
linking_identifier string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

ค่าตัวระบุเฉพาะของแต่ละตำแหน่งที่ตั้งที่พาร์ทเนอร์ใช้ (เช่น "Branch ID", "Location Code", "Store Number") ดูข้อมูลเพิ่มเติม
start_date string จำเป็น

วันที่เริ่มต้นของช่วงเวลาสแนปช็อตในรูปแบบ YYYY-MM-DD
end_date string จำเป็น

วันที่สิ้นสุดของช่วงเวลาสแนปช็อตในรูปแบบ YYYY-MM-DD
metrics object จำเป็น

ออบเจ็กต์เมตริกที่มีข้อมูลสมาชิกและรายได้ของช่วงเวลานั้น

ออบเจ็กต์ Report Snapshot

{
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  // "linking_identifier": "branch_downtown",  // If using linking identifier
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "metrics": {
    "members": {
      "active": 1200,
      "new": 45,
      "cancelled": 12
    },
    "revenue": {
      "total_payments": 289000.00,
      "total_payments_count": 1200,
      "currency": "AUD"
    }
  }
}

บันทึกสแนปช็อตรายงาน

ส่งเมตริกด้านการดำเนินงานและการเงินของสถานที่ในช่วงเวลาที่กำหนด

พารามิเตอร์

snapshots array จำเป็น

อาร์เรย์ของออบเจ็กต์ Report Snapshot ที่จะบันทึก สูงสุด 25 รายการต่อคำขอ แต่ละรายการต้องมี facility_id (จำเป็นหากไม่ใช้ linking_identifier) หรือ linking_identifier (จำเป็นหากไม่ใช้ facility_id)

ค่าที่ส่งคืน

ส่งคืนข้อความสั้น ๆ ที่ยืนยันการดำเนินการซิงค์

คำขอ

curl -X POST https://partner-api.performancehub.co/partner/v1/report-snapshots \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "snapshots": [
      {
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        // "linking_identifier": "branch_downtown",  // If using linking identifier
        "start_date": "2025-01-01",
        "end_date": "2025-01-31",
        "metrics": {
          "members": {
            "active": 1200,
            "new": 45,
            "cancelled": 12
          },
          "revenue": {
            "total_payments": 289000.00,
            "currency": "AUD"
          }
        }
      }
    ]
  }'

การตอบกลับ

{
  "message": "Report snapshot sync successful."
}

ข้อผิดพลาด

Partner API ใช้รหัสสถานะ HTTP มาตรฐานและเนื้อหาการตอบกลับแบบ JSON เพื่ออธิบายสาเหตุที่คำขอล้มเหลว

รูปแบบการตอบกลับข้อผิดพลาด

ข้อผิดพลาดของ API ส่วนใหญ่จะส่งคืนเนื้อหา JSON ที่มีข้อความ และรายละเอียดแบบมีโครงสร้างหากมี

รหัสสถานะ

ความล้มเหลวของ Access Time Window

การตรวจสอบความถูกต้องของช่วงเวลาจะล้มเหลวก่อนที่สแนปช็อตที่ไม่ถูกต้องจะถูกเขียน สาเหตุที่พบบ่อยซึ่งลองใหม่ไม่ได้ ได้แก่:

ไม่มี access_time_windows_revision เมื่อมี access_time_windows
ค่า epoch ที่เป็นสตริง ทศนิยม หรือมีแนวโน้มว่าเป็นมิลลิวินาที
เขตเวลา IANA ที่ไม่ถูกต้อง ช่วงเวลาที่กลับด้าน external_id ซ้ำ บล็อกรายสัปดาห์ที่ทับซ้อนกัน หรือบล็อกข้ามคืนที่ไม่ได้แยกออก
ค่าที่อยู่นอกขีดจำกัดด้านจำนวน ความยาว หรือช่วงเวลาที่ระบุไว้ในเอกสาร

เวอร์ชันซ้ำที่มีเนื้อหาที่ปรับให้เป็นมาตรฐานแล้วแตกต่างกันจะเป็น 409 Conflict ให้กระทบยอดกับสถานะล่าสุดที่เชื่อถือได้และจัดสรรเวอร์ชันที่ใหม่กว่า อย่าลองส่งคู่ที่ขัดแย้งกันซ้ำ เวอร์ชันที่เก่ากว่าจะถูกรายงานเป็นสแนปช็อตเก่าที่ถูกข้าม แทนที่จะได้รับอนุญาตให้เขียนทับสถานะที่ใหม่กว่า scope_key ที่ไม่รู้จักหรือไม่ได้จับคู่ไว้จะไม่ให้สิทธิ์เข้าถึง สำหรับการให้สิทธิ์ และควรถือเป็นการแจ้งเตือนด้านการกำหนดค่า

หากการส่งหมดเวลาหรือได้รับ 5xx ชั่วคราว ให้ลองส่งสแนปช็อตที่ปรับให้เป็นมาตรฐานเดิมทุกประการซ้ำด้วยเวอร์ชันเดิม หากการดึงข้อมูลจากต้นทางล้มเหลว ให้เว้นฟิลด์ช่วงเวลาไว้ทั้งหมด อย่าแทนที่ด้วยอาร์เรย์ว่างเด็ดขาด

คำแนะนำในการลองใหม่

ลองใหม่สำหรับกรณีต่อไปนี้ด้วยการเว้นระยะแบบเอ็กซ์โพเนนเชียลที่จำกัดจำนวนครั้ง:

429
500
502
503
504

อย่าลองใหม่โดยไม่ไตร่ตรองสำหรับกรณีต่อไปนี้:

400
401
403
404
409
422

สำหรับการควบคุมการเข้าถึง ให้ถือว่าการตอบกลับที่หมดเวลาและออฟไลน์เป็นการปลดล็อกที่ล้มเหลวเสมอ เว้นแต่กฎการเข้าถึงและกระบวนการด้านความปลอดภัยของคุณเองจะระบุไว้เป็นอย่างอื่น

รายละเอียดที่ควรระบุเมื่อติดต่อฝ่ายสนับสนุน

เมื่อติดต่อฝ่ายสนับสนุน ให้ระบุ:

ปลายทางและเมธอด HTTP
การประทับเวลาและเขตเวลา
ID ของคีย์พาร์ทเนอร์ ไม่ใช่คีย์ลับ
ตัวระบุสถานที่ที่ใช้
ID ของเรคคอร์ดต้นทางจากระบบของคุณ
สถานะและเนื้อหาของการตอบกลับ
event_id หรือ command_id หากมี

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

ปลายทางเฉพาะโดเมนบางรายการจะส่งคืนสถานะและเหตุผลอย่างชัดเจน ตัวอย่างเช่น ความล้มเหลวของการควบคุมการเข้าถึงจะมีฟิลด์ต่าง ๆ เช่น reason, door_id, facility_id และ event_id

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

400 Bad Request

คำขอมีรูปแบบไม่ถูกต้องหรือไม่มีฟิลด์ที่จำเป็น แก้ไขคำขอก่อนลองใหม่

401 Unauthorized

การยืนยันตัวตนล้มเหลว ตรวจสอบว่าคุณใช้ HTTP Basic Auth โดยใช้คีย์ลับของ API เป็นชื่อผู้ใช้และเว้นรหัสผ่านว่างไว้

403 Forbidden

คีย์ถูกต้องแต่ไม่อนุญาตให้ดำเนินการนี้ สาเหตุที่พบบ่อย ได้แก่ การใช้คีย์แบบอ่านอย่างเดียวสำหรับการดำเนินการเขียน หรือการพยายามเข้าถึงสถานที่ที่ไม่ได้เปิดใช้การผสานรวมของคุณ

404 Not Found

ไม่พบทรัพยากรที่ร้องขอ หรือทรัพยากรนั้นไม่พร้อมให้การผสานรวมของคุณใช้งาน

409 Conflict

คำขอขัดแย้งกับสถานะปัจจุบันของทรัพยากร สำหรับการควบคุมการเข้าถึง อาจรวมถึงกรณีที่ Door/Gate Controller อยู่ในโหมดบำรุงรักษา

422 Unprocessable Entity

คำขอเป็น JSON ที่ถูกต้องแต่ไม่ผ่านการตรวจสอบความถูกต้องเชิงความหมาย แก้ไขข้อมูลก่อนลองใหม่

429 Too Many Requests

การผสานรวมเกินขีดจำกัดอัตราการเรียกใช้ที่ระบุไว้ในเอกสาร ลองใหม่โดยใช้การเว้นระยะแบบเอ็กซ์โพเนนเชียล

500 Internal Server Error

Performance Hub ไม่สามารถดำเนินการตามคำขอได้เนื่องจากข้อผิดพลาดภายใน ลองใหม่โดยเว้นระยะ หากปัญหายังคงอยู่ ให้ติดต่อฝ่ายสนับสนุนพร้อมระบุปลายทาง การประทับเวลา และเนื้อหาการตอบกลับ

503 Service Unavailable

บริการหรืออุปกรณ์ที่เกี่ยวข้องไม่พร้อมใช้งาน สำหรับการปลดล็อก Door/Gate Controller อาจหมายความว่าตัวควบคุมออฟไลน์

504 Gateway Timeout

การดำเนินการหมดเวลา สำหรับการปลดล็อก Door/Gate Controller หมายความว่าการปลดล็อกไม่ได้รับการยืนยันก่อนหมดช่วงเวลาที่กำหนด

การกำหนดเวอร์ชัน

Partner API กำหนดเวอร์ชันไว้ใน URL เวอร์ชันปัจจุบันคือ:

นโยบายการเปลี่ยนแปลง

Performance Hub มุ่งทำการเปลี่ยนแปลงแบบเพิ่มเติมที่เข้ากันได้กับเวอร์ชันก่อนหน้าทุกครั้งที่ทำได้

ตัวอย่างการเปลี่ยนแปลงที่เข้ากันได้กับเวอร์ชันก่อนหน้า:

การเพิ่มฟิลด์ใหม่แบบไม่บังคับในคำขอ
การเพิ่มฟิลด์ใหม่ในการตอบกลับ
การเพิ่มปลายทางใหม่
การเพิ่มค่า enum ใหม่ในกรณีที่ไคลเอนต์ควรรองรับค่าที่ไม่รู้จัก
การปรับปรุงข้อความการตรวจสอบความถูกต้องโดยไม่เปลี่ยนข้อตกลงของรหัสสถานะ

access_time_windows และ access_time_windows_revision เป็นฟิลด์คำขอของ Member แบบเพิ่มเติม ไคลเอนต์ที่มีอยู่ซึ่งไม่ส่งฟิลด์เหล่านี้จะคงสแนปช็อต Access Time Window ที่จัดเก็บไว้โดยไม่เปลี่ยนแปลง กฎการเว้นค่านี้รักษาความเข้ากันได้ของการ upsert บางส่วน การเว้นค่าไม่เทียบเท่ากับการส่งอาร์เรย์ว่าง

ตัวอย่างการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากัน:

การนำฟิลด์ออกหรือเปลี่ยนชื่อฟิลด์
การเปลี่ยนประเภทของฟิลด์
การเปลี่ยนฟิลด์คำขอที่ไม่บังคับให้เป็นฟิลด์ที่จำเป็น
การนำปลายทางออก
การเปลี่ยนความหมายของรหัสสถานะที่มีอยู่หรือ reason เฉพาะโดเมน

การเลิกใช้งาน

เมื่อจำเป็นต้องมีการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากัน Performance Hub จะหลีกเลี่ยงการเปลี่ยนแปลงเวอร์ชันที่มีอยู่โดยตรงเท่าที่ทำได้ แต่จะเปิดตัวเวอร์ชันใหม่หรือแนวทางการย้ายระบบ และแจ้งการเปลี่ยนแปลงให้พาร์ทเนอร์ที่ได้รับผลกระทบทราบ

ประกาศการเลิกใช้งานอาจรวมถึง:

รายการในบันทึกการเปลี่ยนแปลง
การสื่อสารกับพาร์ทเนอร์โดยตรง
หมายเหตุใน Partner Console
คำแนะนำการย้ายระบบในเอกสาร

คำแนะนำสำหรับไคลเอนต์

สร้างไคลเอนต์ที่รองรับการเปลี่ยนแปลงแบบเพิ่มเติมได้:

ละเว้นฟิลด์การตอบกลับที่คุณไม่ได้ใช้
ถือว่าค่า enum ที่ไม่รู้จักเป็นค่าที่ไม่รองรับ แทนที่จะทำให้ระบบขัดข้อง
หลีกเลี่ยงการตรวจสอบการตอบกลับว่าตรงกันทุกประการอย่างเคร่งครัด
บันทึกค่าที่ไม่รู้จักไว้เพื่อให้คุณอัปเดตการผสานรวมได้อย่างตั้งใจ

สำหรับพาร์ทิชันของ Member ที่มีการกำหนดเวอร์ชัน เช่น Access Time Windows ให้เก็บเวอร์ชันและเพย์โหลดที่ปรับให้เป็นมาตรฐานที่ส่งไปไว้จนกว่าจะทราบผลลัพธ์ การใช้เวอร์ชันเดิมซ้ำกับเนื้อหาที่เปลี่ยนแปลงถือเป็นความขัดแย้ง ส่วนการส่งเนื้อหาเดิมซ้ำเป็นแบบ Idempotent ดู Access Time Windows

ข้อกำหนด OpenAPI

ใช้ข้อกำหนด OpenAPI ที่เผยแพร่เพื่อสร้างไคลเอนต์ ตรวจสอบความถูกต้องของคำขอ และติดตามการเปลี่ยนแปลงโครงสร้างของ API เมื่อเวลาผ่านไป

ดูข้อกำหนด OpenAPI

https://partner-api.performancehub.co/partner/v1/

บันทึกการเปลี่ยนแปลง

บันทึกการเปลี่ยนแปลงนี้รวบรวมการเปลี่ยนแปลงที่สำคัญของ Partner API และ Partner Console ที่ส่งผลต่อการทำงานของการผสานรวม

2026-09-09

2026-05-06

2026-05-01

หมวดหมู่การเปลี่ยนแปลง

รายการในอนาคตจะใช้หมวดหมู่เหล่านี้:

เพิ่มใหม่ (Added) - ปลายทาง ฟิลด์ คู่มือ หรือความสามารถใหม่
เปลี่ยนแปลง (Changed) - มีการเปลี่ยนแปลงการทำงานหรือเอกสารโดยไม่ยกเลิกการรองรับ
เลิกใช้งาน (Deprecated) - ฟีเจอร์ยังคงใช้งานได้ แต่มีแผนการย้ายไปใช้สิ่งอื่น
นำออก (Removed) - นำฟีเจอร์หรือปลายทางออกแล้ว
แก้ไข (Fixed) - แก้ไขข้อบกพร่องหรือแก้ไขเอกสาร
ความปลอดภัย (Security) - การเปลี่ยนแปลงด้านการยืนยันตัวตน การให้สิทธิ์ การจัดการข้อมูล หรือการจัดการคีย์

เพิ่มใหม่

เพิ่มสแนปช็อต access_time_windows ของสมาชิกที่ไม่ผูกกับผู้ให้บริการรายใด ซึ่งรองรับช่วงเวลาแบบกำหนดวันเวลาแน่นอนและแบบรายสัปดาห์ที่เกิดซ้ำผสมกัน
เพิ่มการเรียงลำดับด้วย access_time_windows_revision การส่งซ้ำแบบ Idempotent ความขัดแย้ง การข้ามข้อมูลเก่า และหลักการเพิกถอนสิทธิ์อย่างชัดเจน
เพิ่มคำแนะนำเกี่ยวกับเขตเวลา IANA เวลาออมแสง การจับคู่ scope_key เชิงตรรกะ ความเป็นปัจจุบันของข้อมูลต้นทาง การพัฒนาฝั่งผู้ส่งข้อมูล และการรับรอง

เพิ่มใหม่

เพิ่มเอกสารโปรแกรมพาร์ทเนอร์ ซึ่งครอบคลุมประเภทพาร์ทเนอร์ การเริ่มต้นใช้งาน แนวทางปฏิบัติที่ดีที่สุด ความพร้อมในการเปิดใช้งานจริง ข้อผิดพลาด การกำหนดเวอร์ชัน และการสนับสนุน
เพิ่มขั้นตอนการส่งคำขอสมัครเป็นพาร์ทเนอร์โดยเฉพาะ สำหรับผู้ที่สนใจเป็นพาร์ทเนอร์ด้านเทคนิคและด้านการค้า
เพิ่มเอกสารเกี่ยวกับวิธีที่การผสานรวมพาร์ทเนอร์ที่ได้รับอนุมัติปรากฏในไดเรกทอรีพาร์ทเนอร์ของ Performance Hub ภายในแพลตฟอร์มหลักของ Performance Hub

เพิ่มใหม่

เพิ่มเอกสารการควบคุมการเข้าถึงของ Door/Gate Controller รวมถึงการดำเนินการแสดงรายการ ดูสถานะ และปลดล็อก
เพิ่มเอกสารการทำงานของการปลดล็อกแบบซิงโครนัส: API จะส่งคืนผลสำเร็จก็ต่อเมื่อตัวควบคุมในสถานที่ยืนยันว่ารีเลย์ปลดล็อกทางกายภาพแล้วเท่านั้น
เพิ่มเอกสารการรองรับ idempotency_key แบบไม่บังคับสำหรับคำขอปลดล็อก Door/Gate Controller