Logo Performance HubPerformance Hub
Mục trang: Tài nguyên cho nhà phát triển & đối tác

Giới thiệu

Partner API của Performance Hub cho phép các nền tảng đối tác bên ngoài tích hợp liền mạch với các mô-đun cốt lõi của Performance Hub. API hỗ trợ thị giác máy tính, phân tích, ghi nhật ký ra vào của hội viên và thông tin chi tiết về cơ sở.

Định dạng yêu cầu

API chấp nhận nội dung yêu cầu được mã hóa JSON và trả về phản hồi được mã hóa JSON.

Giới hạn tốc độ

Để đảm bảo sử dụng công bằng và hệ thống ổn định, tài khoản Partner API bắt đầu với các giới hạn mặc định:

  • 5 yêu cầu mỗi giây cho mỗi endpoint
  • Khuyến nghị: tối đa 1000 mục cho mỗi yêu cầu theo lô để đạt hiệu suất tối ưu
  • Kích thước payload tối đa 10MB

Giới hạn tốc độ có thể điều chỉnh và được người quản lý tài khoản đối tác Performance Hub của bạn cấu hình theo từng trường hợp. Nếu tích hợp của bạn cần thông lượng cao hơn khi ra mắt, di chuyển dữ liệu, bổ sung dữ liệu báo cáo hoặc cho các cơ sở có lưu lượng lớn, hãy nêu vấn đề này trong quá trình tiếp nhận hoặc trước khung thời gian thay đổi đã lên kế hoạch.

URL cơ sở

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

Xác thực

Để truy cập Partner API, bạn cần xác thực bằng khóa bí mật API. Tạo và quản lý khóa của bạn thông qua Partner Console.

Khóa API đóng vai trò là thông tin xác thực để bạn truy cập tài nguyên đối tác. Mỗi khóa chỉ có quyền truy cập hạn chế vào dữ liệu của các tổ chức cụ thể và có thể bị vô hiệu hóa ngay lập tức khi cần.

Hãy bảo quản khóa API của bạn cẩn thận, vì chúng cung cấp toàn quyền truy cập vào tài khoản của bạn! Không bao giờ để lộ các khóa này trong kho mã công khai, ứng dụng phía máy khách hoặc bất kỳ nơi nào có thể bị xâm phạm.

Xác thực yêu cầu bằng HTTP Basic Auth bằng cách truyền khóa API của bạn làm tên người dùng. Để trống mật khẩu.

API chỉ chấp nhận kết nối HTTPS bảo mật. Các yêu cầu HTTP thông thường sẽ bị từ chối, cũng như mọi yêu cầu thiếu thông tin xác thực hợp lệ.

Yêu cầu mẫu

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.

Xác minh khóa bí mật

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>" }

Danh sách kiểm tra trước khi đưa vào hoạt động

Sử dụng danh sách kiểm tra này trước khi bật tích hợp đối tác cho các cơ sở đang hoạt động trên production.

Thiết lập Partner Console

  • Hồ sơ đối tác của bạn đã đầy đủ.
  • URL logo, trang web, danh mục và mô tả của bạn chính xác.
  • Phương thức liên kết dữ liệu của bạn đã được cấu hình: Direct Link hoặc Linking Identifier.
  • Việc liên kết cơ sở đã được kiểm thử với ít nhất một cơ sở thực tế.
  • Đang sử dụng đúng loại khóa:
    • Dryrun để kiểm thử thao tác ghi mà không gây ảnh hưởng.
    • Read-only để sử dụng dữ liệu an toàn.
    • Live chỉ khi bạn đã sẵn sàng tác động đến dữ liệu production.

Xác thực và quản lý khóa

  • Khóa bí mật chỉ được lưu trữ phía máy chủ.
  • Khóa không được nhúng trong ứng dụng phía máy khách, ứng dụng di động, kho mã công khai hoặc phiếu hỗ trợ.
  • Việc xoay vòng và thu hồi khóa đã được kiểm thử.
  • Đội ngũ của bạn biết khóa nào được dùng cho từng môi trường.

Xác thực dữ liệu

  • Có đầy đủ các trường bắt buộc cho mọi endpoint bạn gọi.
  • Mã định danh cơ sở khớp với phương thức liên kết đã cấu hình.
  • ID từ hệ thống của bạn ổn định và không thay đổi giữa các lần đồng bộ.
  • Các đợt nhập dữ liệu lớn được chia thành các lô dưới giới hạn được nêu trong tài liệu.
  • Có thể xác định và gửi lại các mục bị lỗi trong lô.

Kiểm thử endpoint

Trước khi ra mắt, hãy kiểm thử mọi endpoint mà tích hợp của bạn phụ thuộc vào:

  • Có thể đọc thông tin tổ chức và cơ sở.
  • Có thể lưu và cập nhật hội viên.
  • Gói hội viên, khu vực ra vào và giờ ra vào được đồng bộ chính xác.
  • Lượt check-in được chấp nhận và có thể đối chiếu ngược lại với hệ thống của bạn.
  • Ảnh chụp nhanh báo cáo sử dụng đúng kỳ báo cáo và chỉ số dự kiến.
  • Các luồng Door/Gate Controller được kiểm thử trên phần cứng thực tế nếu áp dụng.

Sẵn sàng cho Access Time Window

Nếu tích hợp cung cấp Access Time Windows:

  • Các ví dụ khung thời gian tuyệt đối và hằng tuần vượt qua danh sách kiểm tra chứng nhận dành cho bên tạo dữ liệu.
  • Giá trị epoch là số nguyên giây Unix không đặt trong dấu ngoặc kép; các ranh giới [from, to) chính xác đã được kiểm thử.
  • Đã xác minh múi giờ UTC mặc định, các múi giờ IANA tùy chỉnh của tích hợp và các thời điểm chuyển đổi giờ mùa hè liên quan.
  • Một chuỗi phiên bản bền vững, tăng đơn điệu theo hội viên/nguồn điều phối các bản cập nhật tăng dần, việc đối soát và các lần thử lại.
  • Người vận hành hiểu hoạt động khi bỏ qua trường, thay thế toàn bộ, idempotent, xung đột, dữ liệu cũ và [] rõ ràng.
  • Mọi scope_key, bao gồm default, đều có ánh xạ Performance Hub đã được phê duyệt; các khóa không xác định đã được kiểm thử để đảm bảo không được cấp quyền truy cập.
  • Tần suất làm mới dự kiến, độ cũ tối đa của nguồn, hoạt động khi nguồn đã cũ và các cảnh báo của tích hợp đã được cấu hình.
  • Đã chứng minh rằng lỗi truy xuất từ upstream không tạo ra ảnh chụp nhanh rỗng hoặc không đầy đủ.
  • Khả năng hội tụ của chuỗi trên môi trường staging, việc hủy/thu hồi và các ranh giới bắt đầu/kết thúc tại cửa thực tế đạt các mục tiêu đã thống nhất.
  • Các quy tắc thông thường và quyền cấp vĩnh viễn đã được xác minh là đường dự phòng, và khung thời gian không thể vượt qua việc vô hiệu hóa người dùng, blockAllAccess, chế độ bảo trì hoặc geofencing.

Sẵn sàng cho kiểm soát ra vào

Đối với các tích hợp kiểm soát ra vào:

  • Hệ thống của bạn đưa ra quyết định ra vào trước khi gọi Performance Hub.
  • Tích hợp xử lý device_offline, maintenance_mode_active và unlock_confirmation_timeout.
  • Người vận hành hiểu rằng hết thời gian chờ có nghĩa là việc mở khóa chưa được xác nhận.
  • Nhật ký của bạn lưu event_id và command_id được trả về.
  • Bạn có quy trình dự phòng thủ công cho nhân viên cơ sở.

Xử lý lỗi và thử lại

  • Các phản hồi 400, 401, 403, 404, 409 và 422 được hiển thị cho người vận hành hoặc đội ngũ hỗ trợ thay vì bị thử lại một cách mù quáng.
  • Các phản hồi 429, 500, 502, 503 và 504 sử dụng logic thử lại có giới hạn với thời gian chờ tăng dần.
  • Các lỗi lặp lại sẽ tạo cảnh báo trong hệ thống của bạn.
  • Tích hợp không bao giờ âm thầm bỏ qua các bản ghi bị lỗi.

Khả năng quan sát

  • Nhật ký của bạn bao gồm endpoint, dấu thời gian, mã định danh cơ sở, ID bản ghi nguồn, kết quả yêu cầu và nội dung phản hồi.
  • Đội ngũ hỗ trợ của bạn có thể tìm kiếm theo ID hội viên, ID cơ sở, ID check-in hoặc ID sự kiện mở khóa.
  • Bạn có cách phát lại hoặc đối soát các lần đồng bộ thất bại.

Ra mắt production

  • Performance Hub đã xác nhận quyền truy cập production của bạn.
  • Ít nhất một cơ sở trên production đã bật tích hợp của bạn.
  • Khóa production của bạn đang hoạt động.
  • Thông tin đầu mối vận hành và kỹ thuật của bạn được cập nhật.
  • Quy trình hỗ trợ của bạn đã được ghi lại cho khách hàng.

Sau khi hoàn tất các bước kiểm tra này, tích hợp đã cấu hình của bạn sẽ xuất hiện trong danh bạ đối tác của Performance Hub bên trong nền tảng Performance Hub cốt lõi.

Các phương pháp hay nhất

Áp dụng các mẫu sau để giữ cho tích hợp đối tác dễ dự đoán, dễ quan sát và an toàn cho các cơ sở.

Xác định cơ sở một cách nhất quán

Chọn phương thức liên kết được cấu hình cho tài khoản đối tác của bạn và sử dụng nhất quán:

  • Direct Link - sử dụng facility_id của Performance Hub do endpoint cơ sở trả về.
  • Linking Identifier - sử dụng mã định danh địa điểm của riêng bạn, chẳng hạn ID chi nhánh, mã địa điểm hoặc số cửa hàng.

Không gửi cả hai mã định danh trong cùng một yêu cầu. Performance Hub xử lý yêu cầu theo phương thức liên kết được cấu hình cho tài khoản đối tác của bạn.

Xem Các phương thức liên kết đối tác để biết hướng dẫn thiết lập.

Ghi theo lô một cách cẩn thận

Partner API chấp nhận nội dung yêu cầu dạng JSON và được thiết kế cho các quy trình đồng bộ theo lô ở những nơi được nêu trong tài liệu. Hãy giữ các lô có kích thước giới hạn và có thể thử lại.

Hướng dẫn mặc định:

  • Sử dụng tối đa 1000 mục cho mỗi yêu cầu theo lô để đạt hiệu suất tối ưu.
  • Giữ payload dưới 10MB.
  • Không vượt quá 5 yêu cầu mỗi giây cho mỗi endpoint.

Giới hạn tốc độ có thể điều chỉnh và được người quản lý tài khoản đối tác Performance Hub của bạn cấu hình theo từng trường hợp. Nếu bạn dự kiến nhập dữ liệu khối lượng lớn, lưu lượng khi ra mắt hoặc bổ sung dữ liệu báo cáo, hãy thống nhất thông lượng cần thiết trước khung thời gian thay đổi.

Nếu bạn cần đồng bộ một tập dữ liệu lớn, hãy chia thành các phần xác định và ghi nhật ký ID của từng phần ở phía bạn. Điều này giúp việc phân tích các lần thử lại thất bại dễ dàng hơn.

Thử lại an toàn

Sử dụng thời gian chờ tăng theo cấp số nhân (exponential backoff) cho các lỗi tạm thời như 429, 500, 502, 503 và 504.

Tránh các vòng lặp thử lại liên tục. Một điểm khởi đầu tốt là:

  1. Thử lại sau 1 giây.
  2. Thử lại sau 2 giây.
  3. Thử lại sau 4 giây.
  4. Dừng lại và gửi cảnh báo nếu thao tác vẫn thất bại.

Đối với các lỗi xác thực dữ liệu như 400 hoặc 422, hãy sửa yêu cầu trước khi thử lại.

Sử dụng tính idempotent khi được hỗ trợ

Endpoint mở khóa Door/Gate Controller hỗ trợ idempotency_key không bắt buộc. Dùng lại cùng một khóa cho cùng đối tác, cơ sở và cửa sẽ trả về kết quả hiện có nếu có.

Sử dụng một khóa ổn định cho hành động đang thực hiện, ví dụ ID check-in hoặc ID sự kiện ra vào từ hệ thống của bạn.

Đừng giả định mọi endpoint ghi đều hỗ trợ tính idempotent, trừ khi điều đó được nêu trong tài liệu của endpoint đó.

Giữ dữ liệu nguồn sạch

Gửi các giá trị ổn định, đã chuẩn hóa bất cứ khi nào có thể:

  • Sử dụng ID hội viên, gói, cơ sở và check-in nhất quán từ hệ thống nguồn của bạn.
  • Sử dụng dấu thời gian ISO 8601 cho ngày và giờ.
  • Gửi số điện thoại theo định dạng quốc tế nếu có.
  • Gửi đơn vị tiền tệ bằng các trường được nêu trong tài liệu của từng endpoint.
  • Tránh nhồi vào các trường văn bản tự do những dữ liệu thuộc về các trường có cấu trúc.

Thiết kế cho cả đồng bộ tăng dần và đồng bộ toàn bộ

Hầu hết các tích hợp đối tác cần cả hai:

  • Đồng bộ tăng dần cho các thay đổi hằng ngày.
  • Đồng bộ đối soát toàn bộ để khắc phục các sự kiện bị bỏ sót, nhập dữ liệu lịch sử hoặc sai lệch dữ liệu.

Tích hợp của bạn cần có khả năng gửi lại trạng thái hiện tại của một hội viên, gói hội viên hoặc ảnh chụp nhanh báo cáo mà không phụ thuộc vào việc một yêu cầu trước đó đã thành công.

Phát hành Access Time Windows an toàn

Hãy coi giá trị access_time_windows của mỗi hội viên là một ảnh chụp nhanh đầy đủ, có phiên bản độc lập:

  • Điều phối một chuỗi access_time_windows_revision tăng đơn điệu duy nhất giữa các worker đồng bộ tăng dần và worker đối soát.
  • Thử lại một lần gửi không chắc chắn hoặc lỗi tạm thời với cùng phiên bản và payload đã chuẩn hóa.
  • Bỏ qua access_time_windows khi bạn không cập nhật trường này.
  • Chỉ gửi [] sau khi một lần truy xuất thành công từ nguồn có thẩm quyền chứng minh rằng không còn khung thời gian nào. Không bao giờ biến một lần hết thời gian chờ từ upstream, kết quả không đầy đủ hoặc lỗi phân tích cú pháp thành việc thu hồi quyền.
  • Giữ external_id và scope_key ổn định, và chứng nhận mọi ánh xạ phạm vi trước khi đưa lên production.
  • Theo dõi độ cũ của dữ liệu nguồn so với chính sách về độ mới đã thống nhất cho tích hợp đó.

Xem hướng dẫn chính thức dành cho bên tạo dữ liệu Access Time Windows để biết về ảnh chụp nhanh đầy đủ, múi giờ, giờ mùa hè (DST), hủy bỏ và các bộ dữ liệu kiểm thử.

Coi kiểm soát ra vào là yếu tố quan trọng về an toàn

Đối với thao tác mở khóa Door/Gate Controller:

  • Hệ thống của bạn phải quyết định người đó có được phép vào hay không trước khi gọi Performance Hub.
  • Performance Hub chỉ trả về 200 sau khi bộ điều khiển tại chỗ xác nhận rơ-le đã thực sự mở khóa.
  • Hầu hết các xác nhận hoàn tất trong 3-5 giây.
  • Hết thời gian chờ là một lần mở khóa thất bại rõ ràng, không phải một thao tác thành công chạy ngầm.
  • Chỉ thử lại theo các quy tắc ra vào và an toàn của riêng bạn.

Luôn ghi nhật ký event_id và command_id do endpoint mở khóa trả về.

Giám sát tích hợp của bạn

Sử dụng nhật ký yêu cầu trong Partner Console trong quá trình phát triển và ra mắt. Trên production, hãy duy trì thêm nhật ký của riêng bạn với:

  • Dấu thời gian của yêu cầu.
  • Endpoint.
  • ID bản ghi nguồn.
  • Mã định danh cơ sở.
  • Mã trạng thái HTTP.
  • Nội dung phản hồi hoặc thông báo lỗi từ Performance Hub.

Các trường này giúp việc hỗ trợ và đối soát nhanh hơn nhiều khi khách hàng hỏi điều gì đã xảy ra.

Tổ chức

Đại diện cho pháp nhân kinh doanh cấp cao nhất vận hành một hoặc nhiều cơ sở được tích hợp với nền tảng Performance Hub.

Các endpoint

GET /partner/v1/organisations - List all organisations

Đối tượng Organisation

Thuộc tính

  • org_id string bắt buộc

    Mã định danh duy nhất của tổ chức.

  • name string bắt buộc

    Tên tổ chức.

Đối tượng Organisation

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

Liệt kê tất cả các tổ chức

Trả về danh sách các tổ chức mà tài khoản đối tác của bạn có thể truy cập.

Giá trị trả về

Trả về một đối tượng JSON có thuộc tính data chứa một mảng các đối tượng Organisation.

Yêu cầu

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

Phản hồi

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

Cơ sở

Đại diện cho một địa điểm thực tế, chẳng hạn văn phòng, cửa hàng, địa điểm tổ chức sự kiện, khuôn viên, phòng khám hoặc phòng tập, nơi hội viên có thể sử dụng dịch vụ.

Các endpoint

GET /partner/v1/facilities - List all facilities

Đối tượng cơ sở (Facility)

Thuộc tính

  • facility_id string bắt buộc

    Mã định danh duy nhất của cơ sở.

  • org_id string bắt buộc

    Mã định danh duy nhất của tổ chức mẹ.

  • name string bắt buộc

    Tên cơ sở.

  • brand string tùy chọn

    Tên thương hiệu mà cơ sở sử dụng.

  • website_url string tùy chọn

    URL trang web của cơ sở.

  • place_data object tùy chọn

    Dữ liệu vị trí từ Google Places API, gồm quốc gia, địa chỉ đã định dạng, Google Place ID, tỉnh/bang và thành phố.

  • social_links object tùy chọn

    Các liên kết mạng xã hội của cơ sở.

  • timezone string tùy chọn

    Mã định danh múi giờ IANA (ví dụ: "Australia/Sydney", "America/New_York").

Đối tượng cơ sở (Facility)

{
  "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"
}

Liệt kê tất cả các cơ sở

Trả về danh sách các cơ sở mà tài khoản đối tác của bạn có thể truy cập.

Giá trị trả về

Trả về một đối tượng JSON có thuộc tính data chứa một mảng các đối tượng Facility.

Yêu cầu

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

Phản hồi

{
  "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"
    }
  ]
}

Gói hội viên

Xác định một sản phẩm có thể mua của tổ chức hoặc cơ sở, bao gồm dịch vụ, quyền lợi, lịch trình và giá.

Các endpoint

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

Đối tượng Membership Plan

Thuộc tính

  • membership_plan_id string bắt buộc

    Mã định danh duy nhất của gói hội viên.

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh duy nhất của cơ sở trong Performance Hub.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Giá trị mã định danh duy nhất mà đối tác dùng cho từng địa điểm (ví dụ: "Branch ID", "Location Code", "Store Number"). Tìm hiểu thêm

  • name string bắt buộc

    Tên gói dễ đọc (ví dụ: "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").

  • billing_cycle string tùy chọn

    Tần suất thanh toán. Một trong các giá trị weekly, fortnightly, monthly, annually hoặc one_time.

  • price integer tùy chọn

    Chi phí cơ bản tính theo đơn vị tiền tệ nhỏ nhất (cent đối với USD/AUD).

  • currency string tùy chọn

    Mã tiền tệ ISO 4217 (ví dụ: "AUD", "USD").

  • description string tùy chọn

    Mô tả tiếp thị hoặc mô tả nội bộ không bắt buộc.

  • active_members integer tùy chọn

    Số hội viên đang hoạt động sử dụng gói hội viên này

  • is_recurring boolean tùy chọn

    Gói có tự động gia hạn hay không.

  • is_trial boolean tùy chọn

    Đây có phải là gói dùng thử hay không.

  • visible_to_public boolean tùy chọn

    Gói có thể được tự mua hay không.

  • duration_days integer tùy chọn

    Số ngày gói hội viên có hiệu lực.

  • access_zones array tùy chọn

    Mảng các khu vực ra vào có trong gói hội viên. Mỗi khu vực có thể xác định giờ ra vào riêng. Xem Khu vực ra vào để biết chi tiết.

  • class_limit integer tùy chọn

    Số lớp học tối đa được phép (null nếu không giới hạn).

Đối tượng Membership Plan

Ví dụ này sử dụng facility_id. Đối với tích hợp dùng mã định danh liên kết, hãy gửi "linking_identifier": "branch_downtown" thay thế.

{
  "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
}

Khu vực ra vào

Khu vực ra vào xác định các khu vực cụ thể trong một cơ sở mà gói hội viên cấp quyền ra vào. Mỗi khu vực có thể có giờ ra vào riêng, cho phép áp dụng các giới hạn thời gian khác nhau cho từng khu vực.

Cấu trúc

Mỗi khu vực ra vào bao gồm:

  • name string bắt buộc

    Tên của khu vực (ví dụ: "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor").

  • description string tùy chọn

    Mô tả những gì có trong khu vực đó.

  • access_hours object tùy chọn

    Giờ ra vào dành riêng cho khu vực này. Xem Giờ ra vào để biết định dạng khoảng thời gian.

Ví dụ

Một tòa nhà văn phòng có phòng tập dành cho khách thuê: quyền ra vào khu vực thuê trong giờ hành chính và vào phòng tập từ sáng sớm đến tối muộn.

{
  "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"]]
      }
    }
  ]
}

Giờ ra vào

Giờ ra vào xác định thời điểm hội viên có thể vào một khu vực cụ thể trong từng ngày của tuần. Giờ ra vào được xác định theo từng khu vực ra vào, cho phép áp dụng các giới hạn thời gian khác nhau cho các khu vực khác nhau của cơ sở.

Cấu trúc

{
  "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"]]
}

Mỗi ngày là một mảng các khoảng thời gian theo định dạng HH:MM (đồng hồ 24 giờ). Mảng rỗng [] có nghĩa là không được ra vào trong ngày đó. Các ngày bị bỏ qua được xử lý giống như mảng rỗng.

Ví dụ về trường hợp sử dụng

Khách thuê văn phòng – giờ hành chính: chỉ được ra vào trong giờ hành chính vào các ngày trong tuần.

{
  "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"]]
  }
}

Sinh viên – quyền ra vào theo học kỳ: thư viện trong khuôn viên mở cửa vào các ngày trong tuần, có nghỉ giữa ngày, và vào sáng thứ Bảy.

{
  "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"]]
  }
}

Phòng tập – khung giờ sáng sớm: chỉ được ra vào buổi sáng vào các ngày trong tuần.

{
  "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"]]
  }
}

Khách lưu trú khách sạn – 24/7: quyền ra vào liên tục, trường hợp sử dụng phổ biến nhất.

{
  "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"]]
  }
}

Ví dụ theo từng khu vực

Một gói dành cho khách lưu trú khách sạn với quyền ra vào suốt ngày đêm tại các tầng phòng khách và giờ ngắn hơn cho hồ bơi:

{
  "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"]]
      }
    }
  ]
}

Lưu gói hội viên

Tạo hoặc cập nhật bản ghi gói hội viên. API xác định việc tạo mới hay cập nhật dựa trên membership_plan_id.

Tham số

  • membership_plans array bắt buộc

    Mảng các đối tượng Membership Plan cần lưu. Khuyến nghị tối đa: 1000 mục mỗi yêu cầu để đạt hiệu suất tối ưu. API tự động chia lô các mục để xử lý. Mỗi mục phải có facility_id (bắt buộc nếu không dùng linking_identifier) hoặc linking_identifier (bắt buộc nếu không dùng facility_id).

Giá trị trả về

Trả về một thông báo đơn giản xác nhận thao tác đồng bộ.

Yêu cầu

Ví dụ này sử dụng facility_id. Đối với tích hợp dùng mã định danh liên kết, hãy gửi "linking_identifier": "branch_downtown" thay thế.

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
      }
    ]
  }'

Phản hồi

Trả về thông báo thành công kèm siêu dữ liệu về thao tác đồng bộ.

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

Các trường siêu dữ liệu:

  • success - Số gói hội viên đã được xử lý thành công
  • skipped - Số gói bị bỏ qua (nếu có)
  • skipped_items - Mảng các gói bị bỏ qua kèm lý do (nếu có)
  • dry-run - Cờ boolean nếu sử dụng loại khóa dryrun (nếu áp dụng)

Hội viên

Đại diện cho một khách hàng cá nhân của cơ sở. Có thể là khách hàng tiềm năng, người quan tâm, khách hàng định kỳ, hội viên đã hết hạn hoặc người dùng bị chặn.

Các thao tác upsert hội viên cũng có thể mang theo ảnh chụp nhanh access_time_windows đầy đủ, có phiên bản, chứa quyền ra vào theo khung thời gian tuyệt đối và lặp lại hằng tuần. Xem Access Time Windows trước khi tạo các trường này. Đây là các quyền bổ sung và không thay thế các quy tắc thông thường hoặc quyền cấp vĩnh viễn của cơ sở.

Các endpoint

POST /partner/v1/members - Save a member

Đối tượng Member

Thuộc tính

  • member_id string bắt buộc

    Mã định danh duy nhất của hội viên.

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh duy nhất của cơ sở trong Performance Hub.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Giá trị mã định danh duy nhất mà đối tác dùng cho từng địa điểm (ví dụ: "Branch ID", "Location Code", "Store Number"). Tìm hiểu thêm

  • first_name string bắt buộc

    Tên của hội viên.

  • last_name string bắt buộc

    Họ của hội viên.

  • email string tùy chọn

    Địa chỉ email.

  • mobile_phone string tùy chọn

    Số điện thoại di động theo định dạng E.123 (ví dụ: "+1 415 555 2671").

  • address object tùy chọn

    Đối tượng địa chỉ thực tế với các thuộc tính sau:

    • address_line_1 (string) - Địa chỉ đường phố chính
    • address_line_2 (string, optional) - Dòng địa chỉ phụ
    • city (string) - Tên thành phố
    • state (string) - Mã bang/tỉnh
    • postal_code (string) - Mã bưu chính/ZIP
    • country (string) - Mã quốc gia ISO 3166-1 alpha-2 (ví dụ: "AU", "US")
    • country_name (string, optional) - Tên quốc gia đầy đủ

  • date_of_birth string tùy chọn

    Ngày sinh theo định dạng YYYY-MM-DD.

  • gender string tùy chọn

    Một trong các giá trị male, female, non_binary, prefer_not_to_say hoặc unknown.

  • type string tùy chọn

    Loại hội viên (ví dụ: staff, member, prospect).

  • tags array tùy chọn

    Các chuỗi hoặc văn bản hỗ trợ nhanh để phân loại và nhận diện các hội viên cụ thể (ví dụ: ["vip", "personal-training", "student"]).

  • membership_status string tùy chọn

    Trạng thái hội viên hiện tại (ví dụ: active, expired, on_hold).

  • membership_plans array tùy chọn

    Mảng các gói hội viên gắn với hội viên.

  • profile_picture string tùy chọn

    Ảnh hồ sơ được mã hóa Base64 (không bắt buộc).

  • created string tùy chọn

    Dấu thời gian ISO 8601 khi hội viên được tạo.

  • updated string tùy chọn

    Dấu thời gian ISO 8601 khi hội viên được cập nhật lần gần nhất.

  • access_time_windows array tùy chọn

    Ảnh chụp nhanh đầy đủ thuộc nguồn, gồm các Access Time Windows tuyệt đối và/hoặc lặp lại hằng tuần. Bỏ qua trường này để giữ nguyên ảnh chụp nhanh; gửi một mảng rỗng với phiên bản mới hơn để thu hồi. Xem Access Time Windows để biết về cấu trúc, kiểm tra dữ liệu, ánh xạ phạm vi và ngữ nghĩa thay thế.

  • access_time_windows_revision integer bắt buộc khi có access_time_windows

    Số nguyên không âm, tăng đơn điệu, an toàn với JSON cho chuỗi của hội viên/nguồn này. Bắt buộc bất cứ khi nào có access_time_windows.

Đối tượng 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
    }
  ]
}

Khung thời gian Cấp quyền

Access Time Windows cho phép một Partner Member mang theo quyền ra vào tạm thời hoặc định kỳ do một hệ thống bên ngoài cung cấp. Trang này là hướng dẫn chính thức dành cho bên tạo dữ liệu access_time_windows và access_time_windows_revision.

Access Time Windows là các quyền bổ sung chỉ có tác dụng cho phép. Một khung thời gian đang hiệu lực có thể cho phép ra vào, nhưng một khung thời gian không hiệu lực, đã hết hạn, đã cũ hoặc chưa được ánh xạ sẽ không từ chối quyền ra vào mà một quy tắc thông thường hoặc quyền cấp vĩnh viễn đã cho phép. Việc vô hiệu hóa người dùng, chặn cửa rõ ràng, chế độ bảo trì, geofencing, giới hạn tốc độ và tình trạng khả dụng của bộ điều khiển vẫn được áp dụng.

Phần triển khai cho từng hệ thống upstream cụ thể là các bộ điều hợp (adapter) riêng biệt. Chúng phải chuyển đổi dữ liệu nguồn sang hợp đồng không phụ thuộc nhà cung cấp này mà không thay đổi ý nghĩa của các trường.

Các trường ảnh chụp nhanh của hội viên

  • access_time_windows array tùy chọn

    Ảnh chụp nhanh Access Time Window đầy đủ cho hội viên này và nguồn đối tác này. Một ảnh chụp nhanh có thể kết hợp các khung thời gian absolute và weekly. Bỏ qua trường này để giữ nguyên ảnh chụp nhanh đã lưu; gửi [] để thu hồi mọi khung thời gian thuộc nguồn này.

  • access_time_windows_revision integer bắt buộc khi có access_time_windows

    Một số nguyên không âm, tăng đơn điệu, an toàn với JSON cho chuỗi phiên bản của hội viên/nguồn này. Trường này bắt buộc bất cứ khi nào có access_time_windows và không được vượt quá 9007199254740991.

Mỗi ảnh chụp nhanh chấp nhận tối đa 50 khung thời gian. external_id, scope_key và label chấp nhận tối đa 120 ký tự. Khung thời gian tuyệt đối có thể kéo dài tối đa 90 ngày. Mỗi ngày trong tuần chấp nhận tối đa tám khối không chồng lấn. Dữ liệu không hợp lệ sẽ bị từ chối thay vì bị cắt bớt hoặc suy đoán.

Cấu trúc khung thời gian

Một khung thời gian tuyệt đối xác định một khoảng thời gian chính xác:

Yêu cầu kết hợp đầy đủ

Yêu cầu này thay thế ảnh chụp nhanh trước đó thuộc nguồn của hội viên bằng một khung thời gian tuyệt đối và một khung thời gian hằng tuần:

Quy tắc về thời gian và ranh giới

from, to, active_from và active_until là số nguyên JSON tính bằng giây Unix, xác định các thời điểm UTC:

  • Gửi số nguyên JSON không đặt trong dấu ngoặc kép. Chuỗi số, số thực, chuỗi RFC 3339 và mili giây Unix sẽ bị từ chối.
  • Mọi khoảng thời gian đều là nửa mở: [from, to). Quyền ra vào có thể bắt đầu đúng tại from; quyền không còn hiệu lực đúng tại to.
  • from phải nhỏ hơn to. Khi có cả hai giới hạn hằng tuần, active_from phải nhỏ hơn active_until.
  • Không suy ra epoch từ ngày/giờ địa phương không có múi giờ. Trước tiên hãy quy đổi thời gian nguồn thành một thời điểm UTC, sau đó chia số mili giây Unix cho 1000 và xác minh kết quả là số nguyên.

Múi giờ và giờ mùa hè

timezone phải là một múi giờ IANA hợp lệ, chẳng hạn UTC, Australia/Perth hoặc America/New_York. Mặc định là UTC khi bị bỏ qua.

  • Khung thời gian tuyệt đối: from và to đã xác định chính xác các thời điểm UTC. timezone chỉ là siêu dữ liệu để hiển thị và kiểm toán; việc thay đổi trường này không bao giờ làm dịch chuyển hai thời điểm đó.
  • Khung thời gian hằng tuần: timezone xác định giờ địa phương và quy tắc giờ mùa hè dùng để đánh giá access_hours. Không chuyển đổi trước các khối hằng tuần sang UTC.
  • Khi chuyển sang giờ mùa hè (đồng hồ tiến lên), một giờ địa phương bị múi giờ bỏ qua sẽ không bao giờ xảy ra.
  • Khi kết thúc giờ mùa hè (đồng hồ lùi lại), cả hai thời điểm thực mang cùng giờ địa phương lặp lại đều khớp với khối hằng tuần.
  • active_from và active_until vẫn là thời điểm UTC ngay cả khi khung thời gian hằng tuần sử dụng múi giờ khác UTC.

access_hours sử dụng chữ thường từ sun đến sat. Mỗi giá trị là một mảng các cặp [start, end] theo định dạng HH:mm 24 giờ có số 0 đứng đầu. Các khối phải không rỗng, được sắp xếp theo thứ tự và không chồng lấn. end không bao gồm thời điểm kết thúc. Một khối không được vượt qua nửa đêm; hãy tách một khoảng thời gian qua đêm từ nguồn thành một khối muộn vào ngày đầu tiên và một khối sớm vào ngày hôm sau.

ID ổn định và ánh xạ phạm vi

external_id phải ổn định trong suốt vòng đời của một khung thời gian logic và là duy nhất trong ảnh chụp nhanh của hội viên. Giữ nguyên giá trị này khi thời gian hoặc nhãn thay đổi để người vận hành và bản ghi kiểm toán có thể đối chiếu các phiên bản. Không dùng lại giá trị này cho một khung thời gian không liên quan.

scope_key là mục tiêu ra vào logic ổn định của bạn. Mặc định là default. Quản trị viên cơ sở ánh xạ từng khóa được phép tới các mục tiêu trong Performance Hub: toàn bộ cơ sở, cửa hoặc Phạm vi truy cập:

Ảnh chụp nhanh đầy đủ và phiên bản

Hãy coi hai trường này là một phân vùng có phiên bản riêng trong thao tác upsert Member:

Đầu vào Kết quả
Bỏ qua access_time_windows Ảnh chụp nhanh hiện có được giữ nguyên; không cần phiên bản
Có mặt với phiên bản mới hơn Toàn bộ ảnh chụp nhanh đã lưu của hội viên/nguồn này được thay thế
Cùng phiên bản và cùng payload đã chuẩn hóa Phát lại idempotent; ảnh chụp nhanh không thay đổi
Cùng phiên bản nhưng payload đã chuẩn hóa khác Xung đột; cấp phiên bản mới sau khi đối soát
Phiên bản cũ hơn Ảnh chụp nhanh cũ bị bỏ qua; không thể ghi đè trạng thái mới hơn
access_time_windows: [] với phiên bản mới hơn Thu hồi rõ ràng mọi khung thời gian thuộc nguồn

Ảnh chụp nhanh là bản đầy đủ, không phải bản vá. Nếu phiên bản 1842 có khung thời gian A và B, thì phiên bản 1843 chỉ chứa B sẽ xóa A.

Duy trì một chuỗi phiên bản được điều phối thống nhất cho mỗi đối tác/hội viên giữa các worker webhook, thăm dò định kỳ, phát lại và đối soát toàn bộ. Nên dùng một sequence bền vững trong cơ sở dữ liệu. Chỉ có thể dùng giá trị mili giây Unix làm phiên bản khi mọi bên ghi đều được điều phối và đảm bảo thứ tự nghiêm ngặt cũng như tính duy nhất; đó là giá trị phiên bản, không phải trường epoch.

Lưu lại chính xác yêu cầu và phiên bản cho đến khi biết phản hồi của API. Thử lại cùng ảnh chụp nhanh đã chuẩn hóa với cùng phiên bản sau khi hết thời gian chờ hoặc gặp lỗi tạm thời. Không cấp phiên bản mới chỉ vì việc truyền tải không chắc chắn.

Hủy bỏ, hết hạn và lỗi upstream

  • Hủy một khung thời gian: truy xuất thành công trạng thái nguồn có thẩm quyền, xóa khung thời gian đó và gửi ảnh chụp nhanh đầy đủ còn lại với phiên bản mới hơn.
  • Hủy tất cả khung thời gian: gửi access_time_windows: [] với phiên bản mới hơn.
  • Để khung thời gian tuyệt đối hết hạn: khung thời gian ngừng cho phép tại to; hãy gửi một lần đối soát sau đó không có mục đã hết hạn để giữ ảnh chụp nhanh gọn gàng.
  • Kết thúc khung thời gian hằng tuần: xóa khung thời gian đó trong một ảnh chụp nhanh mới hơn, hoặc dùng active_until khi nguồn có thời điểm kết thúc đã biết.
  • Truy xuất nguồn thất bại hoặc không đầy đủ: không gửi [] và không phát hành ảnh chụp nhanh không đầy đủ. Hãy cảnh báo và thử truy xuất lại. Biến lỗi upstream thành ảnh chụp nhanh rỗng là một lần thu hồi quyền ra vào ngoài ý muốn.
  • Yêu cầu Partner API không vượt qua kiểm tra dữ liệu: sửa dữ liệu và chỉ gửi phiên bản mới hơn nếu ảnh chụp nhanh đã chuẩn hóa thay đổi. Thử lại các lỗi tạm thời với phiên bản ban đầu.

Độ mới của nguồn được cấu hình theo từng tích hợp dựa trên tần suất gửi và đối soát đã cam kết. Trước khi kích hoạt, hãy thống nhất độ cũ tối đa của nguồn, điều gì xảy ra khi vượt quá, các ngưỡng cảnh báo và liệu người vận hành có thể xác nhận việc chỉ dựa vào giới hạn riêng của từng khung thời gian hay không. Một khung thời gian từ nguồn đã cũ không bao giờ trở thành quy tắc từ chối; các quy tắc thông thường và quyền cấp vĩnh viễn vẫn là đường dự phòng.

Thuật toán dành cho bên tạo dữ liệu

Áp dụng quy trình không phụ thuộc ngôn ngữ lập trình này cho mọi lần cập nhật hội viên:

Danh sách kiểm tra chứng nhận

Hoàn tất các bước kiểm tra sau tại một cơ sở staging bằng ánh xạ scope_key cuối cùng:

  • Khung thời gian tuyệt đối được chấp nhận khi bỏ qua múi giờ và được đánh giá theo UTC.
  • Khung thời gian tuyệt đối với múi giờ IANA tùy chỉnh giữ nguyên các thời điểm from/to.
  • Khung thời gian hằng tuần với múi giờ IANA tùy chỉnh tuân theo giờ địa phương qua các lần chuyển sang và kết thúc giờ mùa hè.
  • Ảnh chụp nhanh kết hợp tuyệt đối/hằng tuần thay thế hoàn toàn ảnh chụp nhanh trước đó.
  • Quyền ra vào bắt đầu đúng tại from và dừng đúng tại to; thời điểm kết thúc của khối hằng tuần cũng không được bao gồm.
  • Cập nhật thời gian dưới cùng external_id với phiên bản mới hơn sẽ có hiệu lực.
  • Bỏ qua access_time_windows sẽ thay đổi các trường Member khác mà không thay đổi khung thời gian.
  • Phát lại cùng phiên bản/payload là idempotent.
  • Cùng phiên bản/payload khác trả về xung đột và không thay đổi ảnh chụp nhanh.
  • Phiên bản cũ hơn đến không theo thứ tự được báo cáo là cũ và không thể đưa trạng thái quay lại.
  • Một [] mới hơn thu hồi các khung thời gian thuộc nguồn; lỗi truy xuất từ upstream không gửi gì cả.
  • Một scope_key không xác định hoặc chưa được ánh xạ không cấp quyền truy cập và tạo cảnh báo mà người vận hành có thể thấy.
  • Cảnh báo về độ cũ của nguồn và chính sách nguồn đã cũ được cấu hình hoạt động đúng tại ngưỡng đã thống nhất.
  • Đường webhook và đường đối soát toàn bộ hội tụ về cùng ảnh chụp nhanh và thứ tự phiên bản.
  • Dữ liệu từ chuỗi đến được Door & Gate Access trong thời gian mục tiêu đã thống nhất.
  • Khung thời gian đang hiệu lực có thể cho phép ra vào cửa thực tế đã được ánh xạ, nhưng không thể vượt qua việc vô hiệu hóa người dùng, blockAllAccess, chế độ bảo trì hoặc geofencing.
  • Trước, ngoài và sau một khung thời gian, các quy tắc thông thường và quyền cấp vĩnh viễn vẫn cho phép những người dùng đủ điều kiện theo cách khác.

Hướng dẫn liên quan

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

Các trường bắt buộc là external_id, kind, from và to. timezone, scope_key và label là không bắt buộc.

Một khung thời gian hằng tuần xác định các khoảng thời gian định kỳ theo giờ địa phương, có thể được giới hạn bởi các thời điểm 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"
}

Các trường bắt buộc là external_id, kind và access_hours. timezone, active_from, active_until, scope_key và label là không bắt buộc.

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"
          }
        ]
      }
    ]
  }'

Sử dụng facility_id hoặc linking_identifier theo phương thức liên kết đã cấu hình. Không gửi cả hai.

Chuyển đổi epoch

2026-10-15T08:30:00Z được chuyển đổi thành 1792053000:

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

Cách chuyển đổi không phụ thuộc ngôn ngữ lập trình:

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

Nếu nguồn có độ chính xác dưới một giây, hãy xác định chính sách làm tròn thời điểm bắt đầu/kết thúc một cách có chủ đích trước khi kiểm thử tích hợp. Không bao giờ truyền mili giây và trông chờ API tự suy ra đơn vị.

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

Đối tác không gửi ID cơ sở, ID cửa hoặc ID Phạm vi truy cập của Performance Hub bên trong một khung thời gian. Một scope_key không xác định, bị vô hiệu hóa hoặc chưa được ánh xạ sẽ khiến khung thời gian đó không cấp quyền truy cập nào; nó không mở rộng quyền ra vào. Hãy thống nhất và kiểm thử các ánh xạ trước khi ra mắt.

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)

Bộ dữ liệu kiểm thử tối thiểu

[
  {
    "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."
  }
]

Đồng thời gửi các bộ dữ liệu kiểm thử phủ định cho mili giây Unix, chuỗi số, số thực, múi giờ IANA không hợp lệ, from >= to, external_id trùng lặp, các khối chồng lấn, khối qua đêm, hơn tám khối trong một ngày, hơn 50 khung thời gian và các khóa phạm vi chưa được ánh xạ.

Lưu hội viên

Tạo hoặc cập nhật bản ghi hội viên. API xác định việc tạo mới hay cập nhật dựa trên member_id.

Tham số

  • members array bắt buộc

    Mảng các đối tượng Member cần lưu. Khuyến nghị tối đa: 1000 mục mỗi yêu cầu để đạt hiệu suất tối ưu. API tự động chia lô các mục để xử lý. Mỗi mục phải có facility_id (bắt buộc nếu không dùng linking_identifier) hoặc linking_identifier (bắt buộc nếu không dùng facility_id).

    Khi một hội viên có access_time_windows, hội viên đó cũng phải có access_time_windows_revision. Mảng này là ảnh chụp nhanh đầy đủ từ nguồn, không phải bản vá. Bỏ qua mảng để giữ nguyên ảnh chụp nhanh hiện có, hoặc gửi [] với phiên bản mới hơn để thu hồi mọi khung thời gian thuộc nguồn. Hãy đọc hướng dẫn Access Time Windows trước khi bật trường này.

Giá trị trả về

Trả về một thông báo đơn giản xác nhận thao tác đồng bộ.

Các trường hồ sơ hội viên vẫn được upsert bình thường ngay cả khi ảnh chụp nhanh khung thời gian được báo cáo là phát lại idempotent hoặc bị bỏ qua do đã cũ. Một ảnh chụp nhanh xung đột cùng phiên bản/khác payload không thể thử lại mà không thay đổi; hãy đối soát trạng thái nguồn và gửi phiên bản mới hơn.

Yêu cầu

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
          }
        ]
      }
    ]
  }'

Phản hồi

Trả về thông báo thành công kèm siêu dữ liệu về thao tác đồng bộ.

{
  "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"
      }
    ]
  }
}

Các trường siêu dữ liệu:

  • success - Số hội viên đã được xử lý thành công
  • skipped - Số hội viên bị bỏ qua (nếu có)
  • skipped_items - Mảng các hội viên bị bỏ qua kèm lý do (nếu có)
  • dry-run - Cờ boolean nếu sử dụng loại khóa dryrun (nếu áp dụng)

Check-in

Đại diện cho bản ghi về việc một người có mặt tại một cơ sở, lớp học hoặc hoạt động. Được dùng để theo dõi lượt tham dự, phân tích mức sử dụng và cải thiện độ chính xác của nhận diện hình ảnh.

Các endpoint

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

Đối tượng Check-In

Thuộc tính

  • check_in_id string tùy chọn

    Mã định danh duy nhất của lượt check-in. Không bắt buộc - được tạo tự động từ cặp member_id và timestamp nếu không được cung cấp.

  • member_id string bắt buộc

    Mã định danh duy nhất của hội viên.

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh duy nhất của cơ sở trong Performance Hub.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Giá trị mã định danh duy nhất mà đối tác dùng cho từng địa điểm (ví dụ: "Branch ID", "Location Code", "Store Number"). Tìm hiểu thêm

  • check_in_type string tùy chọn

    Loại lượt ghé thăm. Một trong các giá trị member, class, staff, guest hoặc trial.

  • source string tùy chọn

    Cách thức ghi nhận lượt check-in. Các giá trị phổ biến gồm manual, tag, rfid, kiosk, app. Cũng có thể sử dụng các giá trị khác như door_reader hoặc booking.

  • class_id string tùy chọn

    Không bắt buộc. Dùng khi lượt check-in gắn với một lượt đặt chỗ hoặc tham dự lớp học.

  • timestamp string bắt buộc

    Dấu thời gian theo định dạng ISO 8601 cho biết thời điểm diễn ra lượt check-in.

Đối tượng 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"
}

Lưu check-in

Tạo các bản ghi check-in. API tự động loại bỏ trùng lặp dựa trên hội viên, cơ sở và dấu thời gian.

Tham số

  • check_ins array bắt buộc

    Mảng các đối tượng Check-In cần lưu. Khuyến nghị tối đa: 1000 mục mỗi yêu cầu để đạt hiệu suất tối ưu. API tự động chia lô các mục để xử lý. Mỗi mục phải có facility_id (bắt buộc nếu không dùng linking_identifier) hoặc linking_identifier (bắt buộc nếu không dùng facility_id).

Giá trị trả về

Trả về một thông báo đơn giản xác nhận thao tác đồng bộ.

Yêu cầu

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"
      }
    ]
  }'

Phản hồi

Trả về thông báo thành công kèm siêu dữ liệu về thao tác đồng bộ.

{
  "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"
      }
    ]
  }
}

Các trường siêu dữ liệu:

  • success - Số lượt check-in đã được xử lý thành công
  • skipped - Số lượt check-in bị bỏ qua (nếu có)
  • skipped_items - Mảng các lượt check-in bị bỏ qua kèm lý do (nếu có)
  • dry-run - Cờ boolean nếu sử dụng loại khóa dryrun (nếu áp dụng)

Kiểm soát ra vào

Partner API có thể kích hoạt phần cứng Door/Gate Controller của Performance Hub tại các cơ sở đã bật tích hợp của bạn.

Sử dụng API này khi hệ thống quản lý hội viên của bạn đã quyết định rằng một người được phép vào. Performance Hub không đánh giá trạng thái hội viên, giờ ra vào, quy tắc khu vực cửa, kiểm tra gian lận hoặc logic tạm ngưng. Hệ thống của bạn vẫn là bên có thẩm quyền đối với các quyết định đó.

Yêu cầu mở khóa là đồng bộ. Performance Hub gửi lệnh đến bộ điều khiển tại chỗ theo thời gian thực và chỉ trả về 200 sau khi thiết bị xác nhận rằng rơ-le đã thực sự mở khóa. Hầu hết các xác nhận sẽ hoàn tất trong 3-5 giây. Nếu không nhận được xác nhận trong khoảng thời gian chờ, API sẽ trả về lỗi rõ ràng.

Bạn cũng có thể ghi lại một lượt thử hoặc lượt từ chối ra vào chưa từng đến được bộ điều khiển. Lệnh gọi đó không mở khóa cửa. Nó ghi một sự kiện vào Nhật ký truy cập của Door & Gate Access.

Các endpoint

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

Đối tượng Door/Gate Controller

Thuộc tính

  • door_id string bắt buộc

    Mã định danh duy nhất của Door/Gate Controller. Lưu giá trị này trong hệ thống của bạn sau khi phát hiện và sử dụng khi gọi endpoint mở khóa.

  • facility_id string bắt buộc

    ID cơ sở trong Performance Hub.

  • linking_identifier string tùy chọn

    Mã định danh cơ sở của đối tác khi tích hợp của bạn sử dụng mã định danh liên kết. Tìm hiểu thêm

  • name string bắt buộc

    Tên thiết bị dễ đọc được cấu hình trong Performance Hub.

  • zone string tùy chọn

    Khu vực hoặc vị trí của cửa, chẳng hạn Entrance.

  • status string bắt buộc

    online hoặc offline.

  • relay_state string tùy chọn

    Trạng thái rơ-le gần nhất đã biết, chẳng hạn locked hoặc unlocked.

  • maintenance_mode string bắt buộc

    Chế độ bảo trì hiện tại. Một trong các giá trị off, force-open hoặc force-closed.

  • hold_time_seconds integer bắt buộc

    Thời gian giữ mở khóa mặc định được cấu hình cho cửa.

  • last_seen string tùy chọn

    Dấu thời gian ISO của lần cập nhật siêu dữ liệu thiết bị gần nhất.

Đối tượng 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"
}

Liệt kê Door/Gate Controller

Trả về các Door/Gate Controller mà tích hợp của bạn có thể sử dụng.

Nếu không cung cấp facility_id hoặc linking_identifier, API sẽ trả về Door/Gate Controller trên tất cả các cơ sở được liên kết với tài khoản đối tác của bạn.

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.

Tham số

  • facility_id string tùy chọn một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    ID cơ sở trong Performance Hub. Sử dụng tham số này cho tích hợp liên kết trực tiếp.

  • linking_identifier string tùy chọn một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh cơ sở/địa điểm của riêng bạn. Sử dụng tham số này khi tích hợp của bạn được cấu hình dùng mã định danh liên kết.

Giá trị trả về

Trả về một mảng các đối tượng Door/Gate Controller.

Yêu cầu

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:

Phản hồi

{
  "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"
    }
  ]
}

Lấy trạng thái Door/Gate Controller

Truy xuất trạng thái gần nhất đã biết và cấu hình cơ bản của một Door/Gate Controller.

Cung cấp mã định danh cơ sở để Performance Hub có thể xác minh rằng cửa thuộc về một cơ sở mà tích hợp của bạn có quyền truy cập.

Tham số

  • door_id string bắt buộc

    ID của Door/Gate Controller do endpoint liệt kê trả về.

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    ID cơ sở trong Performance Hub. Bắt buộc đối với tích hợp liên kết trực tiếp.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh cơ sở của đối tác. Bắt buộc đối với tích hợp dùng mã định danh liên kết.

Giá trị trả về

Trả về một đối tượng Door/Gate Controller.

Yêu cầu

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:

Phản hồi

{
  "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"
  }
}

Mở khóa Door/Gate Controller

Gửi lệnh mở khóa đến Door/Gate Controller và chờ rơ-le vật lý xác nhận đã mở khóa.

Hệ thống của bạn phải quyết định người đó có được cấp phép hay không trước khi gọi endpoint này. Performance Hub chỉ xác minh khóa đối tác, quyền truy cập cơ sở, quyền sở hữu cửa và trạng thái thiết bị.

Tham số

  • door_id string bắt buộc

    ID của Door/Gate Controller do endpoint liệt kê trả về.

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    ID cơ sở trong Performance Hub. Bắt buộc đối với tích hợp liên kết trực tiếp.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh cơ sở của đối tác. Bắt buộc đối với tích hợp dùng mã định danh liên kết.

  • member_id string bắt buộc

    ID hội viên của đối tác. Giá trị này được dùng cho nhật ký kiểm toán và liên kết dữ liệu sau này.

  • first_name string bắt buộc

    Tên của người mở cửa.

  • last_name string bắt buộc

    Họ của người mở cửa.

  • full_name string tùy chọn

    Không bắt buộc. Nếu bỏ qua, Performance Hub sẽ ghép first_name và last_name.

  • check_in_id string tùy chọn

    ID check-in không bắt buộc từ hệ thống của bạn để đối chiếu.

  • idempotency_key string tùy chọn

    Khóa chống phát lại không bắt buộc. Dùng lại cùng một khóa cho cùng đối tác, cơ sở và cửa sẽ trả về kết quả hiện có nếu có.

Giá trị trả về

Chỉ trả về 200 khi thiết bị xác nhận rơ-le đã thực sự mở khóa. Cửa sử dụng thời gian giữ được cấu hình trong Quản lý thiết bị của Performance Hub; đối tác không thể ghi đè thời gian rơ-le cho từng yêu cầu. Hầu hết các xác nhận sẽ hoàn tất trong 3-5 giây. Hãy coi trường hợp hết thời gian chờ được nêu trong tài liệu là một lần mở khóa thất bại rõ ràng và chỉ thử lại theo các quy tắc an toàn của riêng bạn.

Các lỗi thường gặp:

  • 403 integration_not_enabled - tích hợp của bạn chưa được bật cho cơ sở.
  • 409 maintenance_mode_active - nhân viên cơ sở đã bật chế độ bảo trì cho cửa.
  • 503 device_offline - Door/Gate Controller đang ngoại tuyến hoặc dữ liệu đã cũ.
  • 504 unlock_confirmation_timeout - lệnh đã được gửi nhưng không nhận được xác nhận tương ứng trước khi hết thời gian chờ.

Yêu cầu

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"
  }'

Phản hồi

{
  "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"
}

Phản hồi lỗi

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

Ghi lại lượt thử hoặc lượt từ chối ra vào

Ghi lại một lượt thử hoặc lượt từ chối ra vào mà hệ thống của bạn đã quyết định. Door/Gate Controller không được liên hệ và cửa không mở khóa.

Sử dụng endpoint này khi hệ thống của bạn từ chối cho vào, hoặc khi một lượt thử cần xuất hiện trong Nhật ký truy cập của Door & Gate Access mà không mở khóa. Performance Hub không đánh giá trạng thái hội viên, giờ ra vào hoặc các quy tắc ra vào khác.

Một sự kiện bị từ chối xuất hiện trong Nhật ký truy cập của Door & Gate Access với kết quả Denied, tên đối tác của bạn, cửa, mã định danh hội viên khi bạn gửi và mã lý do ở dạng dễ đọc. Ví dụ: membership_expired được hiển thị là "Membership Expired". reason_display_text và user_email được lưu cùng với sự kiện.

Tham số

  • door_id string bắt buộc

    ID của Door/Gate Controller do endpoint liệt kê trả về.

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    ID cơ sở trong Performance Hub. Bắt buộc đối với tích hợp liên kết trực tiếp.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh cơ sở của đối tác. Bắt buộc đối với tích hợp dùng mã định danh liên kết.

  • outcome string bắt buộc

    denied hoặc attempted.

  • reason string tùy chọn

    Mã lý do dạng snake_case chữ thường, tối đa 64 ký tự. Bắt buộc khi outcome là denied. Ví dụ: membership_expired.

  • reason_display_text string tùy chọn

    Lý do ở dạng dễ đọc, tối đa 256 ký tự. Ví dụ: Membership expired on 2026-04-01.

  • member_id string tùy chọn

    ID hội viên của đối tác. Bỏ qua trường này khi thông tin xác thực không khớp với hội viên nào, chẳng hạn một thẻ không xác định.

  • user_email string tùy chọn

    Email của người đã thử ra vào.

  • timestamp string tùy chọn

    Thời điểm diễn ra lượt thử, theo định dạng ISO 8601 có múi giờ. Ví dụ: 2026-05-18T10:15:30Z. Mặc định là thời điểm nhận được yêu cầu. Không được muộn hơn hiện tại quá 5 phút hoặc cũ hơn 30 ngày.

  • idempotency_key string tùy chọn

    Khóa chống phát lại, tối đa 128 ký tự. Dùng lại cùng một khóa cho cùng đối tác, cơ sở và cửa sẽ trả về kết quả ban đầu.

Giá trị trả về

Trả về 201 khi sự kiện được ghi lại. Gửi lại cùng một idempotency_key sẽ trả về 200 với idempotent được đặt thành true và không tạo thêm sự kiện nào.

Khóa dry-run trả về 200 với dry_run được đặt thành true. Không có gì được ghi lại.

Các lỗi thường gặp:

  • 400 - nội dung yêu cầu không hợp lệ, lượt từ chối không có reason, dấu thời gian nằm ngoài phạm vi, hoặc facility_id / linking_identifier không khớp với cơ sở đã liên kết.
  • 403 - khóa là loại chỉ đọc.
  • 403 integration_not_enabled - tích hợp của bạn chưa được bật cho cơ sở. message cho biết lý do.
  • 404 - không tìm thấy Door/Gate Controller cho cơ sở đã liên kết.

Yêu cầu

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"
  }'

Phản hồi

{
  "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"
}

Phát lại 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
}

Báo cáo cơ sở

Bản ghi tại một thời điểm, ghi lại các chỉ số vận hành và tài chính chính của một cơ sở trong một kỳ cụ thể.

Các endpoint

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

Đối tượng Report Snapshot

Thuộc tính

  • facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Mã định danh duy nhất của cơ sở trong Performance Hub.

  • linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

    Giá trị mã định danh duy nhất mà đối tác dùng cho từng địa điểm (ví dụ: "Branch ID", "Location Code", "Store Number"). Tìm hiểu thêm

  • start_date string bắt buộc

    Ngày bắt đầu kỳ của ảnh chụp nhanh theo định dạng YYYY-MM-DD.

  • end_date string bắt buộc

    Ngày kết thúc kỳ của ảnh chụp nhanh theo định dạng YYYY-MM-DD.

  • metrics object bắt buộc

    Đối tượng chỉ số chứa dữ liệu hội viên và doanh thu trong kỳ.

Đối tượng 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"
    }
  }
}

Lưu ảnh chụp nhanh báo cáo

Gửi các chỉ số vận hành và tài chính của một cơ sở trong một kỳ cụ thể.

Tham số

  • snapshots array bắt buộc

    Mảng các đối tượng Report Snapshot cần lưu. Tối đa 25 mục mỗi yêu cầu. Mỗi mục phải có facility_id (bắt buộc nếu không dùng linking_identifier) hoặc linking_identifier (bắt buộc nếu không dùng facility_id).

Giá trị trả về

Trả về một thông báo đơn giản xác nhận thao tác đồng bộ.

Yêu cầu

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"
          }
        }
      }
    ]
  }'

Phản hồi

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

Lỗi

Partner API sử dụng mã trạng thái HTTP tiêu chuẩn và nội dung phản hồi JSON để giải thích lý do yêu cầu thất bại.

Cấu trúc phản hồi lỗi

Hầu hết các lỗi API trả về nội dung JSON gồm một thông báo và, khi có, các chi tiết có cấu trúc.

Mã trạng thái

Lỗi Access Time Window

Bước kiểm tra khung thời gian thất bại trước khi ảnh chụp nhanh không hợp lệ được ghi. Các nguyên nhân phổ biến không thể thử lại gồm:

  • Thiếu access_time_windows_revision khi có access_time_windows.
  • Giá trị epoch dạng chuỗi, dạng số thực hoặc có khả năng tính bằng mili giây.
  • Múi giờ IANA không hợp lệ, khoảng thời gian bị đảo ngược, external_id trùng lặp, các khối hằng tuần chồng lấn hoặc một khối qua đêm chưa được tách.
  • Giá trị nằm ngoài giới hạn về số lượng, độ dài hoặc khoảng thời gian được nêu trong tài liệu.

Một phiên bản lặp lại với nội dung đã chuẩn hóa khác sẽ trả về 409 Conflict. Hãy đối soát với trạng thái có thẩm quyền mới nhất và cấp một phiên bản mới hơn; không tiếp tục thử lại cặp đang xung đột. Một phiên bản cũ hơn được báo cáo là ảnh chụp nhanh cũ bị bỏ qua thay vì được phép ghi đè trạng thái mới hơn. Một scope_key không xác định hoặc chưa được ánh xạ sẽ không được cấp quyền truy cập và cần được xử lý như một cảnh báo cấu hình.

Nếu việc gửi bị hết thời gian chờ hoặc nhận lỗi 5xx tạm thời, hãy thử lại đúng ảnh chụp nhanh đã chuẩn hóa đó với cùng phiên bản. Nếu việc truy xuất từ nguồn upstream thất bại, hãy bỏ hoàn toàn trường khung thời gian; không bao giờ thay thế bằng một mảng rỗng.

Hướng dẫn thử lại

Thử lại các lỗi sau với thời gian chờ tăng theo cấp số nhân có giới hạn:

  • 429
  • 500
  • 502
  • 503
  • 504

Không thử lại một cách mù quáng đối với các lỗi sau:

  • 400
  • 401
  • 403
  • 404
  • 409
  • 422

Đối với kiểm soát ra vào, luôn coi các phản hồi hết thời gian chờ và ngoại tuyến là lần mở khóa thất bại, trừ khi các quy tắc ra vào và quy trình an toàn của riêng bạn quy định khác.

Thông tin cần cung cấp cho bộ phận hỗ trợ

Khi liên hệ bộ phận hỗ trợ, hãy cung cấp:

  • Endpoint và phương thức HTTP.
  • Dấu thời gian và múi giờ.
  • ID khóa đối tác, không phải khóa bí mật.
  • Mã định danh cơ sở đã sử dụng.
  • ID bản ghi nguồn từ hệ thống của bạn.
  • Trạng thái và nội dung phản hồi.
  • event_id hoặc command_id nếu có.
{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

Một số endpoint theo lĩnh vực cụ thể trả về trạng thái và lý do rõ ràng. Ví dụ: các lỗi kiểm soát ra vào bao gồm các trường như reason, door_id, facility_id và 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

Yêu cầu sai định dạng hoặc thiếu các trường bắt buộc. Hãy sửa yêu cầu trước khi thử lại.

401 Unauthorized

Xác thực thất bại. Hãy kiểm tra rằng bạn đang sử dụng HTTP Basic Auth với khóa bí mật API làm tên người dùng và mật khẩu để trống.

403 Forbidden

Khóa hợp lệ nhưng thao tác không được phép. Các nguyên nhân phổ biến gồm dùng khóa chỉ đọc cho thao tác ghi hoặc cố truy cập một cơ sở chưa bật tích hợp của bạn.

404 Not Found

Không tìm thấy tài nguyên được yêu cầu hoặc tài nguyên đó không khả dụng với tích hợp của bạn.

409 Conflict

Yêu cầu xung đột với trạng thái hiện tại của tài nguyên. Đối với kiểm soát ra vào, trường hợp này có thể bao gồm việc Door/Gate Controller đang ở chế độ bảo trì.

422 Unprocessable Entity

Yêu cầu là JSON hợp lệ nhưng không vượt qua bước kiểm tra ngữ nghĩa. Hãy sửa dữ liệu trước khi thử lại.

429 Too Many Requests

Tích hợp đã vượt quá giới hạn tốc độ được nêu trong tài liệu. Hãy thử lại với thời gian chờ tăng theo cấp số nhân.

500 Internal Server Error

Performance Hub không thể hoàn tất yêu cầu do lỗi nội bộ. Hãy thử lại với thời gian chờ tăng dần. Nếu sự cố vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ kèm endpoint, dấu thời gian và nội dung phản hồi.

503 Service Unavailable

Một dịch vụ hoặc thiết bị phụ thuộc không khả dụng. Đối với thao tác mở khóa Door/Gate Controller, điều này có thể có nghĩa là bộ điều khiển đang ngoại tuyến.

504 Gateway Timeout

Thao tác đã hết thời gian chờ. Đối với thao tác mở khóa Door/Gate Controller, điều này có nghĩa là việc mở khóa chưa được xác nhận trước khi hết khoảng thời gian chờ.

Quản lý phiên bản

Partner API được đánh phiên bản trong URL. Phiên bản hiện tại là:

Chính sách thay đổi

Performance Hub hướng đến việc thực hiện các thay đổi bổ sung, tương thích ngược bất cứ khi nào có thể.

Ví dụ về các thay đổi tương thích ngược:

  • Thêm một trường không bắt buộc mới vào yêu cầu.
  • Thêm một trường mới vào phản hồi.
  • Thêm một endpoint mới.
  • Thêm một giá trị enum mới ở những nơi ứng dụng khách được kỳ vọng xử lý các giá trị không xác định.
  • Cải thiện thông báo kiểm tra dữ liệu mà không thay đổi cam kết về mã trạng thái.

access_time_windows và access_time_windows_revision là các trường bổ sung trong yêu cầu Member. Các ứng dụng khách hiện có bỏ qua các trường này sẽ giữ nguyên ảnh chụp nhanh Access Time Window đã lưu. Quy tắc bỏ qua này duy trì khả năng tương thích với upsert một phần; việc bỏ qua không tương đương với việc gửi một mảng rỗng.

Ví dụ về các thay đổi gây gián đoạn:

  • Xóa hoặc đổi tên một trường.
  • Thay đổi kiểu dữ liệu của một trường.
  • Chuyển một trường yêu cầu không bắt buộc thành bắt buộc.
  • Xóa một endpoint.
  • Thay đổi ý nghĩa của một mã trạng thái hiện có hoặc một reason theo lĩnh vực cụ thể.

Ngừng hỗ trợ

Khi cần thực hiện một thay đổi gây gián đoạn, Performance Hub sẽ tránh thay đổi trực tiếp phiên bản hiện có khi có thể. Thay vào đó, chúng tôi sẽ giới thiệu một phiên bản mới hoặc lộ trình chuyển đổi và thông báo thay đổi cho các đối tác bị ảnh hưởng.

Thông báo ngừng hỗ trợ có thể bao gồm:

  • Một mục trong nhật ký thay đổi.
  • Liên lạc trực tiếp với đối tác.
  • Ghi chú trong Partner Console.
  • Hướng dẫn chuyển đổi trong tài liệu.

Khuyến nghị cho ứng dụng khách

Xây dựng ứng dụng khách có khả năng chấp nhận các thay đổi bổ sung:

  • Bỏ qua các trường phản hồi mà bạn không sử dụng.
  • Coi các giá trị enum không xác định là không được hỗ trợ thay vì để ứng dụng gặp sự cố.
  • Tránh kiểm tra so khớp phản hồi một cách tuyệt đối.
  • Ghi nhật ký các giá trị không nhận dạng được để bạn có thể chủ động cập nhật tích hợp của mình.

Đối với các phân vùng Member có phiên bản như Access Time Windows, hãy lưu lại phiên bản đã gửi và payload đã chuẩn hóa cho đến khi biết kết quả. Dùng lại một phiên bản cho nội dung đã thay đổi là xung đột, còn phát lại cùng nội dung là idempotent. Xem Access Time Windows.

Đặc tả OpenAPI

Sử dụng các đặc tả OpenAPI đã công bố để tạo ứng dụng khách, kiểm tra yêu cầu và theo dõi các thay đổi về cấu trúc API theo thời gian.

Xem Đặc tả OpenAPI.

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

Nhật ký thay đổi

Nhật ký thay đổi này ghi lại các thay đổi đáng chú ý của Partner API và Partner Console có ảnh hưởng đến hoạt động của tích hợp.

2026-09-09

2026-05-06

2026-05-01

Các loại thay đổi

Các mục trong tương lai sử dụng các loại sau:

  • Added - endpoint, trường, hướng dẫn hoặc khả năng mới.
  • Changed - hoạt động hoặc tài liệu đã thay đổi nhưng không ngừng hỗ trợ.
  • Deprecated - tính năng vẫn khả dụng nhưng đã có lộ trình chuyển đổi theo kế hoạch.
  • Removed - tính năng hoặc endpoint đã bị gỡ bỏ.
  • Fixed - sửa lỗi hoặc đính chính tài liệu.
  • Security - thay đổi về xác thực, phân quyền, xử lý dữ liệu hoặc quản lý khóa.

Đã thêm

  • Đã thêm ảnh chụp nhanh access_time_windows của Member, không phụ thuộc nhà cung cấp, kết hợp các khung thời gian tuyệt đối và khung thời gian lặp lại hằng tuần.
  • Đã thêm cơ chế sắp xếp theo access_time_windows_revision, phát lại idempotent, xung đột, bỏ qua dữ liệu cũ và thu hồi rõ ràng.
  • Đã thêm hướng dẫn về múi giờ IANA, giờ mùa hè, ánh xạ scope_key logic, độ mới của dữ liệu nguồn, cách triển khai phía bên tạo dữ liệu và chứng nhận.

Đã thêm

  • Đã thêm tài liệu chương trình đối tác về các loại đối tác, quy trình tiếp nhận, phương pháp hay nhất, sự sẵn sàng đưa vào hoạt động, lỗi, quản lý phiên bản và hỗ trợ.
  • Đã thêm luồng gửi yêu cầu Trở thành đối tác riêng cho các đối tác kỹ thuật và thương mại tiềm năng.
  • Đã thêm tài liệu về cách các tích hợp đối tác đã được phê duyệt xuất hiện trong danh bạ đối tác của Performance Hub trên nền tảng Performance Hub cốt lõi.

Đã thêm

  • Đã thêm tài liệu kiểm soát ra vào cho Door/Gate Controller, bao gồm các thao tác liệt kê, trạng thái và mở khóa.
  • Đã thêm tài liệu về hoạt động mở khóa đồng bộ: API chỉ trả về kết quả thành công sau khi bộ điều khiển tại chỗ xác nhận rơ-le đã thực sự mở khóa.
  • Đã thêm tài liệu hỗ trợ idempotency_key không bắt buộc cho các yêu cầu mở khóa Door/Gate Controller.