يتيح إشعار الشراء المُلغى لخادم Google Play الخاص بك إلغاء الوصول في اللحظة التي يصل فيها الاسترداد

لا يجب أن يكون الاسترداد على Google Play شيئًا تكتشفه لاحقًا في تقرير. يمكن لـ Google Play أن يدفع إلى خادمك إشعار شراء مُلغى في اللحظة التي يُلغى فيها الشراء، سواء طلب المشتري استردادًا ذاتي الخدمة، أو منحه أحد موظفي الدعم، أو فرض بنك سدادًا عكسيًا، أو استرددت الطلب بنفسك مع تفعيل علامة الإلغاء. الرسالة صغيرة جدًا، تسمّي الشراء المحدد بالضبط، وتحمل تعليمة واحدة، أعِد الاستحقاق، لأن المال قد ذهب بالفعل.

ما هو إشعار الشراء المُلغى في الحقيقة

إشعار الشراء المُلغى هو أحد أنواع Real-time Developer Notifications من Google Play، أو RTDN. إن RTDN قناة دفع. ينشر Google رسالة إلى موضوع Cloud Pub/Sub تملكه أنت، ويتلقاها خادمك الخلفي خلال لحظات من الحدث، بدلاً من اكتشافها في استطلاعك المجدول التالي. هذه هي الفكرة كلها من إشعار الشراء المُلغى مقارنةً بمسار السحب الأقدم: تعلم بالاسترداد وهو يحدث، لا بعد ساعات.

لا يزال مسار السحب موجودًا ولا يزال مهمًا. تتيح Voided Purchases API لخادمك أن يطلب، وفق جدولك الخاص، قائمة المشتريات التي أُلغيت خلال نطاق زمني. الاثنان متكاملان. يخبرك الإشعار في اللحظة التي تنقلب فيها حالة شراء واحد؛ وتتيح لك الـ API أن تُطابق بالجملة وأن تسدّ أي شيء كانت رسالة فائتة ستتركه خلفها.

يأتي محمولًا داخل Real-time Developer Notification

لا يصل إشعار الشراء المُلغى وحده أبدًا. إنه يقع داخل غلاف DeveloperNotification، ويُسلَّم ذلك الغلاف كسلسلة نصية واحدة مُرمَّزة بـ base64 في حقل data من رسالة Pub/Sub. يفكّ معالِجك ترميز تلك السلسلة إلى JSON قبل أن يتمكن من قراءة أي شيء. يسمّي الغلاف دائمًا التطبيق ووقت الحدث، ويحتوي على كائن إشعار واحد بالضبط من الخمسة التي يعرّفها Google. وهي متنافية، لذا فإن رسالة تحمل voidedPurchaseNotification لن تحمل معها أيضًا حدث اشتراك أو حدثًا لمرة واحدة.

الحقول الأربعة التي يحملها

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

productType يخبرك بما أُلغي

قيمة productType عدد صحيح صغير، وهي تحدّد أي مسارات الإلغاء لديك تسلك. إلغاء الاشتراك عليه أن يحلّ وصولًا مستمرًا؛ أما إلغاء الشراء لمرة واحدة فيزيل استحقاقًا واحدًا فقط.

refundType يخبرك بكم الذي عاد

يفصل refundType بين عكسٍ كاملٍ نظيف وعكسٍ جزئي. الحالة الجزئية ضيّقة. لا تظهر إلا عندما يكون شراء لمرة واحدة متعدد الكميات قد استُرد بعضُ كميته، لا كلها.

شغّله أولًا، وإلا فلن يصل أبدًا

لا تتدفق إشعارات الشراء المُلغى افتراضيًا. تُفعّل RTDN مرة واحدة، في Play Console، وتوجّهه إلى موضوع Pub/Sub تتحكم فيه. يقع المفتاح ضمن Monetize، ثم Monetization setup، في قسم Real-time developer notifications أعلى الصفحة. حدّد Enable real-time notifications، ثم الصق اسم موضوعك الكامل بالصيغة projects/{project_id}/topics/{topic_name}، واستخدم Send Test Message للتأكد من أن القناة تعمل قبل أن تثق بها.

مفتاح تبديل المحتوى هو حيث يفوّت الناس المشتريات المُلغاة. كلا الخيارين يشملها، لذا لا يمكنك عن طريق الخطأ استبعاد الاستردادات مع الإبقاء على الاشتراكات.

• تلقَّ إشعارات للاشتراكات وجميع المشتريات المُلغاة. تتلقى أحداث الاشتراك وكل عملية شراء مُلغاة، لكن ليس أحداث شراء المنتجات لمرة واحدة.
• تلقَّ جميع الإشعارات للاشتراكات والمنتجات لمرة واحدة. تتلقى ما سبق إضافةً إلى أحداث المنتجات لمرة واحدة مثل ONE_TIME_PRODUCT_PURCHASED و ONE_TIME_PRODUCT_CANCELED.

ما الذي يكلّفك إياه، بالمال

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

النزيف أسوأ ما يكون على الاشتراكات وأسوأ ما يكون على السداد العكسي. الاشتراك الذي تفشل في إلغائه يظل يكلّفك خدمته، شهرًا بعد شهر، لعميل لم يعد يدفع. والسداد العكسي هو أغلى أنواع الإلغاء. اعتبارًا من August 3, 2026، تنص وثائق Google على أن السداد العكسي يمرّر إلى المطوّر سعر الشراء مضافًا إليه رسوم البنك. غالبًا ما يكون إشعار الشراء المُلغى هو المكان الأول الذي تسمع فيه أنظمتك أن سدادًا عكسيًا قد اكتمل، لذا فإن معالِجًا يلغي على الفور هو ما يمنع بيعًا مفقودًا من أن يتحول إلى بيع مفقود إضافةً إلى أسابيع من الخدمة المجانية.

كيفية التعامل مع إشعار شراء مُلغى، خطوة بخطوة

تحقّق من الرسالة وأزل التكرار

• تأكّد من أن رسالة Pub/Sub جاءت من Google وتستهدف الموضوع الذي أعددته، ثم فُكّ ترميز حقل data بترميز base64 للحصول على JSON الخاص بـ DeveloperNotification.
• استخدم messageId الخاص بـ Pub/Sub لإسقاط التكرارات. يحذّر Google من أن الإشعار نفسه قد يُسلَّم أكثر من مرة، لذا عامِل إعادة التسليم كأمر طبيعي واجعل معالِجك عديم التأثير عند التكرار (idempotent).
• لا تُقرّ باستلام الرسالة إلا بعد أن تكون قد سجّلتها بأمان، حتى لا يفقد عطلٌ في منتصف المعالجة الحدثَ.

ابحث عن الشراء

• طابِق purchaseToken مع الشراء الذي خزّنته عندما منحت الاستحقاق لأول مرة. ارجع إلى orderId لعمليات بحث الدعم والمطابقة اليدوية.
• اقرأ productType لاختيار مسار إلغاء الاشتراك أو الشراء لمرة واحدة، واقرأ refundType للاختيار بين إلغاء كامل وإلغاء جزئي.

ألغِ وسجّل

• أزِل الاستحقاق. في حالة الاسترداد الكامل، اقطع الوصول إلى العنصر. في حالة الاسترداد الجزئي القائم على الكمية، خفّض الكمية الممنوحة بمقدار المبلغ المسترد واترك الباقي سليمًا.
• دوّن ما فعلته ومتى، مفهرسًا بـ purchaseToken و orderId. ذلك السجل هو ما يتيح لك الرد على تذكرة دعم لاحقًا، وما يتيح لـ Voided Purchases API أن تطابق بنظافة مقابل حالتك الخاصة.

أين يقع بين إشارات الاسترداد الأخرى

إشعار الشراء المُلغى إشعار، لا مفاوضة. يخبرك بنتيجة تقرّرت بالفعل. يجدر النظر إليه بجانب الإشارات التي يسهل الخلط بينه وبينها، لأن بعضها فقط يطلب في أي وقت روايتك للأمر.

الخلاصة التي يجب التمسّك بها بسيطة. عبر المتجرين هناك تدفّقا استرداد اثنان بالضبط يكون فيهما للمطوّر رأي، CONSUMPTION_REQUEST من Apple ومراجعة السداد العكسي في Google Play. وإشعار الشراء المُلغى ليس أيًّا منهما. بحلول وقت وصوله إليك، يكون القرار قد صار خلفك ولا يبقى في يديك سوى مدى سرعتك في الإلغاء.