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:

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

Permintaan gabungan yang lengkap

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

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.

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.

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.

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:

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.

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:

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)

Senarai semak pensijilan

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

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.

Objek Ahli
Simpan ahli
Amalan Terbaik
Ralat
Senarai Semak Go-Live