واجهة برمجة تطبيقات 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": { ... } }، سجل بطاقة واحد pass record.

سرد البطاقات

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

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	معرف المُصدر (Issuer ID) المكوّن في 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	مرحلة نقل واحدة أو أكثر transit legs بترتيب السفر.
`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	كائن البطاقة الكامل، للتحرير.