Giriş

Performance Hub Partner API, harici iş ortağı platformlarının Performance Hub'ın temel modülleriyle sorunsuz biçimde entegre olmasını sağlar. API; bilgisayarlı görü, analiz, üye erişim kaydı ve tesis içgörülerini destekler.

İstek biçimi

API, JSON ile kodlanmış istek gövdelerini kabul eder ve JSON ile kodlanmış yanıtlar döndürür.

Hız sınırlama

Adil kullanımı ve sistem kararlılığını sağlamak için Partner API hesapları şu varsayılan sınırlarla başlar:

Uç nokta başına saniyede 5 istek
En iyi performans için toplu istek başına önerilen: en fazla 1000 öğe
En fazla 10MB yük boyutu

Hız sınırları ayarlanabilir ve Performance Hub iş ortağı hesap yöneticiniz tarafından duruma göre yapılandırılabilir. Entegrasyonunuzun lansman, geçişler, raporlama geri doldurmaları veya yüksek hacimli tesisler için daha yüksek işlem hacmine ihtiyacı varsa bunu katılım sürecinde veya planlanan değişiklik penceresinden önce belirtin.

Temel URL

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

Kimlik doğrulama

Partner API'ye erişim, API gizli anahtarları kullanılarak kimlik doğrulaması gerektirir. Anahtarlarınızı Partner Console üzerinden oluşturun ve yönetin.

API anahtarları, iş ortağı kaynaklarına erişim için kimlik bilgilerinizdir. Her anahtarın belirli organizasyon verilerine kısıtlı erişimi vardır ve gerektiğinde anında devre dışı bırakılabilir.

API anahtarlarınızı dikkatle kullanın; hesabınıza tam erişim sağlarlar! Bu anahtarları hiçbir zaman herkese açık depolarda, istemci tarafı uygulamalarda veya ele geçirilebilecekleri herhangi bir yerde açığa çıkarmayın.

İstekleri, API anahtarınızı kullanıcı adı olarak ileterek HTTP Basic Auth ile doğrulayın. Parolayı boş bırakın.

API yalnızca güvenli HTTPS bağlantılarını kabul eder. Düz HTTP istekleri ve uygun kimlik doğrulama bilgileri eksik olan tüm istekler reddedilir.

Örnek istek

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.

Gizli anahtarı doğrulama

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

Yayına geçiş kontrol listesi

Bir iş ortağı entegrasyonunu üretimdeki tesisler için etkinleştirmeden önce bu kontrol listesini kullanın.

Partner Console kurulumu

İş ortağı profiliniz eksiksiz.
Logo URL'niz, web siteniz, kategoriniz ve açıklamanız doğru.
Veri bağlama yönteminiz yapılandırılmış: Direct Link veya Linking Identifier.
Tesis bağlama en az bir gerçek tesisle test edilmiş.
Doğru anahtar türü kullanılıyor:
- Yıkıcı olmayan yazma testleri için Dryrun.
- Güvenli veri kullanımı için Read-only.
- Yalnızca üretim verilerini etkilemeye hazır olduğunuzda Live.

Kimlik doğrulama ve anahtar yönetimi

Gizli anahtarlar yalnızca sunucu tarafında saklanıyor.
Anahtarlar istemci tarafı uygulamalara, mobil uygulamalara, herkese açık depolara veya destek taleplerine gömülmüyor.
Anahtar döndürme ve iptal etme test edilmiş.
Ekibiniz her ortamda hangi anahtarın kullanıldığını biliyor.

Veri doğrulama

Çağırdığınız her uç nokta için zorunlu alanlar mevcut.
Tesis tanımlayıcıları yapılandırdığınız bağlama yöntemiyle eşleşiyor.
Sisteminizdeki kimlikler sabit ve eşitlemeler arasında değişmiyor.
Büyük içe aktarmalar belgelenen sınırların altındaki toplu işlemlere bölünüyor.
Başarısız toplu işlem öğeleri belirlenip yeniden gönderilebiliyor.

Uç nokta testi

Lansmandan önce entegrasyonunuzun bağlı olduğu her uç noktayı test edin:

Organizasyonlar ve tesisler okunabiliyor.
Üyeler kaydedilip güncellenebiliyor.
Üyelik planları, erişim alanları ve erişim saatleri doğru şekilde eşitleniyor.
Check-in'ler kabul ediliyor ve sisteminizle ilişkilendirilebiliyor.
Rapor anlık görüntüleri beklenen raporlama dönemini ve ölçümleri kullanıyor.
Door/Gate Controller akışları, uygun olduğu durumlarda gerçek donanım üzerinde test edilmiş.

Access Time Window hazırlığı

Entegrasyon Access Time Windows sağlıyorsa:

Mutlak ve haftalık örnekler üretici sertifikasyon kontrol listesinden geçiyor.
Epoch değerleri tırnaksız tam sayı Unix saniyeleri; tam [from, to) sınırları test edilmiş.
UTC varsayılanları, entegrasyonun özel IANA saat dilimleri ve ilgili yaz saati geçişleri doğrulanmış.
Tek bir kalıcı, tekdüze üye/kaynak revizyon akışı artımlı güncellemeleri, mutabakatı ve yeniden denemeleri koordine ediyor.
Operatörler; gönderilmeyen, tamamen değiştirilen, idempotent, çakışan, eski ve açık [] davranışlarını anlıyor.
default dahil her scope_key onaylanmış bir Performance Hub eşlemesine sahip; bilinmeyen anahtarların kapalı başarısız olduğu (fail closed) test edilmiş.
Entegrasyonun beklenen yenileme sıklığı, maksimum kaynak yaşı, eski kaynak davranışı ve uyarıları yapılandırılmış.
Bir üst kaynak sorgu hatasının boş veya kısmi bir anlık görüntü göndermediği kanıtlanmış.
Aşamalı akış yakınsaması, iptal/geri alma ve fiziksel kapı başlangıç/bitiş sınırları kararlaştırılan hedefleri karşılıyor.
Normal kurallar ve kalıcı izinler yedek yollar olarak doğrulanmış ve pencereler kullanıcı devre dışı bırakmayı, blockAllAccess ayarını, bakımı veya coğrafi sınırlamayı (geofencing) atlayamıyor.

Erişim denetimi hazırlığı

Erişim denetimi entegrasyonları için:

Sisteminiz Performance Hub'ı çağırmadan önce erişim kararını veriyor.
Entegrasyon device_offline, maintenance_mode_active ve unlock_confirmation_timeout durumlarını ele alıyor.
Operatörler, zaman aşımının kilit açmanın onaylanmadığı anlamına geldiğini anlıyor.
Kayıtlarınız döndürülen event_id ve command_id değerlerini saklıyor.
Tesis personeli için manuel bir yedek süreciniz var.

Hata işleme ve yeniden denemeler

400, 401, 403, 404, 409 ve 422 yanıtları körü körüne yeniden denenmek yerine operatörlere veya destek ekiplerine iletiliyor.
429, 500, 502, 503 ve 504 yanıtları geri çekilmeli, sınırlı yeniden deneme mantığı kullanıyor.
Tekrarlanan hatalar sisteminizde bir uyarı oluşturuyor.
Entegrasyon başarısız kayıtları hiçbir zaman sessizce düşürmüyor.

Gözlemlenebilirlik

Kayıtlarınız uç noktayı, zaman damgasını, tesis tanımlayıcısını, kaynak kayıt kimliğini, istek sonucunu ve yanıt gövdesini içeriyor.
Destek ekibiniz üye kimliğine, tesis kimliğine, check-in kimliğine veya kilit açma olay kimliğine göre arama yapabiliyor.
Başarısız eşitlemeleri yeniden oynatmanın veya mutabakatını sağlamanın bir yolu var.

Üretime geçiş

Performance Hub üretim erişiminizi onaylamış.
En az bir üretim tesisi entegrasyonunuzu etkinleştirmiş.
Üretim anahtarınız etkin.
Operasyonel ve teknik irtibat kişileriniz güncel.
Destek süreciniz müşteriler için belgelenmiş.

Bu kontroller tamamlandıktan sonra, yapılandırdığınız entegrasyon temel Performance Hub platformundaki Performance Hub iş ortağı dizininde görünür.

En iyi uygulamalar

İş ortağı entegrasyonlarını tesisler için öngörülebilir, izlenebilir ve güvenli tutmak üzere bu kalıpları kullanın.

Tesisleri tutarlı biçimde tanımlayın

İş ortağı hesabınız için yapılandırılmış bağlama yöntemini seçin ve tutarlı biçimde kullanın:

Direct Link - tesisler uç noktasının döndürdüğü Performance Hub facility_id değerini kullanın.
Linking Identifier - şube kimliği, konum kodu veya mağaza numarası gibi kendi konum tanımlayıcınızı kullanın.

Aynı istekte iki tanımlayıcıyı birden göndermeyin. Performance Hub istekleri, iş ortağı hesabınız için yapılandırılmış bağlama yöntemini kullanarak çözümler.

Kurulum yönergeleri için İş Ortağı Bağlama Yöntemleri sayfasına bakın.

Toplu yazma işlemlerini dikkatli yapın

Partner API, JSON istek gövdelerini kabul eder ve belgelendiği yerlerde toplu işleme odaklı eşitleme iş akışları için tasarlanmıştır. Toplu işlemleri sınırlı ve yeniden denenebilir tutun.

Varsayılan yönergeler:

En iyi performans için toplu istek başına en fazla 1000 öğe kullanın.
Yükleri 10MB altında tutun.
Uç nokta başına saniyede 5 istek sınırında kalın.

Hız sınırları ayarlanabilir ve Performance Hub iş ortağı hesap yöneticiniz tarafından duruma göre yapılandırılabilir. Yüksek hacimli içe aktarmalar, lansman trafiği veya raporlama geri doldurmaları bekliyorsanız gereken işlem hacmini değişiklik penceresinden önce kararlaştırın.

Büyük bir veri kümesini eşitlemeniz gerekiyorsa onu belirlenimci parçalara bölün ve her parçanın kimliğini kendi tarafınızda kaydedin. Bu, başarısız yeniden denemeleri anlamayı kolaylaştırır.

Güvenli şekilde yeniden deneyin

429, 500, 502, 503 ve 504 gibi geçici hatalar için üstel geri çekilme kullanın.

Sıkı yeniden deneme döngülerinden kaçının. İyi bir başlangıç noktası şudur:

1 saniye sonra yeniden deneyin.
2 saniye sonra yeniden deneyin.
4 saniye sonra yeniden deneyin.
İşlem hâlâ başarısız oluyorsa durun ve uyarı verin.

400 veya 422 gibi doğrulama hataları için yeniden denemeden önce isteği düzeltin.

Desteklendiği yerlerde idempotency kullanın

Door/Gate Controller kilit açma uç noktası isteğe bağlı bir idempotency_key destekler. Aynı iş ortağı, tesis ve kapı için aynı anahtarı yeniden kullanmak, varsa mevcut sonucu döndürür.

Gerçekleştirilen eylem için sabit bir anahtar kullanın; örneğin sisteminizdeki bir check-in kimliği veya erişim olayı kimliği.

O uç nokta için belgelenmedikçe her yazma uç noktasının idempotency'yi desteklediğini varsaymayın.

Kaynak verileri temiz tutun

Mümkün olan her yerde sabit, normalleştirilmiş değerler gönderin:

Kaynak sisteminizdeki tutarlı üye, plan, tesis ve check-in kimliklerini kullanın.
Tarihler ve saatler için ISO 8601 zaman damgaları kullanın.
Mümkün olduğunda telefon numaralarını uluslararası biçimde gönderin.
Para birimlerini her uç nokta için belgelenen alanları kullanarak gönderin.
Serbest metin alanlarını yapılandırılmış alanlara ait verilerle aşırı yüklemekten kaçının.

Artımlı ve tam eşitlemeler için tasarlayın

Çoğu iş ortağı entegrasyonu ikisine de ihtiyaç duyar:

Günlük değişiklikler için artımlı eşitlemeler.
Kaçırılan olayları, geçmiş içe aktarmaları veya veri kaymasını düzeltmek için tam mutabakat eşitlemeleri.

Entegrasyonunuz bir üye, üyelik planı veya rapor anlık görüntüsünün güncel durumunu, önceki bir isteğin başarılı olmasına bağlı olmadan yeniden gönderebilmelidir.

Access Time Windows'u güvenli şekilde yayımlayın

Her üyenin access_time_windows değerini eksiksiz ve bağımsız olarak revizyonlanan bir anlık görüntü olarak ele alın:

Artımlı ve mutabakat çalışanları genelinde tekdüze artan tek bir access_time_windows_revision akışını koordine edin.
Belirsiz veya geçici bir teslimatı aynı revizyon ve normalleştirilmiş yükle yeniden deneyin.
access_time_windows değerini güncellemiyorsanız göndermeyin.
[] değerini yalnızca başarılı ve yetkili bir kaynak sorgusu hiçbir pencere kalmadığını kanıtladıktan sonra gönderin. Bir üst kaynak zaman aşımını, kısmi sonucu veya ayrıştırma hatasını asla iptale dönüştürmeyin.
external_id ve scope_key değerlerini sabit tutun ve üretimden önce her kapsam eşlemesini sertifikalandırın.
Kaynak yaşını o entegrasyon için kararlaştırılan güncellik ilkesine göre izleyin.

Eksiksiz anlık görüntüler, saat dilimleri, yaz saati uygulaması, iptal ve test vektörleri için yetkili Access Time Windows üretici kılavuzuna bakın.

Erişim denetimini güvenlik açısından kritik olarak ele alın

Door/Gate Controller kilit açma işlemleri için:

Sisteminiz Performance Hub'ı çağırmadan önce kişinin girişine izin verilip verilmeyeceğine karar vermelidir.
Performance Hub, yalnızca sahadaki kontrol cihazı rölenin fiziksel olarak kilidinin açıldığını onayladıktan sonra 200 döndürür.
Onayların çoğu 3-5 saniye içinde tamamlanır.
Zaman aşımı, arka planda gerçekleşen bir başarı değil, açık bir başarısız kilit açma işlemidir.
Yalnızca kendi erişim ve güvenlik kurallarınıza göre yeniden deneyin.

Kilit açma uç noktasının döndürdüğü event_id ve command_id değerlerini her zaman kaydedin.

Entegrasyonunuzu izleyin

Geliştirme ve lansman sırasında Partner Console istek kayıtlarını kullanın. Üretimde ayrıca şu bilgileri içeren kendi kayıtlarınızı tutun:

İstek zaman damgası.
Uç nokta.
Kaynak kayıt kimliği.
Tesis tanımlayıcısı.
HTTP durum kodu.
Performance Hub yanıt gövdesi veya hata mesajı.

Bu alanlar, bir müşteri ne olduğunu sorduğunda destek ve mutabakat işlemlerini çok daha hızlı hale getirir.

Organizasyonlar

Performance Hub platformuyla entegre bir veya daha fazla tesisi işleten en üst düzey ticari kuruluşu temsil eder.

Uç noktalar

GET /partner/v1/organisations - List all organisations

Organizasyon nesnesi

Öznitelikler

org_id string zorunlu

Organizasyonun benzersiz tanımlayıcısı.
name string zorunlu

Organizasyon adı.

Organizasyon nesnesi

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

Tüm organizasyonları listeleme

İş ortağı hesabınızın erişebildiği organizasyonların listesini döndürür.

Döndürülen değer

Organizasyon nesnelerinden oluşan bir dizi içeren data özelliğine sahip bir JSON nesnesi döndürür.

İstek

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

Yanıt

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

Tesisler

Üyelerin hizmetlere erişebildiği ofis, mağaza, mekan, kampüs, klinik veya spor salonu gibi fiziksel bir konumu temsil eder.

Uç noktalar

GET /partner/v1/facilities - List all facilities

Tesis nesnesi

Öznitelikler

facility_id string zorunlu

Tesisin benzersiz tanımlayıcısı.
org_id string zorunlu

Üst organizasyonun benzersiz tanımlayıcısı.
name string zorunlu

Tesis adı.
brand string isteğe bağlı

Tesisin kullandığı marka adı.
website_url string isteğe bağlı

Tesisin web sitesi URL'si.
place_data object isteğe bağlı

Ülke, biçimlendirilmiş adres, Google Place ID, il ve şehir bilgilerini içeren Google Places API konum verileri.
social_links object isteğe bağlı

Tesisin sosyal medya bağlantıları.
timezone string isteğe bağlı

IANA saat dilimi tanımlayıcısı (ör. "Australia/Sydney", "America/New_York").

Tesis nesnesi

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

Tüm tesisleri listeleme

İş ortağı hesabınızın erişebildiği tesislerin listesini döndürür.

Döndürülen değer

Tesis nesnelerinden oluşan bir dizi içeren data özelliğine sahip bir JSON nesnesi döndürür.

İstek

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

Yanıt

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

Üyelik planları

Bir organizasyonun veya tesisin hizmetler, haklar, program ve fiyatlandırma dahil satın alınabilir bir teklifini tanımlar.

Uç noktalar

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

Membership Plan nesnesi

Öznitelikler

membership_plan_id string zorunlu

Üyelik planının benzersiz tanımlayıcısı.
facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub'daki tesisin benzersiz tanımlayıcısı.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağının her konum için kullandığı benzersiz tanımlayıcı değeri (ör. "Branch ID", "Location Code", "Store Number"). Daha fazla bilgi
name string zorunlu

İnsan tarafından okunabilir plan adı (ör. "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").
billing_cycle string isteğe bağlı

Faturalandırma sıklığı. weekly, fortnightly, monthly, annually veya one_time değerlerinden biri.
price integer isteğe bağlı

En küçük para birimi cinsinden temel maliyet (USD/AUD için sent).
currency string isteğe bağlı

ISO 4217 para birimi kodu (ör. "AUD", "USD").
description string isteğe bağlı

İsteğe bağlı pazarlama veya dahili açıklama.
active_members integer isteğe bağlı

Bu üyelik planını kullanan etkin üye sayısı
is_recurring boolean isteğe bağlı

Planın otomatik olarak yenilenip yenilenmediği.
is_trial boolean isteğe bağlı

Bunun bir deneme teklifi olup olmadığı.
visible_to_public boolean isteğe bağlı

Planın self servis satın alma için kullanılabilir olup olmadığı.
duration_days integer isteğe bağlı

Üyelik planının geçerli olduğu gün sayısı.
access_zones array isteğe bağlı

Üyelik planına dahil olan erişim alanlarının dizisi. Her alan kendi erişim saatlerini tanımlayabilir. Ayrıntılar için Erişim alanları bölümüne bakın.
class_limit integer isteğe bağlı

İzin verilen maksimum ders sayısı (sınırsız için null).

Membership Plan nesnesi

Bu örnek facility_id kullanır. Bağlama tanımlayıcısı entegrasyonu için bunun yerine "linking_identifier": "branch_downtown" gönderin.

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

Erişim alanları

Erişim alanları, bir tesis içinde bir üyelik planının erişim verdiği belirli bölümleri tanımlar. Her alanın kendi erişim saatleri olabilir; böylece her alan için farklı zaman kısıtlamaları uygulanabilir.

Yapı

Her erişim alanı şunları içerir:

name string zorunlu

Alanın adı (ör. "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor").
description string isteğe bağlı

O alana nelerin dahil olduğunun açıklaması.
access_hours object isteğe bağlı

Bu alana özgü erişim saatleri. Zaman aralığı biçimi için Erişim saatleri bölümüne bakın.

Örnek

Kiracıları için spor salonu bulunan bir ofis binası: mesai saatlerinde kiralanan alana, sabahın erken saatlerinden akşamın geç saatlerine kadar da spor salonuna erişim.

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

Erişim saatleri

Erişim saatleri, üyelerin haftanın her günü belirli bir alana ne zaman erişebileceğini belirtir. Erişim saatleri her erişim alanı için ayrı tanımlanır; böylece bir tesisin farklı bölümleri için farklı zaman kısıtlamaları uygulanabilir.

Yapı

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

Her gün, HH:MM biçiminde (24 saatlik) zaman aralıklarından oluşan bir dizidir. Boş bir [] dizisi o gün erişim olmadığı anlamına gelir. Belirtilmeyen günler boş bir diziyle aynı şekilde değerlendirilir.

Örnek kullanım senaryoları

Ofis kiracısı – mesai saatleri: yalnızca hafta içi mesai saatlerinde erişim.

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

Öğrenci – dönem erişimi: hafta içi gün ortasında bir araya sahip olarak ve cumartesi sabahları açık olan bir kampüs kütüphanesi.

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

Spor salonu – erken kalkan: hafta içi yalnızca sabah erişimi.

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

Otel misafiri – 7/24: her zaman açık erişim; en yaygın kullanım senaryosu.

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

Alan başına örnek

Misafir katlarına günün her saatinde erişim ve havuz için daha kısa saatler içeren bir otel misafiri planı:

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

Bir üyelik planını kaydetme

Üyelik planı kayıtları oluşturur veya günceller. API, oluşturma ya da güncelleme yapılacağına membership_plan_id değerine göre karar verir.

Parametreler

membership_plans array zorunlu

Kaydedilecek Membership Plan nesnelerinin dizisi. En iyi performans için önerilen üst sınır: istek başına 1000 öğe. API, öğeleri işlenmek üzere otomatik olarak gruplar. Her öğe facility_id (linking_identifier kullanılmıyorsa zorunlu) veya linking_identifier (facility_id kullanılmıyorsa zorunlu) içermelidir.

Döndürülen değer

Eşitleme işlemini onaylayan basit bir mesaj döndürür.

İstek

Bu örnek facility_id kullanır. Bağlama tanımlayıcısı entegrasyonu için bunun yerine "linking_identifier": "branch_downtown" gönderin.

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

Yanıt

Eşitleme işlemine ilişkin meta verilerle birlikte bir başarı mesajı döndürür.

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

Meta veri alanları:

success - Başarıyla işlenen üyelik planı sayısı
skipped - Atlanan plan sayısı (varsa)
skipped_items - Atlanan planların nedenleriyle birlikte dizisi (varsa)
dry-run - dryrun anahtar türü kullanılıyorsa Boolean bayrak (varsa)

Üyeler

Bir tesisin bireysel müşterisini temsil eder. Potansiyel müşteri, aday, düzenli müşteri, süresi dolmuş üye veya engellenmiş kullanıcı olabilir.

Üye upsert işlemleri, mutlak ve yinelenen haftalık erişim içeren eksiksiz, revizyonlu bir access_time_windows anlık görüntüsü de taşıyabilir. Bu alanları üretmeden önce Access Time Windows bölümüne bakın. Bunlar ek izinlerdir ve tesisin normal kurallarının veya kalıcı izinlerinin yerini almaz.

Uç noktalar

POST /partner/v1/members - Save a member

Member nesnesi

Öznitelikler

member_id string zorunlu

Üyenin benzersiz tanımlayıcısı.
facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub'daki tesisin benzersiz tanımlayıcısı.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağının her konum için kullandığı benzersiz tanımlayıcı değeri (ör. "Branch ID", "Location Code", "Store Number"). Daha fazla bilgi
first_name string zorunlu

Üyenin adı.
last_name string zorunlu

Üyenin soyadı.
email string isteğe bağlı

E-posta adresi.
mobile_phone string isteğe bağlı

E.123 biçiminde cep telefonu numarası (ör. "+1 415 555 2671").
address object isteğe bağlı

Aşağıdaki özelliklere sahip fiziksel adres nesnesi:
- address_line_1 (string) - Birincil sokak adresi
- address_line_2 (string, isteğe bağlı) - İkincil adres satırı
- city (string) - Şehir adı
- state (string) - Eyalet/il kodu
- postal_code (string) - Posta kodu/ZIP kodu
- country (string) - ISO 3166-1 alpha-2 ülke kodu (ör. "AU", "US")
- country_name (string, isteğe bağlı) - Tam ülke adı
date_of_birth string isteğe bağlı

YYYY-MM-DD biçiminde doğum tarihi.
gender string isteğe bağlı

male, female, non_binary, prefer_not_to_say veya unknown değerlerinden biri.
type string isteğe bağlı

Üye türü (ör. staff, member, prospect).
tags array isteğe bağlı

Belirli üyeleri kategorilere ayırmak ve tanımlamak için kısa yardımcı dizeler veya metinler (ör. ["vip", "personal-training", "student"]).
membership_status string isteğe bağlı

Geçerli üyelik durumu (ör. active, expired, on_hold).
membership_plans array isteğe bağlı

Üyeyle ilişkili üyelik planlarının dizisi.
profile_picture string isteğe bağlı

Base64 ile kodlanmış profil resmi (isteğe bağlı).
created string isteğe bağlı

Üyenin oluşturulduğu zamanın ISO 8601 zaman damgası.
updated string isteğe bağlı

Üyenin son güncellendiği zamanın ISO 8601 zaman damgası.
access_time_windows array isteğe bağlı

Mutlak ve/veya yinelenen haftalık Access Time Windows'un kaynağa ait eksiksiz anlık görüntüsü. Anlık görüntüyü değiştirmeden bırakmak için alanı göndermeyin; iptal etmek için daha yeni bir revizyonla boş bir dizi gönderin. Biçimler, doğrulama, kapsam eşlemesi ve değiştirme semantiği için Access Time Windows bölümüne bakın.
access_time_windows_revision integer access_time_windows ile zorunlu

Bu üye/kaynak akışı için tekdüze artan, negatif olmayan, JSON açısından güvenli bir tam sayı. access_time_windows mevcut olduğunda her zaman zorunludur.

Member nesnesi

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

Erişim Zaman Pencereleri

Access Time Windows, bir Partner Member'ın harici bir sistem tarafından sağlanan geçici veya yinelenen erişim taşımasını sağlar. Bu sayfa, access_time_windows ve access_time_windows_revision için yetkili üretici kılavuzudur.

Access Time Windows, yalnızca izin veren ek izinlerdir. Etkin bir pencere erişime izin verebilir; ancak etkin olmayan, süresi dolmuş, eski veya eşlenmemiş bir pencere, normal bir kuralın veya kalıcı bir iznin zaten verdiği erişimi reddetmez. Kullanıcının devre dışı bırakılması, açık kapı engellemesi, bakım modu, coğrafi sınırlama (geofencing), hız sınırları ve kontrol cihazının kullanılabilirliği yine geçerlidir.

Belirli üst kaynak sistemlere yönelik uygulamalar ayrı bağdaştırıcılardır. Bunlar, kaynak verilerini alan anlamlarını değiştirmeden bu sağlayıcıdan bağımsız sözleşmeye dönüştürmelidir.

Üye anlık görüntüsü alanları

access_time_windows array isteğe bağlı

Bu üye ve iş ortağı kaynağı için eksiksiz Access Time Window anlık görüntüsü. Bir anlık görüntü absolute ve weekly pencereleri karışık olarak içerebilir. Saklanan anlık görüntüyü değiştirmeden bırakmak için alanı göndermeyin; bu kaynağa ait tüm pencereleri iptal etmek için [] gönderin.
access_time_windows_revision integer access_time_windows ile zorunlu

Bu üye/kaynak revizyon akışı için tekdüze artan, negatif olmayan, JSON açısından güvenli bir tam sayı. access_time_windows mevcut olduğunda her zaman zorunludur ve 9007199254740991 değerini aşmamalıdır.

Her anlık görüntü en fazla 50 pencere kabul eder. external_id, scope_key ve label en fazla 120 karakter kabul eder. Mutlak pencereler en fazla 90 gün kapsayabilir. Haftalık bir gün, en fazla sekiz çakışmayan blok kabul eder. Geçersiz veriler kırpılmaz veya tahmin edilmez, reddedilir.

Pencere biçimleri

Mutlak bir pencere tek bir kesin aralığı tanımlar:

Eksiksiz karışık istek

Bu istek, üyenin kaynağa ait önceki anlık görüntüsünü bir mutlak ve bir haftalık pencereyle değiştirir:

Zaman ve sınır kuralları

from, to, active_from ve active_until, UTC anlarını tanımlayan JSON tam sayı Unix saniyeleridir:

Tırnaksız bir JSON tam sayısı gönderin. Sayısal dizeler, kayan noktalı sayılar, RFC 3339 dizeleri ve Unix milisaniyeleri reddedilir.
Her aralık yarı açıktır: [from, to). Erişim tam olarak from anında başlayabilir; tam olarak to anında artık etkin değildir.
from, to değerinden küçük olmalıdır. Her iki haftalık sınır da mevcut olduğunda active_from, active_until değerinden küçük olmalıdır.
Epoch değerlerini saat dilimi belirtilmemiş yerel bir tarih/saatten türetmeyin. Önce kaynak zamanı bir UTC anına çözümleyin, ardından Unix milisaniyelerini 1000'e bölün ve sonucun tam sayı olduğunu doğrulayın.

Saat dilimleri ve yaz saati uygulaması

timezone, UTC, Australia/Perth veya America/New_York gibi geçerli bir IANA saat dilimi olmalıdır. Belirtilmezse varsayılan olarak UTC olur.

Mutlak pencereler: from ve to zaten kesin UTC anlarını tanımlar. timezone yalnızca görüntüleme ve denetim meta verisidir; değiştirilmesi iki andan hiçbirini kaydırmaz.
Haftalık pencereler: timezone, access_hours değerlendirmesinde kullanılan yerel duvar saatini ve yaz saati kurallarını tanımlar. Haftalık blokları önceden UTC'ye dönüştürmeyin.
İleri alma değişikliği sırasında, saat diliminin atladığı bir yerel saat hiç gerçekleşmez.
Geri alma değişikliği sırasında, yinelenen yerel saati taşıyan her iki gerçek an da haftalık blokla eşleşir.
Haftalık bir pencere UTC dışı bir saat dilimi kullansa bile active_from ve active_until UTC anları olarak kalır.

access_hours, küçük harfli sun ile sat arasındaki değerleri kullanır. Her değer, başında sıfır olan 24 saatlik HH:mm biçiminde [start, end] çiftlerinden oluşan bir dizidir. Bloklar boş olmamalı, sıralı olmalı ve çakışmamalıdır. end hariçtir. Bir blok gece yarısını geçemez; gece boyunca süren bir kaynak aralığını ilk gün için geç bir bloğa ve sonraki gün için erken bir bloğa bölün.

Sabit kimlikler ve kapsam eşlemesi

external_id, mantıksal bir pencerenin ömrü boyunca sabit ve üye anlık görüntüsü içinde benzersiz olmalıdır. Operatörlerin ve denetim kayıtlarının revizyonları ilişkilendirebilmesi için saatler veya etiketler değiştiğinde de sabit tutun. İlgisiz bir pencere için yeniden kullanmayın.

scope_key, sabit mantıksal erişim hedefinizdir. Varsayılan değeri default olur. Bir tesis yöneticisi, izin verilen her anahtarı Performance Hub'ın tesis geneli, kapı veya Erişim Kapsamı hedeflerine eşler:

Eksiksiz anlık görüntüler ve revizyonlar

İki alanı, Member upsert işlemi içinde ayrı olarak sürümlenen bir bölüm olarak ele alın:

Girdi	Sonuç
`access_time_windows` gönderilmedi	Mevcut anlık görüntü değişmeden kalır; revizyon gerekmez
Daha yeni bir revizyonla mevcut	Bu üye/kaynak için saklanan anlık görüntünün tamamı değiştirilir
Aynı revizyon ve aynı normalleştirilmiş yük	Idempotent yeniden oynatma; anlık görüntü değişmez
Aynı revizyon ve farklı normalleştirilmiş yük	Çakışma; mutabakattan sonra yeni bir revizyon atayın
Daha eski revizyon	Eski anlık görüntü atlanır; daha yeni durumun üzerine yazamaz
Daha yeni bir revizyonla `access_time_windows: []`	Kaynağa ait tüm pencereleri açıkça iptal eder

Bir anlık görüntü yama değil, eksiksiz bir bütündür. 1842 revizyonunda A ve B pencereleri varsa, yalnızca B'yi içeren 1843 revizyonu A'yı kaldırır.

Webhook çalışanları, yoklama, yeniden oynatma ve tam mutabakat genelinde iş ortağı/üye başına tek bir koordineli revizyon akışı sürdürün. Kalıcı bir veritabanı dizisi tercih edilir. Bir Unix milisaniye değeri, yalnızca her yazıcı koordineli çalışıp katı sıralama ve benzersizliği garanti ettiğinde revizyon olarak kullanılabilir; bu bir revizyon değeridir, epoch alanı değildir.

API yanıtı bilinene kadar tam isteği ve revizyonu kalıcı olarak saklayın. Bir zaman aşımı veya geçici hatadan sonra aynı normalleştirilmiş anlık görüntüyü aynı revizyonla yeniden deneyin. Yalnızca aktarım teslimatı belirsiz olduğu için yeni bir revizyon atamayın.

İptal, süre sonu ve üst kaynak hataları

Tek bir pencereyi iptal etme: yetkili kaynak durumunu başarıyla alın, o pencereyi kaldırın ve kalan eksiksiz anlık görüntüyü daha yeni bir revizyonla gönderin.
Tüm pencereleri iptal etme: daha yeni bir revizyonla access_time_windows: [] gönderin.
Mutlak bir pencerenin süresinin dolmasına izin verme: pencere to anında izin vermeyi durdurur; anlık görüntüleri temiz tutmak için süresi dolan kaydı içermeyen daha sonraki bir mutabakat gönderin.
Haftalık bir pencereyi sonlandırma: onu daha yeni bir anlık görüntüde kaldırın veya kaynağın bilinen bir bitiş anı varsa active_until kullanın.
Kaynak sorgusu başarısız veya eksik: [] göndermeyin ve kısmi bir anlık görüntü yayımlamayın. Uyarı verin ve sorguyu yeniden deneyin. Bir üst kaynak hatasını boş bir anlık görüntüye dönüştürmek istenmeyen bir erişim iptalidir.
Partner API isteği doğrulamadan geçemiyor: verileri düzeltin ve yalnızca normalleştirilmiş anlık görüntü değişirse daha yeni bir revizyon gönderin. Geçici hataları orijinal revizyonla yeniden deneyin.

Kaynak güncelliği, her entegrasyon için taahhüt edilen teslimat ve mutabakat sıklığına göre yapılandırılır. Etkinleştirmeden önce maksimum kaynak yaşını, aşıldığında ne olacağını, uyarı eşiklerini ve operatörlerin yalnızca her pencerenin kendi sınırlarına güvenmeyi onaylayıp onaylayamayacağını kararlaştırın. Eski bir kaynak penceresi asla bir reddetme kuralına dönüşmez; normal kurallar ve kalıcı izinler yedek yollar olarak kalır.

Üretici algoritması

Her üye güncellemesi için bu dilden bağımsız iş akışını kullanın:

Sertifikasyon kontrol listesi

Bu kontrolleri son scope_key eşlemesini kullanarak bir stage tesisinde tamamlayın:

Saat dilimi belirtilmemiş mutlak bir pencere kabul ediliyor ve UTC olarak değerlendiriliyor.
Özel IANA saat dilimli mutlak bir pencere aynı from/to anlarını koruyor.
Özel IANA saat dilimli haftalık bir pencere, ileri ve geri alma geçişlerinde yerel duvar saatini izliyor.
Karışık mutlak/haftalık bir anlık görüntü önceki anlık görüntünün tamamen yerini alıyor.
Erişim tam olarak from anında başlıyor ve tam olarak to anında duruyor; haftalık blok sonları da hariç tutuluyor.
Aynı external_id altında saatlerin daha yeni bir revizyonla güncellenmesi etkili oluyor.
access_time_windows gönderilmediğinde diğer Member alanları pencereler değişmeden güncelleniyor.
Aynı revizyonun/yükün yeniden oynatılması idempotent.
Aynı revizyon/farklı yük bir çakışma döndürüyor ve anlık görüntüyü değiştirmiyor.
Sırası bozuk, daha eski bir revizyon eski olarak bildiriliyor ve durumu geri alamıyor.
Daha yeni bir [] kaynağa ait pencereleri iptal ediyor; bir üst kaynak sorgu hatası hiçbir şey göndermiyor.
Bilinmeyen veya eşlenmemiş bir scope_key kapalı başarısız oluyor ve operatörün görebileceği bir uyarı oluşturuyor.
Kaynak yaşı uyarıları ve yapılandırılmış eski kaynak ilkesi kararlaştırılan eşikte çalışıyor.
Webhook ve tam mutabakat yolları aynı anlık görüntü ve revizyon sırasında birleşiyor.
Akış teslimatı, kararlaştırılan hedef süre içinde Door & Gate Access'e ulaşıyor.
Etkin bir pencere eşlenen fiziksel kapıya izin verebiliyor ancak kullanıcı devre dışı bırakmayı, blockAllAccess ayarını, bakımı veya coğrafi sınırlamayı atlayamıyor.
Bir pencereden önce, pencere dışında ve pencereden sonra, normal kurallar ve kalıcı izinler başka açılardan uygun olan kullanıcılara hâlâ izin veriyor.

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

Zorunlu alanlar external_id, kind, from ve to alanlarıdır. timezone, scope_key ve label isteğe bağlıdır.

Haftalık bir pencere, isteğe bağlı olarak UTC anlarıyla sınırlandırılmış, yinelenen yerel duvar saati aralıklarını tanımlar:

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

Zorunlu alanlar external_id, kind ve access_hours alanlarıdır. timezone, active_from, active_until, scope_key ve label isteğe bağlıdır.

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

Yapılandırdığınız bağlama yöntemine göre facility_id veya linking_identifier kullanın. İkisini birden göndermeyin.

Epoch dönüştürme

2026-10-15T08:30:00Z, 1792053000 değerine dönüşür:

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

Dilden bağımsız dönüştürme:

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

Kaynak saniyenin altında hassasiyete sahipse entegrasyon testinden önce bilinçli bir başlangıç/bitiş yuvarlama ilkesi tanımlayın. Asla milisaniye gönderip birimi API'nin çıkarmasına güvenmeyin.

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

İş ortakları bir pencere içinde Performance Hub tesis, kapı veya Erişim Kapsamı kimlikleri göndermez. Bilinmeyen, devre dışı bırakılmış veya eşlenmemiş bir scope_key, o pencere için kapalı başarısız olur (fail closed); erişimi genişletmez. Eşlemeleri lansmandan önce kararlaştırın ve test edin.

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)

Minimum test vektörleri

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

Ayrıca Unix milisaniyeleri, sayısal dizeler, kayan noktalı sayılar, geçersiz IANA saat dilimleri, from >= to, yinelenen external_id, çakışan bloklar, gece blokları, bir günde sekizden fazla blok, 50'den fazla pencere ve eşlenmemiş kapsam anahtarları için negatif vektörler gönderin.

Bir üyeyi kaydetme

Üye kayıtları oluşturur veya günceller. API, oluşturma ya da güncelleme yapılacağına member_id değerine göre karar verir.

Parametreler

members array zorunlu

Kaydedilecek Member nesnelerinin dizisi. En iyi performans için önerilen üst sınır: istek başına 1000 öğe. API, öğeleri işlenmek üzere otomatik olarak gruplar. Her öğe facility_id (linking_identifier kullanılmıyorsa zorunlu) veya linking_identifier (facility_id kullanılmıyorsa zorunlu) içermelidir.

Bir üye access_time_windows içerdiğinde access_time_windows_revision değerini de içermelidir. Dizi bir yama değil, eksiksiz bir kaynak anlık görüntüsüdür. Mevcut anlık görüntüyü korumak için göndermeyin veya kaynağa ait tüm pencereleri iptal etmek için daha yeni bir revizyonla [] gönderin. Bu alanı etkinleştirmeden önce Access Time Windows kılavuzunu okuyun.

Döndürülen değer

Eşitleme işlemini onaylayan basit bir mesaj döndürür.

Bir pencere anlık görüntüsü idempotent yeniden oynatma veya eski olduğu için atlama olarak bildirilse bile üye profili alanları normal upsert işlemleri olarak kalır. Aynı revizyona sahip, farklı yük içeren çakışan bir anlık görüntü değiştirilmeden yeniden denenemez; kaynak durumuyla mutabakat sağlayın ve daha yeni bir revizyon gönderin.

İstek

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

Yanıt

Eşitleme işlemine ilişkin meta verilerle birlikte bir başarı mesajı döndürür.

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

Meta veri alanları:

success - Başarıyla işlenen üye sayısı
skipped - Atlanan üye sayısı (varsa)
skipped_items - Atlanan üyelerin nedenleriyle birlikte dizisi (varsa)
dry-run - dryrun anahtar türü kullanılıyorsa Boolean bayrak (varsa)

Check-in'ler

Bir kişinin bir tesiste, derste veya etkinlikte bulunduğuna ilişkin bir kaydı temsil eder. Katılımı takip etmek, kullanım analizi yapmak ve görsel algılama doğruluğunu artırmak için kullanılır.

Uç noktalar

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

Check-in nesnesi

Öznitelikler

check_in_id string isteğe bağlı

Check-in için benzersiz tanımlayıcı. İsteğe bağlı; sağlanmazsa member_id ve timestamp çiftinden otomatik olarak oluşturulur.
member_id string zorunlu

Üyenin benzersiz tanımlayıcısı.
facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub'daki tesisin benzersiz tanımlayıcısı.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağının her konum için kullandığı benzersiz tanımlayıcı değeri (ör. "Branch ID", "Location Code", "Store Number"). Daha fazla bilgi
check_in_type string isteğe bağlı

Ziyaret türü. member, class, staff, guest veya trial değerlerinden biri.
source string isteğe bağlı

Check-in'in nasıl kaydedildiği. Yaygın değerler arasında manual, tag, rfid, kiosk, app bulunur. door_reader veya booking gibi ek değerler de kullanılabilir.
class_id string isteğe bağlı

İsteğe bağlı. Bir ders rezervasyonuna veya katılımına bağlıysa.
timestamp string zorunlu

Check-in'in gerçekleştiği zamanın ISO 8601 biçimindeki zaman damgası.

Check-in nesnesi

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

Check-in'leri kaydetme

Check-in kayıtları oluşturur. API, üye, tesis ve zaman damgasına göre yinelenen kayıtları otomatik olarak ayıklar.

Parametreler

check_ins array zorunlu

Kaydedilecek Check-in nesnelerinin dizisi. En iyi performans için önerilen üst sınır: istek başına 1000 öğe. API, öğeleri işlenmek üzere otomatik olarak gruplar. Her öğe facility_id (linking_identifier kullanılmıyorsa zorunlu) veya linking_identifier (facility_id kullanılmıyorsa zorunlu) içermelidir.

Döndürülen değer

Eşitleme işlemini onaylayan basit bir mesaj döndürür.

İstek

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

Yanıt

Eşitleme işlemine ilişkin meta verilerle birlikte bir başarı mesajı döndürür.

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

Meta veri alanları:

success - Başarıyla işlenen check-in sayısı
skipped - Atlanan check-in sayısı (varsa)
skipped_items - Atlanan check-in'lerin nedenleriyle birlikte dizisi (varsa)
dry-run - dryrun anahtar türü kullanılıyorsa Boolean bayrak (varsa)

Erişim denetimi

Partner API, entegrasyonunuzun etkin olduğu tesislerde Performance Hub Door/Gate Controller donanımını tetikleyebilir.

Bu API'yi, üye yönetim sisteminiz bir kişinin girişine izin verildiğine zaten karar verdiğinde kullanın. Performance Hub üyelik durumunu, erişim saatlerini, kapı alanı kurallarını, dolandırıcılık kontrollerini veya askıya alma mantığını değerlendirmez. Bu kararlar için yetkili kaynak sizin sisteminiz olmaya devam eder.

Kilit açma isteği eşzamanlıdır. Performance Hub komutu sahadaki kontrol cihazına gerçek zamanlı olarak gönderir ve yalnızca cihaz rölenin fiziksel olarak kilidinin açıldığını onayladıktan sonra 200 döndürür. Onayların çoğu 3-5 saniye içinde tamamlanmalıdır. Zaman aşımı penceresi içinde onay alınmazsa API açık bir hata döndürür.

Kontrol cihazına hiç ulaşmayan bir erişim girişimini veya reddi de kaydedebilirsiniz. Bu çağrı kapının kilidini açmaz. Door & Gate Access kayıtlarına bir olay yazar.

Uç noktalar

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

Door/Gate Controller nesnesi

Öznitelikler

door_id string zorunlu

Door/Gate Controller için benzersiz tanımlayıcı. Keşiften sonra bunu sisteminizde saklayın ve kilit açma uç noktasını çağırırken kullanın.
facility_id string zorunlu

Performance Hub tesis kimliği.
linking_identifier string isteğe bağlı

Entegrasyonunuz bağlama tanımlayıcıları kullandığında iş ortağı tesis tanımlayıcısı. Daha fazla bilgi
name string zorunlu

Performance Hub'da yapılandırılmış, insan tarafından okunabilir cihaz adı.
zone string isteğe bağlı

Entrance gibi kapı alanı veya konumu.
status string zorunlu

online veya offline.
relay_state string isteğe bağlı

locked veya unlocked gibi bilinen en son röle durumu.
maintenance_mode string zorunlu

Geçerli bakım modu. off, force-open veya force-closed değerlerinden biri.
hold_time_seconds integer zorunlu

Kapı için yapılandırılmış varsayılan kilit açık tutma süresi.
last_seen string isteğe bağlı

En son cihaz meta verisi güncellemesinin ISO zaman damgası.

Door/Gate Controller nesnesi

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

Door/Gate Controller'ları listeleme

Entegrasyonunuzun kullanabildiği Door/Gate Controller'ları döndürür.

Ne facility_id ne de linking_identifier sağlanırsa API, iş ortağı hesabınıza bağlı tüm tesislerdeki Door/Gate Controller'ları döndürür.

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.

Parametreler

facility_id string isteğe bağlı ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub tesis kimliği. Bunu doğrudan bağlantı entegrasyonları için kullanın.
linking_identifier string isteğe bağlı ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Kendi tesis/konum tanımlayıcınız. Entegrasyonunuz bağlama tanımlayıcıları için yapılandırıldığında bunu kullanın.

Döndürülen değer

Door/Gate Controller nesnelerinden oluşan bir dizi döndürür.

İstek

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:

Yanıt

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

Door/Gate Controller durumunu alma

Tek bir Door/Gate Controller'ın bilinen en son durumunu ve temel yapılandırmasını alır.

Performance Hub'ın kapının, entegrasyonunuzun erişebildiği bir tesise ait olduğunu doğrulayabilmesi için bir tesis tanımlayıcısı sağlayın.

Parametreler

door_id string zorunlu

Liste uç noktasının döndürdüğü Door/Gate Controller kimliği.
facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub tesis kimliği. Doğrudan bağlantı entegrasyonları için zorunludur.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağı tesis tanımlayıcısı. Bağlama tanımlayıcısı entegrasyonları için zorunludur.

Döndürülen değer

Bir Door/Gate Controller nesnesi döndürür.

İstek

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:

Yanıt

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

Bir Door/Gate Controller'ın kilidini açma

Door/Gate Controller'a bir kilit açma komutu gönderir ve fiziksel rölenin kilidin açıldığını onaylamasını bekler.

Sisteminiz bu uç noktayı çağırmadan önce kişinin yetkili olup olmadığına karar vermelidir. Performance Hub yalnızca iş ortağı anahtarını, tesis erişimini, kapı sahipliğini ve cihaz durumunu doğrular.

Parametreler

door_id string zorunlu

Liste uç noktasının döndürdüğü Door/Gate Controller kimliği.
facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub tesis kimliği. Doğrudan bağlantı entegrasyonları için zorunludur.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağı tesis tanımlayıcısı. Bağlama tanımlayıcısı entegrasyonları için zorunludur.
member_id string zorunlu

İş ortağı üye kimliği. Denetim kaydı ve sonraki veri bağlama için kullanılır.
first_name string zorunlu

Kapıyı açan kişinin adı.
last_name string zorunlu

Kapıyı açan kişinin soyadı.
full_name string isteğe bağlı

İsteğe bağlı. Belirtilmezse Performance Hub first_name ve last_name değerlerini birleştirir.
check_in_id string isteğe bağlı

İlişkilendirme için sisteminizden isteğe bağlı check-in kimliği.
idempotency_key string isteğe bağlı

İsteğe bağlı yeniden oynatma koruması anahtarı. Aynı iş ortağı, tesis ve kapı için aynı anahtarı yeniden kullanmak, varsa mevcut sonucu döndürür.

Döndürülen değer

Yalnızca cihaz rölenin fiziksel olarak kilidinin açıldığını onayladığında 200 döndürür. Kapı, Performance Hub Aygıt Yönetimi'nde yapılandırılan açık tutma süresini kullanır; iş ortakları röle zamanlamasını istek bazında geçersiz kılamaz. Onayların çoğu 3-5 saniye içinde tamamlanmalıdır. Belgelenen zaman aşımını açık bir başarısız kilit açma olarak değerlendirin ve yalnızca kendi güvenlik kurallarınıza göre yeniden deneyin.

Yaygın hatalar:

403 integration_not_enabled - entegrasyonunuz tesis için etkin değil.
409 maintenance_mode_active - tesis personeli kapı için bakım modunu etkinleştirmiş.
503 device_offline - Door/Gate Controller çevrimdışı veya güncel değil.
504 unlock_confirmation_timeout - komut gönderildi ancak zaman aşımından önce eşleşen bir onay alınamadı.

İstek

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

Yanıt

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

Hata yanıtı

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

Bir erişim girişimini veya reddini kaydetme

Sisteminizin önceden karar verdiği bir erişim girişimini veya reddi kaydeder. Door/Gate Controller ile iletişim kurulmaz ve kapının kilidi açılmaz.

Bunu, sisteminiz girişi reddettiğinde veya bir girişimin kilit açılmadan Door & Gate Access kayıtlarında görünmesi gerektiğinde kullanın. Performance Hub üyelik durumunu, erişim saatlerini veya diğer erişim kurallarını değerlendirmez.

Reddedilen bir olay, Door & Gate Access kayıtlarında Denied sonucu, iş ortağı adınız, kapı, gönderdiyseniz üye tanımlayıcısı ve okunabilir biçimdeki neden koduyla görünür. Örneğin membership_expired, "Membership Expired" olarak gösterilir. reason_display_text ve user_email olayla birlikte saklanır.

Parametreler

door_id string zorunlu

Liste uç noktasının döndürdüğü Door/Gate Controller kimliği.
facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub tesis kimliği. Doğrudan bağlantı entegrasyonları için zorunludur.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağı tesis tanımlayıcısı. Bağlama tanımlayıcısı entegrasyonları için zorunludur.
outcome string zorunlu

denied veya attempted.
reason string isteğe bağlı

Küçük harfli snake_case neden kodu, en fazla 64 karakter. outcome değeri denied olduğunda zorunludur. Örnek: membership_expired.
reason_display_text string isteğe bağlı

İnsan tarafından okunabilir neden, en fazla 256 karakter. Örnek: Membership expired on 2026-04-01.
member_id string isteğe bağlı

İş ortağı üye kimliği. Kimlik bilgisi bir üyeyle eşleşmediğinde (örneğin tanınmayan bir kart) bunu göndermeyin.
user_email string isteğe bağlı

Erişim girişiminde bulunan kişinin e-posta adresi.
timestamp string isteğe bağlı

Girişimin gerçekleştiği zaman, saat dilimiyle ISO 8601 biçiminde. Örnek: 2026-05-18T10:15:30Z. Varsayılan olarak isteğin alındığı zamandır. 5 dakikadan fazla ileri tarihli veya 30 günden eski olmamalıdır.
idempotency_key string isteğe bağlı

Yeniden oynatma koruması anahtarı, en fazla 128 karakter. Aynı iş ortağı, tesis ve kapı için aynı anahtarı yeniden kullanmak orijinal sonucu döndürür.

Döndürülen değer

Olay kaydedildiğinde 201 döndürür. Aynı idempotency_key ile yinelenen istek, idempotent değeri true olarak ayarlanmış şekilde 200 döndürür ve başka bir olay oluşturmaz.

Bir dry-run anahtarı, dry_run değeri true olarak ayarlanmış şekilde 200 döndürür. Hiçbir şey kaydedilmez.

Yaygın hatalar:

400 - gövde geçersiz, bir retta reason yok, zaman damgası aralık dışında veya facility_id / linking_identifier bağlı bir tesisle eşleşmiyor.
403 - anahtar salt okunur.
403 integration_not_enabled - entegrasyonunuz tesis için etkin değil. message nedeni belirtir.
404 - bağlı tesis için Door/Gate Controller bulunamadı.

İstek

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

Yanıt

{
  "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 yeniden oynatma

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

Tesis raporları

Bir tesisin belirli bir dönemdeki temel operasyonel ve finansal ölçümlerini kaydeden, belirli bir zamana ait kayıt.

Uç noktalar

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

Report Snapshot nesnesi

Öznitelikler

facility_id string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

Performance Hub'daki tesisin benzersiz tanımlayıcısı.
linking_identifier string ikisinden biriEntegrasyonunuz için yapılandırılmış tesis tanımlayıcısı türünü sağlayın: doğrudan bağlantı (direct-link) entegrasyonları için facility_id, bağlama tanımlayıcısı (linking-identifier) entegrasyonları için linking_identifier kullanın. İkisini birden göndermeyin; API, iş ortağı hesabınız için yapılandırılmış tanımlayıcı türünü kullanır ve diğerini yok sayar. Daha fazla bilgi

İş ortağının her konum için kullandığı benzersiz tanımlayıcı değeri (ör. "Branch ID", "Location Code", "Store Number"). Daha fazla bilgi
start_date string zorunlu

YYYY-MM-DD biçiminde anlık görüntü dönemi başlangıç tarihi.
end_date string zorunlu

YYYY-MM-DD biçiminde anlık görüntü dönemi bitiş tarihi.
metrics object zorunlu

Dönemin üye ve gelir verilerini içeren ölçümler nesnesi.

Report Snapshot nesnesi

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

Rapor anlık görüntülerini kaydetme

Bir tesisin belirli bir dönemdeki operasyonel ve finansal ölçümlerini gönderir.

Parametreler

snapshots array zorunlu

Kaydedilecek Report Snapshot nesnelerinin dizisi. İstek başına en fazla 25 öğe. Her öğe facility_id (linking_identifier kullanılmıyorsa zorunlu) veya linking_identifier (facility_id kullanılmıyorsa zorunlu) içermelidir.

Döndürülen değer

Eşitleme işlemini onaylayan basit bir mesaj döndürür.

İstek

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

Yanıt

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

Hatalar

Partner API, bir isteğin neden başarısız olduğunu açıklamak için standart HTTP durum kodlarını ve JSON yanıt gövdelerini kullanır.

Hata yanıtı biçimi

Çoğu API hatası, bir mesaj ve varsa yapılandırılmış ayrıntılar içeren bir JSON gövdesi döndürür.

Durum kodları

Access Time Window hataları

Pencere doğrulaması, geçersiz anlık görüntü yazılmadan önce başarısız olur. Yeniden denenemeyen yaygın nedenler şunlardır:

access_time_windows mevcutken access_time_windows_revision değerinin eksik olması.
Dize, kayan noktalı veya büyük olasılıkla milisaniye cinsinden epoch değerleri.
Geçersiz bir IANA saat dilimi, ters çevrilmiş aralık, yinelenen external_id, çakışan haftalık bloklar veya bölünmemiş bir gece bloğu.
Belgelenen sayı, uzunluk veya kapsam sınırlarının dışında bir değer.

Farklı normalleştirilmiş içerikle yinelenen bir revizyon 409 Conflict hatasıdır. En son yetkili durumla mutabakat sağlayın ve daha yeni bir revizyon atayın; çakışan çifti yeniden denemeye devam etmeyin. Daha eski bir revizyon, daha yeni durumun üzerine yazmasına izin verilmek yerine eski olduğu için atlanan bir anlık görüntü olarak bildirilir. Bilinmeyen veya eşlenmemiş bir scope_key, yetkilendirme açısından kapalı başarısız olur (fail closed) ve bir yapılandırma uyarısı olarak ele alınmalıdır.

Teslimat zaman aşımına uğrarsa veya geçici bir 5xx alırsa tam olarak aynı normalleştirilmiş anlık görüntüyü aynı revizyonla yeniden deneyin. Üst kaynak sorgusu başarısız olduysa pencere alanını tamamen göndermeyin; asla boş bir diziyle değiştirmeyin.

Yeniden deneme yönergeleri

Bunları sınırlı üstel geri çekilmeyle yeniden deneyin:

429
500
502
503
504

Bunları körü körüne yeniden denemeyin:

400
401
403
404
409
422

Erişim denetiminde, kendi erişim kurallarınız ve güvenlik süreçleriniz aksini söylemedikçe zaman aşımı ve çevrimdışı yanıtlarını her zaman başarısız kilit açma olarak değerlendirin.

Eklenecek destek ayrıntıları

Destekle iletişime geçerken şunları ekleyin:

Uç nokta ve HTTP yöntemi.
Zaman damgası ve saat dilimi.
Gizli anahtar değil, iş ortağı anahtar kimliği.
Kullanılan tesis tanımlayıcısı.
Sisteminizdeki kaynak kayıt kimliği.
Yanıt durumu ve gövdesi.
Varsa event_id veya command_id.

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

Bazı alana özgü uç noktalar açık bir durum ve neden döndürür. Örneğin erişim denetimi hataları reason, door_id, facility_id ve event_id gibi alanlar içerir.

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

İstek hatalı biçimlendirilmiş veya zorunlu alanlar eksik. Yeniden denemeden önce isteği düzeltin.

401 Unauthorized

Kimlik doğrulama başarısız oldu. API gizli anahtarınızı kullanıcı adı olarak ve boş bir parolayla HTTP Basic Auth kullandığınızı kontrol edin.

403 Forbidden

Anahtar geçerli ancak işleme izin verilmiyor. Yaygın nedenler arasında bir yazma işlemi için salt okunur anahtar kullanmak veya entegrasyonunuzun etkin olmadığı bir tesise erişmeye çalışmak bulunur.

404 Not Found

İstenen kaynak bulunamadı veya entegrasyonunuz tarafından kullanılamıyor.

409 Conflict

İstek, kaynağın mevcut durumuyla çakışıyor. Erişim denetimi için bu, bir Door/Gate Controller'ın bakım modunda olmasını içerebilir.

422 Unprocessable Entity

İstek geçerli bir JSON ancak anlamsal doğrulamadan geçemiyor. Yeniden denemeden önce verileri düzeltin.

429 Too Many Requests

Entegrasyon belgelenen hız sınırını aştı. Üstel geri çekilmeyle yeniden deneyin.

500 Internal Server Error

Performance Hub, dahili bir hata nedeniyle isteği tamamlayamadı. Geri çekilmeyle yeniden deneyin. Sorun devam ederse uç nokta, zaman damgası ve yanıt gövdesiyle destekle iletişime geçin.

503 Service Unavailable

Bağımlı bir hizmet veya cihaz kullanılamıyor. Door/Gate Controller kilit açma işlemlerinde bu, kontrol cihazının çevrimdışı olduğu anlamına gelebilir.

504 Gateway Timeout

İşlem zaman aşımına uğradı. Door/Gate Controller kilit açma işlemlerinde bu, kilit açmanın zaman aşımı penceresinden önce onaylanmadığı anlamına gelir.

Sürümlendirme

Partner API, URL'de sürümlendirilir. Geçerli sürüm şudur:

Değişiklik ilkesi

Performance Hub, mümkün olan her yerde ekleme niteliğinde, geriye dönük uyumlu değişiklikler yapmayı amaçlar.

Geriye dönük uyumlu değişiklik örnekleri:

Bir isteğe yeni bir isteğe bağlı alan eklemek.
Bir yanıta yeni bir alan eklemek.
Yeni bir uç nokta eklemek.
İstemcilerin bilinmeyen değerleri işlemesinin beklendiği durumlarda yeni bir enum değeri eklemek.
Durum kodu sözleşmesini değiştirmeden doğrulama mesajlarını iyileştirmek.

access_time_windows ve access_time_windows_revision, ekleme niteliğindeki Member istek alanlarıdır. Bunları göndermeyen mevcut istemciler, saklanan Access Time Window anlık görüntüsünü değiştirmeden korur. Bu gönderilmeme kuralı kısmi upsert uyumluluğunu korur; alanı göndermemek boş bir dizi göndermekle eşdeğer değildir.

Uyumluluğu bozan değişiklik örnekleri:

Bir alanı kaldırmak veya yeniden adlandırmak.
Bir alanın türünü değiştirmek.
İsteğe bağlı bir istek alanını zorunlu hale getirmek.
Bir uç noktayı kaldırmak.
Mevcut bir durum kodunun veya alana özgü bir reason değerinin anlamını değiştirmek.

Kullanımdan kaldırmalar

Uyumluluğu bozan bir değişiklik gerektiğinde Performance Hub, mümkün olduğunca mevcut sürümü yerinde değiştirmekten kaçınır. Bunun yerine yeni bir sürüm veya geçiş yolu sunar ve değişikliği etkilenen iş ortaklarına bildiririz.

Kullanımdan kaldırma bildirimleri şunları içerebilir:

Bir değişiklik günlüğü kaydı.
Doğrudan iş ortağı iletişimi.
Partner Console'daki notlar.
Belgelerdeki geçiş yönergeleri.

İstemci önerileri

Ekleme niteliğindeki değişikliklere dayanıklı istemciler geliştirin:

Kullanmadığınız yanıt alanlarını yok sayın.
Bilinmeyen enum değerlerini çökmek yerine desteklenmeyen değerler olarak ele alın.
Katı yanıt eşitliği kontrollerinden kaçının.
Entegrasyonunuzu bilinçli olarak güncelleyebilmek için tanınmayan değerleri kaydedin.

Access Time Windows gibi revizyonlu Member bölümleri için gönderilen revizyonu ve normalleştirilmiş yükü sonuç bilinene kadar kalıcı olarak saklayın. Değişen içerik için bir revizyonu yeniden kullanmak bir çakışmadır; aynı içeriği yeniden oynatmak ise idempotent bir işlemdir. Access Time Windows bölümüne bakın.

OpenAPI belirtimleri

İstemci oluşturmak, istekleri doğrulamak ve API yapısındaki değişiklikleri zaman içinde izlemek için yayımlanan OpenAPI belirtimlerini kullanın.

OpenAPI Belirtimleri sayfasına bakın.

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

Değişiklik günlüğü

Bu değişiklik günlüğü, entegrasyon davranışını etkileyen önemli Partner API ve Partner Console değişikliklerini kaydeder.

2026-09-09

2026-05-06

2026-05-01

Değişiklik kategorileri

Gelecekteki kayıtlar şu kategorileri kullanır:

Eklenenler - yeni uç nokta, alan, kılavuz veya özellik.
Değişenler - desteği kaldırmadan değiştirilen davranış veya belgeler.
Kullanımdan kaldırılanlar - özellik kullanılabilir olmaya devam eder ancak planlanmış bir geçiş yolu vardır.
Kaldırılanlar - kaldırılan özellik veya uç nokta.
Düzeltilenler - hata düzeltmesi veya belge düzeltmesi.
Güvenlik - kimlik doğrulama, yetkilendirme, veri işleme veya anahtar yönetimi değişikliği.

Eklenenler

Mutlak ve yinelenen haftalık pencerelerin karışık kullanılabildiği, sağlayıcıdan bağımsız Member access_time_windows anlık görüntüleri eklendi.
access_time_windows_revision sıralaması, idempotent yeniden oynatma, çakışma, eskiyi atlama ve açık iptal semantiği eklendi.
IANA saat dilimi, yaz saati uygulaması, mantıksal scope_key eşlemesi, kaynak güncelliği, üretici uygulaması ve sertifikasyon yönergeleri eklendi.

Eklenenler

İş ortağı türlerini, katılım sürecini, en iyi uygulamaları, yayına geçiş hazırlığını, hataları, sürümlendirmeyi ve desteği kapsayan iş ortağı programı belgeleri eklendi.
Potansiyel teknik ve ticari iş ortakları için özel bir İş Ortağı Olun talep akışı eklendi.
Onaylanan iş ortağı entegrasyonlarının temel Performance Hub platformundaki Performance Hub iş ortağı dizininde nasıl göründüğüne ilişkin belgeler eklendi.

Eklenenler

Listeleme, durum ve kilit açma işlemleri dahil Door/Gate Controller erişim denetimi belgeleri eklendi.
Eşzamanlı kilit açma davranışı belgeleri eklendi: API yalnızca sahadaki kontrol cihazı rölenin fiziksel olarak kilidinin açıldığını onayladıktan sonra başarı döndürür.
Door/Gate Controller kilit açma istekleri için isteğe bağlı idempotency_key desteği belgeleri eklendi.