واجهة برمجة تطبيقات Apple Wallet PassKit

تتيح لك واجهة برمجة تطبيقات PassKit Designer إنشاء وتحديث وتنزيل وإدارة بطاقات Apple Wallet برمجيًا. وهي تدعم نفس العمليات التي يقوم بها منشئ البطاقات في لوحة التحكم. استخدمها لإصدار بطاقات الولاء، والكوبونات، وتذاكر الفعاليات، وبطاقات الصعود إلى الطائرة، وبطاقات المتاجر، ولإرسال تحديثات حية إلى البطاقات المثبتة بالفعل على أجهزة المستخدمين.

شرط مسبق: شهادة PassKit

قبل أن تتمكن من إنشاء بطاقات لتطبيق ما، يجب تكوين شهادة توقيع iOS PassKit لهذا التطبيق. تتم إدارة الشهادة في لوحة تحكم Pushwoosh. بدونها، ستفشل طلبات create و update. انظر تكوين بطاقة Apple Wallet لنظام iOS.

عنوان URL الأساسي

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

يتم تقديم جميع نقاط النهاية عبر HTTPS. تستخدم الطلبات والاستجابات application/json ما لم يُذكر خلاف ذلك.

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز الوصول لواجهة برمجة تطبيقات Pushwoosh الخاص بك:

Authorization: Token <api-token>

يجب أن يكون الحساب الذي يمتلك الرمز هو مالك التطبيق المشار إليه بواسطة applicationCode. أي طلب لتطبيق ينتمي إلى حساب آخر سيعيد 403 Forbidden.

الاصطلاحات

• تسمية الحقول: تستخدم حقول JSON lowerCamelCase (على سبيل المثال، passTypeIdentifier، serialNumber، backgroundColor).
• الحقول غير المعبأة: تتضمن الاستجابات جميع الحقول، حتى لو كانت فارغة أو قيمتها صفر.
• البيانات الثنائية: حقول bytes مثل pkpassData وبيانات الصورة data هي سلاسل نصية مشفرة بـ Base64 في JSON.
• الأرقام التسلسلية: يتم دائمًا تعيين serialNumber بواسطة الخادم عند إنشاء بطاقة. يتم تجاهل أي قيمة ترسلها عند الإنشاء؛ فهو يحدد البطاقة لجميع العمليات اللاحقة.

استجابات الخطأ

تقوم واجهة برمجة التطبيقات بربط رموز الحالة الداخلية برموز حالة 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

نصيحة

للحصول على ملف .pkpass نفسه، استدعِ تنزيل بطاقة (أو أنشئ رابط تثبيت / رمز QR) باستخدام الرقم التسلسلي المُرجع.

نص الطلب

المعلمة	النوع	مطلوب	الوصف
pass	object	نعم	كائن البطاقة الذي يصف البطاقة.
images	array of objects	لا	صور البطاقة (أيقونة، شعار، إلخ). icon و logo مطلوبان لبطاقة صالحة.
userId	string	نعم	معرف مستخدم Pushwoosh الذي صدرت له البطاقة.
applicationCode	string	نعم	رمز تطبيق Pushwoosh.

ملاحظة

عند الإنشاء، إذا تم حذف teamIdentifier أو passTypeIdentifier أو organizationName، فسيتم تعيينها افتراضيًا إلى القيم من شهادة التطبيق المكونة. يتم تعيين formatVersion افتراضيًا إلى 1. يتم تعيين serialNumber من جانب الخادم.

مثال على الطلب

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "بطاقة ولاء Acme",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "الرصيد", "value": "1200 نقطة" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "عضو", "value": "جين دو" }
      ]
    },
    "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": "تم إنشاء البطاقة بنجاح"
}

التحقق من صحة بطاقة

يتحقق من تكوين بطاقة مقابل مواصفات Apple دون إنشاء ملف. مفيد قبل استدعاء الإنشاء.

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	علامة التحديث الجديدة (طابع زمني Unix).
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": [ /* سجلات البطاقات */ ],
  "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	معرف مكتبة جهاز Apple.
pushToken	string	رمز الدفع للبطاقة للجهاز.

الحصول على التكوين

يُرجع تكوين PassKit الذي تم حله لتطبيق من شهادته.

GET /api/config?applicationCode=XXXXX-XXXXX

الاستجابة

الحقل	النوع	الوصف
teamIdentifier	string	معرف فريق Apple من الشهادة.
passTypeIdentifier	string	معرف نوع البطاقة من الشهادة.
organizationName	string	اسم المنظمة من الشهادة.
hasCertificate	boolean	ما إذا كانت الشهادة مكونة.
webServiceUrl	string	عنوان URL الأساسي لخدمة الويب للبطاقة. يقوم العملاء بإنشاء رابط تثبيت بإضافة /v1/passes/{passType}/{serial}?token={authToken}.

القوالب

سرد قوالب البطاقات المتاحة، أو جلب قالب واحد كـ كائن بطاقة يمكنك استخدامه كنقطة بداية.

GET /api/templates — يُرجع { "templates": [ { "filename", "name", "description", "style" } ] }.

GET /api/templates/{filename} — يُرجع { "template": { ...كائن البطاقة... } }.

مشاركة بطاقة كرمز QR

للسماح للمستخدمين بإضافة بطاقة عن طريق مسح رمز QR (أو النقر على رابط)، قم بترميز عنوان URL لتثبيت البطاقة في رمز QR. يتم بناء عنوان URL من القيم التي تحصل عليها بالفعل من واجهة برمجة التطبيقات:

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

جزء URL	من أين تحصل عليه
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

قم بعرض عنوان URL هذا كرمز QR باستخدام أي مكتبة QR. عندما يقوم المستخدم بمسحه، يفتح جهازه الرابط، ويقوم بتنزيل أحدث .pkpass، ويطالبه Wallet بإضافته—مما يسجل الجهاز أيضًا للتحديثات.

مرجع الكائنات

كائن البطاقة

الحقل	النوع	الوصف
formatVersion	integer	إصدار تنسيق البطاقة. الافتراضي هو 1.
passTypeIdentifier	string	معرف نوع بطاقة Apple (pass.com.yourcompany.passtype). يتم تعيينه افتراضيًا من الشهادة.
serialNumber	string	يتم تعيينه بواسطة الخادم عند الإنشاء؛ يحدد البطاقة.
teamIdentifier	string	معرف فريق Apple. يتم تعيينه افتراضيًا من الشهادة.
organizationName	string	المنظمة المعروضة على البطاقة. يتم تعيينها افتراضيًا من الشهادة.
description	string	وصف يمكن قراءته من قبل الإنسان (مطلوب من قبل Apple).
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	المنارات (Beacons) التي تجعل البطاقة ذات صلة.
relevantDate	string	تاريخ ISO 8601 عندما تصبح البطاقة ذات صلة.
maxDistance	integer	أقصى مسافة (بالأمتار) لصلة الموقع.
expirationDate	string	تاريخ انتهاء الصلاحية ISO 8601.
voided	boolean	يحدد البطاقة على أنها باطلة.
groupingIdentifier	string	يجمع البطاقات ذات الصلة (تذاكر الفعاليات/بطاقات الصعود).
userInfo	object (map)	بيانات تطبيق عشوائية من نوع مفتاح/قيمة.

ملاحظة

تتم إدارة authenticationToken و webServiceUrl بواسطة الخدمة ولا يحتاج عملاء واجهة برمجة التطبيقات إلى تعيينهما.

كائن مجموعة الحقول

كل نمط بطاقة (boardingPass، coupon، eventTicket، storeCard، generic) يجمع الحقول في مناطق:

الحقل	النوع	الوصف
headerFields	array	تظهر في رأس البطاقة (مرئية عند تكديسها في Wallet).
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	النص المعروض على شاشة القفل بالقرب من هذا الموقع.

كائن المنارة (Beacon)

الحقل	النوع	الوصف
proximityUuid	string	iBeacon proximity 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 الذي صدرت له البطاقة.