Performance Hub लोगोPerformance Hub
साइट अनुभाग: डेवलपर और पार्टनर संसाधन

परिचय

Performance Hub Partner API बाहरी पार्टनर प्लेटफ़ॉर्म को Performance Hub के मुख्य मॉड्यूल के साथ सहजता से इंटीग्रेट करने में सक्षम बनाता है। API कंप्यूटर विज़न, एनालिटिक्स, सदस्य एक्सेस लॉगिंग और सुविधा इनसाइट्स का समर्थन करता है।

अनुरोध का प्रारूप

API, JSON-एन्कोडेड अनुरोध बॉडी स्वीकार करता है और JSON-एन्कोडेड रिस्पॉन्स लौटाता है।

रेट लिमिटिंग

उचित उपयोग और सिस्टम की स्थिरता सुनिश्चित करने के लिए, Partner API खाते डिफ़ॉल्ट सीमाओं के साथ शुरू होते हैं:

  • प्रति एंडपॉइंट प्रति सेकंड 5 अनुरोध
  • बेहतर प्रदर्शन के लिए प्रति बैच अनुरोध अनुशंसित: अधिकतम 1000 आइटम
  • पेलोड का अधिकतम आकार 10MB

रेट लिमिट समायोज्य हैं और आपके Performance Hub पार्टनर अकाउंट मैनेजर द्वारा हर मामले के अनुसार कॉन्फ़िगर की जा सकती हैं। यदि आपके इंटीग्रेशन को लॉन्च, माइग्रेशन, रिपोर्टिंग बैकफ़िल या अधिक मात्रा वाली सुविधाओं के लिए अधिक थ्रूपुट की आवश्यकता है, तो इसे ऑनबोर्डिंग के दौरान या नियोजित बदलाव की समयावधि से पहले उठाएँ।

बेस URL

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

प्रमाणीकरण

Partner API तक पहुँचने के लिए API सीक्रेट कुंजियों का उपयोग करके प्रमाणीकरण आवश्यक है। Partner Console के माध्यम से अपनी कुंजियाँ बनाएँ और प्रबंधित करें।

API कुंजियाँ पार्टनर संसाधनों तक पहुँचने के लिए आपके क्रेडेंशियल के रूप में काम करती हैं। हर कुंजी की पहुँच विशिष्ट संगठन डेटा तक सीमित होती है और आवश्यकता पड़ने पर उसे तुरंत निष्क्रिय किया जा सकता है।

अपनी API कुंजियों को सावधानी से संभालें—वे आपके खाते तक पूर्ण पहुँच देती हैं! इन कुंजियों को कभी भी सार्वजनिक रिपॉज़िटरी, क्लाइंट-साइड एप्लिकेशन या किसी भी ऐसी जगह उजागर न करें जहाँ उनसे समझौता हो सकता है।

अपनी API कुंजी को यूज़रनेम के रूप में भेजकर HTTP Basic Auth का उपयोग करके अनुरोधों को प्रमाणित करें। पासवर्ड खाली छोड़ दें।

API केवल सुरक्षित HTTPS कनेक्शन स्वीकार करता है। सामान्य HTTP अनुरोध अस्वीकार कर दिए जाते हैं, साथ ही ऐसे सभी अनुरोध भी जिनमें उचित प्रमाणीकरण क्रेडेंशियल नहीं हैं।

उदाहरण अनुरोध

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

सीक्रेट कुंजी सत्यापित करें

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

गो-लाइव चेकलिस्ट

प्रोडक्शन सुविधाओं के लिए किसी पार्टनर इंटीग्रेशन को सक्षम करने से पहले इस चेकलिस्ट का उपयोग करें।

Partner Console सेटअप

  • आपकी पार्टनर प्रोफ़ाइल पूरी है।
  • आपका लोगो URL, वेबसाइट, श्रेणी और विवरण सटीक हैं।
  • आपकी डेटा लिंकिंग विधि कॉन्फ़िगर है: Direct Link या Linking Identifier।
  • कम से कम एक वास्तविक सुविधा के साथ सुविधा लिंकिंग का परीक्षण किया गया है।
  • सही कुंजी प्रकार का उपयोग किया जा रहा है:
    • गैर-विनाशकारी राइट परीक्षण के लिए Dryrun।
    • डेटा के सुरक्षित उपयोग के लिए Read-only।
    • Live केवल तब, जब आप प्रोडक्शन डेटा को प्रभावित करने के लिए तैयार हों।

प्रमाणीकरण और कुंजी प्रबंधन

  • सीक्रेट कुंजियाँ केवल सर्वर-साइड पर संग्रहीत हैं।
  • कुंजियाँ क्लाइंट-साइड एप्लिकेशन, मोबाइल ऐप, सार्वजनिक रिपॉज़िटरी या सहायता टिकट में शामिल नहीं हैं।
  • कुंजी रोटेशन और रद्दीकरण का परीक्षण किया गया है।
  • आपकी टीम जानती है कि हर एनवायरनमेंट में कौन-सी कुंजी उपयोग होती है।

डेटा सत्यापन

  • आपके द्वारा कॉल किए जाने वाले हर एंडपॉइंट के लिए आवश्यक फ़ील्ड मौजूद हैं।
  • सुविधा पहचानकर्ता आपकी कॉन्फ़िगर की गई लिंकिंग विधि से मेल खाते हैं।
  • आपके सिस्टम की ID स्थिर हैं और सिंक के बीच नहीं बदलतीं।
  • बड़े इम्पोर्ट प्रलेखित सीमाओं के भीतर बैचों में बाँटे गए हैं।
  • विफल बैच आइटम की पहचान की जा सकती है और उन्हें दोबारा भेजा जा सकता है।

एंडपॉइंट परीक्षण

लॉन्च से पहले, हर उस एंडपॉइंट का परीक्षण करें जिस पर आपका इंटीग्रेशन निर्भर है:

  • संगठनों और सुविधाओं को पढ़ा जा सकता है।
  • सदस्यों को सहेजा और अपडेट किया जा सकता है।
  • सदस्यता प्लान, एक्सेस ज़ोन और एक्सेस घंटे सही तरीके से सिंक होते हैं।
  • चेक-इन स्वीकार किए जाते हैं और उन्हें आपके सिस्टम से वापस जोड़ा जा सकता है।
  • रिपोर्ट स्नैपशॉट अपेक्षित रिपोर्टिंग अवधि और मेट्रिक्स का उपयोग करते हैं।
  • जहाँ लागू हो, Door/Gate Controller फ़्लो का वास्तविक हार्डवेयर पर परीक्षण किया गया है।

Access Time Window की तैयारी

यदि इंटीग्रेशन Access Time Windows प्रदान करता है:

  • निरपेक्ष और साप्ताहिक उदाहरण प्रोड्यूसर प्रमाणन चेकलिस्ट पास करते हैं।
  • Epoch मान बिना उद्धरण चिह्नों वाले पूर्णांक Unix सेकंड हैं; सटीक [from, to) सीमाओं का परीक्षण किया गया है।
  • UTC डिफ़ॉल्ट, इंटीग्रेशन के कस्टम IANA टाइमज़ोन और प्रासंगिक डेलाइट-सेविंग बदलावों को सत्यापित किया गया है।
  • एक टिकाऊ, एकदिशीय (monotonic) सदस्य/स्रोत रिविज़न स्ट्रीम इंक्रीमेंटल अपडेट, रिकंसिलिएशन और पुनःप्रयासों का समन्वय करती है।
  • ऑपरेटर omitted, complete-replacement, idempotent, conflicting, stale और स्पष्ट-[] व्यवहार को समझते हैं।
  • default सहित हर scope_key का एक स्वीकृत Performance Hub मैपिंग है; अज्ञात कुंजियों के बंद अवस्था में विफल (fail closed) होने का परीक्षण किया गया है।
  • इंटीग्रेशन की अपेक्षित रीफ़्रेश आवृत्ति, स्रोत की अधिकतम आयु, पुराने स्रोत का व्यवहार और अलर्ट कॉन्फ़िगर किए गए हैं।
  • यह सिद्ध किया गया है कि अपस्ट्रीम फ़ेच विफलता से खाली या आंशिक स्नैपशॉट नहीं भेजा जाता।
  • स्टेज स्ट्रीम कन्वर्जेंस, रद्दीकरण/निरसन और भौतिक दरवाज़े की शुरुआत/समाप्ति सीमाएँ तय लक्ष्यों को पूरा करती हैं।
  • नियमित नियमों और स्थायी अनुमतियों को फ़ॉलबैक पथ के रूप में सत्यापित किया गया है, और विंडो उपयोगकर्ता अक्षमीकरण, blockAllAccess, मेंटेनेंस या जियोफ़ेंसिंग को बायपास नहीं कर सकतीं।

एक्सेस कंट्रोल की तैयारी

एक्सेस कंट्रोल इंटीग्रेशन के लिए:

  • Performance Hub को कॉल करने से पहले आपका सिस्टम एक्सेस का निर्णय लेता है।
  • इंटीग्रेशन device_offline, maintenance_mode_active और unlock_confirmation_timeout को संभालता है।
  • ऑपरेटर समझते हैं कि टाइमआउट का अर्थ है कि अनलॉक की पुष्टि नहीं हुई।
  • आपके लॉग लौटाए गए event_id और command_id को संग्रहीत करते हैं।
  • सुविधा के स्टाफ़ के लिए आपके पास एक मैन्युअल फ़ॉलबैक प्रक्रिया है।

त्रुटि प्रबंधन और पुनःप्रयास

  • 400, 401, 403, 404, 409 और 422 रिस्पॉन्स को बिना सोचे-समझे पुनः प्रयास करने के बजाय ऑपरेटरों या सहायता टीमों के सामने लाया जाता है।
  • 429, 500, 502, 503 और 504 रिस्पॉन्स बैकऑफ़ के साथ सीमित पुनःप्रयास लॉजिक का उपयोग करते हैं।
  • बार-बार की विफलताएँ आपके सिस्टम में एक अलर्ट बनाती हैं।
  • इंटीग्रेशन कभी भी विफल रिकॉर्ड को चुपचाप नहीं छोड़ता।

ऑब्ज़र्वेबिलिटी

  • आपके लॉग में एंडपॉइंट, टाइमस्टैम्प, सुविधा पहचानकर्ता, स्रोत रिकॉर्ड ID, अनुरोध का परिणाम और रिस्पॉन्स बॉडी शामिल हैं।
  • आपकी सहायता टीम सदस्य ID, सुविधा ID, चेक-इन ID या अनलॉक इवेंट ID से खोज सकती है।
  • आपके पास विफल सिंक को दोबारा चलाने या उनका मिलान करने का तरीका है।

प्रोडक्शन लॉन्च

  • Performance Hub ने आपकी प्रोडक्शन पहुँच की पुष्टि कर दी है।
  • कम से कम एक प्रोडक्शन सुविधा ने आपका इंटीग्रेशन सक्षम किया है।
  • आपकी प्रोडक्शन कुंजी सक्रिय है।
  • आपके परिचालन और तकनीकी संपर्क अद्यतन हैं।
  • ग्राहकों के लिए आपकी सहायता प्रक्रिया प्रलेखित है।

ये जाँच पूरी होने के बाद, आपका कॉन्फ़िगर किया गया इंटीग्रेशन मुख्य Performance Hub प्लेटफ़ॉर्म के भीतर Performance Hub पार्टनर डायरेक्टरी में दिखाई देगा।

सर्वोत्तम तरीके

पार्टनर इंटीग्रेशन को पूर्वानुमेय, निगरानी योग्य और सुविधाओं के लिए सुरक्षित बनाए रखने के लिए इन पैटर्न का उपयोग करें।

सुविधाओं की पहचान सुसंगत रूप से करें

अपने पार्टनर खाते के लिए कॉन्फ़िगर की गई लिंकिंग विधि चुनें और उसका सुसंगत रूप से उपयोग करें:

  • Direct Link - सुविधाओं वाले एंडपॉइंट द्वारा लौटाए गए Performance Hub facility_id का उपयोग करें।
  • Linking Identifier - अपने स्वयं के स्थान पहचानकर्ता का उपयोग करें, जैसे ब्रांच ID, स्थान कोड या स्टोर नंबर।

एक ही अनुरोध में दोनों पहचानकर्ता न भेजें। Performance Hub आपके पार्टनर खाते के लिए कॉन्फ़िगर की गई लिंकिंग विधि का उपयोग करके अनुरोधों को हल करता है।

सेटअप मार्गदर्शन के लिए पार्टनर लिंकिंग विधियाँ देखें।

बैच राइट सावधानी से करें

Partner API, JSON अनुरोध बॉडी स्वीकार करता है और जहाँ प्रलेखित है, वहाँ बैच-आधारित सिंक वर्कफ़्लो के लिए डिज़ाइन किया गया है। बैचों को सीमित और पुनः प्रयास योग्य रखें।

डिफ़ॉल्ट दिशानिर्देश:

  • बेहतर प्रदर्शन के लिए प्रति बैच अनुरोध अधिकतम 1000 आइटम का उपयोग करें।
  • पेलोड को 10MB से कम रखें।
  • प्रति एंडपॉइंट प्रति सेकंड 5 अनुरोधों की सीमा के भीतर रहें।

रेट लिमिट समायोज्य हैं और आपके Performance Hub पार्टनर अकाउंट मैनेजर द्वारा हर मामले के अनुसार कॉन्फ़िगर की जा सकती हैं। यदि आप बड़ी मात्रा में इम्पोर्ट, लॉन्च ट्रैफ़िक या रिपोर्टिंग बैकफ़िल की अपेक्षा करते हैं, तो बदलाव की समयावधि से पहले आवश्यक थ्रूपुट पर सहमति बना लें।

यदि आपको कोई बड़ा डेटासेट सिंक करना है, तो उसे निर्धारित (deterministic) हिस्सों में बाँटें और अपनी ओर हर हिस्से की ID लॉग करें। इससे विफल पुनःप्रयासों को समझना आसान हो जाता है।

सुरक्षित रूप से पुनः प्रयास करें

429, 500, 502, 503 और 504 जैसी अस्थायी विफलताओं के लिए एक्सपोनेंशियल बैकऑफ़ का उपयोग करें।

लगातार तेज़ पुनःप्रयास लूप से बचें। शुरुआत के लिए एक अच्छा तरीका है:

  1. 1 सेकंड के बाद पुनः प्रयास करें।
  2. 2 सेकंड के बाद पुनः प्रयास करें।
  3. 4 सेकंड के बाद पुनः प्रयास करें।
  4. यदि ऑपरेशन फिर भी विफल होता है, तो रुकें और अलर्ट भेजें।

400 या 422 जैसी सत्यापन विफलताओं के लिए, पुनः प्रयास करने से पहले अनुरोध ठीक करें।

जहाँ समर्थित हो, वहाँ आइडेम्पोटेंसी का उपयोग करें

Door/Gate Controller अनलॉक एंडपॉइंट एक वैकल्पिक idempotency_key का समर्थन करता है। समान पार्टनर, सुविधा और दरवाज़े के लिए समान कुंजी का दोबारा उपयोग करने पर, उपलब्ध होने पर मौजूदा परिणाम लौटाया जाता है।

की जा रही कार्रवाई के लिए एक स्थिर कुंजी का उपयोग करें, उदाहरण के लिए आपके सिस्टम की कोई चेक-इन ID या एक्सेस इवेंट ID।

यह न मानें कि हर राइट एंडपॉइंट आइडेम्पोटेंसी का समर्थन करता है, जब तक कि उस एंडपॉइंट के लिए यह प्रलेखित न हो।

स्रोत डेटा को साफ़ रखें

जहाँ भी संभव हो, स्थिर और सामान्यीकृत मान भेजें:

  • अपने स्रोत सिस्टम से सुसंगत सदस्य, प्लान, सुविधा और चेक-इन ID का उपयोग करें।
  • तारीखों और समय के लिए ISO 8601 टाइमस्टैम्प का उपयोग करें।
  • जहाँ उपलब्ध हो, फ़ोन नंबर अंतरराष्ट्रीय प्रारूप में भेजें।
  • हर एंडपॉइंट के लिए प्रलेखित फ़ील्ड का उपयोग करके मुद्राएँ भेजें।
  • फ़्री-टेक्स्ट फ़ील्ड में ऐसा डेटा भरने से बचें जो संरचित फ़ील्ड में होना चाहिए।

इंक्रीमेंटल और पूर्ण सिंक के लिए डिज़ाइन करें

अधिकांश पार्टनर इंटीग्रेशन को दोनों की आवश्यकता होती है:

  • दिन-प्रतिदिन के बदलावों के लिए इंक्रीमेंटल सिंक।
  • छूटे हुए इवेंट, ऐतिहासिक इम्पोर्ट या डेटा ड्रिफ़्ट को ठीक करने के लिए पूर्ण रिकंसिलिएशन सिंक।

आपका इंटीग्रेशन किसी सदस्य, सदस्यता प्लान या रिपोर्ट स्नैपशॉट की वर्तमान स्थिति को, किसी पिछले अनुरोध के सफल होने पर निर्भर हुए बिना, दोबारा भेजने में सक्षम होना चाहिए।

Access Time Windows सुरक्षित रूप से प्रकाशित करें

हर सदस्य के access_time_windows मान को एक पूर्ण, स्वतंत्र रूप से संशोधित स्नैपशॉट मानें:

  • इंक्रीमेंटल और रिकंसिलिएशन वर्कर्स में एक ही, लगातार बढ़ने वाली access_time_windows_revision स्ट्रीम का समन्वय करें।
  • अनिश्चित या अस्थायी डिलीवरी को उसी रिविज़न और सामान्यीकृत पेलोड के साथ पुनः प्रयास करें।
  • जब आप access_time_windows अपडेट नहीं कर रहे हों, तो उसे छोड़ दें।
  • [] केवल तब भेजें जब किसी सफल आधिकारिक स्रोत फ़ेच से यह सिद्ध हो जाए कि कोई विंडो शेष नहीं है। अपस्ट्रीम टाइमआउट, आंशिक परिणाम या पार्स विफलता को कभी भी रद्दीकरण में न बदलें।
  • external_id और scope_key को स्थिर रखें, और प्रोडक्शन से पहले हर स्कोप मैपिंग को प्रमाणित करें।
  • उस इंटीग्रेशन के लिए तय की गई ताज़गी नीति के अनुसार स्रोत की आयु की निगरानी करें।

पूर्ण स्नैपशॉट, टाइमज़ोन, DST, रद्दीकरण और टेस्ट वेक्टर के लिए आधिकारिक Access Time Windows प्रोड्यूसर गाइड देखें।

एक्सेस कंट्रोल को सुरक्षा-महत्वपूर्ण मानें

Door/Gate Controller अनलॉक के लिए:

  • Performance Hub को कॉल करने से पहले आपके सिस्टम को तय करना होगा कि व्यक्ति को प्रवेश की अनुमति है या नहीं।
  • Performance Hub 200 केवल तब लौटाता है जब ऑन-साइट कंट्रोलर पुष्टि करता है कि रिले भौतिक रूप से अनलॉक हो गया है।
  • अधिकांश पुष्टियाँ 3-5 सेकंड में पूरी हो जाती हैं।
  • टाइमआउट एक स्पष्ट विफल अनलॉक है, बैकग्राउंड में हुई सफलता नहीं।
  • केवल अपने स्वयं के एक्सेस और सुरक्षा नियमों के अनुसार ही पुनः प्रयास करें।

अनलॉक एंडपॉइंट द्वारा लौटाए गए event_id और command_id को हमेशा लॉग करें।

अपने इंटीग्रेशन की निगरानी करें

डेवलपमेंट और लॉन्च के दौरान Partner Console के अनुरोध लॉग का उपयोग करें। प्रोडक्शन में, इन जानकारियों के साथ अपने स्वयं के लॉग भी रखें:

  • अनुरोध का टाइमस्टैम्प।
  • एंडपॉइंट।
  • स्रोत रिकॉर्ड ID।
  • सुविधा पहचानकर्ता।
  • HTTP स्टेटस कोड।
  • Performance Hub रिस्पॉन्स बॉडी या त्रुटि संदेश।

जब कोई ग्राहक पूछता है कि क्या हुआ, तो ये फ़ील्ड सहायता और रिकंसिलिएशन को बहुत तेज़ बना देते हैं।

संगठन

उस शीर्ष-स्तरीय व्यावसायिक इकाई को दर्शाता है जो Performance Hub प्लेटफ़ॉर्म से इंटीग्रेटेड एक या अधिक सुविधाओं का संचालन करती है।

एंडपॉइंट

GET /partner/v1/organisations - List all organisations

संगठन ऑब्जेक्ट

एट्रिब्यूट

  • org_id string आवश्यक

    संगठन के लिए अद्वितीय पहचानकर्ता।

  • name string आवश्यक

    संगठन का नाम।

संगठन ऑब्जेक्ट

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

सभी संगठनों की सूची बनाएँ

आपके पार्टनर खाते के लिए उपलब्ध संगठनों की सूची लौटाता है।

रिटर्न

एक JSON ऑब्जेक्ट लौटाता है जिसकी data प्रॉपर्टी में संगठन ऑब्जेक्ट का एक ऐरे होता है।

अनुरोध

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

रिस्पॉन्स

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

सुविधाएँ

किसी भौतिक स्थान को दर्शाता है, जैसे कार्यालय, स्टोर, स्थल, कैंपस, क्लिनिक या जिम, जहाँ सदस्य सेवाओं का उपयोग कर सकते हैं।

एंडपॉइंट

GET /partner/v1/facilities - List all facilities

सुविधा ऑब्जेक्ट

एट्रिब्यूट

  • facility_id string आवश्यक

    सुविधा के लिए अद्वितीय पहचानकर्ता।

  • org_id string आवश्यक

    मूल संगठन के लिए अद्वितीय पहचानकर्ता।

  • name string आवश्यक

    सुविधा का नाम।

  • brand string वैकल्पिक

    सुविधा द्वारा उपयोग किया जाने वाला ब्रांड नाम।

  • website_url string वैकल्पिक

    सुविधा की वेबसाइट का URL।

  • place_data object वैकल्पिक

    Google Places API से प्राप्त स्थान डेटा, जिसमें देश, फ़ॉर्मेट किया गया पता, Google Place ID, प्रांत और शहर शामिल हैं।

  • social_links object वैकल्पिक

    सुविधा के सोशल मीडिया लिंक।

  • timezone string वैकल्पिक

    IANA टाइमज़ोन पहचानकर्ता (जैसे, "Australia/Sydney", "America/New_York")।

सुविधा ऑब्जेक्ट

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

सभी सुविधाओं की सूची बनाएँ

आपके पार्टनर खाते के लिए उपलब्ध सुविधाओं की सूची लौटाता है।

रिटर्न

एक JSON ऑब्जेक्ट लौटाता है जिसकी data प्रॉपर्टी में सुविधा ऑब्जेक्ट का एक ऐरे होता है।

अनुरोध

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

रिस्पॉन्स

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

सदस्यता प्लान

किसी संगठन या सुविधा द्वारा खरीदी जा सकने वाली पेशकश को परिभाषित करता है, जिसमें सेवाएँ, पात्रताएँ, शेड्यूल और मूल्य निर्धारण शामिल हैं।

एंडपॉइंट

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

सदस्यता प्लान ऑब्जेक्ट

एट्रिब्यूट

  • membership_plan_id string आवश्यक

    सदस्यता प्लान के लिए अद्वितीय पहचानकर्ता।

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub से सुविधा का अद्वितीय पहचानकर्ता।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    हर स्थान के लिए वह अद्वितीय पहचानकर्ता मान जिसका उपयोग पार्टनर करता है (जैसे, "Branch ID", "Location Code", "Store Number")। और जानें

  • name string आवश्यक

    मानव-पठनीय प्लान नाम (जैसे, "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack")।

  • billing_cycle string वैकल्पिक

    बिलिंग आवृत्ति। weekly, fortnightly, monthly, annually या one_time में से एक।

  • price integer वैकल्पिक

    मुद्रा की सबसे छोटी इकाई में आधार लागत (USD/AUD के लिए सेंट)।

  • currency string वैकल्पिक

    ISO 4217 मुद्रा कोड (जैसे, "AUD", "USD")।

  • description string वैकल्पिक

    वैकल्पिक मार्केटिंग या आंतरिक विवरण।

  • active_members integer वैकल्पिक

    इस सदस्यता प्लान का उपयोग करने वाले सक्रिय सदस्यों की संख्या

  • is_recurring boolean वैकल्पिक

    प्लान अपने आप नवीनीकृत होता है या नहीं।

  • is_trial boolean वैकल्पिक

    यह ट्रायल पेशकश है या नहीं।

  • visible_to_public boolean वैकल्पिक

    प्लान सेल्फ़-सर्विस खरीद के लिए उपलब्ध है या नहीं।

  • duration_days integer वैकल्पिक

    सदस्यता प्लान कितने दिनों के लिए मान्य है।

  • access_zones array वैकल्पिक

    सदस्यता प्लान में शामिल एक्सेस ज़ोन का ऐरे। हर ज़ोन अपने एक्सेस घंटे परिभाषित कर सकता है। विवरण के लिए एक्सेस ज़ोन देखें।

  • class_limit integer वैकल्पिक

    अनुमत क्लासों की अधिकतम संख्या (असीमित के लिए null)।

सदस्यता प्लान ऑब्जेक्ट

यह उदाहरण facility_id का उपयोग करता है। लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए, इसके बजाय "linking_identifier": "branch_downtown" भेजें।

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

एक्सेस ज़ोन

एक्सेस ज़ोन किसी सुविधा के भीतर उन विशिष्ट क्षेत्रों को परिभाषित करते हैं जहाँ सदस्यता प्लान पहुँच देता है। हर ज़ोन के अपने एक्सेस घंटे हो सकते हैं, जिससे हर क्षेत्र के लिए अलग-अलग समय प्रतिबंध संभव होते हैं।

संरचना

हर एक्सेस ज़ोन में ये शामिल होते हैं:

  • name string आवश्यक

    ज़ोन का नाम (जैसे, "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor")।

  • description string वैकल्पिक

    उस ज़ोन में क्या शामिल है, इसका विवरण।

  • access_hours object वैकल्पिक

    इस ज़ोन के लिए विशिष्ट एक्सेस घंटे। समय सीमा के प्रारूप के लिए एक्सेस घंटे देखें।

उदाहरण

अपने किरायेदारों के लिए जिम वाला एक कार्यालय भवन: व्यावसायिक घंटों के दौरान किराए वाले स्थान तक पहुँच, और सुबह जल्दी से देर शाम तक जिम तक पहुँच।

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

एक्सेस घंटे

एक्सेस घंटे यह निर्दिष्ट करते हैं कि सप्ताह के हर दिन सदस्य किसी विशिष्ट ज़ोन तक कब पहुँच सकते हैं। एक्सेस घंटे हर एक्सेस ज़ोन के लिए परिभाषित किए जाते हैं, जिससे किसी सुविधा के अलग-अलग क्षेत्रों के लिए अलग-अलग समय प्रतिबंध संभव होते हैं।

संरचना

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

हर दिन HH:MM प्रारूप (24-घंटे की घड़ी) में समय सीमाओं का एक ऐरे है। खाली ऐरे [] का अर्थ है कि उस दिन कोई पहुँच नहीं है। छोड़े गए दिनों को खाली ऐरे के समान माना जाता है।

उपयोग के उदाहरण

कार्यालय किरायेदार – व्यावसायिक घंटे: केवल कार्यदिवसों में व्यावसायिक घंटों के दौरान पहुँच।

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

छात्र – सत्र पहुँच: एक कैंपस पुस्तकालय जो कार्यदिवसों में, दिन के बीच में एक ब्रेक के साथ, और शनिवार की सुबह खुला रहता है।

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

जिम – अर्ली बर्ड: कार्यदिवसों में केवल सुबह की पहुँच।

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

होटल अतिथि – 24/7: हमेशा उपलब्ध पहुँच, जो सबसे सामान्य उपयोग का मामला है।

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

प्रति-ज़ोन उदाहरण

एक होटल अतिथि प्लान, जिसमें अतिथि फ़्लोर तक चौबीसों घंटे पहुँच और पूल के लिए कम घंटे हैं:

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

सदस्यता प्लान सहेजें

सदस्यता प्लान रिकॉर्ड बनाता या अपडेट करता है। API, membership_plan_id के आधार पर तय करता है कि रिकॉर्ड बनाना है या अपडेट करना है।

पैरामीटर

  • membership_plans array आवश्यक

    सहेजे जाने वाले सदस्यता प्लान ऑब्जेक्ट का ऐरे। अनुशंसित अधिकतम: बेहतर प्रदर्शन के लिए प्रति अनुरोध 1000 आइटम। API प्रोसेसिंग के लिए आइटम को अपने आप बैच करता है। हर आइटम में या तो facility_id (यदि linking_identifier का उपयोग नहीं कर रहे हैं तो आवश्यक) या linking_identifier (यदि facility_id का उपयोग नहीं कर रहे हैं तो आवश्यक) शामिल होना चाहिए।

रिटर्न

सिंक ऑपरेशन की पुष्टि करने वाला एक सरल संदेश लौटाता है।

अनुरोध

यह उदाहरण facility_id का उपयोग करता है। लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए, इसके बजाय "linking_identifier": "branch_downtown" भेजें।

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

रिस्पॉन्स

सिंक ऑपरेशन के मेटाडेटा के साथ एक सफलता संदेश लौटाता है।

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

मेटाडेटा फ़ील्ड:

  • success - सफलतापूर्वक प्रोसेस किए गए सदस्यता प्लान की संख्या
  • skipped - छोड़े गए प्लान की संख्या (यदि कोई हो)
  • skipped_items - कारणों सहित छोड़े गए प्लान का ऐरे (यदि कोई हो)
  • dry-run - dryrun कुंजी प्रकार का उपयोग करने पर बूलियन फ़्लैग (यदि लागू हो)

सदस्य

किसी सुविधा के एक व्यक्तिगत ग्राहक को दर्शाता है। यह कोई लीड, संभावित ग्राहक, नियमित ग्राहक, समाप्त सदस्यता वाला सदस्य या अवरुद्ध उपयोगकर्ता हो सकता है।

सदस्य अपसर्ट में एक पूर्ण, रिविज़न वाला access_time_windows स्नैपशॉट भी हो सकता है, जिसमें निरपेक्ष और आवर्ती साप्ताहिक पहुँच शामिल होती है। ये फ़ील्ड बनाने से पहले Access Time Windows देखें। ये अतिरिक्त अनुमतियाँ हैं और सुविधा के नियमित नियमों या स्थायी अनुमतियों की जगह नहीं लेतीं।

एंडपॉइंट

POST /partner/v1/members - Save a member

सदस्य ऑब्जेक्ट

एट्रिब्यूट

  • member_id string आवश्यक

    सदस्य के लिए अद्वितीय पहचानकर्ता।

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub से सुविधा का अद्वितीय पहचानकर्ता।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    हर स्थान के लिए वह अद्वितीय पहचानकर्ता मान जिसका उपयोग पार्टनर करता है (जैसे, "Branch ID", "Location Code", "Store Number")। और जानें

  • first_name string आवश्यक

    सदस्य का पहला नाम।

  • last_name string आवश्यक

    सदस्य का अंतिम नाम।

  • email string वैकल्पिक

    ईमेल पता।

  • mobile_phone string वैकल्पिक

    E.123 प्रारूप में मोबाइल फ़ोन नंबर (जैसे, "+1 415 555 2671")।

  • address object वैकल्पिक

    निम्नलिखित प्रॉपर्टी वाला भौतिक पता ऑब्जेक्ट:

    • address_line_1 (string) - प्राथमिक सड़क का पता
    • address_line_2 (string, optional) - पते की दूसरी पंक्ति
    • city (string) - शहर का नाम
    • state (string) - राज्य/प्रांत कोड
    • postal_code (string) - पोस्टल/ZIP कोड
    • country (string) - ISO 3166-1 alpha-2 देश कोड (जैसे, "AU", "US")
    • country_name (string, optional) - देश का पूरा नाम

  • date_of_birth string वैकल्पिक

    YYYY-MM-DD प्रारूप में जन्म तिथि।

  • gender string वैकल्पिक

    male, female, non_binary, prefer_not_to_say या unknown में से एक।

  • type string वैकल्पिक

    सदस्य का प्रकार (जैसे staff, member, prospect)।

  • tags array वैकल्पिक

    विशिष्ट सदस्यों को वर्गीकृत करने और पहचानने के लिए त्वरित सहायक स्ट्रिंग या टेक्स्ट (जैसे ["vip", "personal-training", "student"])।

  • membership_status string वैकल्पिक

    वर्तमान सदस्यता स्थिति (जैसे, active, expired, on_hold)।

  • membership_plans array वैकल्पिक

    सदस्य से संबद्ध सदस्यता प्लान का ऐरे।

  • profile_picture string वैकल्पिक

    Base64-एन्कोडेड प्रोफ़ाइल चित्र (वैकल्पिक)।

  • created string वैकल्पिक

    सदस्य कब बनाया गया, इसका ISO 8601 टाइमस्टैम्प।

  • updated string वैकल्पिक

    सदस्य को पिछली बार कब अपडेट किया गया, इसका ISO 8601 टाइमस्टैम्प।

  • access_time_windows array वैकल्पिक

    निरपेक्ष और/या आवर्ती साप्ताहिक Access Time Windows का पूर्ण, स्रोत के स्वामित्व वाला स्नैपशॉट। स्नैपशॉट को अपरिवर्तित रखने के लिए फ़ील्ड को छोड़ दें; इसे रद्द करने के लिए नए रिविज़न के साथ खाली ऐरे भेजें। स्वरूपों, सत्यापन, स्कोप मैपिंग और प्रतिस्थापन सिमेंटिक्स के लिए Access Time Windows देखें।

  • access_time_windows_revision integer access_time_windows के साथ आवश्यक

    इस सदस्य/स्रोत स्ट्रीम के लिए एक लगातार बढ़ने वाला, गैर-ऋणात्मक, JSON-सुरक्षित पूर्णांक। जब भी access_time_windows मौजूद हो, यह आवश्यक है।

सदस्य ऑब्जेक्ट

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

एक्सेस समय विंडोज

Access Time Windows किसी Partner Member को किसी बाहरी सिस्टम द्वारा दी गई अस्थायी या आवर्ती पहुँच रखने देती हैं। यह पेज access_time_windows और access_time_windows_revision के लिए आधिकारिक प्रोड्यूसर गाइड है।

Access Time Windows अतिरिक्त, केवल-अनुमति देने वाली अनुमतियाँ हैं। एक सक्रिय विंडो पहुँच की अनुमति दे सकती है, लेकिन निष्क्रिय, समाप्त, पुरानी (stale) या मैप न की गई विंडो ऐसी पहुँच से इनकार नहीं करती जिसकी अनुमति कोई नियमित नियम या स्थायी अनुमति पहले से देती है। उपयोगकर्ता अक्षमीकरण, स्पष्ट डोर ब्लॉकिंग, मेंटेनेंस मोड, जियोफ़ेंसिंग, रेट लिमिट और कंट्रोलर की उपलब्धता फिर भी लागू होती हैं।

विशेष अपस्ट्रीम सिस्टमों के लिए इम्प्लीमेंटेशन अलग एडेप्टर होते हैं। उन्हें अपने स्रोत डेटा को इसके फ़ील्ड के अर्थ बदले बिना इस विक्रेता-निरपेक्ष अनुबंध में बदलना होगा।

सदस्य स्नैपशॉट फ़ील्ड

  • access_time_windows array वैकल्पिक

    इस सदस्य और पार्टनर स्रोत के लिए पूर्ण Access Time Window स्नैपशॉट। एक स्नैपशॉट में absolute और weekly विंडो मिश्रित हो सकती हैं। संग्रहीत स्नैपशॉट को अपरिवर्तित रखने के लिए फ़ील्ड को छोड़ दें; इस स्रोत की हर विंडो को रद्द करने के लिए [] भेजें।

  • access_time_windows_revision integer access_time_windows के साथ आवश्यक

    इस सदस्य/स्रोत रिविज़न स्ट्रीम के लिए एक लगातार बढ़ने वाला, गैर-ऋणात्मक, JSON-सुरक्षित पूर्णांक। जब भी access_time_windows मौजूद हो, यह आवश्यक है और 9007199254740991 से अधिक नहीं होना चाहिए।

हर स्नैपशॉट में अधिकतम 50 विंडो स्वीकार की जाती हैं। external_id, scope_key और label में अधिकतम 120 अक्षर स्वीकार किए जाते हैं। निरपेक्ष विंडो अधिकतम 90 दिनों की हो सकती हैं। एक साप्ताहिक दिन में अधिकतम आठ गैर-ओवरलैपिंग ब्लॉक स्वीकार किए जाते हैं। अमान्य डेटा को काटने या अनुमान लगाने के बजाय अस्वीकार कर दिया जाता है।

विंडो के स्वरूप

एक निरपेक्ष विंडो एक सटीक अंतराल की पहचान करती है:

पूर्ण मिश्रित अनुरोध

यह अनुरोध सदस्य के पिछले, स्रोत के स्वामित्व वाले स्नैपशॉट को एक निरपेक्ष और एक साप्ताहिक विंडो से बदल देता है:

समय और सीमा संबंधी नियम

from, to, active_from और active_until, UTC क्षणों की पहचान करने वाले JSON पूर्णांक Unix सेकंड हैं:

  • बिना उद्धरण चिह्नों वाला JSON पूर्णांक भेजें। संख्यात्मक स्ट्रिंग, फ़्लोट, RFC 3339 स्ट्रिंग और Unix मिलीसेकंड अस्वीकार कर दिए जाते हैं।
  • हर अंतराल अर्ध-खुला है: [from, to)। पहुँच ठीक from पर शुरू हो सकती है; ठीक to पर यह सक्रिय नहीं रहती।
  • from का मान to से कम होना चाहिए। जब दोनों साप्ताहिक सीमाएँ मौजूद हों, तो active_from का मान active_until से कम होना चाहिए।
  • बिना टाइमज़ोन वाली स्थानीय तारीख/समय से epoch न निकालें। पहले स्रोत समय को UTC क्षण में बदलें, फिर Unix मिलीसेकंड को 1000 से विभाजित करें और सत्यापित करें कि परिणाम पूर्णांक है।

टाइमज़ोन और डेलाइट सेविंग

timezone एक मान्य IANA टाइमज़ोन होना चाहिए, जैसे UTC, Australia/Perth या America/New_York। छोड़े जाने पर यह डिफ़ॉल्ट रूप से UTC होता है।

  • निरपेक्ष विंडो: from और to पहले से ही सटीक UTC क्षणों की पहचान करते हैं। timezone केवल प्रदर्शन और ऑडिट मेटाडेटा है; इसे बदलने से कोई भी क्षण कभी नहीं खिसकता।
  • साप्ताहिक विंडो: timezone उस स्थानीय घड़ी-समय और डेलाइट-सेविंग नियमों को परिभाषित करता है जिनका उपयोग access_hours के मूल्यांकन के लिए किया जाता है। साप्ताहिक ब्लॉक को पहले से UTC में न बदलें।
  • घड़ी आगे होने (spring-forward) के बदलाव के दौरान, वह स्थानीय समय जिसे टाइमज़ोन छोड़ देता है, कभी नहीं आता।
  • घड़ी पीछे होने (fall-back) के बदलाव के दौरान, दोहराए गए स्थानीय समय वाले दोनों वास्तविक क्षण साप्ताहिक ब्लॉक से मेल खाते हैं।
  • active_from और active_until, UTC क्षण ही रहते हैं, भले ही साप्ताहिक विंडो गैर-UTC टाइमज़ोन का उपयोग करे।

access_hours लोअरकेस sun से sat तक का उपयोग करता है। हर मान शून्य-पैडेड, 24-घंटे वाले HH:mm का उपयोग करने वाली [start, end] जोड़ियों का ऐरे है। ब्लॉक खाली नहीं होने चाहिए, क्रम में होने चाहिए और ओवरलैप नहीं होने चाहिए। end अपवर्जी (exclusive) है। कोई ब्लॉक आधी रात को पार नहीं कर सकता; रात भर के स्रोत अंतराल को पहले दिन के देर वाले ब्लॉक और अगले दिन के शुरुआती ब्लॉक में विभाजित करें।

स्थिर ID और स्कोप मैपिंग

external_id किसी तार्किक विंडो के पूरे जीवनकाल के लिए स्थिर और सदस्य स्नैपशॉट के भीतर अद्वितीय होना चाहिए। समय या लेबल बदलने पर भी इसे स्थिर रखें ताकि ऑपरेटर और ऑडिट रिकॉर्ड रिविज़न को आपस में जोड़ सकें। इसे किसी असंबंधित विंडो के लिए दोबारा उपयोग न करें।

scope_key आपका स्थिर तार्किक एक्सेस लक्ष्य है। यह डिफ़ॉल्ट रूप से default होता है। एक सुविधा व्यवस्थापक हर अनुमत कुंजी को Performance Hub के सुविधा-व्यापी, दरवाज़े या पहुँच का दायरा लक्ष्यों से मैप करता है:

पूर्ण स्नैपशॉट और रिविज़न

इन दो फ़ील्ड को Member अपसर्ट के भीतर एक अलग से संस्करणित विभाजन मानें:

इनपुट परिणाम
access_time_windows छोड़ा गया मौजूदा स्नैपशॉट अपरिवर्तित रहता है; किसी रिविज़न की आवश्यकता नहीं है
नए रिविज़न के साथ मौजूद इस सदस्य/स्रोत का पूरा संग्रहीत स्नैपशॉट बदल दिया जाता है
वही रिविज़न और वही सामान्यीकृत पेलोड आइडेम्पोटेंट रीप्ले; स्नैपशॉट में कोई बदलाव नहीं
वही रिविज़न और अलग सामान्यीकृत पेलोड कॉन्फ़्लिक्ट; मिलान करने के बाद नया रिविज़न आवंटित करें
पुराना रिविज़न पुराना (stale) स्नैपशॉट छोड़ दिया जाता है; यह नई स्थिति को ओवरराइट नहीं कर सकता
नए रिविज़न के साथ access_time_windows: [] स्रोत के स्वामित्व वाली सभी विंडो को स्पष्ट रूप से रद्द करता है

स्नैपशॉट पूर्ण होता है, पैच नहीं। यदि रिविज़न 1842 में विंडो A और B हैं, तो केवल B वाला रिविज़न 1843, A को हटा देता है।

वेबहुक वर्कर्स, पोलिंग, रीप्ले और पूर्ण रिकंसिलिएशन में हर पार्टनर/सदस्य के लिए एक समन्वित रिविज़न स्ट्रीम बनाए रखें। एक टिकाऊ डेटाबेस सीक्वेंस बेहतर है। Unix-मिलीसेकंड मान का उपयोग रिविज़न के रूप में केवल तब किया जा सकता है जब हर लेखक समन्वय करता हो और सख्त क्रम और अद्वितीयता की गारंटी देता हो; यह एक रिविज़न मान है, epoch फ़ील्ड नहीं।

API रिस्पॉन्स ज्ञात होने तक सटीक अनुरोध और रिविज़न को सहेजे रखें। टाइमआउट या अस्थायी त्रुटि के बाद उसी सामान्यीकृत स्नैपशॉट को उसी रिविज़न के साथ पुनः प्रयास करें। केवल इसलिए नया रिविज़न आवंटित न करें कि ट्रांसपोर्ट डिलीवरी अनिश्चित है।

रद्दीकरण, समाप्ति और अपस्ट्रीम विफलताएँ

  • एक विंडो रद्द करें: आधिकारिक स्रोत स्थिति को सफलतापूर्वक फ़ेच करें, उस विंडो को हटाएँ, और शेष पूर्ण स्नैपशॉट को नए रिविज़न के साथ भेजें।
  • सभी विंडो रद्द करें: नए रिविज़न के साथ access_time_windows: [] भेजें।
  • किसी निरपेक्ष विंडो को समाप्त होने दें: यह to पर अनुमति देना बंद कर देती है; स्नैपशॉट को साफ़ रखने के लिए बाद में समाप्त प्रविष्टि के बिना एक रिकंसिलिएशन भेजें।
  • किसी साप्ताहिक विंडो को समाप्त करें: इसे नए स्नैपशॉट में हटा दें, या जब स्रोत में समाप्ति का ज्ञात क्षण हो, तो active_until का उपयोग करें।
  • स्रोत फ़ेच विफल या अधूरा है: [] न भेजें और आंशिक स्नैपशॉट प्रकाशित न करें। अलर्ट करें और फ़ेच को पुनः प्रयास करें। किसी अपस्ट्रीम विफलता को खाली स्नैपशॉट में बदलना अनपेक्षित रूप से पहुँच को रद्द करना है।
  • Partner API अनुरोध सत्यापन में विफल होता है: डेटा ठीक करें और नया रिविज़न केवल तब भेजें जब सामान्यीकृत स्नैपशॉट बदलता है। अस्थायी विफलताओं को मूल रिविज़न के साथ पुनः प्रयास करें।

स्रोत की ताज़गी हर इंटीग्रेशन के लिए उसकी वादा की गई डिलीवरी और रिकंसिलिएशन आवृत्ति के आधार पर कॉन्फ़िगर की जाती है। सक्रिय करने से पहले, स्रोत की अधिकतम आयु, इसके पार होने पर क्या होता है, अलर्ट सीमाएँ, और क्या ऑपरेटर केवल हर विंडो की अपनी सीमाओं पर निर्भर रहने को स्वीकार कर सकते हैं, इन पर सहमति बनाएँ। पुरानी (stale) स्रोत विंडो कभी भी इनकार का नियम नहीं बनती; नियमित नियम और स्थायी अनुमतियाँ फ़ॉलबैक पथ बने रहते हैं।

प्रोड्यूसर एल्गोरिदम

हर सदस्य अपडेट के लिए इस भाषा-निरपेक्ष वर्कफ़्लो का उपयोग करें:

प्रमाणन चेकलिस्ट

अंतिम scope_key मैपिंग का उपयोग करते हुए किसी स्टेज सुविधा में ये जाँच पूरी करें:

  • छोड़े गए टाइमज़ोन वाली निरपेक्ष विंडो स्वीकार की जाती है और उसका मूल्यांकन UTC के रूप में होता है।
  • कस्टम-IANA निरपेक्ष विंडो समान from/to क्षणों को बनाए रखती है।
  • साप्ताहिक कस्टम-IANA विंडो, घड़ी आगे और पीछे होने के बदलावों में स्थानीय घड़ी-समय का पालन करती है।
  • मिश्रित निरपेक्ष/साप्ताहिक स्नैपशॉट पिछले स्नैपशॉट को पूरी तरह बदल देता है।
  • पहुँच ठीक from पर शुरू होती है और ठीक to पर रुकती है; साप्ताहिक ब्लॉक की समाप्ति भी अपवर्जी है।
  • नए रिविज़न के साथ उसी external_id के अंतर्गत समय अपडेट करना प्रभावी होता है।
  • access_time_windows छोड़ने से विंडो बदले बिना अन्य Member फ़ील्ड बदलते हैं।
  • उसी रिविज़न/पेलोड को दोबारा भेजना आइडेम्पोटेंट है।
  • वही रिविज़न/अलग पेलोड कॉन्फ़्लिक्ट लौटाता है और स्नैपशॉट नहीं बदलता।
  • क्रम से बाहर आया पुराना रिविज़न stale के रूप में रिपोर्ट होता है और स्थिति को पीछे नहीं ले जा सकता।
  • नया [] स्रोत के स्वामित्व वाली विंडो को रद्द करता है; अपस्ट्रीम फ़ेच विफल होने पर कुछ भी नहीं भेजा जाता।
  • अज्ञात या मैप न किया गया scope_key बंद अवस्था में विफल होता है और ऑपरेटर को दिखने वाली चेतावनी बनाता है।
  • स्रोत-आयु अलर्ट और कॉन्फ़िगर की गई पुराने-स्रोत की नीति तय सीमा पर काम करती हैं।
  • वेबहुक और पूर्ण रिकंसिलिएशन पथ समान स्नैपशॉट और रिविज़न क्रम पर पहुँचते हैं।
  • स्ट्रीम डिलीवरी तय लक्ष्य के भीतर Door & Gate Access तक पहुँचती है।
  • सक्रिय विंडो मैप किए गए भौतिक दरवाज़े की अनुमति दे सकती है, लेकिन उपयोगकर्ता अक्षमीकरण, blockAllAccess, मेंटेनेंस या जियोफ़ेंसिंग को बायपास नहीं कर सकती।
  • विंडो से पहले, उसके बाहर और उसके बाद, नियमित नियम और स्थायी अनुमतियाँ अन्यथा योग्य उपयोगकर्ताओं को अब भी अनुमति देते हैं।

संबंधित मार्गदर्शन

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

आवश्यक फ़ील्ड external_id, kind, from और to हैं। timezone, scope_key और label वैकल्पिक हैं।

एक साप्ताहिक विंडो आवर्ती स्थानीय घड़ी-समय अंतरालों की पहचान करती है, जो वैकल्पिक रूप से UTC क्षणों से सीमित होते हैं:

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

आवश्यक फ़ील्ड external_id, kind और access_hours हैं। timezone, active_from, active_until, scope_key और label वैकल्पिक हैं।

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

अपनी कॉन्फ़िगर की गई लिंकिंग विधि के अनुसार facility_id या linking_identifier में से किसी एक का उपयोग करें। दोनों न भेजें।

Epoch रूपांतरण

2026-10-15T08:30:00Z का रूपांतरण 1792053000 होता है:

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

भाषा-निरपेक्ष रूपांतरण:

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

यदि स्रोत में सेकंड से कम की सटीकता है, तो इंटीग्रेशन परीक्षण से पहले शुरुआत/समाप्ति के लिए एक सोची-समझी राउंडिंग नीति तय करें। कभी भी मिलीसेकंड न भेजें और इकाई का अनुमान लगाने के लिए API पर निर्भर न रहें।

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

पार्टनर किसी विंडो के भीतर Performance Hub सुविधा, दरवाज़े या पहुँच का दायरा ID नहीं भेजते। अज्ञात, अक्षम या मैप न किया गया scope_key उस विंडो के लिए बंद अवस्था में विफल (fail closed) होता है; यह पहुँच का विस्तार नहीं करता। लॉन्च से पहले मैपिंग पर सहमति बनाएँ और उनका परीक्षण करें।

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

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

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

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

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

न्यूनतम टेस्ट वेक्टर

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

Unix मिलीसेकंड, संख्यात्मक स्ट्रिंग, फ़्लोट, अमान्य IANA ज़ोन, from >= to, डुप्लिकेट external_id, ओवरलैप होते ब्लॉक, रात भर के ब्लॉक, एक दिन में आठ से अधिक ब्लॉक, 50 से अधिक विंडो और मैप न की गई स्कोप कुंजियों के लिए नकारात्मक वेक्टर भी सबमिट करें।

सदस्य सहेजें

सदस्य रिकॉर्ड बनाता या अपडेट करता है। API, member_id के आधार पर तय करता है कि रिकॉर्ड बनाना है या अपडेट करना है।

पैरामीटर

  • members array आवश्यक

    सहेजे जाने वाले सदस्य ऑब्जेक्ट का ऐरे। अनुशंसित अधिकतम: बेहतर प्रदर्शन के लिए प्रति अनुरोध 1000 आइटम। API प्रोसेसिंग के लिए आइटम को अपने आप बैच करता है। हर आइटम में या तो facility_id (यदि linking_identifier का उपयोग नहीं कर रहे हैं तो आवश्यक) या linking_identifier (यदि facility_id का उपयोग नहीं कर रहे हैं तो आवश्यक) शामिल होना चाहिए।

    जब किसी सदस्य में access_time_windows शामिल हो, तो उसमें access_time_windows_revision भी शामिल होना चाहिए। ऐरे एक पूर्ण स्रोत स्नैपशॉट है, पैच नहीं। मौजूदा स्नैपशॉट को बनाए रखने के लिए इसे छोड़ दें, या स्रोत के स्वामित्व वाली सभी विंडो को रद्द करने के लिए नए रिविज़न के साथ [] भेजें। इस फ़ील्ड को सक्षम करने से पहले Access Time Windows गाइड पढ़ें।

रिटर्न

सिंक ऑपरेशन की पुष्टि करने वाला एक सरल संदेश लौटाता है।

सदस्य प्रोफ़ाइल फ़ील्ड सामान्य अपसर्ट ही रहते हैं, भले ही किसी विंडो स्नैपशॉट को आइडेम्पोटेंट रीप्ले या stale skip के रूप में रिपोर्ट किया गया हो। समान रिविज़न/अलग पेलोड वाले टकराव वाले स्नैपशॉट को बिना बदले पुनः प्रयास नहीं किया जा सकता; स्रोत स्थिति का मिलान करें और नया रिविज़न भेजें।

अनुरोध

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

रिस्पॉन्स

सिंक ऑपरेशन के मेटाडेटा के साथ एक सफलता संदेश लौटाता है।

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

मेटाडेटा फ़ील्ड:

  • success - सफलतापूर्वक प्रोसेस किए गए सदस्यों की संख्या
  • skipped - छोड़े गए सदस्यों की संख्या (यदि कोई हो)
  • skipped_items - कारणों सहित छोड़े गए सदस्यों का ऐरे (यदि कोई हो)
  • dry-run - dryrun कुंजी प्रकार का उपयोग करने पर बूलियन फ़्लैग (यदि लागू हो)

चेक-इन

किसी सुविधा, क्लास या गतिविधि में किसी व्यक्ति की उपस्थिति के रिकॉर्ड को दर्शाता है। इसका उपयोग उपस्थिति ट्रैक करने, उपयोग एनालिटिक्स और विज़ुअल डिटेक्शन की सटीकता बेहतर करने के लिए किया जाता है।

एंडपॉइंट

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

चेक-इन ऑब्जेक्ट

एट्रिब्यूट

  • check_in_id string वैकल्पिक

    चेक-इन के लिए अद्वितीय पहचानकर्ता। वैकल्पिक - यदि नहीं दिया जाता, तो member_id और timestamp की जोड़ी से अपने आप बनाया जाता है।

  • member_id string आवश्यक

    सदस्य का अद्वितीय पहचानकर्ता।

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub से सुविधा का अद्वितीय पहचानकर्ता।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    हर स्थान के लिए वह अद्वितीय पहचानकर्ता मान जिसका उपयोग पार्टनर करता है (जैसे, "Branch ID", "Location Code", "Store Number")। और जानें

  • check_in_type string वैकल्पिक

    विज़िट का प्रकार। member, class, staff, guest या trial में से एक।

  • source string वैकल्पिक

    चेक-इन कैसे दर्ज किया गया। सामान्य मानों में manual, tag, rfid, kiosk, app शामिल हैं। door_reader या booking जैसे अतिरिक्त मानों का भी उपयोग किया जा सकता है।

  • class_id string वैकल्पिक

    वैकल्पिक। यदि यह किसी क्लास बुकिंग या उपस्थिति से जुड़ा है।

  • timestamp string आवश्यक

    चेक-इन कब हुआ, इसका ISO 8601 प्रारूप टाइमस्टैम्प।

चेक-इन ऑब्जेक्ट

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

चेक-इन सहेजें

चेक-इन रिकॉर्ड बनाता है। API सदस्य, सुविधा और टाइमस्टैम्प के आधार पर अपने आप डुप्लिकेट हटाता है।

पैरामीटर

  • check_ins array आवश्यक

    सहेजे जाने वाले चेक-इन ऑब्जेक्ट का ऐरे। अनुशंसित अधिकतम: बेहतर प्रदर्शन के लिए प्रति अनुरोध 1000 आइटम। API प्रोसेसिंग के लिए आइटम को अपने आप बैच करता है। हर आइटम में या तो facility_id (यदि linking_identifier का उपयोग नहीं कर रहे हैं तो आवश्यक) या linking_identifier (यदि facility_id का उपयोग नहीं कर रहे हैं तो आवश्यक) शामिल होना चाहिए।

रिटर्न

सिंक ऑपरेशन की पुष्टि करने वाला एक सरल संदेश लौटाता है।

अनुरोध

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

रिस्पॉन्स

सिंक ऑपरेशन के मेटाडेटा के साथ एक सफलता संदेश लौटाता है।

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

मेटाडेटा फ़ील्ड:

  • success - सफलतापूर्वक प्रोसेस किए गए चेक-इन की संख्या
  • skipped - छोड़े गए चेक-इन की संख्या (यदि कोई हो)
  • skipped_items - कारणों सहित छोड़े गए चेक-इन का ऐरे (यदि कोई हो)
  • dry-run - dryrun कुंजी प्रकार का उपयोग करने पर बूलियन फ़्लैग (यदि लागू हो)

एक्सेस कंट्रोल

Partner API उन सुविधाओं के लिए Performance Hub Door/Gate Controller हार्डवेयर को ट्रिगर कर सकता है जहाँ आपका इंटीग्रेशन सक्षम है।

इस API का उपयोग तब करें जब आपका सदस्य प्रबंधन सिस्टम पहले ही तय कर चुका हो कि किसी व्यक्ति को प्रवेश की अनुमति है। Performance Hub सदस्यता की स्थिति, एक्सेस घंटे, डोर-ज़ोन नियम, धोखाधड़ी जाँच या निलंबन लॉजिक का मूल्यांकन नहीं करता है। इन निर्णयों के लिए आपका सिस्टम ही प्राधिकारी बना रहता है।

अनलॉक अनुरोध सिंक्रोनस होता है। Performance Hub रीयल टाइम में ऑन-साइट कंट्रोलर को कमांड भेजता है और 200 तभी लौटाता है जब डिवाइस पुष्टि कर देता है कि रिले भौतिक रूप से अनलॉक हो गया है। अधिकांश पुष्टियाँ 3-5 सेकंड में पूरी हो जानी चाहिए। यदि टाइमआउट अवधि के भीतर कोई पुष्टि नहीं मिलती, तो API एक स्पष्ट विफलता लौटाता है।

आप ऐसे एक्सेस प्रयास या अस्वीकार को भी रिकॉर्ड कर सकते हैं जो कभी कंट्रोलर तक नहीं पहुँचा। वह कॉल दरवाज़ा अनलॉक नहीं करती। यह Door & Gate Access के एक्सेस लॉग में एक इवेंट लिखती है।

एंडपॉइंट

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

Door/Gate Controller ऑब्जेक्ट

एट्रिब्यूट

  • door_id string आवश्यक

    Door/Gate Controller के लिए अद्वितीय पहचानकर्ता। खोज के बाद इसे अपने सिस्टम में संग्रहीत करें और अनलॉक एंडपॉइंट को कॉल करते समय इसका उपयोग करें।

  • facility_id string आवश्यक

    Performance Hub सुविधा ID।

  • linking_identifier string वैकल्पिक

    जब आपका इंटीग्रेशन लिंकिंग पहचानकर्ताओं का उपयोग करता है, तब पार्टनर सुविधा पहचानकर्ता। और जानें

  • name string आवश्यक

    Performance Hub में कॉन्फ़िगर किया गया, मानव-पठनीय डिवाइस नाम।

  • zone string वैकल्पिक

    डोर ज़ोन या स्थान, जैसे Entrance।

  • status string आवश्यक

    online या offline।

  • relay_state string वैकल्पिक

    नवीनतम ज्ञात रिले स्थिति, जैसे locked या unlocked।

  • maintenance_mode string आवश्यक

    वर्तमान मेंटेनेंस मोड। off, force-open या force-closed में से एक।

  • hold_time_seconds integer आवश्यक

    दरवाज़े के लिए कॉन्फ़िगर किया गया डिफ़ॉल्ट अनलॉक होल्ड समय।

  • last_seen string वैकल्पिक

    नवीनतम डिवाइस मेटाडेटा अपडेट का ISO टाइमस्टैम्प।

Door/Gate Controller ऑब्जेक्ट

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

Door/Gate Controllers की सूची बनाएँ

आपके इंटीग्रेशन के लिए उपलब्ध Door/Gate Controllers लौटाता है।

यदि न तो facility_id और न ही linking_identifier दिया जाता है, तो API आपके पार्टनर खाते से लिंक की गई सभी सुविधाओं के Door/Gate Controllers लौटाता है।

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

पैरामीटर

  • facility_id string वैकल्पिक इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub सुविधा ID। डायरेक्ट-लिंक इंटीग्रेशन के लिए इसका उपयोग करें।

  • linking_identifier string वैकल्पिक इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    आपका अपना सुविधा/स्थान पहचानकर्ता। इसका उपयोग तब करें जब आपका इंटीग्रेशन लिंकिंग पहचानकर्ताओं के लिए कॉन्फ़िगर किया गया हो।

रिटर्न

Door/Gate Controller ऑब्जेक्ट का एक ऐरे लौटाता है।

अनुरोध

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

रिस्पॉन्स

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

Door/Gate Controller की स्थिति प्राप्त करें

किसी एक Door/Gate Controller की नवीनतम ज्ञात स्थिति और बुनियादी कॉन्फ़िगरेशन प्राप्त करता है।

एक सुविधा पहचानकर्ता दें ताकि Performance Hub सत्यापित कर सके कि दरवाज़ा ऐसी सुविधा से संबंधित है जिस तक आपका इंटीग्रेशन पहुँच सकता है।

पैरामीटर

  • door_id string आवश्यक

    सूची एंडपॉइंट द्वारा लौटाया गया Door/Gate Controller ID।

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub सुविधा ID। डायरेक्ट-लिंक इंटीग्रेशन के लिए आवश्यक।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    पार्टनर सुविधा पहचानकर्ता। लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए आवश्यक।

रिटर्न

एक Door/Gate Controller ऑब्जेक्ट लौटाता है।

अनुरोध

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

रिस्पॉन्स

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

Door/Gate Controller अनलॉक करें

Door/Gate Controller को अनलॉक कमांड भेजता है और भौतिक रिले द्वारा अनलॉक होने की पुष्टि की प्रतीक्षा करता है।

इस एंडपॉइंट को कॉल करने से पहले आपके सिस्टम को तय करना होगा कि व्यक्ति अधिकृत है या नहीं। Performance Hub केवल पार्टनर कुंजी, सुविधा पहुँच, दरवाज़े के स्वामित्व और डिवाइस की स्थिति को सत्यापित करता है।

पैरामीटर

  • door_id string आवश्यक

    सूची एंडपॉइंट द्वारा लौटाया गया Door/Gate Controller ID।

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub सुविधा ID। डायरेक्ट-लिंक इंटीग्रेशन के लिए आवश्यक।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    पार्टनर सुविधा पहचानकर्ता। लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए आवश्यक।

  • member_id string आवश्यक

    पार्टनर सदस्य ID। इसका उपयोग ऑडिट लॉगिंग और बाद में डेटा लिंकिंग के लिए किया जाता है।

  • first_name string आवश्यक

    दरवाज़ा खोलने वाले व्यक्ति का पहला नाम।

  • last_name string आवश्यक

    दरवाज़ा खोलने वाले व्यक्ति का अंतिम नाम।

  • full_name string वैकल्पिक

    वैकल्पिक। यदि छोड़ दिया जाए, तो Performance Hub first_name और last_name को जोड़ देता है।

  • check_in_id string वैकल्पिक

    सहसंबंध के लिए आपके सिस्टम से वैकल्पिक चेक-इन ID।

  • idempotency_key string वैकल्पिक

    वैकल्पिक रीप्ले-सुरक्षा कुंजी। समान पार्टनर, सुविधा और दरवाज़े के लिए समान कुंजी का दोबारा उपयोग करने पर, उपलब्ध होने पर मौजूदा परिणाम लौटाया जाता है।

रिटर्न

200 केवल तब लौटाता है जब डिवाइस पुष्टि करता है कि रिले भौतिक रूप से अनलॉक हो गया है। दरवाज़ा Performance Hub के डिवाइस प्रबंधन में कॉन्फ़िगर किए गए होल्ड समय का उपयोग करता है; पार्टनर प्रति अनुरोध रिले टाइमिंग को ओवरराइड नहीं कर सकते। अधिकांश पुष्टियाँ 3-5 सेकंड में पूरी हो जानी चाहिए। प्रलेखित टाइमआउट को एक स्पष्ट विफल अनलॉक मानें और केवल अपने स्वयं के सुरक्षा नियमों के अनुसार ही पुनः प्रयास करें।

सामान्य विफलताएँ:

  • 403 integration_not_enabled - सुविधा के लिए आपका इंटीग्रेशन सक्षम नहीं है।
  • 409 maintenance_mode_active - सुविधा के स्टाफ़ ने दरवाज़े के लिए मेंटेनेंस मोड सक्षम किया है।
  • 503 device_offline - Door/Gate Controller ऑफ़लाइन है या उसकी स्थिति पुरानी है।
  • 504 unlock_confirmation_timeout - कमांड भेजा गया था, लेकिन टाइमआउट से पहले कोई मेल खाती पुष्टि प्राप्त नहीं हुई।

अनुरोध

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

रिस्पॉन्स

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

विफलता रिस्पॉन्स

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

एक्सेस प्रयास या अस्वीकार रिकॉर्ड करें

ऐसा एक्सेस प्रयास या अस्वीकार रिकॉर्ड करता है जिसका निर्णय आपका सिस्टम पहले ही ले चुका है। Door/Gate Controller से संपर्क नहीं किया जाता, और दरवाज़ा अनलॉक नहीं होता।

इसका उपयोग तब करें जब आपका सिस्टम प्रवेश से इनकार करता है, या जब किसी प्रयास को बिना अनलॉक के Door & Gate Access के एक्सेस लॉग में दिखना चाहिए। Performance Hub सदस्यता की स्थिति, एक्सेस घंटे या अन्य एक्सेस नियमों का मूल्यांकन नहीं करता है।

अस्वीकार किया गया इवेंट Door & Gate Access के एक्सेस लॉग में Denied परिणाम, आपके पार्टनर नाम, दरवाज़े, सदस्य पहचानकर्ता (यदि आप भेजते हैं) और पढ़ने योग्य रूप में कारण कोड के साथ दिखाई देता है। उदाहरण के लिए, membership_expired को "Membership Expired" के रूप में दिखाया जाता है। reason_display_text और user_email इवेंट के साथ संग्रहीत किए जाते हैं।

पैरामीटर

  • door_id string आवश्यक

    सूची एंडपॉइंट द्वारा लौटाया गया Door/Gate Controller ID।

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub सुविधा ID। डायरेक्ट-लिंक इंटीग्रेशन के लिए आवश्यक।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    पार्टनर सुविधा पहचानकर्ता। लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए आवश्यक।

  • outcome string आवश्यक

    denied या attempted।

  • reason string वैकल्पिक

    लोअरकेस snake_case कारण कोड, अधिकतम 64 अक्षर। outcome के denied होने पर आवश्यक। उदाहरण: membership_expired।

  • reason_display_text string वैकल्पिक

    मानव-पठनीय कारण, अधिकतम 256 अक्षर। उदाहरण: Membership expired on 2026-04-01।

  • member_id string वैकल्पिक

    पार्टनर सदस्य ID। जब क्रेडेंशियल किसी सदस्य से मेल नहीं खाता, जैसे कोई अज्ञात कार्ड, तब इसे छोड़ दें।

  • user_email string वैकल्पिक

    उस व्यक्ति का ईमेल जिसने पहुँच का प्रयास किया।

  • timestamp string वैकल्पिक

    प्रयास कब हुआ, टाइमज़ोन सहित ISO 8601 के रूप में। उदाहरण: 2026-05-18T10:15:30Z। डिफ़ॉल्ट रूप से अनुरोध प्राप्त होने का समय। यह भविष्य में 5 मिनट से अधिक या 30 दिनों से अधिक पुराना नहीं होना चाहिए।

  • idempotency_key string वैकल्पिक

    रीप्ले-सुरक्षा कुंजी, अधिकतम 128 अक्षर। समान पार्टनर, सुविधा और दरवाज़े के लिए समान कुंजी का दोबारा उपयोग करने पर मूल परिणाम लौटाया जाता है।

रिटर्न

इवेंट रिकॉर्ड होने पर 201 लौटाता है। समान idempotency_key को दोबारा भेजने पर idempotent को true पर सेट करके 200 लौटाया जाता है और कोई दूसरा इवेंट नहीं बनाया जाता।

dry-run कुंजी dry_run को true पर सेट करके 200 लौटाती है। कुछ भी रिकॉर्ड नहीं किया जाता।

सामान्य विफलताएँ:

  • 400 - बॉडी अमान्य है, किसी अस्वीकार में reason नहीं है, टाइमस्टैम्प सीमा से बाहर है, या facility_id / linking_identifier किसी लिंक की गई सुविधा से मेल नहीं खाता।
  • 403 - कुंजी read-only है।
  • 403 integration_not_enabled - सुविधा के लिए आपका इंटीग्रेशन सक्षम नहीं है। message कारण बताता है।
  • 404 - लिंक की गई सुविधा के लिए Door/Gate Controller नहीं मिला।

अनुरोध

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

रिस्पॉन्स

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

आइडेम्पोटेंट रीप्ले

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

सुविधा रिपोर्ट

किसी विशिष्ट अवधि के दौरान किसी सुविधा के प्रमुख परिचालन और वित्तीय मेट्रिक्स को दर्ज करने वाला एक समय-बिंदु रिकॉर्ड।

एंडपॉइंट

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

रिपोर्ट स्नैपशॉट ऑब्जेक्ट

एट्रिब्यूट

  • facility_id string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    Performance Hub से सुविधा का अद्वितीय पहचानकर्ता।

  • linking_identifier string इनमें से एकअपने इंटीग्रेशन के लिए कॉन्फ़िगर किया गया सुविधा पहचानकर्ता प्रकार दें: डायरेक्ट-लिंक इंटीग्रेशन के लिए facility_id का उपयोग करें, या लिंकिंग-आइडेंटिफ़ायर इंटीग्रेशन के लिए linking_identifier का उपयोग करें। दोनों न भेजें; API आपके पार्टनर खाते के लिए कॉन्फ़िगर किए गए पहचानकर्ता प्रकार का उपयोग करता है और दूसरे को अनदेखा करता है। और जानें

    हर स्थान के लिए वह अद्वितीय पहचानकर्ता मान जिसका उपयोग पार्टनर करता है (जैसे, "Branch ID", "Location Code", "Store Number")। और जानें

  • start_date string आवश्यक

    YYYY-MM-DD प्रारूप में स्नैपशॉट अवधि की आरंभ तिथि।

  • end_date string आवश्यक

    YYYY-MM-DD प्रारूप में स्नैपशॉट अवधि की समाप्ति तिथि।

  • metrics object आवश्यक

    अवधि के सदस्य और राजस्व डेटा वाला मेट्रिक्स ऑब्जेक्ट।

रिपोर्ट स्नैपशॉट ऑब्जेक्ट

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

रिपोर्ट स्नैपशॉट सहेजें

किसी विशिष्ट अवधि के दौरान किसी सुविधा के परिचालन और वित्तीय मेट्रिक्स सबमिट करता है।

पैरामीटर

  • snapshots array आवश्यक

    सहेजे जाने वाले रिपोर्ट स्नैपशॉट ऑब्जेक्ट का ऐरे। प्रति अनुरोध अधिकतम 25 आइटम। हर आइटम में या तो facility_id (यदि linking_identifier का उपयोग नहीं कर रहे हैं तो आवश्यक) या linking_identifier (यदि facility_id का उपयोग नहीं कर रहे हैं तो आवश्यक) शामिल होना चाहिए।

रिटर्न

सिंक ऑपरेशन की पुष्टि करने वाला एक सरल संदेश लौटाता है।

अनुरोध

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

रिस्पॉन्स

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

त्रुटियाँ

Partner API यह बताने के लिए कि कोई अनुरोध क्यों विफल हुआ, मानक HTTP स्टेटस कोड और JSON रिस्पॉन्स बॉडी का उपयोग करता है।

त्रुटि रिस्पॉन्स का स्वरूप

अधिकांश API त्रुटियाँ एक संदेश और, जहाँ उपलब्ध हो, संरचित विवरण वाली JSON बॉडी लौटाती हैं।

स्टेटस कोड

Access Time Window विफलताएँ

अमान्य स्नैपशॉट लिखे जाने से पहले ही विंडो सत्यापन विफल हो जाता है। पुनः प्रयास न किए जा सकने वाले सामान्य कारणों में शामिल हैं:

  • access_time_windows मौजूद होने पर access_time_windows_revision का न होना।
  • स्ट्रिंग, फ़्लोटिंग-पॉइंट, या संभवतः मिलीसेकंड वाले epoch मान।
  • अमान्य IANA टाइमज़ोन, उलटा अंतराल, डुप्लिकेट external_id, ओवरलैप होते साप्ताहिक ब्लॉक, या ऐसा रात भर का ब्लॉक जिसे विभाजित नहीं किया गया।
  • प्रलेखित संख्या, लंबाई या अवधि सीमाओं से बाहर का मान।

अलग सामान्यीकृत सामग्री के साथ दोहराया गया रिविज़न 409 Conflict होता है। नवीनतम आधिकारिक स्थिति से मिलान करें और एक नया रिविज़न आवंटित करें; टकराव वाली जोड़ी को बार-बार पुनः प्रयास न करें। पुराने रिविज़न को नई स्थिति को ओवरराइट करने देने के बजाय छोड़े गए पुराने (stale) स्नैपशॉट के रूप में रिपोर्ट किया जाता है। अज्ञात या मैप न किया गया scope_key प्राधिकरण के लिए बंद अवस्था में विफल (fail closed) होता है और इसे कॉन्फ़िगरेशन अलर्ट माना जाना चाहिए।

यदि डिलीवरी का समय समाप्त हो जाता है या अस्थायी 5xx प्राप्त होता है, तो उसी रिविज़न के साथ ठीक वही सामान्यीकृत स्नैपशॉट पुनः भेजें। यदि अपस्ट्रीम स्रोत फ़ेच विफल हुआ है, तो विंडो फ़ील्ड को पूरी तरह छोड़ दें; उसकी जगह कभी भी खाली ऐरे न भेजें।

पुनः प्रयास संबंधी मार्गदर्शन

इन्हें सीमित एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करें:

  • 429
  • 500
  • 502
  • 503
  • 504

इन्हें बिना सोचे-समझे पुनः प्रयास न करें:

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

एक्सेस कंट्रोल के लिए, टाइमआउट और ऑफ़लाइन रिस्पॉन्स को हमेशा विफल अनलॉक मानें, जब तक कि आपके अपने एक्सेस नियम और सुरक्षा प्रक्रियाएँ कुछ और न कहें।

सहायता के लिए शामिल किए जाने वाले विवरण

सहायता से संपर्क करते समय, ये शामिल करें:

  • एंडपॉइंट और HTTP मेथड।
  • टाइमस्टैम्प और टाइमज़ोन।
  • पार्टनर कुंजी ID, सीक्रेट कुंजी नहीं।
  • उपयोग किया गया सुविधा पहचानकर्ता।
  • आपके सिस्टम का स्रोत रिकॉर्ड ID।
  • रिस्पॉन्स स्टेटस और बॉडी।
  • जहाँ उपलब्ध हो, event_id या command_id।
{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

कुछ डोमेन-विशिष्ट एंडपॉइंट एक स्पष्ट स्टेटस और कारण लौटाते हैं। उदाहरण के लिए, एक्सेस-कंट्रोल विफलताओं में reason, door_id, facility_id और event_id जैसे फ़ील्ड शामिल होते हैं।

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

400 Bad Request

अनुरोध गलत तरीके से बना है या उसमें आवश्यक फ़ील्ड नहीं हैं। पुनः प्रयास करने से पहले अनुरोध ठीक करें।

401 Unauthorized

प्रमाणीकरण विफल रहा। जाँचें कि आप अपनी API सीक्रेट कुंजी को यूज़रनेम और खाली पासवर्ड के साथ HTTP Basic Auth का उपयोग कर रहे हैं।

403 Forbidden

कुंजी मान्य है, लेकिन ऑपरेशन की अनुमति नहीं है। सामान्य कारणों में राइट ऑपरेशन के लिए read-only कुंजी का उपयोग करना या ऐसी सुविधा तक पहुँचने का प्रयास करना शामिल है जहाँ आपका इंटीग्रेशन सक्षम नहीं है।

404 Not Found

अनुरोधित संसाधन नहीं मिला या आपके इंटीग्रेशन के लिए उपलब्ध नहीं है।

409 Conflict

अनुरोध संसाधन की वर्तमान स्थिति से टकराता है। एक्सेस कंट्रोल के लिए, इसमें किसी Door/Gate Controller का मेंटेनेंस मोड में होना शामिल हो सकता है।

422 Unprocessable Entity

अनुरोध मान्य JSON है, लेकिन सिमेंटिक सत्यापन में विफल रहता है। पुनः प्रयास करने से पहले डेटा ठीक करें।

429 Too Many Requests

इंटीग्रेशन ने प्रलेखित रेट लिमिट पार कर दी है। एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करें।

500 Internal Server Error

किसी आंतरिक त्रुटि के कारण Performance Hub अनुरोध पूरा नहीं कर सका। बैकऑफ़ के साथ पुनः प्रयास करें। यदि समस्या बनी रहती है, तो एंडपॉइंट, टाइमस्टैम्प और रिस्पॉन्स बॉडी के साथ सहायता से संपर्क करें।

503 Service Unavailable

कोई निर्भर सेवा या डिवाइस उपलब्ध नहीं है। Door/Gate Controller अनलॉक के लिए, इसका अर्थ हो सकता है कि कंट्रोलर ऑफ़लाइन है।

504 Gateway Timeout

ऑपरेशन का समय समाप्त हो गया। Door/Gate Controller अनलॉक के लिए, इसका अर्थ है कि टाइमआउट अवधि से पहले अनलॉक की पुष्टि नहीं हुई।

वर्ज़निंग

Partner API का संस्करण URL में होता है। वर्तमान संस्करण है:

बदलाव नीति

Performance Hub जहाँ भी संभव हो, अतिरिक्त और पिछले संस्करणों के साथ संगत (backward-compatible) बदलाव करने का लक्ष्य रखता है।

पिछले संस्करणों के साथ संगत बदलावों के उदाहरण:

  • किसी अनुरोध में नया वैकल्पिक फ़ील्ड जोड़ना।
  • किसी रिस्पॉन्स में नया फ़ील्ड जोड़ना।
  • नया एंडपॉइंट जोड़ना।
  • ऐसा नया enum मान जोड़ना जहाँ क्लाइंट से अज्ञात मानों को संभालने की अपेक्षा की जाती है।
  • स्टेटस कोड अनुबंध बदले बिना सत्यापन संदेशों में सुधार करना।

access_time_windows और access_time_windows_revision अतिरिक्त Member अनुरोध फ़ील्ड हैं। जो मौजूदा क्लाइंट इन्हें छोड़ते हैं, उनका संग्रहीत Access Time Window स्नैपशॉट अपरिवर्तित रहता है। छोड़ने का यह नियम आंशिक-अपसर्ट संगतता बनाए रखता है; फ़ील्ड छोड़ना खाली ऐरे भेजने के बराबर नहीं है।

असंगत (breaking) बदलावों के उदाहरण:

  • किसी फ़ील्ड को हटाना या उसका नाम बदलना।
  • किसी फ़ील्ड का प्रकार बदलना।
  • किसी वैकल्पिक अनुरोध फ़ील्ड को आवश्यक बनाना।
  • किसी एंडपॉइंट को हटाना।
  • किसी मौजूदा स्टेटस कोड या डोमेन-विशिष्ट reason का अर्थ बदलना।

अप्रचलन

जब कोई असंगत बदलाव आवश्यक हो, तो Performance Hub जहाँ संभव हो, मौजूदा संस्करण को उसी जगह बदलने से बचेगा। इसके बजाय, हम एक नया संस्करण या माइग्रेशन पथ पेश करेंगे और प्रभावित पार्टनरों को बदलाव की सूचना देंगे।

अप्रचलन सूचनाओं में ये शामिल हो सकते हैं:

  • एक चेंजलॉग प्रविष्टि।
  • पार्टनर से सीधा संवाद।
  • Partner Console में नोट।
  • दस्तावेज़ों में माइग्रेशन मार्गदर्शन।

क्लाइंट के लिए अनुशंसाएँ

ऐसे क्लाइंट बनाएँ जो अतिरिक्त बदलावों को सहन कर सकें:

  • उन रिस्पॉन्स फ़ील्ड को अनदेखा करें जिनका आप उपयोग नहीं करते।
  • अज्ञात enum मानों को क्रैश होने के बजाय असमर्थित मानें।
  • रिस्पॉन्स की सख्त समानता जाँच से बचें।
  • अपरिचित मानों को लॉग करें ताकि आप अपने इंटीग्रेशन को सोच-समझकर अपडेट कर सकें।

Access Time Windows जैसे रिविज़न वाले Member विभाजनों के लिए, परिणाम ज्ञात होने तक सबमिट किए गए रिविज़न और सामान्यीकृत पेलोड को सहेजे रखें। बदली गई सामग्री के लिए किसी रिविज़न का दोबारा उपयोग करना कॉन्फ़्लिक्ट है, जबकि समान सामग्री को दोबारा भेजना आइडेम्पोटेंट है। Access Time Windows देखें।

OpenAPI विनिर्देश

क्लाइंट बनाने, अनुरोधों को सत्यापित करने और समय के साथ API के स्वरूप में बदलावों को ट्रैक करने के लिए प्रकाशित OpenAPI विनिर्देशों का उपयोग करें।

OpenAPI विनिर्देश देखें।

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

चेंजलॉग

यह चेंजलॉग Partner API और Partner Console के उन उल्लेखनीय बदलावों को दर्ज करता है जो इंटीग्रेशन के व्यवहार को प्रभावित करते हैं।

2026-09-09

2026-05-06

2026-05-01

बदलाव की श्रेणियाँ

भविष्य की प्रविष्टियाँ इन श्रेणियों का उपयोग करती हैं:

  • Added - नया एंडपॉइंट, फ़ील्ड, गाइड या क्षमता।
  • Changed - समर्थन हटाए बिना व्यवहार या दस्तावेज़ बदले गए।
  • Deprecated - फ़ीचर उपलब्ध रहता है, लेकिन उसके लिए माइग्रेशन का एक नियोजित मार्ग है।
  • Removed - फ़ीचर या एंडपॉइंट हटाया गया।
  • Fixed - बग फ़िक्स या दस्तावेज़ सुधार।
  • Security - प्रमाणीकरण, प्राधिकरण, डेटा प्रबंधन या कुंजी-प्रबंधन में बदलाव।

जोड़ा गया

  • मिश्रित निरपेक्ष और आवर्ती साप्ताहिक विंडो वाले, विक्रेता-निरपेक्ष Member access_time_windows स्नैपशॉट जोड़े गए।
  • access_time_windows_revision क्रम, आइडेम्पोटेंट रीप्ले, कॉन्फ़्लिक्ट, stale-skip और स्पष्ट-रद्दीकरण सिमेंटिक्स जोड़े गए।
  • IANA टाइमज़ोन, डेलाइट-सेविंग, लॉजिकल scope_key मैपिंग, स्रोत-ताज़गी, प्रोड्यूसर इम्प्लीमेंटेशन और प्रमाणन मार्गदर्शन जोड़ा गया।

जोड़ा गया

  • पार्टनर के प्रकार, ऑनबोर्डिंग, सर्वोत्तम तरीके, गो-लाइव तैयारी, त्रुटियाँ, वर्ज़निंग और सहायता को कवर करने वाले पार्टनर प्रोग्राम दस्तावेज़ जोड़े गए।
  • संभावित तकनीकी और व्यावसायिक पार्टनरों के लिए एक समर्पित Become a Partner पूछताछ फ़्लो जोड़ा गया।
  • इस बारे में दस्तावेज़ जोड़े गए कि स्वीकृत पार्टनर इंटीग्रेशन मुख्य Performance Hub प्लेटफ़ॉर्म में Performance Hub पार्टनर डायरेक्टरी के भीतर कैसे दिखाई देते हैं।

जोड़ा गया

  • सूची, स्थिति और अनलॉक ऑपरेशनों सहित Door/Gate Controller एक्सेस-कंट्रोल दस्तावेज़ जोड़े गए।
  • सिंक्रोनस अनलॉक व्यवहार के दस्तावेज़ जोड़े गए: API सफलता तभी लौटाता है जब ऑन-साइट कंट्रोलर पुष्टि करता है कि रिले भौतिक रूप से अनलॉक हो गया है।
  • Door/Gate Controller अनलॉक अनुरोधों के लिए वैकल्पिक idempotency_key समर्थन के दस्तावेज़ जोड़े गए।