واجهة برمجة تطبيقات 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 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"
}

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

يتحقق من تكوين بطاقة مقابل مواصفات 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": { ...pass object... } }.

مشاركة بطاقة كرمز 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	المنارات التي تجعل البطاقة ذات صلة.
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	النص المعروض على شاشة القفل بالقرب من هذا الموقع.

كائن المنارة

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