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

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

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

عنوان 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 ساعة.

الاستجابة

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

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

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

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

الاستجابة

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

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

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

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 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... } }.

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

كائن البطاقة

الحقل	النوع	الوصف
`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`.

الكائن العام

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

كائن العرض

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

كائن الولاء

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

كائن تذكرة الفعالية

الحقل	النوع	الوصف
`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`.

كائن بطاقة الهدايا

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

كائن الرحلة الجوية

الحقل	النوع	الوصف
`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`، ثم رمز شركة الطيران.

كائن النقل

الحقل	النوع	الوصف
`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`.

كائن مرحلة النقل

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

كائن الباركود

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

كائن وحدة النص

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

كائن وحدة الرابط

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

كائن رابط التطبيق

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

كائن الموقع

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

كائن سجل البطاقة

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

الحقل	النوع	الوصف
`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	كائن البطاقة الكامل، للتحرير.