एप्पल वॉलेट पासकिट एपीआई

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

बेस यूआरएल

https://apple-passkit.svc-nue.pushwoosh.com

सभी एंडपॉइंट HTTPS पर परोसे जाते हैं। अनुरोध और प्रतिक्रियाएं application/json का उपयोग करती हैं जब तक कि अन्यथा उल्लेख न किया गया हो।

प्रमाणीकरण

प्रत्येक अनुरोध में आपके Pushwoosh API एक्सेस टोकन के साथ एक Authorization हेडर शामिल होना चाहिए:

Authorization: Token <api-token>

टोकन का स्वामी खाता उस एप्लिकेशन का स्वामी होना चाहिए जिसे applicationCode द्वारा संदर्भित किया गया है। किसी अन्य खाते से संबंधित एप्लिकेशन के लिए एक अनुरोध 403 Forbidden लौटाता है।

परंपराएं

फील्ड नेमिंग: JSON फ़ील्ड lowerCamelCase का उपयोग करते हैं (उदाहरण के लिए, passTypeIdentifier, serialNumber, backgroundColor)।
अनपॉप्युलेटेड फ़ील्ड: प्रतिक्रियाओं में सभी फ़ील्ड शामिल होते हैं, भले ही वे खाली या शून्य-मूल्य वाले हों।
बाइनरी डेटा: bytes फ़ील्ड जैसे pkpassData और छवि data JSON में Base64-एन्कोडेड स्ट्रिंग्स हैं।
सीरियल नंबर: serialNumber हमेशा सर्वर द्वारा असाइन किया जाता है जब एक पास बनाया जाता है। बनाने पर आपके द्वारा भेजा गया कोई भी मान अनदेखा कर दिया जाता है; यह बाद के सभी ऑपरेशनों के लिए पास की पहचान करता है।

त्रुटि प्रतिक्रियाएं

API आंतरिक स्थिति कोड को HTTP स्थिति कोड में मैप करता है:

HTTP स्थिति	अर्थ
`400 Bad Request`	अमान्य तर्क—एक आवश्यक फ़ील्ड गुम या विकृत है।
`401 Unauthorized`	`Authorization` हेडर गुम या अमान्य है।
`403 Forbidden`	एप्लिकेशन कॉलर के खाते से संबंधित नहीं है।
`404 Not Found`	पास, टेम्पलेट, या एप्लिकेशन नहीं मिला।
`503 Service Unavailable`	सेवा क्षमता पर है या अस्थायी रूप से अनुपलब्ध है।

एंडपॉइंट्स

विधि	पथ	विवरण
`POST`	`/api/pass/validate`	एक पास कॉन्फ़िगरेशन को मान्य करें
`POST`	`/api/pass/create`	एक नया `.pkpass` बनाएं
`POST`	`/api/pass/update/{serialNumber}`	एक मौजूदा पास को अपडेट करें और उपकरणों को सूचित करें
`GET`	`/api/passes`	एक एप्लिकेशन के लिए सभी पास सूचीबद्ध करें
`GET`	`/api/pass/{applicationCode}/{serialNumber}`	एक एकल पास प्राप्त करें
`GET`	`/api/pass/{applicationCode}/{serialNumber}/download`	एक मौजूदा पास का `.pkpass` डाउनलोड करें
`DELETE`	`/api/pass/{applicationCode}/{serialNumber}`	एक पास हटाएं
`GET`	`/api/pass/{serialNumber}/registrations`	एक पास के लिए पंजीकृत उपकरणों को सूचीबद्ध करें
`GET`	`/api/config`	एप्लिकेशन का PassKit कॉन्फ़िगरेशन प्राप्त करें
`GET`	`/api/templates`	उपलब्ध पास टेम्पलेट्स को सूचीबद्ध करें
`GET`	`/api/templates/{filename}`	एक एकल टेम्पलेट प्राप्त करें

एक पास बनाएं

एक नया पास बनाता है, हस्ताक्षर करता है, और संग्रहीत करता है, फिर उसका सर्वर-असाइन किया गया सीरियल नंबर लौटाता है।

POST /api/pass/create

अनुरोध बॉडी

पैरामीटर	प्रकार	आवश्यक	विवरण
`pass`	ऑब्जेक्ट	हाँ	पास का वर्णन करने वाला पास ऑब्जेक्ट।
`images`	ऑब्जेक्ट्स का ऐरे	नहीं	पास छवियां (आइकन, लोगो, आदि)। एक वैध पास के लिए `icon` और `logo` आवश्यक हैं।
`userId`	स्ट्रिंग	हाँ	Pushwoosh यूज़र आईडी जिसे पास जारी किया गया है।
`applicationCode`	स्ट्रिंग	हाँ	Pushwoosh एप्लिकेशन कोड।

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

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`serialNumber`	स्ट्रिंग	बनाए गए पास की सर्वर-असाइन की गई अद्वितीय पहचान। इसका उपयोग पास को लाने (एक पास प्राप्त करें) या `.pkpass` डाउनलोड करने (एक पास डाउनलोड करें) के लिए करें।
`message`	स्ट्रिंग	परिणाम संदेश।

प्रतिक्रिया उदाहरण

{
  "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678",
  "message": "Pass created successfully"
}

एक पास को मान्य करें

एक फ़ाइल बनाए बिना एप्पल के विनिर्देशों के खिलाफ एक पास कॉन्फ़िगरेशन की जाँच करता है। बनाने से पहले कॉल करने के लिए उपयोगी।

POST /api/pass/validate

अनुरोध बॉडी

पैरामीटर	प्रकार	आवश्यक	विवरण
`pass`	ऑब्जेक्ट	हाँ	मान्य करने के लिए पास ऑब्जेक्ट।

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`valid`	बूलियन	क्या पास सत्यापन पास करता है।
`errors`	स्ट्रिंग्स का ऐरे	अवरुद्ध करने वाली समस्याएं जिन्हें ठीक किया जाना चाहिए।
`warnings`	स्ट्रिंग्स का ऐरे	गैर-अवरुद्ध सलाह।

एक पास को अपडेट करें

पास को नई सामग्री के साथ पुन: उत्पन्न करता है, इसे फिर से हस्ताक्षर करता है, इसके अपडेट टैग को बढ़ाता है, और पास को पंजीकृत करने वाले प्रत्येक उपकरण को एक साइलेंट पुश नोटिफिकेशन भेजता है। iOS फिर पृष्ठभूमि में अद्यतन संस्करण को प्राप्त और इंस्टॉल करता है।

POST /api/pass/update/{serialNumber}

पथ पैरामीटर

पैरामीटर	प्रकार	विवरण
`serialNumber`	स्ट्रिंग	पास बनाए जाने पर लौटाया गया सीरियल नंबर।

अनुरोध बॉडी

पैरामीटर	प्रकार	आवश्यक	विवरण
`updates`	ऑब्जेक्ट	हाँ	नई सामग्री के साथ पूर्ण पास ऑब्जेक्ट।
`applicationCode`	स्ट्रिंग	हाँ	Pushwoosh एप्लिकेशन कोड।

serialNumber (पथ से) और पास का प्रमाणीकरण टोकन सर्वर द्वारा संरक्षित किया जाता है, भले ही आप कुछ भी भेजें।

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`success`	बूलियन	क्या अपडेट सफल हुआ।
`updateTag`	पूर्णांक	नया अपडेट टैग (एक यूनिक्स टाइमस्टैम्प)।
`message`	स्ट्रिंग	परिणाम संदेश।

पास सूचीबद्ध करें

एक एप्लिकेशन के लिए संग्रहीत पास की एक पृष्ठित, क्रमबद्ध सूची लौटाता है।

GET /api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

क्वेरी पैरामीटर

पैरामीटर	प्रकार	आवश्यक	विवरण
`applicationCode`	स्ट्रिंग	हाँ	Pushwoosh एप्लिकेशन कोड।
`orderBy`	स्ट्रिंग	नहीं	सॉर्ट फ़ील्ड: `UPDATED` (डिफ़ॉल्ट) या `CREATED`।
`orderDirection`	स्ट्रिंग	नहीं	सॉर्ट दिशा: `DESC` (डिफ़ॉल्ट, सबसे नया पहले) या `ASC`।
`page`	पूर्णांक	नहीं	शून्य-आधारित पृष्ठ सूचकांक। `0` पर डिफ़ॉल्ट।
`perPage`	पूर्णांक	नहीं	पृष्ठ आकार। `0` या छोड़ा गया सर्वर डिफ़ॉल्ट का उपयोग करता है।

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`passes`	ऑब्जेक्ट्स का ऐरे	पास रिकॉर्ड्स का वर्तमान पृष्ठ।
`page`	पूर्णांक	लौटाया गया पृष्ठ सूचकांक।
`perPage`	पूर्णांक	इस प्रतिक्रिया के लिए उपयोग किया गया पृष्ठ आकार।
`total`	पूर्णांक	सभी पृष्ठों पर एप्लिकेशन के लिए पास की कुल संख्या।

प्रतिक्रिया उदाहरण

{
  "passes": [ /* pass records */ ],
  "page": 0,
  "perPage": 20,
  "total": 137
}

एक पास प्राप्त करें

एक एकल संग्रहीत पास लौटाता है, जिसमें उसका पूर्ण पास ऑब्जेक्ट शामिल है।

GET /api/pass/{applicationCode}/{serialNumber}

पथ पैरामीटर

पैरामीटर	प्रकार	विवरण
`applicationCode`	स्ट्रिंग	Pushwoosh एप्लिकेशन कोड।
`serialNumber`	स्ट्रिंग	पास सीरियल नंबर।

प्रतिक्रिया

{ "pass": { ... } } लौटाता है, एक एकल पास रिकॉर्ड।

एक पास डाउनलोड करें

एक मौजूदा पास की संग्रहीत .pkpass फ़ाइल लौटाता है।

GET /api/pass/{applicationCode}/{serialNumber}/download

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`pkpassData`	स्ट्रिंग (Base64)	`.pkpass` फ़ाइल।
`filename`	स्ट्रिंग	सुझाया गया फ़ाइल नाम।

एक पास हटाएं

एक पास रिकॉर्ड और उसकी संग्रहीत .pkpass फ़ाइल को हटाता है।

DELETE /api/pass/{applicationCode}/{serialNumber}

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`success`	बूलियन	क्या पास हटा दिया गया था।
`message`	स्ट्रिंग	परिणाम संदेश।

पास पंजीकरण प्राप्त करें

उन उपकरणों को सूचीबद्ध करता है जिन्होंने पास जोड़ा है और अपडेट के लिए पंजीकृत हैं।

GET /api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX

प्रतिक्रिया

{ "registrations": [ ... ] } लौटाता है, जहां प्रत्येक आइटम में है:

फ़ील्ड	प्रकार	विवरण
`deviceLibraryIdentifier`	स्ट्रिंग	एप्पल डिवाइस लाइब्रेरी पहचानकर्ता।
`pushToken`	स्ट्रिंग	डिवाइस के लिए पास पुश टोकन।

कॉन्फ़िगरेशन प्राप्त करें

एक एप्लिकेशन के लिए उसके प्रमाणपत्र से हल किए गए PassKit कॉन्फ़िगरेशन को लौटाता है।

GET /api/config?applicationCode=XXXXX-XXXXX

प्रतिक्रिया

फ़ील्ड	प्रकार	विवरण
`teamIdentifier`	स्ट्रिंग	प्रमाणपत्र से एप्पल टीम आईडी।
`passTypeIdentifier`	स्ट्रिंग	प्रमाणपत्र से पास प्रकार आईडी।
`organizationName`	स्ट्रिंग	प्रमाणपत्र से संगठन का नाम।
`hasCertificate`	बूलियन	क्या एक प्रमाणपत्र कॉन्फ़िगर किया गया है।
`webServiceUrl`	स्ट्रिंग	पास वेब सेवा का बेस यूआरएल। क्लाइंट `/v1/passes/{passType}/{serial}?token={authToken}` जोड़कर एक इंस्टॉल लिंक बनाते हैं।

टेम्पलेट्स

उपलब्ध पास टेम्पलेट्स को सूचीबद्ध करें, या एक को पास ऑब्जेक्ट के रूप में प्राप्त करें जिसे आप एक शुरुआती बिंदु के रूप में उपयोग कर सकते हैं।

GET /api/templates — { "templates": [ { "filename", "name", "description", "style" } ] } लौटाता है।

GET /api/templates/{filename} — { "template": { ...pass object... } } लौटाता है।

एक पास को क्यूआर कोड के रूप में साझा करें

उपयोगकर्ताओं को एक क्यूआर कोड स्कैन करके (या एक लिंक पर टैप करके) एक पास जोड़ने देने के लिए, पास इंस्टॉल यूआरएल को एक क्यूआर कोड में एन्कोड करें। यूआरएल उन मानों से बनाया गया है जो आपको पहले से ही एपीआई से वापस मिलते हैं:

{webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken}

यूआरएल भाग	इसे कहाँ से प्राप्त करें
`webServiceUrl`	`GET /api/config` → `webServiceUrl`
`passTypeIdentifier`	पास रिकॉर्ड → `pass.passTypeIdentifier` (सूची/प्राप्त से)
`serialNumber`	पास रिकॉर्ड → `serialNumber`
`authenticationToken`	पास रिकॉर्ड → `pass.authenticationToken`

उदाहरण:

https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ

इस यूआरएल को किसी भी क्यूआर लाइब्रेरी के साथ एक क्यूआर कोड के रूप में प्रस्तुत करें। जब कोई उपयोगकर्ता इसे स्कैन करता है, तो उनका डिवाइस लिंक खोलता है, नवीनतम .pkpass डाउनलोड करता है, और वॉलेट उन्हें इसे जोड़ने के लिए संकेत देता है—जो डिवाइस को अपडेट के लिए भी पंजीकृत करता है।

ऑब्जेक्ट संदर्भ

पास ऑब्जेक्ट

फ़ील्ड	प्रकार	विवरण
`formatVersion`	पूर्णांक	पास प्रारूप संस्करण। `1` पर डिफ़ॉल्ट।
`passTypeIdentifier`	स्ट्रिंग	एप्पल पास प्रकार आईडी (`pass.com.yourcompany.passtype`)। प्रमाणपत्र से डिफ़ॉल्ट।
`serialNumber`	स्ट्रिंग	बनाने पर सर्वर द्वारा असाइन किया गया; पास की पहचान करता है।
`teamIdentifier`	स्ट्रिंग	एप्पल टीम आईडी। प्रमाणपत्र से डिफ़ॉल्ट।
`organizationName`	स्ट्रिंग	पास पर दिखाया गया संगठन। प्रमाणपत्र से डिफ़ॉल्ट।
`description`	स्ट्रिंग	मानव-पठनीय विवरण (एप्पल द्वारा आवश्यक)।
`boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic`	ऑब्जेक्ट	पास शैली। ठीक एक सेट होना चाहिए। फ़ील्ड समूह देखें।
`backgroundColor`	स्ट्रिंग	पृष्ठभूमि रंग, `rgb(r, g, b)`।
`foregroundColor`	स्ट्रिंग	अग्रभूमि (पाठ) रंग, `rgb(r, g, b)`।
`labelColor`	स्ट्रिंग	फ़ील्ड लेबल रंग, `rgb(r, g, b)`।
`logoText`	स्ट्रिंग	लोगो के बगल में दिखाया गया पाठ।
`suppressStripShine`	बूलियन	स्ट्रिप छवि पर चमक प्रभाव को अक्षम करें।
`barcodes`	ऐरे	पास पर दिखाए गए बारकोड।
`locations`	ऐरे	स्थान जो पास को प्रासंगिक बनाते हैं।
`beacons`	ऐरे	बीकन जो पास को प्रासंगिक बनाते हैं।
`relevantDate`	स्ट्रिंग	आईएसओ 8601 दिनांक जब पास प्रासंगिक हो जाता है।
`maxDistance`	पूर्णांक	स्थान प्रासंगिकता के लिए अधिकतम दूरी (मीटर)।
`expirationDate`	स्ट्रिंग	आईएसओ 8601 समाप्ति दिनांक।
`voided`	बूलियन	पास को शून्य के रूप में चिह्नित करता है।
`groupingIdentifier`	स्ट्रिंग	संबंधित पास (इवेंट टिकट/बोर्डिंग पास) को समूहित करता है।
`userInfo`	ऑब्जेक्ट (मैप)	मनमाना कुंजी/मान ऐप डेटा।

फ़ील्ड समूह ऑब्जेक्ट

प्रत्येक पास शैली (boardingPass, coupon, eventTicket, storeCard, generic) फ़ील्ड्स को क्षेत्रों में समूहित करती है:

फ़ील्ड	प्रकार	विवरण
`headerFields`	ऐरे	पास हेडर में दिखाया गया (वॉलेट में स्टैक होने पर दिखाई देता है)।
`primaryFields`	ऐरे	सबसे प्रमुख फ़ील्ड।
`secondaryFields`	ऐरे	प्राथमिक फ़ील्ड के नीचे।
`auxiliaryFields`	ऐरे	द्वितीयक के नीचे अतिरिक्त फ़ील्ड।
`backFields`	ऐरे	पास के पीछे दिखाया गया।

boardingPass में अतिरिक्त रूप से transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, या PKTransitTypeGeneric) होता है।

फ़ील्ड ऑब्जेक्ट

फ़ील्ड	प्रकार	विवरण
`key`	स्ट्रिंग	पास के भीतर अद्वितीय फ़ील्ड कुंजी।
`label`	स्ट्रिंग	फ़ील्ड लेबल।
`value`	स्ट्रिंग	फ़ील्ड मान (पाठ या संख्या स्ट्रिंग के रूप में)।
`changeMessage`	स्ट्रिंग	मान बदलने पर दिखाया गया संदेश (प्लेसहोल्डर के रूप में `%@` का उपयोग करें)।
`textAlignment`	स्ट्रिंग	`PKTextAlignment` मान।
`dateStyle` / `timeStyle`	स्ट्रिंग	दिनांक/समय स्वरूपण के लिए `PKDateStyle`।
`isRelative`	बूलियन	दिनांक को अब के सापेक्ष दिखाएं।
`numberStyle`	स्ट्रिंग	संख्या स्वरूपण के लिए `PKNumberStyle`।
`currencyCode`	स्ट्रिंग	आईएसओ 4217 मुद्रा कोड।
`dataDetectorTypes`	स्ट्रिंग्स का ऐरे	मान पर लागू करने के लिए डेटा डिटेक्टर।

बारकोड ऑब्जेक्ट

फ़ील्ड	प्रकार	विवरण
`format`	स्ट्रिंग	`PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec`, या `PKBarcodeFormatCode128`।
`message`	स्ट्रिंग	बारकोड में एन्कोड किया गया डेटा।
`messageEncoding`	स्ट्रिंग	पाठ एन्कोडिंग, आमतौर पर `iso-8859-1`।
`altText`	स्ट्रिंग	बारकोड के नीचे दिखाया गया पाठ।

स्थान ऑब्जेक्ट

फ़ील्ड	प्रकार	विवरण
`latitude`	संख्या	अक्षांश।
`longitude`	संख्या	देशांतर।
`altitude`	संख्या	मीटर में ऊंचाई।
`relevantText`	स्ट्रिंग	इस स्थान के पास लॉक स्क्रीन पर दिखाया गया पाठ।

बीकन ऑब्जेक्ट

फ़ील्ड	प्रकार	विवरण
`proximityUuid`	स्ट्रिंग	iBeacon निकटता UUID।
`major`	पूर्णांक	प्रमुख मान।
`minor`	पूर्णांक	लघु मान।
`relevantText`	स्ट्रिंग	इस बीकन के पास लॉक स्क्रीन पर दिखाया गया पाठ।

पास छवि ऑब्जेक्ट

फ़ील्ड	प्रकार	विवरण
`imageType`	स्ट्रिंग	`icon`, `logo`, `strip`, `background`, `footer`, `thumbnail` में से एक। `icon` और `logo` आवश्यक हैं।
`data`	स्ट्रिंग (Base64)	छवि बाइट्स।
`contentType`	स्ट्रिंग	MIME प्रकार, उदाहरण के लिए `image/png`।

पास रिकॉर्ड ऑब्जेक्ट

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

फ़ील्ड	प्रकार	विवरण
`serialNumber`	स्ट्रिंग	पास सीरियल नंबर।
`passTypeIdentifier`	स्ट्रिंग	पास प्रकार आईडी।
`organizationName`	स्ट्रिंग	संगठन का नाम।
`description`	स्ट्रिंग	पास विवरण।
`createdAt`	स्ट्रिंग	निर्माण टाइमस्टैम्प (RFC 3339)।
`updatedAt`	स्ट्रिंग	अंतिम अपडेट टाइमस्टैम्प (RFC 3339)।
`updateTag`	पूर्णांक	वर्तमान अपडेट टैग।
`pass`	ऑब्जेक्ट	संपादन के लिए पूर्ण पास ऑब्जेक्ट।
`userId`	स्ट्रिंग	Pushwoosh यूज़र आईडी जिसे पास जारी किया गया था।