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

تتيح لك واجهة برمجة تطبيقات Google Wallet إنشاء وتحديث وسرد وإدارة بطاقات Google Wallet برمجيًا. وهي تدعم نفس العمليات التي تقوم بها أداة إنشاء البطاقات في لوحة التحكم.

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

شرط مسبق: إعداد Google Wallet

قبل أن تتمكن من إنشاء بطاقات لتطبيق ما، يجب تكوين معرّف جهة الإصدار (Issuer ID) ومفتاح حساب الخدمة (service account key) من Google Wallet لهذا التطبيق في لوحة تحكم Pushwoosh. بدونهما، ستفشل طلبات create وupdate. راجع إعداد بطاقة Google Wallet لنظام Android.

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

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

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

المصادقة

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

Authorization: Token <api-token>

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

الاصطلاحات

• تسمية الحقول: تستخدم حقول JSON lowerCamelCase (على سبيل المثال، serialNumber، hexBackgroundColor، logoUrl).
• الحقول غير المعبأة: تتضمن الاستجابات جميع الحقول، حتى لو كانت فارغة أو قيمتها صفر.
• الهوية: يتم دائمًا تعيين serialNumber بواسطة الخادم عند إنشاء بطاقة. يتم تجاهل أي قيمة ترسلها عند الإنشاء. معرّف كائن Google Wallet الكامل هو {issuerId}.{serialNumber}.
• الصور: logoUrl و heroImageUrl هي عناوين URL عامة بصيغة HTTPS لصور تقوم Google بجلبها—وليست ملفات مرفوعة.
• نمط البطاقة: يجب تعيين نمط واحد بالضبط (generic، offer، loyalty، eventTicket، giftCard، flight، أو transit) على البطاقة. لا يمكن تغيير النمط بعد الإنشاء.

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

حالة HTTP	المعنى
400 Bad Request	وسيطة غير صالحة—حقل مطلوب مفقود أو مشوه.
401 Unauthorized	ترويسة Authorization مفقودة أو غير صالحة.
403 Forbidden	التطبيق لا ينتمي إلى حساب المتصل.
404 Not Found	لم يتم العثور على البطاقة أو القالب أو التطبيق.
503 Service Unavailable	الخدمة بكامل طاقتها أو غير متاحة مؤقتًا.

نقاط النهاية

الطريقة	المسار	الوصف
POST	/api/google/pass/validate	التحقق من صحة تكوين بطاقة
POST	/api/google/pass/create	إنشاء كائن بطاقة جديد والحصول على رابط حفظ
POST	/api/google/pass/update/{serialNumber}	تحديث بطاقة موجودة؛ تقوم Google بتسليم التغيير
GET	/api/google/pass/{applicationCode}/{serialNumber}/save-link	الحصول على رابط حفظ “إضافة إلى Google Wallet”
GET	/api/google/pass/{applicationCode}/{serialNumber}	الحصول على بطاقة واحدة
GET	/api/google/passes	سرد جميع البطاقات لتطبيق ما
POST	/api/google/pass/{applicationCode}/{serialNumber}/state	تفعيل أو إبطال بطاقة
DELETE	/api/google/pass/{applicationCode}/{serialNumber}	حذف بطاقة
GET	/api/google/config	الحصول على تكوين Google Wallet للتطبيق
GET	/api/google/templates	سرد قوالب البطاقات المتاحة
GET	/api/google/templates/{filename}	الحصول على قالب واحد

إنشاء بطاقة

ينشئ فئة وكائن البطاقة في Google Wallet، ثم يُرجع الرقم التسلسلي المعين من الخادم، ومعرّف الكائن الكامل، ورابط حفظ “إضافة إلى Google Wallet”.

POST /api/google/pass/create

نص الطلب

المعلمة	النوع	مطلوب	الوصف
pass	object	نعم	كائن البطاقة الذي يصف البطاقة. يجب تعيين نمط واحد بالضبط.
userId	string	نعم	معرّف مستخدم Pushwoosh الذي تصدر له البطاقة.
applicationCode	string	نعم	رمز تطبيق Pushwoosh.

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

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

الاستجابة

الحقل	النوع	الوصف
serialNumber	string	هوية فريدة معينة من الخادم للبطاقة التي تم إنشاؤها.
objectId	string	معرّف كائن Google Wallet الكامل: {issuerId}.{serialNumber}.
saveLink	string	رابط “إضافة إلى Google Wallet”: https://pay.google.com/gp/v/save/{jwt}.
message	string	رسالة النتيجة.

مثال على الاستجابة

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

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

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

POST /api/google/pass/validate

نص الطلب

المعلمة	النوع	مطلوب	الوصف
pass	object	نعم	كائن البطاقة للتحقق من صحته.

الاستجابة

الحقل	النوع	الوصف
valid	boolean	ما إذا كانت البطاقة تجتاز التحقق من الصحة.
errors	array of strings	مشاكل مانعة يجب إصلاحها.
warnings	array of strings	إرشادات غير مانعة.

تحديث بطاقة

يصحح كائن البطاقة بمحتوى جديد. ثم تقوم Google بتسليم الإصدار المحدث إلى كل جهاز قام بحفظ البطاقة. يرسل اختياريًا إشعار Android مع التحديث.

POST /api/google/pass/update/{serialNumber}

معلمات المسار

المعلمة	النوع	الوصف
serialNumber	string	الرقم التسلسلي الذي تم إرجاعه عند إنشاء البطاقة.

نص الطلب

المعلمة	النوع	مطلوب	الوصف
updates	object	نعم	كائن البطاقة مع المحتوى الجديد. لا يمكن تغيير النمط.
applicationCode	string	نعم	رمز تطبيق Pushwoosh.
notifyMessage	string	لا	عندما لا يكون فارغًا، أرسل إشعار Android بهذا النص إلى كل من قام بحفظ البطاقة. يعني الفراغ تحديثًا صامتًا.
notifyOnUpdate	boolean	لا	طلب إشعار تحديث حقل. فقط بطاقات loyalty و eventTicket و flight هي التي تُعلم فعليًا؛ تقبل الأنماط الأخرى العلامة ولكنها لا ترسل إشعارًا أبدًا. يتم إطلاق الإشعارات فقط في غضون 3 ساعات من وقت البدء ذي الصلة، وتحد Google من الإشعارات إلى 3 إشعارات لكل بطاقة كل 24 ساعة.

طريقتان للإشعار عند التحديث

notifyMessage يرسل إشعار Android مخصصًا إلى كل من قام بحفظ البطاقة ويعمل مع أي نمط بطاقة. notifyOnUpdate يطلب من Google إرسال إشعار تحديث حقل خاص بها، والذي يتم إطلاقه فقط لبطاقات loyalty و eventTicket و flight.

الاستجابة

الحقل	النوع	الوصف
success	boolean	ما إذا كان التحديث قد نجح.
message	string	رسالة النتيجة.

الحصول على رابط حفظ

يُرجع رابط حفظ “إضافة إلى Google Wallet” لبطاقة تم إنشاؤها بالفعل. يجب أن يكون كائن البطاقة موجودًا بالفعل (تم إنشاؤه عبر إنشاء بطاقة).

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

الاستجابة

الحقل	النوع	الوصف
saveLink	string	https://pay.google.com/gp/v/save/{jwt}.

شارك الرابط أو اعرضه كرمز QR

ضع saveLink خلف زر “إضافة إلى Google Wallet”، أو اعرضه كرمز QR باستخدام أي مكتبة QR. عندما يفتحه المستخدم، تطلب منه Google حفظ البطاقة وتسجل جهازه للتحديثات.

الحصول على بطاقة

يُرجع بطاقة واحدة مخزنة، بما في ذلك كائن البطاقة الكامل الخاص بها.

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

الاستجابة

يُرجع { "pass": { ... } }، وهو سجل بطاقة واحد.

سرد البطاقات

يُرجع قائمة مقسمة إلى صفحات ومرتبة للبطاقات المخزنة لتطبيق ما.

GET /api/google/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	العدد الإجمالي للبطاقات للتطبيق عبر جميع الصفحات.

تعيين حالة البطاقة

ينشط أو يبطل بطاقة. تنتقل البطاقة المبطلة (غير النشطة) إلى قسم البطاقات منتهية الصلاحية للمستخدم في Google Wallet؛ يتم الاحتفاظ بالسجل حتى يمكن إعادة تنشيطه.

POST /api/google/pass/{applicationCode}/{serialNumber}/state

نص الطلب

المعلمة	النوع	مطلوب	الوصف
active	boolean	نعم	true يضبط البطاقة على ACTIVE؛ false يبطلها (INACTIVE).

الاستجابة

يُرجع كائنًا فارغًا {} عند النجاح.

حذف بطاقة

يبطل البطاقة في Google ويزيل سجلها المخزن في Pushwoosh.

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

لا يمكن إزالة البطاقة المحفوظة بالقوة

لا تسمح Google بإزالة بطاقة محفوظة بالفعل على جهاز المستخدم. الحذف يبطل البطاقة (تنتقل إلى البطاقات منتهية الصلاحية) ويسقط سجل Pushwoosh.

الاستجابة

يُرجع كائنًا فارغًا {} عند النجاح.

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

يُرجع حالة تكوين Google Wallet لتطبيق ما.

GET /api/google/config?applicationCode=XXXXX-XXXXX

الاستجابة

الحقل	النوع	الوصف
hasServiceAccount	boolean	ما إذا كان مفتاح حساب الخدمة مكونًا.
issuerId	string	معرّف جهة الإصدار في Google Pay & Wallet Console المكون.
serviceAccountEmail	string	client_email لـ حساب الخدمة المكون.

القوالب

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

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

GET /api/google/templates/{filename} — يُرجع { "template": { ...pass object... } }.

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

كائن البطاقة (Pass object)

الحقل	النوع	الوصف
serialNumber	string	يتم تعيينه بواسطة الخادم عند الإنشاء؛ يحدد البطاقة.
generic / offer / loyalty / eventTicket / giftCard / flight / transit	object	نمط البطاقة. يجب تعيين واحد بالضبط. انظر كائنات النمط أدناه.
hexBackgroundColor	string	لون خلفية البطاقة، #rrggbb.
logoUrl	string	عنوان URL عام بصيغة HTTPS لصورة الشعار. مطلوب لبطاقات الولاء والنقل.
heroImageUrl	string	عنوان URL عام بصيغة HTTPS لصورة لافتة عريضة.
barcode	object	كائن الباركود المعروض على البطاقة.
textModules	array	وحدات النص المعروضة في عرض التفاصيل.
links	array	وحدات الروابط المعروضة في عرض التفاصيل.
expirationTime	string	وقت ISO 8601 عندما تقوم Google بإنهاء صلاحية البطاقة تلقائيًا. يعني الفراغ عدم وجود انتهاء صلاحية.
appLink	object	رابط التطبيق: زر دعوة لاتخاذ إجراء على واجهة البطاقة.
locations	array	المواقع التي تطلق إشعارًا جغرافيًا (بحد أقصى 10).
holdersPolicy	string	من يمكنه حفظ البطاقة: ONE_USER_ALL_DEVICES (افتراضي)، ONE_USER_ONE_DEVICE، أو MULTIPLE_HOLDERS.

كائن عام (Generic object)

الحقل	النوع	الوصف
cardTitle	string	مطلوب. اسم جهة الإصدار/البرنامج في أعلى البطاقة.
header	string	مطلوب. العنوان الرئيسي للبطاقة.
subheader	string	عنوان ثانوي.
cardFields	array	ما يصل إلى 6 وحدات نصية مثبتة على الواجهة (حتى 3 صفوف من 2).

كائن العرض (Offer object)

الحقل	النوع	الوصف
title	string	مطلوب. على سبيل المثال، خصم 20% على كل شيء.
provider	string	مطلوب. اسم التاجر.
details	string	تفاصيل العرض.
finePrint	string	الشروط والأحكام.
redemptionChannel	string	ONLINE، INSTORE، BOTH (افتراضي)، أو TEMPORARY_PRICE_REDUCTION.
issuerName	string	يظهر على أسطح “صادر عن” في Google؛ الافتراضي هو provider.

كائن الولاء (Loyalty object)

الحقل	النوع	الوصف
programName	string	مطلوب. يتطلب logoUrl على البطاقة.
accountName	string	اسم العضو المعروض على البطاقة.
accountId	string	معرّف العضو المعروض على البطاقة.
pointsLabel	string	على سبيل المثال، نقاط. يظهر فقط مع رصيد.
pointsBalance	string	رصيد النقاط.
rewardsTier	string	على سبيل المثال، ذهبي.
rewardsTierLabel	string	التسمية بجوار الفئة؛ الافتراضي هو الفئة.
issuerName	string	الافتراضي هو programName.

كائن تذكرة الفعالية (Event ticket object)

الحقل	النوع	الوصف
eventName	string	مطلوب.
venueName / venueAddress	string	تفاصيل المكان.
startDateTime / endDateTime	string	ISO 8601 مع إزاحة (على سبيل المثال، 2026-07-01T19:30:00+02:00).
ticketHolderName / ticketNumber / ticketType	string	تفاصيل حامل التذكرة والتذكرة.
section / row / seat / gate	string	تفاصيل المقاعد.
issuerName	string	الافتراضي هو eventName.

كائن بطاقة الهدايا (Gift card object)

الحقل	النوع	الوصف
merchantName	string	مطلوب.
cardNumber	string	مطلوب.
pin	string	رقم التعريف الشخصي للبطاقة.
balance	string	مبلغ عشري، على سبيل المثال 25.00. يتطلب balanceCurrency.
balanceCurrency	string	رمز عملة ISO 4217، على سبيل المثال USD.
issuerName	string	الافتراضي هو merchantName.

كائن الطيران (Flight object)

الحقل	النوع	الوصف
carrierIataCode	string	مطلوب. رمز IATA المكون من حرفين، على سبيل المثال LX.
airlineName	string	اسم عرض شركة الطيران.
flightNumber	string	مطلوب. أرقام فقط، على سبيل المثال 113.
originAirportCode / destinationAirportCode	string	مطلوب. رموز IATA المكونة من 3 أحرف.
originTerminal / originGate / destinationTerminal	string	تفاصيل المحطة والبوابة.
departureDateTime	string	مطلوب. الوقت المحلي لمطار المغادرة، ISO 8601 بدون إزاحة (على سبيل المثال، 2026-09-01T06:30:00).
boardingTime / arrivalDateTime	string	نفس التنسيق المحلي. arrivalDateTime هو الوقت المحلي للوجهة.
passengerName	string	مطلوب.
confirmationCode / seatNumber / seatClass / boardingGroup	string	تفاصيل الراكب.
issuerName	string	الافتراضي هو airlineName، ثم رمز شركة النقل.

كائن النقل (Transit object)

الحقل	النوع	الوصف
transitType	string	مطلوب. BUS، RAIL، TRAM، FERRY، أو OTHER.
transitOperatorName	string	مطلوب. يتطلب logoUrl على البطاقة.
passengerName	string	مطلوب.
ticketNumber	string	رقم التذكرة.
tripType	string	ONE_WAY (افتراضي) أو ROUND_TRIP.
legs	array	مرحلة أو أكثر من مراحل النقل بترتيب السفر.
issuerName	string	الافتراضي هو transitOperatorName.

كائن مرحلة النقل (Transit leg object)

الحقل	النوع	الوصف
originName / destinationName	string	مطلوب.
departureDateTime / arrivalDateTime	string	ISO 8601؛ الإزاحة اختيارية (الوقت المحلي عند حذفها).
platform / coach / seat	string	تفاصيل الصعود.
fareName	string	على سبيل المثال، Anytime Single.

كائن الباركود (Barcode object)

الحقل	النوع	الوصف
format	string	QR_CODE، PDF_417، AZTEC، CODE_128، EAN_13، وأنواع باركود Google Wallet الأخرى.
value	string	البيانات المشفرة في الباركود.
altText	string	النص المعروض أسفل الباركود.

كائن وحدة النص (Text module object)

الحقل	النوع	الوصف
id	string	معرّف الوحدة.
header	string	عنوان الوحدة.
body	string	نص الوحدة.

كائن وحدة الرابط (Link module object)

الحقل	النوع	الوصف
uri	string	عنوان URL للرابط الخارجي.
description	string	تسمية الرابط المعروضة في عرض التفاصيل.

كائن رابط التطبيق (App link object)

الحقل	النوع	الوصف
uri	string	عنوان URL للويب أو URI هدف الرابط العميق.
androidPackageName	string	اختياري. عند تعيينه، يفتح تطبيق Android.
description	string	وصف داخلي لـ URI الهدف (ليس تسمية زر مرئية)؛ الافتراضي هو URI.

كائن الموقع (Location object)

الحقل	النوع	الوصف
latitude	number	-90.0 إلى +90.0.
longitude	number	-180.0 إلى +180.0.

كائن سجل البطاقة (Pass record object)

يتم إرجاعه بواسطة نقاط نهاية السرد/الحصول.

الحقل	النوع	الوصف
serialNumber	string	الرقم التسلسلي للبطاقة.
objectId	string	معرّف كائن Google Wallet الكامل {issuerId}.{serialNumber}.
cardTitle	string	عنوان العرض/الترويسة للبطاقة.
header	string	عنوان عرض ثانوي.
userId	string	معرّف مستخدم Pushwoosh الذي صدرت له البطاقة.
createdAt / updatedAt	string	الطوابع الزمنية للإنشاء وآخر تحديث.
state	string	ACTIVE أو INACTIVE.
style	string	generic، offer، loyalty، eventTicket، giftCard، flight، أو transit.
pass	object	كائن البطاقة الكامل، للتحرير.