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

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`	object	हाँ	पास का वर्णन करने वाला पास ऑब्जेक्ट।
`images`	array of objects	नहीं	पास छवियां (आइकन, लोगो, आदि)। एक वैध पास के लिए `icon` और `logo` आवश्यक हैं।
`userId`	string	हाँ	Pushwoosh User ID जिसे पास जारी किया गया है।
`applicationCode`	string	हाँ	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`	string	बनाए गए पास की सर्वर-असाइन की गई अद्वितीय पहचान। इसका उपयोग पास को लाने (एक पास प्राप्त करें) या `.pkpass` डाउनलोड करने (एक पास डाउनलोड करें) के लिए करें।
`message`	string	परिणाम संदेश।

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

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

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

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

POST /api/pass/validate

अनुरोध बॉडी

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

प्रतिक्रिया

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

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

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

POST /api/pass/update/{serialNumber}

पाथ पैरामीटर

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

अनुरोध बॉडी

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

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

प्रतिक्रिया

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

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

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

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

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

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

प्रतिक्रिया

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

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

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

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

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

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

पाथ पैरामीटर

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

प्रतिक्रिया

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

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

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

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

प्रतिक्रिया

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

एक पास हटाएं

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

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

प्रतिक्रिया

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

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

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

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

प्रतिक्रिया

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

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

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

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

GET /api/config?applicationCode=XXXXX-XXXXX

प्रतिक्रिया

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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