Apple Wallet PassKit API

PassKit Designer API ช่วยให้คุณสามารถสร้าง อัปเดต ดาวน์โหลด และจัดการ Apple Wallet passes ผ่านโปรแกรมได้ รองรับการทำงานเช่นเดียวกับตัวสร้าง pass ใน Control Panel ใช้เพื่อออกบัตรสะสมคะแนน คูปอง ตั๋วเข้าร่วมงาน บัตรผ่านขึ้นเครื่อง และบัตรของร้านค้า และเพื่อส่งการอัปเดตสดไปยัง pass ที่ติดตั้งอยู่บนอุปกรณ์ของผู้ใช้ของคุณแล้ว

URL พื้นฐาน

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

Endpoints ทั้งหมดให้บริการผ่าน HTTPS คำขอและการตอบกลับใช้ application/json เว้นแต่จะระบุไว้เป็นอย่างอื่น

การรับรองความถูกต้อง

ทุกคำขอต้องมีเฮดเดอร์ Authorization พร้อมกับ Pushwoosh API access token ของคุณ:

Authorization: Token <api-token>

บัญชีที่เป็นเจ้าของโทเค็นจะต้องเป็นเจ้าของแอปพลิเคชันที่อ้างอิงโดย applicationCode คำขอสำหรับแอปพลิเคชันที่เป็นของบัญชีอื่นจะส่งคืน 403 Forbidden

ข้อตกลงทั่วไป

การตั้งชื่อฟิลด์: ฟิลด์ JSON ใช้ lowerCamelCase (ตัวอย่างเช่น passTypeIdentifier, serialNumber, backgroundColor)
ฟิลด์ที่ไม่มีข้อมูล: การตอบกลับจะรวมทุกฟิลด์ แม้ว่าจะว่างเปล่าหรือมีค่าเป็นศูนย์
ข้อมูลไบนารี: ฟิลด์ bytes เช่น pkpassData และ data ของรูปภาพเป็นสตริงที่เข้ารหัสแบบ Base64 ใน JSON
หมายเลขซีเรียล: serialNumber จะถูกกำหนดโดยเซิร์ฟเวอร์เสมอเมื่อมีการสร้าง pass ค่าใดๆ ที่คุณส่งเมื่อสร้างจะถูกละเว้น มันจะระบุ pass สำหรับการดำเนินการทั้งหมดในภายหลัง

การตอบกลับข้อผิดพลาด

API จะแมปสถานะโค้ดภายในกับสถานะโค้ด HTTP:

สถานะ HTTP	ความหมาย
`400 Bad Request`	อาร์กิวเมนต์ไม่ถูกต้อง—ฟิลด์ที่จำเป็นขาดหายไปหรือมีรูปแบบไม่ถูกต้อง
`401 Unauthorized`	เฮดเดอร์ `Authorization` ขาดหายไปหรือไม่ถูกต้อง
`403 Forbidden`	แอปพลิเคชันไม่ได้เป็นของบัญชีของผู้เรียก
`404 Not Found`	ไม่พบ pass, เทมเพลต หรือแอปพลิเคชัน
`503 Service Unavailable`	บริการมีความจุเต็มหรือใช้งานไม่ได้ชั่วคราว

Endpoints

เมธอด	พาธ	คำอธิบาย
`POST`	`/api/pass/validate`	ตรวจสอบความถูกต้องของการกำหนดค่า pass
`POST`	`/api/pass/create`	สร้าง `.pkpass` ใหม่
`POST`	`/api/pass/update/{serialNumber}`	อัปเดต pass ที่มีอยู่และแจ้งเตือนอุปกรณ์
`GET`	`/api/passes`	แสดงรายการ pass ทั้งหมดสำหรับแอปพลิเคชัน
`GET`	`/api/pass/{applicationCode}/{serialNumber}`	รับ pass เดียว
`GET`	`/api/pass/{applicationCode}/{serialNumber}/download`	ดาวน์โหลด `.pkpass` ของ pass ที่มีอยู่
`DELETE`	`/api/pass/{applicationCode}/{serialNumber}`	ลบ pass
`GET`	`/api/pass/{serialNumber}/registrations`	แสดงรายการอุปกรณ์ที่ลงทะเบียนสำหรับ pass
`GET`	`/api/config`	รับการกำหนดค่า PassKit ของแอปพลิเคชัน
`GET`	`/api/templates`	แสดงรายการเทมเพลต pass ที่มีอยู่
`GET`	`/api/templates/{filename}`	รับเทมเพลตเดียว

สร้าง pass

สร้าง ลงนาม และจัดเก็บ pass ใหม่ จากนั้นส่งคืนหมายเลขซีเรียลที่เซิร์ฟเวอร์กำหนด

POST /api/pass/create

เนื้อหาของคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`pass`	object	ใช่	อ็อบเจกต์ pass ที่อธิบาย pass
`images`	array of objects	ไม่	รูปภาพ pass (ไอคอน, โลโก้, ฯลฯ) `icon` และ `logo` จำเป็นสำหรับ pass ที่ถูกต้อง
`userId`	string	ใช่	Pushwoosh User ID ที่ pass ถูกออกให้
`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	ข้อมูลระบุตัวตนเฉพาะของ pass ที่สร้างขึ้นซึ่งกำหนดโดยเซิร์ฟเวอร์ ใช้เพื่อดึงข้อมูล pass (รับ pass) หรือดาวน์โหลด `.pkpass` (ดาวน์โหลด pass)
`message`	string	ข้อความผลลัพธ์

ตัวอย่างการตอบกลับ

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

ตรวจสอบความถูกต้องของ pass

ตรวจสอบการกำหนดค่า pass เทียบกับข้อกำหนดของ Apple โดยไม่ต้องสร้างไฟล์ มีประโยชน์ก่อนที่จะเรียก create

POST /api/pass/validate

เนื้อหาของคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`pass`	object	ใช่	อ็อบเจกต์ pass ที่จะตรวจสอบ

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`valid`	boolean	ระบุว่า pass ผ่านการตรวจสอบหรือไม่
`errors`	array of strings	ปัญหาที่บล็อกซึ่งต้องได้รับการแก้ไข
`warnings`	array of strings	คำแนะนำที่ไม่ใช่การบล็อก

อัปเดต pass

สร้าง pass ใหม่ด้วยเนื้อหาใหม่ ลงนามใหม่ เพิ่มแท็กอัปเดต และส่ง silent push notification ไปยังทุกอุปกรณ์ที่ลงทะเบียน pass นั้น จากนั้น iOS จะดึงข้อมูลและติดตั้งเวอร์ชันที่อัปเดตในเบื้องหลัง

POST /api/pass/update/{serialNumber}

พารามิเตอร์ของพาธ

พารามิเตอร์	ประเภท	คำอธิบาย
`serialNumber`	string	หมายเลขซีเรียลที่ส่งคืนเมื่อ pass ถูกสร้างขึ้น

เนื้อหาของคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`updates`	object	ใช่	อ็อบเจกต์ pass ทั้งหมดพร้อมเนื้อหาใหม่
`applicationCode`	string	ใช่	รหัสแอปพลิเคชัน Pushwoosh

serialNumber (จากพาธ) และโทเค็นการรับรองความถูกต้องของ pass จะถูกเก็บรักษาโดยเซิร์ฟเวอร์โดยไม่คำนึงถึงสิ่งที่คุณส่ง

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`success`	boolean	ระบุว่าการอัปเดตสำเร็จหรือไม่
`updateTag`	integer	แท็กอัปเดตใหม่ (การประทับเวลา Unix)
`message`	string	ข้อความผลลัพธ์

แสดงรายการ pass

ส่งคืนรายการ pass ที่จัดเก็บไว้สำหรับแอปพลิเคชันแบบแบ่งหน้าและจัดเรียง

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	หน้าปัจจุบันของ ระเบียน pass
`page`	integer	ดัชนีหน้าที่ส่งคืน
`perPage`	integer	ขนาดหน้าที่ใช้สำหรับการตอบกลับนี้
`total`	integer	จำนวน pass ทั้งหมดสำหรับแอปพลิเคชันในทุกหน้า

ตัวอย่างการตอบกลับ

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

รับ pass

ส่งคืน pass ที่จัดเก็บไว้เดียว รวมถึงอ็อบเจกต์ pass ทั้งหมด

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

พารามิเตอร์ของพาธ

พารามิเตอร์	ประเภท	คำอธิบาย
`applicationCode`	string	รหัสแอปพลิเคชัน Pushwoosh
`serialNumber`	string	หมายเลขซีเรียลของ pass

การตอบกลับ

ส่งคืน { "pass": { ... } } ซึ่งเป็น ระเบียน pass เดียว

ดาวน์โหลด pass

ส่งคืนไฟล์ .pkpass ที่จัดเก็บไว้ของ pass ที่มีอยู่

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

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`pkpassData`	string (Base64)	ไฟล์ `.pkpass`
`filename`	string	ชื่อไฟล์ที่แนะนำ

ลบ pass

ลบระเบียน pass และไฟล์ .pkpass ที่จัดเก็บไว้

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

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`success`	boolean	ระบุว่า pass ถูกลบหรือไม่
`message`	string	ข้อความผลลัพธ์

รับการลงทะเบียน pass

แสดงรายการอุปกรณ์ที่ได้เพิ่ม pass และลงทะเบียนเพื่อรับการอัปเดต

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

การตอบกลับ

ส่งคืน { "registrations": [ ... ] } โดยแต่ละรายการมี:

ฟิลด์	ประเภท	คำอธิบาย
`deviceLibraryIdentifier`	string	ตัวระบุไลบรารีอุปกรณ์ Apple
`pushToken`	string	โทเค็น push ของ pass สำหรับอุปกรณ์

รับการกำหนดค่า

ส่งคืนการกำหนดค่า PassKit ที่แก้ไขสำหรับแอปพลิเคชันจากใบรับรอง

GET /api/config?applicationCode=XXXXX-XXXXX

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`teamIdentifier`	string	Apple Team ID จากใบรับรอง
`passTypeIdentifier`	string	Pass Type ID จากใบรับรอง
`organizationName`	string	ชื่อองค์กรจากใบรับรอง
`hasCertificate`	boolean	ระบุว่ามีการกำหนดค่าใบรับรองหรือไม่
`webServiceUrl`	string	URL พื้นฐานของบริการเว็บ pass ไคลเอ็นต์สร้างลิงก์ติดตั้งโดยต่อท้าย `/v1/passes/{passType}/{serial}?token={authToken}`

เทมเพลต

แสดงรายการเทมเพลต pass ที่มีอยู่ หรือดึงข้อมูลหนึ่งรายการเป็น อ็อบเจกต์ pass ที่คุณสามารถใช้เป็นจุดเริ่มต้นได้

GET /api/templates — ส่งคืน { "templates": [ { "filename", "name", "description", "style" } ] }

GET /api/templates/{filename} — ส่งคืน { "template": { ...pass object... } }

แชร์ pass เป็น QR code

เพื่อให้ผู้ใช้สามารถเพิ่ม pass โดยการสแกน QR code (หรือแตะลิงก์) ให้เข้ารหัส URL การติดตั้ง pass เป็น QR code URL นี้สร้างขึ้นจากค่าที่คุณได้รับกลับมาจาก API อยู่แล้ว:

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

ส่วนของ URL	หาได้จากที่ไหน
`webServiceUrl`	`GET /api/config` → `webServiceUrl`
`passTypeIdentifier`	ระเบียน pass → `pass.passTypeIdentifier` (จาก list/get)
`serialNumber`	ระเบียน pass → `serialNumber`
`authenticationToken`	ระเบียน pass → `pass.authenticationToken`

ตัวอย่าง:

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

แสดงผล URL นี้เป็น QR code ด้วยไลบรารี QR ใดก็ได้ เมื่อผู้ใช้สแกน อุปกรณ์ของพวกเขาจะเปิดลิงก์ ดาวน์โหลด .pkpass ล่าสุด และ Wallet จะแจ้งให้พวกเขาเพิ่ม ซึ่งจะลงทะเบียนอุปกรณ์เพื่อรับการอัปเดตด้วย

การอ้างอิงอ็อบเจกต์

อ็อบเจกต์ pass

ฟิลด์	ประเภท	คำอธิบาย
`formatVersion`	integer	เวอร์ชันรูปแบบของ pass ค่าเริ่มต้นคือ `1`
`passTypeIdentifier`	string	Apple Pass Type ID (`pass.com.yourcompany.passtype`) ค่าเริ่มต้นจากใบรับรอง
`serialNumber`	string	กำหนดโดยเซิร์ฟเวอร์เมื่อสร้าง ใช้ระบุ pass
`teamIdentifier`	string	Apple Team ID ค่าเริ่มต้นจากใบรับรอง
`organizationName`	string	องค์กรที่แสดงบน pass ค่าเริ่มต้นจากใบรับรอง
`description`	string	คำอธิบายที่มนุษย์อ่านได้ (จำเป็นโดย Apple)
`boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic`	object	สไตล์ของ pass ต้องตั้งค่า เพียงหนึ่งอย่างเท่านั้น ดู กลุ่มฟิลด์
`backgroundColor`	string	สีพื้นหลัง, `rgb(r, g, b)`
`foregroundColor`	string	สีพื้นหน้า (ข้อความ), `rgb(r, g, b)`
`labelColor`	string	สีป้ายกำกับฟิลด์, `rgb(r, g, b)`
`logoText`	string	ข้อความที่แสดงถัดจากโลโก้
`suppressStripShine`	boolean	ปิดใช้งานเอฟเฟกต์เงาบนภาพแถบ
`barcodes`	array	บาร์โค้ด ที่แสดงบน pass
`locations`	array	ตำแหน่ง ที่ทำให้ pass มีความเกี่ยวข้อง
`beacons`	array	บีคอน ที่ทำให้ pass มีความเกี่ยวข้อง
`relevantDate`	string	วันที่ในรูปแบบ ISO 8601 ที่ pass จะมีความเกี่ยวข้อง
`maxDistance`	integer	ระยะทางสูงสุด (เมตร) สำหรับความเกี่ยวข้องของตำแหน่ง
`expirationDate`	string	วันหมดอายุในรูปแบบ ISO 8601
`voided`	boolean	ทำเครื่องหมาย pass ว่าเป็นโมฆะ
`groupingIdentifier`	string	จัดกลุ่ม pass ที่เกี่ยวข้อง (ตั๋วเข้าร่วมงาน/บัตรผ่านขึ้นเครื่อง)
`userInfo`	object (map)	ข้อมูลแอปที่เป็นคีย์/ค่าใดๆ

อ็อบเจกต์กลุ่มฟิลด์

แต่ละสไตล์ของ pass (boardingPass, coupon, eventTicket, storeCard, generic) จะจัดกลุ่ม ฟิลด์ เป็นพื้นที่ต่างๆ:

ฟิลด์	ประเภท	คำอธิบาย
`headerFields`	array	แสดงในส่วนหัวของ pass (มองเห็นได้เมื่อซ้อนกันใน Wallet)
`primaryFields`	array	ฟิลด์ที่โดดเด่นที่สุด
`secondaryFields`	array	อยู่ใต้ฟิลด์หลัก
`auxiliaryFields`	array	ฟิลด์เพิ่มเติมใต้ฟิลด์รอง
`backFields`	array	แสดงที่ด้านหลังของ pass

boardingPass ยังมี transitType เพิ่มเติม (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, หรือ PKTransitTypeGeneric)

อ็อบเจกต์ฟิลด์

ฟิลด์	ประเภท	คำอธิบาย
`key`	string	คีย์ฟิลด์ที่ไม่ซ้ำกันภายใน pass
`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 proximity UUID
`major`	integer	ค่า Major
`minor`	integer	ค่า Minor
`relevantText`	string	ข้อความที่แสดงบนหน้าจอล็อกใกล้กับบีคอนนี้

อ็อบเจกต์รูปภาพ pass

ฟิลด์	ประเภท	คำอธิบาย
`imageType`	string	หนึ่งใน `icon`, `logo`, `strip`, `background`, `footer`, `thumbnail` `icon` และ `logo` เป็นสิ่งจำเป็น
`data`	string (Base64)	ไบต์ของรูปภาพ
`contentType`	string	ประเภท MIME ตัวอย่างเช่น `image/png`

อ็อบเจกต์ระเบียน pass

ส่งคืนโดย endpoints list/get

ฟิลด์	ประเภท	คำอธิบาย
`serialNumber`	string	หมายเลขซีเรียลของ pass
`passTypeIdentifier`	string	Pass Type ID
`organizationName`	string	ชื่อองค์กร
`description`	string	คำอธิบาย pass
`createdAt`	string	การประทับเวลาที่สร้าง (RFC 3339)
`updatedAt`	string	การประทับเวลาอัปเดตล่าสุด (RFC 3339)
`updateTag`	integer	แท็กอัปเดตปัจจุบัน
`pass`	object	อ็อบเจกต์ pass ทั้งหมด สำหรับการแก้ไข
`userId`	string	Pushwoosh User ID ที่ pass ถูกออกให้