Pengenalan

Partner API Performance Hub membolehkan platform rakan kongsi luaran berintegrasi dengan lancar dengan modul teras Performance Hub. API ini menyokong penglihatan komputer, analitik, pengelogan akses ahli dan cerapan kemudahan.

Format Permintaan

API menerima badan permintaan berkod JSON dan mengembalikan respons berkod JSON.

Pengehadan Kadar

Untuk memastikan penggunaan yang adil dan kestabilan sistem, akaun Partner API bermula dengan had lalai:

5 permintaan sesaat bagi setiap titik akhir
Disyorkan: maksimum 1000 item bagi setiap permintaan kelompok untuk prestasi optimum
Saiz muatan maksimum 10MB

Had kadar boleh dilaraskan dan boleh dikonfigurasikan mengikut kes oleh pengurus akaun rakan kongsi Performance Hub anda. Jika integrasi anda memerlukan daya pemprosesan yang lebih tinggi untuk pelancaran, migrasi, pengisian semula laporan atau kemudahan volum tinggi, bangkitkan perkara ini semasa penyertaan atau sebelum tetingkap perubahan yang dirancang.

URL Asas

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

Pengesahan

Akses kepada Partner API memerlukan pengesahan menggunakan kunci rahsia API. Jana dan urus kunci anda melalui Partner Console.

Kunci API berfungsi sebagai kelayakan anda untuk mengakses sumber rakan kongsi. Setiap kunci mempunyai akses terhad kepada data organisasi tertentu dan boleh dinyahaktifkan serta-merta apabila perlu.

Kendalikan kunci API anda dengan berhati-hati—kunci ini memberikan akses penuh kepada akaun anda! Jangan sekali-kali dedahkan kunci ini dalam repositori awam, aplikasi sisi klien atau di mana-mana tempat yang boleh menyebabkannya terjejas.

Sahkan permintaan menggunakan HTTP Basic Auth dengan menghantar kunci API anda sebagai nama pengguna. Biarkan kata laluan kosong.

API hanya menerima sambungan HTTPS yang selamat. Permintaan HTTP biasa ditolak, begitu juga sebarang permintaan yang tidak mempunyai kelayakan pengesahan yang betul.

Contoh Permintaan

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.

Sahkan Kunci Rahsia

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

Senarai Semak Go-Live

Gunakan senarai semak ini sebelum mendayakan integrasi rakan kongsi untuk kemudahan pengeluaran.

Persediaan Partner Console

Profil rakan kongsi anda lengkap.
URL logo, laman web, kategori dan penerangan anda tepat.
Kaedah pemautan data anda telah dikonfigurasikan: Direct Link atau Linking Identifier.
Pemautan kemudahan telah diuji dengan sekurang-kurangnya satu kemudahan sebenar.
Jenis kunci yang betul sedang digunakan:
- Dryrun untuk ujian tulis yang tidak merosakkan.
- Read-only untuk penggunaan data yang selamat.
- Live hanya apabila anda bersedia untuk menjejaskan data pengeluaran.

Pengesahan dan pengurusan kunci

Kunci rahsia disimpan di sisi pelayan sahaja.
Kunci tidak dibenamkan dalam aplikasi sisi klien, aplikasi mudah alih, repositori awam atau tiket sokongan.
Putaran dan pembatalan kunci telah diuji.
Pasukan anda tahu kunci mana yang digunakan oleh setiap persekitaran.

Pengesahan data

Medan yang diperlukan hadir untuk setiap titik akhir yang anda panggil.
Pengecam kemudahan sepadan dengan kaedah pemautan yang anda konfigurasikan.
ID daripada sistem anda stabil dan tidak berubah antara penyegerakan.
Import besar dibahagikan kepada kelompok di bawah had yang didokumenkan.
Item kelompok yang gagal boleh dikenal pasti dan dihantar semula.

Ujian titik akhir

Sebelum pelancaran, uji setiap titik akhir yang menjadi pergantungan integrasi anda:

Organisasi dan kemudahan boleh dibaca.
Ahli boleh disimpan dan dikemas kini.
Pelan keahlian, zon akses dan waktu akses disegerakkan dengan betul.
Daftar masuk diterima dan boleh dikaitkan semula dengan sistem anda.
Petikan laporan menggunakan tempoh pelaporan dan metrik yang dijangkakan.
Aliran Door/Gate Controller diuji pada perkakasan sebenar jika berkenaan.

Kesediaan Access Time Window

Jika integrasi membekalkan Access Time Windows:

Contoh mutlak dan mingguan lulus senarai semak pensijilan pengeluar.
Epoch ialah integer saat Unix tanpa tanda petik; sempadan [from, to) yang tepat telah diuji.
Lalai UTC, zon waktu IANA tersuai integrasi dan peralihan waktu jimat siang yang berkaitan telah disahkan.
Satu aliran semakan ahli/sumber yang tahan lama dan monoton menyelaraskan kemas kini tokokan, penyesuaian dan cubaan semula.
Pengendali memahami tingkah laku medan yang ditinggalkan, penggantian lengkap, idempoten, bercanggah, lapuk dan [] eksplisit.
Setiap scope_key, termasuk default, mempunyai pemetaan Performance Hub yang diluluskan; kunci yang tidak diketahui telah diuji untuk memastikan akses tidak diberikan.
Kekerapan muat semula yang dijangkakan, usia sumber maksimum, tingkah laku sumber lapuk dan amaran bagi integrasi telah dikonfigurasikan.
Kegagalan pengambilan huluan telah dibuktikan tidak menghasilkan petikan kosong atau separa.
Penumpuan aliran peringkat, pembatalan/penarikan balik dan sempadan mula/tamat pintu fizikal memenuhi sasaran yang dipersetujui.
Peraturan biasa dan pemberian kekal telah disahkan sebagai laluan sandaran, dan tetingkap tidak boleh memintas penyahdayaan pengguna, blockAllAccess, penyelenggaraan atau geofencing.

Kesediaan kawalan akses

Untuk integrasi kawalan akses:

Sistem anda membuat keputusan akses sebelum memanggil Performance Hub.
Integrasi mengendalikan device_offline, maintenance_mode_active dan unlock_confirmation_timeout.
Pengendali memahami bahawa tamat masa bermaksud buka kunci tidak disahkan.
Log anda menyimpan event_id dan command_id yang dikembalikan.
Anda mempunyai proses sandaran manual untuk kakitangan kemudahan.

Pengendalian ralat dan cubaan semula

Respons 400, 401, 403, 404, 409 dan 422 dimaklumkan kepada pengendali atau pasukan sokongan dan bukannya dicuba semula secara membuta tuli.
Respons 429, 500, 502, 503 dan 504 menggunakan logik cubaan semula yang terhad dengan penundaan.
Kegagalan berulang mencipta amaran dalam sistem anda.
Integrasi tidak sekali-kali menggugurkan rekod yang gagal secara senyap.

Kebolehcerapan

Log anda merangkumi titik akhir, cap masa, pengecam kemudahan, ID rekod sumber, hasil permintaan dan badan respons.
Pasukan sokongan anda boleh mencari mengikut ID ahli, ID kemudahan, ID daftar masuk atau ID peristiwa buka kunci.
Anda mempunyai cara untuk memainkan semula atau menyelaraskan penyegerakan yang gagal.

Pelancaran pengeluaran

Performance Hub telah mengesahkan akses pengeluaran anda.
Sekurang-kurangnya satu kemudahan pengeluaran telah mendayakan integrasi anda.
Kunci pengeluaran anda aktif.
Hubungan operasi dan teknikal anda terkini.
Proses sokongan anda didokumenkan untuk pelanggan.

Selepas semakan ini selesai, integrasi anda yang dikonfigurasikan akan dipaparkan dalam direktori rakan kongsi Performance Hub di dalam platform teras Performance Hub.

Amalan Terbaik

Gunakan corak ini untuk memastikan integrasi rakan kongsi boleh dijangka, boleh diperhatikan dan selamat untuk kemudahan.

Kenal pasti kemudahan secara konsisten

Pilih kaedah pemautan yang dikonfigurasikan untuk akaun rakan kongsi anda dan gunakannya secara konsisten:

Direct Link - gunakan facility_id Performance Hub yang dikembalikan oleh titik akhir kemudahan.
Linking Identifier - gunakan pengecam lokasi anda sendiri, seperti ID cawangan, kod lokasi atau nombor kedai.

Jangan hantar kedua-dua pengecam dalam permintaan yang sama. Performance Hub menyelesaikan permintaan menggunakan kaedah pemautan yang dikonfigurasikan untuk akaun rakan kongsi anda.

Lihat Kaedah Pemautan Rakan Kongsi untuk panduan persediaan.

Tulis secara kelompok dengan berhati-hati

Partner API menerima badan permintaan JSON dan direka untuk aliran kerja penyegerakan berasaskan kelompok di mana didokumenkan. Pastikan kelompok terhad saiznya dan boleh dicuba semula.

Panduan lalai:

Gunakan sehingga 1000 item bagi setiap permintaan kelompok untuk prestasi optimum.
Pastikan muatan di bawah 10MB.
Kekal dalam had 5 permintaan sesaat bagi setiap titik akhir.

Had kadar boleh dilaraskan dan boleh dikonfigurasikan mengikut kes oleh pengurus akaun rakan kongsi Performance Hub anda. Jika anda menjangkakan import volum tinggi, trafik pelancaran atau pengisian semula laporan, persetujui daya pemprosesan yang diperlukan sebelum tetingkap perubahan.

Jika anda perlu menyegerakkan set data yang besar, bahagikannya kepada cebisan yang deterministik dan log setiap ID cebisan di pihak anda. Ini memudahkan anda memahami cubaan semula yang gagal.

Cuba semula dengan selamat

Gunakan penundaan eksponen untuk kegagalan sementara seperti 429, 500, 502, 503 dan 504.

Elakkan gelung cubaan semula yang rapat. Titik permulaan yang baik ialah:

Cuba semula selepas 1 saat.
Cuba semula selepas 2 saat.
Cuba semula selepas 4 saat.
Berhenti dan beri amaran jika operasi masih gagal.

Untuk kegagalan pengesahan seperti 400 atau 422, betulkan permintaan sebelum mencuba semula.

Gunakan idempotensi jika disokong

Titik akhir buka kunci Door/Gate Controller menyokong idempotency_key pilihan. Menggunakan semula kunci yang sama untuk rakan kongsi, kemudahan dan pintu yang sama mengembalikan hasil sedia ada apabila tersedia.

Gunakan kunci yang stabil untuk tindakan yang dilakukan, contohnya ID daftar masuk atau ID peristiwa akses daripada sistem anda.

Jangan anggap setiap titik akhir tulis menyokong idempotensi melainkan ia didokumenkan untuk titik akhir tersebut.

Pastikan data sumber bersih

Hantar nilai yang stabil dan dinormalkan di mana-mana yang boleh:

Gunakan ID ahli, pelan, kemudahan dan daftar masuk yang konsisten daripada sistem sumber anda.
Gunakan cap masa ISO 8601 untuk tarikh dan masa.
Hantar nombor telefon dalam format antarabangsa jika ada.
Hantar mata wang menggunakan medan yang didokumenkan untuk setiap titik akhir.
Elakkan membebankan medan teks bebas dengan data yang sepatutnya berada dalam medan berstruktur.

Reka untuk penyegerakan tokokan dan penuh

Kebanyakan integrasi rakan kongsi memerlukan kedua-duanya:

Penyegerakan tokokan untuk perubahan harian.
Penyegerakan penyesuaian penuh untuk membetulkan peristiwa yang terlepas, import sejarah atau hanyutan data.

Integrasi anda sepatutnya dapat menghantar semula keadaan semasa bagi ahli, pelan keahlian atau petikan laporan tanpa bergantung pada kejayaan permintaan sebelumnya.

Terbitkan Access Time Windows dengan selamat

Anggap nilai access_time_windows setiap ahli sebagai petikan lengkap yang disemak secara bebas:

Selaraskan satu aliran access_time_windows_revision yang meningkat secara monoton merentas pekerja tokokan dan penyesuaian.
Cuba semula penghantaran yang tidak pasti atau sementara dengan semakan dan muatan dinormalkan yang sama.
Tinggalkan access_time_windows apabila anda tidak mengemas kininya.
Hantar [] hanya selepas pengambilan sumber berautoriti yang berjaya membuktikan bahawa tiada tetingkap yang tinggal. Jangan sekali-kali jadikan tamat masa huluan, hasil separa atau kegagalan penghuraian sebagai pembatalan.
Pastikan external_id dan scope_key stabil, dan sahkan setiap pemetaan skop sebelum pengeluaran.
Pantau usia sumber berbanding dasar kesegaran yang dipersetujui untuk integrasi tersebut.

Lihat panduan pengeluar Access Time Windows yang berautoriti untuk petikan lengkap, zon waktu, DST, pembatalan dan vektor ujian.

Anggap kawalan akses sebagai kritikal keselamatan

Untuk buka kunci Door/Gate Controller:

Sistem anda mesti memutuskan sama ada orang itu dibenarkan masuk sebelum memanggil Performance Hub.
Performance Hub mengembalikan 200 hanya selepas pengawal di premis mengesahkan geganti telah dibuka kunci secara fizikal.
Kebanyakan pengesahan selesai dalam 3-5 saat.
Tamat masa ialah buka kunci yang gagal secara jelas, bukan kejayaan di latar belakang.
Cuba semula hanya mengikut peraturan akses dan keselamatan anda sendiri.

Sentiasa log event_id dan command_id yang dikembalikan oleh titik akhir buka kunci.

Pantau integrasi anda

Gunakan log permintaan Partner Console semasa pembangunan dan pelancaran. Dalam pengeluaran, selenggarakan juga log anda sendiri dengan:

Cap masa permintaan.
Titik akhir.
ID rekod sumber.
Pengecam kemudahan.
Kod status HTTP.
Badan respons atau mesej ralat Performance Hub.

Medan ini menjadikan sokongan dan penyesuaian jauh lebih pantas apabila pelanggan bertanya apa yang berlaku.

Organisasi

Mewakili entiti perniagaan peringkat atas yang mengendalikan satu atau lebih kemudahan yang diintegrasikan dengan platform Performance Hub.

Titik akhir

GET /partner/v1/organisations - List all organisations

Objek Organisasi

Atribut

org_id string wajib

Pengecam unik bagi organisasi.
name string wajib

Nama organisasi.

Objek Organisasi

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

Senaraikan semua organisasi

Mengembalikan senarai organisasi yang boleh diakses oleh akaun rakan kongsi anda.

Nilai pulangan

Mengembalikan objek JSON dengan sifat data yang mengandungi tatasusunan objek Organisasi.

Permintaan

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

Respons

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

Kemudahan

Mewakili lokasi fizikal, seperti pejabat, kedai, tempat acara, kampus, klinik atau gim, di mana ahli boleh mengakses perkhidmatan.

Titik akhir

GET /partner/v1/facilities - List all facilities

Objek Kemudahan

Atribut

facility_id string wajib

Pengecam unik bagi kemudahan.
org_id string wajib

Pengecam unik bagi organisasi induk.
name string wajib

Nama kemudahan.
brand string pilihan

Nama jenama yang digunakan oleh kemudahan.
website_url string pilihan

URL laman web kemudahan.
place_data object pilihan

Data lokasi daripada Google Places API yang mengandungi negara, alamat berformat, Google Place ID, wilayah dan bandar.
social_links object pilihan

Pautan media sosial untuk kemudahan.
timezone string pilihan

Pengecam zon waktu IANA (contohnya, "Australia/Sydney", "America/New_York").

Objek Kemudahan

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

Senaraikan semua kemudahan

Mengembalikan senarai kemudahan yang boleh diakses oleh akaun rakan kongsi anda.

Nilai pulangan

Mengembalikan objek JSON dengan sifat data yang mengandungi tatasusunan objek Kemudahan.

Permintaan

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

Respons

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

Pelan Keahlian

Mentakrifkan tawaran yang boleh dibeli daripada organisasi atau kemudahan, termasuk perkhidmatan, kelayakan, jadual dan harga.

Titik akhir

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

Objek Pelan Keahlian

Atribut

membership_plan_id string wajib

Pengecam unik bagi pelan keahlian.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam unik kemudahan daripada Performance Hub.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Nilai pengecam unik untuk setiap lokasi yang digunakan oleh rakan kongsi (contohnya, "Branch ID", "Location Code", "Store Number"). Ketahui lebih lanjut
name string wajib

Nama pelan yang boleh dibaca oleh manusia (contohnya, "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").
billing_cycle string pilihan

Kekerapan pengebilan. Salah satu daripada weekly, fortnightly, monthly, annually atau one_time.
price integer pilihan

Kos asas dalam unit mata wang terkecil (sen untuk USD/AUD).
currency string pilihan

Kod mata wang ISO 4217 (contohnya, "AUD", "USD").
description string pilihan

Penerangan pemasaran atau dalaman pilihan.
active_members integer pilihan

Bilangan ahli aktif yang menggunakan pelan keahlian ini
is_recurring boolean pilihan

Sama ada pelan diperbaharui secara automatik.
is_trial boolean pilihan

Sama ada ini ialah tawaran percubaan.
visible_to_public boolean pilihan

Sama ada pelan tersedia untuk pembelian layan diri.
duration_days integer pilihan

Bilangan hari pelan keahlian sah.
access_zones array pilihan

Tatasusunan zon akses yang termasuk dalam pelan keahlian. Setiap zon boleh mentakrifkan waktu aksesnya sendiri. Lihat Zon Akses untuk butiran.
class_limit integer pilihan

Bilangan maksimum kelas yang dibenarkan (null untuk tanpa had).

Objek Pelan Keahlian

Contoh ini menggunakan facility_id. Untuk integrasi Linking Identifier, hantar "linking_identifier": "branch_downtown" sebagai gantinya.

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

Zon Akses

Zon akses mentakrifkan kawasan tertentu dalam sesebuah kemudahan di mana pelan keahlian memberikan akses. Setiap zon boleh mempunyai waktu aksesnya sendiri, membolehkan sekatan masa yang berbeza bagi setiap kawasan.

Struktur

Setiap zon akses merangkumi:

name string wajib

Nama zon (contohnya, "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor").
description string pilihan

Penerangan tentang perkara yang termasuk dalam zon tersebut.
access_hours object pilihan

Waktu akses khusus untuk zon ini. Lihat Waktu Akses untuk format julat masa.

Contoh

Bangunan pejabat dengan gim untuk penyewanya: akses ke ruang sewaan semasa waktu perniagaan, dan ke gim dari awal pagi hingga lewat petang.

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

Waktu Akses

Waktu akses menentukan bila ahli boleh mengakses zon tertentu pada setiap hari dalam seminggu. Waktu akses ditakrifkan bagi setiap zon akses, membolehkan sekatan masa yang berbeza untuk kawasan yang berbeza dalam sesebuah kemudahan.

Struktur

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

Setiap hari ialah tatasusunan julat masa dalam format HH:MM (jam 24 jam). Tatasusunan kosong [] bermaksud tiada akses pada hari tersebut. Hari yang ditinggalkan dianggap sama seperti tatasusunan kosong.

Contoh Kes Penggunaan

Penyewa pejabat – waktu perniagaan: akses semasa waktu perniagaan pada hari bekerja sahaja.

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

Pelajar – akses semester: perpustakaan kampus yang dibuka pada hari bekerja, dengan rehat pada tengah hari, dan pada pagi Sabtu.

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

Gim – awal pagi: akses pagi sahaja pada hari bekerja.

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

Tetamu hotel – 24/7: akses sentiasa, kes penggunaan yang paling biasa.

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

Contoh Mengikut Zon

Pelan tetamu hotel dengan akses sepanjang masa ke tingkat tetamu dan waktu yang lebih singkat untuk kolam renang:

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

Simpan pelan keahlian

Mencipta atau mengemas kini rekod pelan keahlian. API menentukan sama ada untuk mencipta atau mengemas kini berdasarkan membership_plan_id.

Parameter

membership_plans array wajib

Tatasusunan objek Pelan Keahlian untuk disimpan. Maksimum yang disyorkan: 1000 item bagi setiap permintaan untuk prestasi optimum. API mengelompokkan item secara automatik untuk pemprosesan. Setiap item mesti menyertakan sama ada facility_id (diperlukan jika tidak menggunakan linking_identifier) atau linking_identifier (diperlukan jika tidak menggunakan facility_id).

Nilai pulangan

Mengembalikan mesej ringkas yang mengesahkan operasi penyegerakan.

Permintaan

Contoh ini menggunakan facility_id. Untuk integrasi Linking Identifier, hantar "linking_identifier": "branch_downtown" sebagai gantinya.

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

Respons

Mengembalikan mesej kejayaan dengan metadata tentang operasi penyegerakan.

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

Medan metadata:

success - Bilangan pelan keahlian yang berjaya diproses
skipped - Bilangan pelan yang dilangkau (jika ada)
skipped_items - Tatasusunan pelan yang dilangkau beserta sebab (jika ada)
dry-run - Bendera boolean jika menggunakan jenis kunci dryrun (jika berkenaan)

Ahli

Mewakili pelanggan individu sesebuah kemudahan. Boleh jadi bakal pelanggan, prospek, pelanggan berulang, ahli yang telah tamat tempoh atau pengguna yang disekat.

Upsert ahli juga boleh membawa petikan access_time_windows yang lengkap dan bersemakan yang mengandungi akses mutlak dan mingguan berulang. Lihat Access Time Windows sebelum menghasilkan medan ini. Medan ini ialah kebenaran tambahan dan tidak menggantikan peraturan biasa atau pemberian kekal kemudahan.

Titik akhir

POST /partner/v1/members - Save a member

Objek Ahli

Atribut

member_id string wajib

Pengecam unik bagi ahli.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam unik kemudahan daripada Performance Hub.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Nilai pengecam unik untuk setiap lokasi yang digunakan oleh rakan kongsi (contohnya, "Branch ID", "Location Code", "Store Number"). Ketahui lebih lanjut
first_name string wajib

Nama pertama ahli.
last_name string wajib

Nama akhir ahli.
email string pilihan

Alamat e-mel.
mobile_phone string pilihan

Nombor telefon mudah alih dalam format E.123 (contohnya, "+1 415 555 2671").
address object pilihan

Objek alamat fizikal dengan sifat berikut:
- address_line_1 (string) - Alamat jalan utama
- address_line_2 (string, pilihan) - Baris alamat kedua
- city (string) - Nama bandar
- state (string) - Kod negeri/wilayah
- postal_code (string) - Poskod/kod ZIP
- country (string) - Kod negara ISO 3166-1 alpha-2 (contohnya, "AU", "US")
- country_name (string, pilihan) - Nama penuh negara
date_of_birth string pilihan

Tarikh lahir dalam format YYYY-MM-DD.
gender string pilihan

Salah satu daripada male, female, non_binary, prefer_not_to_say atau unknown.
type string pilihan

Jenis ahli (contohnya staff, member, prospect).
tags array pilihan

Rentetan atau teks pembantu ringkas untuk mengkategorikan dan mengenal pasti ahli tertentu (contohnya ["vip", "personal-training", "student"]).
membership_status string pilihan

Status keahlian semasa (contohnya, active, expired, on_hold).
membership_plans array pilihan

Tatasusunan pelan keahlian yang dikaitkan dengan ahli.
profile_picture string pilihan

Gambar profil berkod Base64 (pilihan).
created string pilihan

Cap masa ISO 8601 apabila ahli dicipta.
updated string pilihan

Cap masa ISO 8601 apabila ahli kali terakhir dikemas kini.
access_time_windows array pilihan

Petikan lengkap milik sumber bagi Access Time Windows mutlak dan/atau mingguan berulang. Tinggalkan medan ini untuk mengekalkan petikan tanpa perubahan; hantar tatasusunan kosong dengan semakan yang lebih baharu untuk membatalkannya. Lihat Access Time Windows untuk bentuk, pengesahan, pemetaan skop dan semantik penggantian.
access_time_windows_revision integer wajib bersama access_time_windows

Integer bukan negatif yang selamat untuk JSON dan meningkat secara monoton bagi aliran ahli/sumber ini. Diperlukan setiap kali access_time_windows hadir.

Objek Ahli

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

Tempoh Masa Akses

Access Time Windows membolehkan Ahli Rakan Kongsi membawa akses sementara atau berulang yang dibekalkan oleh sistem luaran. Halaman ini ialah panduan pengeluar berautoriti untuk access_time_windows dan access_time_windows_revision.

Access Time Windows ialah kebenaran tambahan yang hanya membenarkan. Tetingkap yang aktif boleh membenarkan akses, tetapi tetingkap yang tidak aktif, tamat tempoh, lapuk atau tidak dipetakan tidak menafikan akses yang sudah dibenarkan oleh peraturan biasa atau pemberian kekal. Penyahdayaan pengguna, penyekatan pintu secara eksplisit, mod penyelenggaraan, geofencing, had kadar dan ketersediaan pengawal masih terpakai.

Pelaksanaan untuk sistem huluan tertentu ialah penyesuai yang berasingan. Penyesuai tersebut mesti menterjemah data sumber mereka ke dalam kontrak neutral vendor ini tanpa mengubah maksud medannya.

Medan petikan ahli

access_time_windows array pilihan

Petikan Access Time Window yang lengkap bagi ahli dan sumber rakan kongsi ini. Petikan boleh menggabungkan tetingkap absolute dan weekly. Tinggalkan medan ini untuk mengekalkan petikan yang disimpan tanpa perubahan; hantar [] untuk membatalkan setiap tetingkap yang dimiliki oleh sumber ini.
access_time_windows_revision integer wajib bersama access_time_windows

Integer bukan negatif yang selamat untuk JSON dan meningkat secara monoton bagi aliran semakan ahli/sumber ini. Ia diperlukan setiap kali access_time_windows hadir dan tidak boleh melebihi 9007199254740991.

Setiap petikan menerima paling banyak 50 tetingkap. external_id, scope_key dan label menerima paling banyak 120 aksara. Tetingkap mutlak boleh merangkumi paling lama 90 hari. Satu hari mingguan menerima paling banyak lapan blok yang tidak bertindih. Data yang tidak sah ditolak dan bukannya dipangkas atau diteka.

Bentuk tetingkap

Tetingkap mutlak mengenal pasti satu selang yang tepat:

Permintaan gabungan yang lengkap

Permintaan ini menggantikan petikan milik sumber yang terdahulu bagi ahli dengan satu tetingkap mutlak dan satu tetingkap mingguan:

Peraturan masa dan sempadan

from, to, active_from dan active_until ialah integer JSON dalam saat Unix yang mengenal pasti detik UTC:

Hantar integer JSON tanpa tanda petik. Rentetan angka, nombor titik terapung, rentetan RFC 3339 dan milisaat Unix ditolak.
Setiap selang adalah separuh terbuka: [from, to). Akses boleh bermula tepat pada from; ia tidak lagi aktif tepat pada to.
from mesti kurang daripada to. Apabila kedua-dua had mingguan hadir, active_from mesti kurang daripada active_until.
Jangan terbitkan epoch daripada tarikh/masa tempatan tanpa zon. Mula-mula selesaikan masa sumber kepada detik UTC, kemudian bahagikan milisaat Unix dengan 1000 dan sahkan bahawa hasilnya ialah integer.

Zon waktu dan waktu jimat siang

timezone mestilah zon waktu IANA yang sah seperti UTC, Australia/Perth atau America/New_York. Ia lalai kepada UTC apabila ditinggalkan.

Tetingkap mutlak: from dan to sudah mengenal pasti detik UTC yang tepat. timezone hanyalah metadata paparan dan audit; mengubahnya tidak sekali-kali mengalihkan mana-mana detik.
Tetingkap mingguan: timezone mentakrifkan jam dinding tempatan dan peraturan waktu jimat siang yang digunakan untuk menilai access_hours. Jangan tukar blok mingguan kepada UTC terlebih dahulu.
Semasa peralihan ke hadapan pada musim bunga, waktu tempatan yang dilangkau oleh zon waktu tidak pernah berlaku.
Semasa peralihan ke belakang pada musim luruh, kedua-dua detik sebenar yang membawa waktu tempatan berulang sepadan dengan blok mingguan.
active_from dan active_until kekal sebagai detik UTC walaupun tetingkap mingguan menggunakan zon waktu bukan UTC.

access_hours menggunakan sun hingga sat dalam huruf kecil. Setiap nilai ialah tatasusunan pasangan [start, end] menggunakan HH:mm 24 jam dengan sifar pendahulu. Blok mestilah tidak kosong, tersusun dan tidak bertindih. end adalah eksklusif. Blok tidak boleh merentasi tengah malam; pecahkan selang sumber semalaman kepada blok lewat pada hari pertama dan blok awal pada hari berikutnya.

ID stabil dan pemetaan skop

external_id mesti stabil sepanjang hayat tetingkap logik dan unik dalam petikan ahli. Kekalkannya stabil apabila masa atau label berubah supaya pengendali dan rekod audit dapat mengaitkan semakan. Jangan gunakannya semula untuk tetingkap yang tidak berkaitan.

scope_key ialah sasaran akses logik anda yang stabil. Ia lalai kepada default. Pentadbir kemudahan memetakan setiap kunci yang dibenarkan kepada sasaran seluruh kemudahan, pintu atau Skop Akses Performance Hub:

Petikan lengkap dan semakan

Anggap kedua-dua medan sebagai partisi berversi berasingan dalam upsert Ahli:

Input	Hasil
`access_time_windows` ditinggalkan	Petikan sedia ada kekal tanpa perubahan; tiada semakan diperlukan
Hadir dengan semakan yang lebih baharu	Keseluruhan petikan yang disimpan untuk ahli/sumber ini digantikan
Semakan sama dan muatan dinormalkan sama	Main semula idempoten; tiada perubahan petikan
Semakan sama dan muatan dinormalkan berbeza	Konflik; peruntukkan semakan baharu selepas penyelarasan
Semakan lebih lama	Petikan lapuk dilangkau; ia tidak boleh menulis ganti keadaan yang lebih baharu
`access_time_windows: []` dengan semakan yang lebih baharu	Membatalkan semua tetingkap milik sumber secara eksplisit

Petikan adalah lengkap, bukan tampalan. Jika semakan 1842 mempunyai tetingkap A dan B, maka semakan 1843 yang hanya mengandungi B akan membuang A.

Selenggarakan satu aliran semakan yang diselaraskan bagi setiap rakan kongsi/ahli merentas pekerja webhook, tinjauan, main semula dan penyesuaian penuh. Jujukan pangkalan data yang tahan lama adalah lebih baik. Nilai milisaat Unix boleh digunakan sebagai semakan hanya apabila setiap penulis menyelaras dan menjamin susunan dan keunikan yang ketat; ia ialah nilai semakan, bukan medan epoch.

Simpan permintaan dan semakan yang tepat sehingga respons API diketahui. Cuba semula petikan dinormalkan yang sama dengan semakan yang sama selepas tamat masa atau ralat sementara. Jangan peruntukkan semakan baharu semata-mata kerana penghantaran tidak pasti.

Pembatalan, tamat tempoh dan kegagalan huluan

Batalkan satu tetingkap: ambil keadaan sumber berautoriti dengan berjaya, buang tetingkap itu dan hantar baki petikan lengkap dengan semakan yang lebih baharu.
Batalkan semua tetingkap: hantar access_time_windows: [] dengan semakan yang lebih baharu.
Biarkan tetingkap mutlak tamat tempoh: ia berhenti membenarkan pada to; hantar penyesuaian kemudian tanpa entri yang tamat tempoh untuk memastikan petikan bersih.
Tamatkan tetingkap mingguan: buang dalam petikan yang lebih baharu, atau gunakan active_until apabila sumber mempunyai detik tamat yang diketahui.
Pengambilan sumber gagal atau tidak lengkap: jangan hantar [] dan jangan terbitkan petikan separa. Beri amaran dan cuba semula pengambilan. Menjadikan kegagalan huluan sebagai petikan kosong ialah pembatalan akses yang tidak disengajakan.
Permintaan Partner API gagal pengesahan: betulkan data dan hantar semakan yang lebih baharu hanya jika petikan dinormalkan berubah. Cuba semula kegagalan sementara dengan semakan asal.

Kesegaran sumber dikonfigurasikan bagi setiap integrasi berdasarkan kekerapan penghantaran dan penyesuaian yang dijanjikan. Sebelum pengaktifan, persetujui usia sumber maksimum, perkara yang berlaku apabila ia dilampaui, ambang amaran dan sama ada pengendali boleh mengakui untuk bergantung hanya pada had setiap tetingkap itu sendiri. Tetingkap sumber yang lapuk tidak sekali-kali menjadi peraturan penafian; peraturan biasa dan pemberian kekal kekal sebagai laluan sandaran.

Algoritma pengeluar

Gunakan aliran kerja neutral bahasa ini untuk setiap kemas kini ahli:

Senarai semak pensijilan

Lengkapkan semakan ini dalam kemudahan peringkat (stage) menggunakan pemetaan scope_key yang muktamad:

Tetingkap mutlak diterima dengan zon waktu ditinggalkan dan dinilai sebagai UTC.
Tetingkap mutlak dengan IANA tersuai mengekalkan detik from/to yang sama.
Tetingkap mingguan dengan IANA tersuai mengikut waktu jam dinding tempatan merentas peralihan ke hadapan dan ke belakang.
Petikan gabungan mutlak/mingguan menggantikan petikan terdahulu sepenuhnya.
Akses bermula tepat pada from dan berhenti tepat pada to; penghujung blok mingguan juga eksklusif.
Mengemas kini masa di bawah external_id yang sama dengan semakan yang lebih baharu berkuat kuasa.
Meninggalkan access_time_windows mengubah medan Ahli lain tanpa mengubah tetingkap.
Memainkan semula semakan/muatan yang sama adalah idempoten.
Semakan sama/muatan berbeza mengembalikan konflik dan tidak mengubah petikan.
Semakan lama yang tidak mengikut urutan dilaporkan lapuk dan tidak boleh mengundurkan keadaan.
[] yang lebih baharu membatalkan tetingkap milik sumber; kegagalan pengambilan huluan tidak menghantar apa-apa.
scope_key yang tidak diketahui atau tidak dipetakan tidak memberikan sebarang akses dan mencipta amaran yang kelihatan kepada pengendali.
Amaran usia sumber dan dasar sumber lapuk yang dikonfigurasikan berfungsi pada ambang yang dipersetujui.
Laluan webhook dan penyesuaian penuh menumpu pada petikan dan susunan semakan yang sama.
Penghantaran aliran sampai ke Door & Gate Access dalam sasaran yang dipersetujui.
Tetingkap aktif boleh membenarkan pintu fizikal yang dipetakan, tetapi tidak boleh memintas penyahdayaan pengguna, blockAllAccess, penyelenggaraan atau geofencing.
Sebelum, di luar dan selepas tetingkap, peraturan biasa dan pemberian kekal masih membenarkan pengguna yang layak dengan cara lain.

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

Medan yang diperlukan ialah external_id, kind, from dan to. timezone, scope_key dan label adalah pilihan.

Tetingkap mingguan mengenal pasti selang waktu jam dinding tempatan yang berulang, dengan pilihan untuk dibatasi oleh detik 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"
}

Medan yang diperlukan ialah external_id, kind dan access_hours. timezone, active_from, active_until, scope_key dan label adalah pilihan.

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

Gunakan sama ada facility_id atau linking_identifier mengikut kaedah pemautan yang anda konfigurasikan. Jangan hantar kedua-duanya.

Penukaran epoch

2026-10-15T08:30:00Z ditukar kepada 1792053000:

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

Penukaran neutral bahasa:

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

Jika sumber mempunyai ketepatan sub-saat, tentukan dasar pembundaran mula/tamat yang disengajakan sebelum ujian integrasi. Jangan sekali-kali menghantar milisaat dan bergantung pada API untuk menyimpulkan unitnya.

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

Rakan kongsi tidak menghantar ID kemudahan, pintu atau Skop Akses Performance Hub di dalam tetingkap. scope_key yang tidak diketahui, dinyahdayakan atau tidak dipetakan menyebabkan tetingkap itu tidak memberikan sebarang akses; ia tidak meluaskan akses. Persetujui dan uji pemetaan sebelum pelancaran.

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)

Vektor ujian minimum

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

Hantar juga vektor negatif untuk milisaat Unix, rentetan angka, nombor titik terapung, zon IANA yang tidak sah, from >= to, external_id pendua, blok bertindih, blok semalaman, lebih daripada lapan blok dalam sehari, lebih daripada 50 tetingkap dan kunci skop yang tidak dipetakan.

Simpan ahli

Mencipta atau mengemas kini rekod ahli. API menentukan sama ada untuk mencipta atau mengemas kini berdasarkan member_id.

Parameter

members array wajib

Tatasusunan objek Ahli untuk disimpan. Maksimum yang disyorkan: 1000 item bagi setiap permintaan untuk prestasi optimum. API mengelompokkan item secara automatik untuk pemprosesan. Setiap item mesti menyertakan sama ada facility_id (diperlukan jika tidak menggunakan linking_identifier) atau linking_identifier (diperlukan jika tidak menggunakan facility_id).

Apabila ahli menyertakan access_time_windows, ia juga mesti menyertakan access_time_windows_revision. Tatasusunan itu ialah petikan sumber yang lengkap, bukan tampalan. Tinggalkannya untuk mengekalkan petikan sedia ada, atau hantar [] dengan semakan yang lebih baharu untuk membatalkan semua tetingkap milik sumber. Baca panduan Access Time Windows sebelum mendayakan medan ini.

Nilai pulangan

Mengembalikan mesej ringkas yang mengesahkan operasi penyegerakan.

Medan profil ahli kekal sebagai upsert biasa walaupun petikan tetingkap dilaporkan sebagai main semula idempoten atau langkau data lapuk. Petikan bercanggah dengan semakan sama/muatan berbeza tidak boleh dicuba semula tanpa perubahan; selaraskan keadaan sumber dan hantar semakan yang lebih baharu.

Permintaan

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

Respons

Mengembalikan mesej kejayaan dengan metadata tentang operasi penyegerakan.

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

Medan metadata:

success - Bilangan ahli yang berjaya diproses
skipped - Bilangan ahli yang dilangkau (jika ada)
skipped_items - Tatasusunan ahli yang dilangkau beserta sebab (jika ada)
dry-run - Bendera boolean jika menggunakan jenis kunci dryrun (jika berkenaan)

Daftar Masuk

Mewakili rekod kehadiran seseorang di kemudahan, kelas atau aktiviti. Digunakan untuk menjejak kehadiran, analitik penggunaan dan meningkatkan ketepatan pengesanan visual.

Titik akhir

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

Objek Daftar Masuk

Atribut

check_in_id string pilihan

Pengecam unik bagi daftar masuk. Pilihan - dijana secara automatik daripada pasangan member_id dan timestamp jika tidak diberikan.
member_id string wajib

Pengecam unik ahli.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam unik kemudahan daripada Performance Hub.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Nilai pengecam unik untuk setiap lokasi yang digunakan oleh rakan kongsi (contohnya, "Branch ID", "Location Code", "Store Number"). Ketahui lebih lanjut
check_in_type string pilihan

Jenis lawatan. Salah satu daripada member, class, staff, guest atau trial.
source string pilihan

Cara daftar masuk direkodkan. Nilai biasa termasuk manual, tag, rfid, kiosk, app. Nilai tambahan seperti door_reader atau booking juga boleh digunakan.
class_id string pilihan

Pilihan. Jika dikaitkan dengan tempahan atau kehadiran kelas.
timestamp string wajib

Cap masa dalam format ISO 8601 bagi masa daftar masuk berlaku.

Objek Daftar Masuk

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

Simpan daftar masuk

Mencipta rekod daftar masuk. API menyahduplikasi secara automatik berdasarkan ahli, kemudahan dan cap masa.

Parameter

check_ins array wajib

Tatasusunan objek Daftar Masuk untuk disimpan. Maksimum yang disyorkan: 1000 item bagi setiap permintaan untuk prestasi optimum. API mengelompokkan item secara automatik untuk pemprosesan. Setiap item mesti menyertakan sama ada facility_id (diperlukan jika tidak menggunakan linking_identifier) atau linking_identifier (diperlukan jika tidak menggunakan facility_id).

Nilai pulangan

Mengembalikan mesej ringkas yang mengesahkan operasi penyegerakan.

Permintaan

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

Respons

Mengembalikan mesej kejayaan dengan metadata tentang operasi penyegerakan.

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

Medan metadata:

success - Bilangan daftar masuk yang berjaya diproses
skipped - Bilangan daftar masuk yang dilangkau (jika ada)
skipped_items - Tatasusunan daftar masuk yang dilangkau beserta sebab (jika ada)
dry-run - Bendera boolean jika menggunakan jenis kunci dryrun (jika berkenaan)

Kawalan Akses

Partner API boleh mencetuskan perkakasan Door/Gate Controller Performance Hub bagi kemudahan yang mendayakan integrasi anda.

Gunakan API ini apabila sistem pengurusan ahli anda telah pun memutuskan bahawa seseorang dibenarkan masuk. Performance Hub tidak menilai status keahlian, waktu akses, peraturan zon pintu, semakan penipuan atau logik penggantungan. Sistem anda kekal sebagai pihak berkuasa bagi keputusan tersebut.

Permintaan buka kunci adalah segerak. Performance Hub menghantar arahan kepada pengawal di premis dalam masa nyata dan mengembalikan 200 hanya selepas peranti mengesahkan bahawa geganti telah dibuka kunci secara fizikal. Kebanyakan pengesahan sepatutnya selesai dalam 3-5 saat. Jika tiada pengesahan diterima dalam tetingkap tamat masa, API mengembalikan kegagalan yang jelas.

Anda juga boleh merekodkan percubaan atau penafian akses yang tidak pernah sampai ke pengawal. Panggilan itu tidak membuka kunci pintu. Ia menulis peristiwa ke Access Logs Door & Gate Access.

Titik akhir

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

Objek Door/Gate Controller

Atribut

door_id string wajib

Pengecam unik bagi Door/Gate Controller. Simpan ini dalam sistem anda selepas penemuan dan gunakannya apabila memanggil titik akhir buka kunci.
facility_id string wajib

ID kemudahan Performance Hub.
linking_identifier string pilihan

Pengecam kemudahan rakan kongsi apabila integrasi anda menggunakan Linking Identifier. Ketahui lebih lanjut
name string wajib

Nama peranti yang boleh dibaca oleh manusia yang dikonfigurasikan dalam Performance Hub.
zone string pilihan

Zon atau lokasi pintu, seperti Entrance.
status string wajib

online atau offline.
relay_state string pilihan

Keadaan geganti terkini yang diketahui, seperti locked atau unlocked.
maintenance_mode string wajib

Mod penyelenggaraan semasa. Salah satu daripada off, force-open atau force-closed.
hold_time_seconds integer wajib

Masa tahan buka kunci lalai yang dikonfigurasikan untuk pintu.
last_seen string pilihan

Cap masa ISO bagi kemas kini metadata peranti terkini.

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

Senaraikan Door/Gate Controller

Mengembalikan Door/Gate Controller yang tersedia untuk integrasi anda.

Jika facility_id mahupun linking_identifier tidak diberikan, API mengembalikan Door/Gate Controller merentas semua kemudahan yang dipautkan kepada akaun rakan kongsi anda.

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.

Parameter

facility_id string pilihan salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

ID kemudahan Performance Hub. Gunakan ini untuk integrasi Direct Link.
linking_identifier string pilihan salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam kemudahan/lokasi anda sendiri. Gunakan ini apabila integrasi anda dikonfigurasikan untuk Linking Identifier.

Nilai pulangan

Mengembalikan tatasusunan objek Door/Gate Controller.

Permintaan

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:

Respons

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

Dapatkan status Door/Gate Controller

Mendapatkan keadaan terkini yang diketahui dan konfigurasi asas bagi satu Door/Gate Controller.

Berikan pengecam kemudahan supaya Performance Hub dapat mengesahkan bahawa pintu itu dimiliki oleh kemudahan yang boleh diakses oleh integrasi anda.

Parameter

door_id string wajib

ID Door/Gate Controller yang dikembalikan oleh titik akhir senarai.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

ID kemudahan Performance Hub. Diperlukan untuk integrasi Direct Link.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam kemudahan rakan kongsi. Diperlukan untuk integrasi Linking Identifier.

Nilai pulangan

Mengembalikan objek Door/Gate Controller.

Permintaan

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:

Respons

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

Buka kunci Door/Gate Controller

Menghantar arahan buka kunci kepada Door/Gate Controller dan menunggu geganti fizikal mengesahkan bahawa ia telah dibuka kunci.

Sistem anda mesti memutuskan sama ada orang itu dibenarkan sebelum memanggil titik akhir ini. Performance Hub hanya mengesahkan kunci rakan kongsi, akses kemudahan, pemilikan pintu dan keadaan peranti.

Parameter

door_id string wajib

ID Door/Gate Controller yang dikembalikan oleh titik akhir senarai.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

ID kemudahan Performance Hub. Diperlukan untuk integrasi Direct Link.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam kemudahan rakan kongsi. Diperlukan untuk integrasi Linking Identifier.
member_id string wajib

ID ahli rakan kongsi. Ini digunakan untuk pengelogan audit dan pemautan data kemudian.
first_name string wajib

Nama pertama orang yang membuka pintu.
last_name string wajib

Nama akhir orang yang membuka pintu.
full_name string pilihan

Pilihan. Jika ditinggalkan, Performance Hub menggabungkan first_name dan last_name.
check_in_id string pilihan

ID daftar masuk pilihan daripada sistem anda untuk korelasi.
idempotency_key string pilihan

Kunci perlindungan main semula pilihan. Menggunakan semula kunci yang sama untuk rakan kongsi, kemudahan dan pintu yang sama mengembalikan hasil sedia ada apabila tersedia.

Nilai pulangan

Mengembalikan 200 hanya apabila peranti mengesahkan geganti telah dibuka kunci secara fizikal. Pintu menggunakan masa tahan yang dikonfigurasikan dalam Pengurusan Peranti Performance Hub; rakan kongsi tidak boleh mengatasi pemasaan geganti bagi setiap permintaan. Kebanyakan pengesahan sepatutnya selesai dalam 3-5 saat. Anggap tamat masa yang didokumenkan sebagai buka kunci yang gagal secara jelas dan cuba semula hanya mengikut peraturan keselamatan anda sendiri.

Kegagalan biasa:

403 integration_not_enabled - integrasi anda tidak didayakan untuk kemudahan tersebut.
409 maintenance_mode_active - kakitangan kemudahan telah mendayakan mod penyelenggaraan untuk pintu tersebut.
503 device_offline - Door/Gate Controller berada di luar talian atau datanya lapuk.
504 unlock_confirmation_timeout - arahan telah dihantar tetapi tiada pengesahan sepadan diterima sebelum tamat masa.

Permintaan

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

Respons

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

Respons kegagalan

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

Rekodkan percubaan atau penafian akses

Merekodkan percubaan atau penafian akses yang telah pun diputuskan oleh sistem anda. Door/Gate Controller tidak dihubungi dan pintu tidak dibuka kunci.

Gunakan ini apabila sistem anda menolak kemasukan, atau apabila sesuatu percubaan patut dipaparkan dalam Access Logs Door & Gate Access tanpa buka kunci. Performance Hub tidak menilai status keahlian, waktu akses atau peraturan akses lain.

Peristiwa yang ditolak dipaparkan dalam Access Logs Door & Gate Access dengan hasil Denied, nama rakan kongsi anda, pintu, pengecam ahli apabila anda menghantarnya dan kod sebab dalam bentuk yang boleh dibaca. Contohnya, membership_expired dipaparkan sebagai "Membership Expired". reason_display_text dan user_email disimpan bersama peristiwa tersebut.

Parameter

door_id string wajib

ID Door/Gate Controller yang dikembalikan oleh titik akhir senarai.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

ID kemudahan Performance Hub. Diperlukan untuk integrasi Direct Link.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam kemudahan rakan kongsi. Diperlukan untuk integrasi Linking Identifier.
outcome string wajib

denied atau attempted.
reason string pilihan

Kod sebab snake_case huruf kecil, sehingga 64 aksara. Diperlukan apabila outcome ialah denied. Contoh: membership_expired.
reason_display_text string pilihan

Sebab yang boleh dibaca oleh manusia, sehingga 256 aksara. Contoh: Membership expired on 2026-04-01.
member_id string pilihan

ID ahli rakan kongsi. Tinggalkannya apabila kelayakan tidak sepadan dengan mana-mana ahli, seperti kad yang tidak dikenali.
user_email string pilihan

E-mel orang yang cuba mendapatkan akses.
timestamp string pilihan

Masa percubaan berlaku, dalam format ISO 8601 dengan zon waktu. Contoh: 2026-05-18T10:15:30Z. Lalai kepada masa permintaan diterima. Tidak boleh lebih daripada 5 minit pada masa hadapan atau lebih lama daripada 30 hari.
idempotency_key string pilihan

Kunci perlindungan main semula, sehingga 128 aksara. Menggunakan semula kunci yang sama untuk rakan kongsi, kemudahan dan pintu yang sama mengembalikan hasil asal.

Nilai pulangan

Mengembalikan 201 apabila peristiwa direkodkan. Memainkan semula idempotency_key yang sama mengembalikan 200 dengan idempotent ditetapkan kepada true dan tidak mencipta peristiwa lain.

Kunci dry-run mengembalikan 200 dengan dry_run ditetapkan kepada true. Tiada apa-apa yang direkodkan.

Kegagalan biasa:

400 - badan permintaan tidak sah, penafian tiada reason, cap masa di luar julat, atau facility_id / linking_identifier tidak sepadan dengan kemudahan yang dipautkan.
403 - kunci adalah read-only.
403 integration_not_enabled - integrasi anda tidak didayakan untuk kemudahan tersebut. message memberikan sebabnya.
404 - Door/Gate Controller tidak ditemui untuk kemudahan yang dipautkan.

Permintaan

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

Respons

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

Main semula idempoten

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

Laporan Kemudahan

Rekod pada satu titik masa yang merakam metrik operasi dan kewangan utama bagi sesebuah kemudahan dalam tempoh tertentu.

Titik akhir

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

Objek Petikan Laporan

Atribut

facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam unik kemudahan daripada Performance Hub.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Nilai pengecam unik untuk setiap lokasi yang digunakan oleh rakan kongsi (contohnya, "Branch ID", "Location Code", "Store Number"). Ketahui lebih lanjut
start_date string wajib

Tarikh mula tempoh petikan dalam format YYYY-MM-DD.
end_date string wajib

Tarikh tamat tempoh petikan dalam format YYYY-MM-DD.
metrics object wajib

Objek metrik yang mengandungi data ahli dan hasil bagi tempoh tersebut.

Objek Petikan Laporan

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

Simpan petikan laporan

Menghantar metrik operasi dan kewangan bagi sesebuah kemudahan dalam tempoh tertentu.

Parameter

snapshots array wajib

Tatasusunan objek Petikan Laporan untuk disimpan. Maksimum 25 item bagi setiap permintaan. Setiap item mesti menyertakan sama ada facility_id (diperlukan jika tidak menggunakan linking_identifier) atau linking_identifier (diperlukan jika tidak menggunakan facility_id).

Nilai pulangan

Mengembalikan mesej ringkas yang mengesahkan operasi penyegerakan.

Permintaan

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

Respons

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

Ralat

Partner API menggunakan kod status HTTP standard dan badan respons JSON untuk menerangkan sebab permintaan gagal.

Bentuk respons ralat

Kebanyakan ralat API mengembalikan badan JSON dengan mesej dan, jika ada, butiran berstruktur.

Kod status

Kegagalan Access Time Window

Pengesahan tetingkap gagal sebelum petikan yang tidak sah ditulis. Punca biasa yang tidak boleh dicuba semula termasuk:

access_time_windows_revision tiada apabila access_time_windows hadir.
Nilai epoch dalam bentuk rentetan, titik terapung atau berkemungkinan milisaat.
Zon waktu IANA yang tidak sah, selang terbalik, external_id pendua, blok mingguan bertindih atau blok semalaman yang tidak dipecahkan.
Nilai di luar had bilangan, panjang atau rentang yang didokumenkan.

Semakan berulang dengan kandungan dinormalkan yang berbeza ialah 409 Conflict. Selaraskan dengan keadaan berautoriti terkini dan peruntukkan semakan yang lebih baharu; jangan terus mencuba semula pasangan yang bercanggah. Semakan yang lebih lama dilaporkan sebagai petikan lapuk yang dilangkau dan tidak dibenarkan menulis ganti keadaan yang lebih baharu. scope_key yang tidak diketahui atau tidak dipetakan menyebabkan akses tidak diberikan dan patut dianggap sebagai amaran konfigurasi.

Jika penghantaran tamat masa atau menerima 5xx sementara, cuba semula petikan dinormalkan yang sama tepat dengan semakan yang sama. Jika pengambilan sumber huluan gagal, tinggalkan medan tetingkap sepenuhnya; jangan sekali-kali gantikannya dengan tatasusunan kosong.

Panduan cubaan semula

Cuba semula yang berikut dengan penundaan eksponen yang terhad:

429
500
502
503
504

Jangan cuba semula yang berikut secara membuta tuli:

400
401
403
404
409
422

Untuk kawalan akses, sentiasa anggap respons tamat masa dan luar talian sebagai buka kunci yang gagal melainkan peraturan akses dan proses keselamatan anda sendiri menyatakan sebaliknya.

Butiran sokongan yang perlu disertakan

Semasa menghubungi sokongan, sertakan:

Titik akhir dan kaedah HTTP.
Cap masa dan zon waktu.
ID kunci rakan kongsi, bukan kunci rahsia.
Pengecam kemudahan yang digunakan.
ID rekod sumber daripada sistem anda.
Status dan badan respons.
event_id atau command_id jika ada.

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

Sesetengah titik akhir khusus domain mengembalikan status dan sebab yang jelas. Contohnya, kegagalan kawalan akses termasuk medan seperti reason, door_id, facility_id dan 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

Permintaan itu cacat atau tiada medan yang diperlukan. Betulkan permintaan sebelum mencuba semula.

401 Unauthorized

Pengesahan gagal. Semak bahawa anda menggunakan HTTP Basic Auth dengan kunci rahsia API anda sebagai nama pengguna dan kata laluan kosong.

403 Forbidden

Kunci adalah sah tetapi operasi tidak dibenarkan. Punca biasa termasuk menggunakan kunci read-only untuk operasi tulis atau cuba mengakses kemudahan yang tidak mendayakan integrasi anda.

404 Not Found

Sumber yang diminta tidak ditemui atau tidak tersedia untuk integrasi anda.

409 Conflict

Permintaan bercanggah dengan keadaan semasa sumber. Untuk kawalan akses, ini boleh termasuk Door/Gate Controller yang berada dalam mod penyelenggaraan.

422 Unprocessable Entity

Permintaan ialah JSON yang sah tetapi gagal pengesahan semantik. Betulkan data sebelum mencuba semula.

429 Too Many Requests

Integrasi telah melebihi had kadar yang didokumenkan. Cuba semula dengan penundaan eksponen.

500 Internal Server Error

Performance Hub tidak dapat melengkapkan permintaan disebabkan ralat dalaman. Cuba semula dengan penundaan. Jika masalah berterusan, hubungi sokongan dengan titik akhir, cap masa dan badan respons.

503 Service Unavailable

Perkhidmatan atau peranti yang bergantung tidak tersedia. Untuk buka kunci Door/Gate Controller, ini boleh bermaksud pengawal berada di luar talian.

504 Gateway Timeout

Operasi telah tamat masa. Untuk buka kunci Door/Gate Controller, ini bermaksud buka kunci tidak disahkan sebelum tetingkap tamat masa.

Pemversian

Partner API diversikan dalam URL. Versi semasa ialah:

Dasar perubahan

Performance Hub berusaha membuat perubahan tambahan yang serasi ke belakang di mana-mana yang boleh.

Contoh perubahan yang serasi ke belakang:

Menambah medan pilihan baharu pada permintaan.
Menambah medan baharu pada respons.
Menambah titik akhir baharu.
Menambah nilai enum baharu di mana klien dijangka mengendalikan nilai yang tidak diketahui.
Menambah baik mesej pengesahan tanpa mengubah kontrak kod status.

access_time_windows dan access_time_windows_revision ialah medan permintaan Ahli tambahan. Klien sedia ada yang meninggalkannya mengekalkan petikan Access Time Window yang disimpan tanpa perubahan. Peraturan peninggalan ini mengekalkan keserasian upsert separa; peninggalan tidak sama dengan menghantar tatasusunan kosong.

Contoh perubahan yang memecahkan keserasian:

Membuang atau menamakan semula medan.
Mengubah jenis medan.
Menjadikan medan permintaan pilihan sebagai wajib.
Membuang titik akhir.
Mengubah maksud kod status sedia ada atau reason khusus domain.

Penamatan

Apabila perubahan yang memecahkan keserasian diperlukan, Performance Hub akan mengelak daripada mengubah versi sedia ada secara langsung di mana-mana yang boleh. Sebaliknya, kami akan memperkenalkan versi atau laluan migrasi baharu dan memaklumkan perubahan itu kepada rakan kongsi yang terjejas.

Notis penamatan boleh termasuk:

Entri log perubahan.
Komunikasi terus dengan rakan kongsi.
Nota dalam Partner Console.
Panduan migrasi dalam dokumentasi.

Cadangan untuk klien

Bina klien yang dapat menerima perubahan tambahan:

Abaikan medan respons yang tidak anda gunakan.
Anggap nilai enum yang tidak diketahui sebagai tidak disokong dan bukannya menyebabkan ranap.
Elakkan semakan kesamaan respons yang ketat.
Log nilai yang tidak dikenali supaya anda boleh mengemas kini integrasi anda dengan sengaja.

Untuk partisi Ahli bersemakan seperti Access Time Windows, simpan semakan dan muatan dinormalkan yang dihantar sehingga hasilnya diketahui. Menggunakan semula semakan untuk kandungan yang berubah ialah konflik, manakala memainkan semula kandungan yang sama adalah idempoten. Lihat Access Time Windows.

Spesifikasi OpenAPI

Gunakan spesifikasi OpenAPI yang diterbitkan untuk menjana klien, mengesahkan permintaan dan menjejak perubahan bentuk API dari semasa ke semasa.

Lihat Spesifikasi OpenAPI.

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

Log Perubahan

Log perubahan ini merekodkan perubahan ketara pada Partner API dan Partner Console yang menjejaskan tingkah laku integrasi.

2026-09-09

2026-05-06

2026-05-01

Kategori perubahan

Entri akan datang menggunakan kategori ini:

Added - titik akhir, medan, panduan atau keupayaan baharu.
Changed - tingkah laku atau dokumentasi berubah tanpa membuang sokongan.
Deprecated - ciri kekal tersedia tetapi mempunyai laluan migrasi yang dirancang.
Removed - ciri atau titik akhir dibuang.
Fixed - pembaikan pepijat atau pembetulan dokumentasi.
Security - perubahan pengesahan, kebenaran, pengendalian data atau pengurusan kunci.

Ditambah

Menambah petikan access_time_windows Ahli yang neutral vendor dengan gabungan tetingkap mutlak dan tetingkap mingguan berulang.
Menambah semantik susunan access_time_windows_revision, main semula idempoten, konflik, langkau data lapuk dan pembatalan eksplisit.
Menambah panduan zon waktu IANA, waktu jimat siang, pemetaan scope_key logik, kesegaran sumber, pelaksanaan pengeluar dan pensijilan.

Ditambah

Menambah dokumentasi program rakan kongsi yang merangkumi jenis rakan kongsi, penyertaan, amalan terbaik, kesediaan go-live, ralat, pemversian dan sokongan.
Menambah aliran pertanyaan Jadi Rakan Kongsi khusus untuk bakal rakan kongsi teknikal dan komersial.
Menambah dokumentasi tentang cara integrasi rakan kongsi yang diluluskan dipaparkan di dalam direktori rakan kongsi Performance Hub dalam platform teras Performance Hub.

Ditambah

Menambah dokumentasi kawalan akses Door/Gate Controller, termasuk operasi senarai, status dan buka kunci.
Menambah dokumentasi tingkah laku buka kunci segerak: API mengembalikan kejayaan hanya selepas pengawal di premis mengesahkan geganti telah dibuka kunci secara fizikal.
Menambah dokumentasi sokongan idempotency_key pilihan untuk permintaan buka kunci Door/Gate Controller.