API ของ Apple Wallet PassKit

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

URL พื้นฐาน

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

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

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

ทุกคำขอต้องมีเฮดเดอร์ Authorization พร้อมกับ โทเค็นการเข้าถึง API ของ Pushwoosh ของคุณ:

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	ใช่	User ID ของ Pushwoosh ที่ 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 ใหม่ด้วยเนื้อหาใหม่ ลงนามใหม่ เพิ่มแท็กการอัปเดต และส่ง push notification แบบเงียบ ไปยังทุกอุปกรณ์ที่ลงทะเบียน pass นั้นไว้ จากนั้น iOS จะดึงข้อมูลและติดตั้งเวอร์ชันที่อัปเดตในเบื้องหลัง

POST /api/pass/update/{serialNumber}

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

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

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

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

serialNumber (จาก path) และโทเค็นการรับรองความถูกต้องของ 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

เพื่อให้ผู้ใช้สามารถเพิ่ม pass โดยการสแกนรหัส QR (หรือแตะลิงก์) ให้เข้ารหัส URL การติดตั้ง ของ pass เป็นรหัส QR 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 ด้วยไลบรารี 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	User ID ของ Pushwoosh ที่ pass ถูกออกให้