إذا قرأت عن CONSUMPTION_REQUEST في أي مكان خلال السنوات القليلة الماضية، فعلى الأرجح رأيت قائمة من اثني عشر حقلاً: عمر الحساب، وإجمالي المبالغ المشتراة بالدولار، ووقت اللعب، والمنصة، وغير ذلك.
تلك القائمة تخص النسخة الأقدم من نقطة النهاية (endpoint). أما النسخة الحالية من Apple فتقبل خمسة حقول، ثلاثة منها مطلوبة، وتغطي أنواع منتجات أكثر من الأصلية. ولا تزال كثير من عمليات التكامل القائمة مبنية على الشكل القديم.
لذا إليك شرحاً لما يعنيه هذا الإشعار فعلاً، وما الذي تريده Apple منك اليوم، وكيف تبني مسار استجابة يصمد.
أهم النقاط
• CONSUMPTION_REQUEST هو إشعار يطلب معلومات أثناء مراجعة طلب استرداد. ليس استرداداً وليس قراراً.
• Apple هي من تتخذ قرار الاسترداد. واستجابتك مجرد مدخل واحد فيه.
• نقطة النهاية الحالية تقبل خمسة حقول، ثلاثة منها مطلوبة، وتغطي جميع أنواع المنتجات.
• موافقة العميل إلزامية. ترفض Apple الطلبات التي لم تُؤكَّد فيها الموافقة.
• تطلب Apple الاستجابة في غضون 12 ساعة من الإشعار.
• توجد نسختان من نقطة النهاية. تحقق من النسخة التي يستدعيها تكاملك.
ما هو Apple CONSUMPTION_REQUEST؟
Apple CONSUMPTION_REQUEST هو إشعار من App Store Server Notifications يُخبر خادمك بأن عميلاً طلب استرداد أمواله ويدعوك إلى إرسال معلومات الاستهلاك المتعلقة بعملية الشراء تلك. يصل إلى عنوان URL للإشعارات الذي قمت بتهيئته، ويحمل المعاملة التي يتعلق بها، ويمنحك نافذة زمنية محدودة للاستجابة.
إنه ليس إشعاراً بالاسترداد. فلم يُتخذ أي قرار عند وصوله؛ Apple في منتصف تقييم الطلب وتجمع السياق قبل أن تنهيه. وبالنسبة للمطوّر، المعنى العملي محدود: مهمة وصلت للتو إلى الواجهة الخلفية لديك، ولها موعد نهائي، وتحتاج إلى بيانات لا تملكها إلا أنظمتك.
لماذا ترسل Apple إشعار CONSUMPTION_REQUEST؟
لأن Apple لا ترى سوى نصف المعاملة.
تعرف Apple ما الذي تم شراؤه، ومتى، ومن أي حساب، وكيف يبدو سجل ذلك الحساب. لكنها لا تستطيع أن ترى ما يجري داخل تطبيقك: هل أُضيفت العملات إلى الرصيد، وهل نجح فتح المحتوى، وكم استخدم العميل قبل أن يطلب استرداد أمواله.
و«الاستهلاك» هنا يعني إلى أي مدى استفاد العميل مما اشتراه. فاشتراك استُخدم يومياً لثلاثة أسابيع وآخر لم يُفتح قط يبدوان متطابقين في نظر Apple. لكنهما لا يبدوان متطابقين في نظرك.
من المهم أن تكون الحدود واضحة. لا توافق Apple ولا ترفض بناءً على رقم الاستهلاك وحده. فالمعلومات تغذي قراراً يوازن بين عدة عوامل، ونسبة الاستهلاك المرتفعة ليست زر رفض.
كيف يعمل Apple CONSUMPTION_REQUEST؟
التسلسل يبدو كالتالي:
يبدأ العميل طلب استرداد
↓
تبدأ Apple مراجعة الاسترداد
↓
يصل CONSUMPTION_REQUEST إلى نقطة نهاية الإشعارات لديك
↓
تتحقق من الإشعار وتحدد المعاملة
↓
تتحقق من الموافقة وتجمع بيانات الاستخدام
↓
ترسل معلومات الاستهلاك، حيث تُستوفى المتطلبات
↓
توازن Apple المعلومات
↓
تتخذ Apple قرار الاسترداد
↓
تتابع حالة المعاملة الناتجة
تحفّظ واحد. تصف وثائق Apple الحالية هذا الإشعار في سياق طلبات الاسترداد عبر جميع أنواع المنتجات، وهو نطاق أوسع مما أشارت إليه الوثائق الأقدم. لكن Apple لا تنشر أي ضمان بوصول إشعار في كل حالة، لذا ابنِ معالجاً يستجيب عند وصول طلب بدلاً من منطق يفترض وصوله دائماً.
ما المعلومات التي تطلب Apple من المطوّرين تقديمها؟
تقبل نقطة النهاية الحالية من Apple Send Consumption Information خمسة حقول. ثلاثة منها مطلوبة واثنان اختياريان.
الحقل | مطلوب | المعنى |
customerConsented | نعم | يجب أن يكون true. وإلا ترفض Apple الطلب. |
deliveryStatus | نعم | هل سلّم تطبيقك عملية شراء تعمل بشكل صحيح، وإن لم يكن، فلماذا. |
sampleContentProvided | نعم | هل كان بوسع العميل تجربة المحتوى قبل الشراء. |
consumptionPercentage | لا | مقدار ما تم استهلاكه، بوحدات milliunits (نسبة 50% تعادل 50000). |
refundPreference | لا | منح كامل، أو رفض، أو استرداد تناسبي — تفضيلك أنت، وليس قراراً. |
قاعدتا تحقق توقعان الكثيرين في الخطأ. إذا كانت حالة التسليم أي شيء غير «تم التسليم»، فيجب أن تكون نسبة الاستهلاك صفراً وإلا يفشل الطلب. كما أن الـ milliunits ليست نسباً مئوية؛ فنصف الاستهلاك هو 50000.
تفضيل الاسترداد هو الجزء الأحدث والأكثر عرضة لسوء الفهم. يمكنك أن تخبر Apple بأنك تفضّل منح الاسترداد كاملاً، أو رفضه، أو منحه تناسبياً، وتوازن Apple ذلك مع كل شيء آخر. وقد تختلف النتيجة. وإذا تمت الموافقة على استرداد تناسبي، فإن الجزء الملغى يعود في حمولة المعاملة، لذا يجب أن يتعامل منطق الاستحقاقات لديك مع الإلغاء الجزئي.
فرق النسخ الذي يستحق التحقق
توثّق Apple نسختين من نقطة النهاية هذه، ومن السهل إساءة قراءة التسمية. Send Consumption Information V1 هي النسخة الأقدم، بجسم الطلب المكوّن من اثني عشر حقلاً الذي ما زالت تصفه معظم مقالات الأطراف الثالثة. وتوجّه ملاحظة Apple نفسها في تلك الصفحة عمليات الشراء داخل التطبيق القياسية إلى نقطة النهاية الحالية بدلاً منها، وتحصر V1 في عمليات الشراء التي تستخدم Advanced Commerce API.
| نقطة النهاية الحالية | نقطة النهاية V1 |
حقول الطلب | 5 (3 مطلوبة) | 12 |
أنواع المنتجات | جميع الأنواع الأربعة | المنتجات الاستهلاكية والاشتراكات المتجددة تلقائياً |
استخدمها لـ | عمليات الشراء داخل التطبيق القياسية | عمليات الشراء عبر Advanced Commerce API |
إذا كان تكاملك يسبق هذا التغيير، فابدأ من هنا.
ما هي معلومات الاستهلاك؟
معلومات الاستهلاك هي البيانات التي ترسلها إلى Apple لوصف ما حدث لعملية الشراء بعد أن أتمّها العميل: هل تم تسليمها، وهل كان بوسعه تجربتها مسبقاً، وكم استخدم منها.
وهي مهمة لأنها الجزء الوحيد من الصورة الذي لا تستطيع Apple رؤيته. فبالنسبة لتطبيق اشتراكات، تصف ما إذا كان العميل قد استخدم الخدمة بعد الشراء. وبالنسبة لمنتج استهلاكي، كم أُنفق من الرصيد. وبالنسبة لمنتج غير استهلاكي، هل نجح فتح المحتوى.
الكلمة المهمة هنا هي الدقة. هذه بيانات حصلت على موافقة لمشاركتها، مستخرجة من سجلاتك. وليست حجة تبنيها، وتحريفها نحو نتيجة مفضّلة يحمل مخاطرة حقيقية دون مكسب يُعتمد عليه.
كيف ينبغي للمطوّرين الاستجابة لـ CONSUMPTION_REQUEST؟
تسع خطوات، ومعظم العمل يقع قبل وصول أي طلب.
1. استلام الإشعار
تصل الطلبات إلى عنوان URL الذي حددته لـ App Store Server Notifications V2. وتغطي وثائق App Store Server Notifications من Apple الإعداد وبنية الحمولة. ونقطة النهاية المهيأة بشكل خاطئ تعني أن الطلب لا يصلك أبداً، وبصمت.
2. التحقق من صحة الإشعار
الحمولات موقّعة. تحقق منها مقابل سلسلة شهادات Apple وأكّد معرّف الحزمة (bundle ID) قبل التصرف بناءً على أي شيء بداخلها.
3. تحديد المعاملة المرتبطة
استخرج معرّفات المعاملة من الحمولة المفكوكة وطابقها مع سجلات الشراء لديك. فبدون سجل مخزَّن، لا بحث، ولا أساس لوصف الاستهلاك.
4. التحقق مما إذا كانت الموافقة تسمح بالاستجابة
تشترط Apple موافقة صالحة من العميل قبل مشاركة بياناته، والحصول عليها مسؤوليتك. ولا يحمل الإشعار أي علامة موافقة، لذا عليك أن تعرف ذلك من سجلاتك. وتوضح Apple أيضاً أن مطالبة App Tracking Transparency ليست الآلية المناسبة لذلك؛ فهي موافقة منفصلة تُجمع داخل تطبيقك. وإذا لم تكن الموافقة موجودة، فإرشادات Apple هي عدم الاستجابة. ويغطي مقالنا عن appAccountToken والدفاع عن استردادات Apple جانب التحديد الذي يجعل هذا البحث ممكناً.
5. جمع معلومات الاستهلاك ذات الصلة
اقرأ حالة التسليم والاستخدام من أنظمتك. إذا كنت تتابع رصيداً استهلاكياً، فالرقم موجود بالفعل. وإذا فشل فتح المحتوى، فسجلاتك تعرف ذلك.
6. إعداد الاستجابة المدعومة
جمّع الحقول المطلوبة، وأضف الاختيارية حيث تملك قيماً حقيقية، وتحقق من قواعد التحقق أولاً.
7. الإرسال ضمن نافذة Apple الزمنية
أرسل طلب PUT إلى نقطة نهاية الاستهلاك باستخدام معرّف المعاملة الأصلي من الإشعار.
8. تسجيل الاستجابة
خزّن ما أرسلته، ومتى، وما الذي عاد إليك. فالإرسال الذي فشل في التحقق يبدو مطابقاً للإرسال الناجح ما لم تكن قد سجّلت النتيجة.
9. متابعة نتيجة الاسترداد النهائية
ترسل Apple القرار كإشعار منفصل. سجّله مقابل المعاملة والعميل.
كم من الوقت لدى المطوّرين للاستجابة؟
تطلب وثائق Apple الحالية الاستجابة في غضون 12 ساعة من استلام الإشعار.
تبدو 12 ساعة سخية حتى تفكر في أوقات وصول الإشعارات. فالطلبات تأتي ليلاً، وفي عطلات نهاية الأسبوع، وخلال الإجازات، والعدّاد لا يتوقف. وطلب يصل في الحادية عشرة ليلاً يوم الجمعة تكون مهلته قد انتهت قبل يوم الاثنين.
لا تذكر Apple أن تفويت النافذة الزمنية يعني تلقائياً منح الاسترداد، ومن الخطأ الادعاء بذلك. ما يعنيه أبسط من ذلك: لم تقدّم معلومات كانت Apple مستعدة لأخذها بعين الاعتبار، ويُتخذ القرار من دونها.
ماذا يحدث بعد استجابة المطوّر؟
تُدخل Apple المعلومات في مراجعتها وتقرر. وسترى النتيجة كإشعار: مُنح، أو رُفض، أو عُكس لاحقاً إذا ألغت Apple استرداداً كانت قد وافقت عليه.
من هنا يصبح العمل عملك. ألغِ الاستحقاق عند منح الاسترداد، وأعده عند العكس، وتعامل مع الحالة التناسبية حيث يعود جزء فقط من المعاملة.
وتحتاج حالة الاشتراك إلى اهتمام أيضاً، لأن الفترة المستردة تنهي الاشتراك عادةً بدلاً من إبقائه سارياً، ويجب أن يصل الاسترداد إلى سجلات الإيرادات للفترة الصحيحة.
يستحق هذا التقسيم أن يُقال بوضوح: أنت تقدّم المعلومات، وApple تقرر، ثم تُبقي أنظمتك متزامنة مع النتيجة. ثلاث مسؤوليات منفصلة، ولا يعود منها إلى Apple إلا الوسطى.
لماذا تُعد المعالجة اليدوية لـ CONSUMPTION_REQUEST صعبة؟
كل قيد في سير العمل هذا يعمل ضد الشخص الذي يقوم به.
تصل الإشعارات على مدار الساعة. والنافذة الزمنية 12 ساعة. وكل طلب يحتاج إلى فحص توقيع، وبحث عن معاملة، ومطابقة مستخدم، وفحص موافقة، وحساب استخدام، واستدعاء API موثَّق، ونتيجة مسجَّلة. لا شيء من ذلك صعب. لكنه كله محدود بالوقت ومتكرر، ولا ينتج شيئاً ملحوظاً حين يسير على ما يرام.
ويزيد الحجم الأمر سوءاً: عدة تطبيقات، وبيانات المعاملات في نظام وبيانات الاستخدام في آخر، وسجلات استجابة تصبح متقطعة، وحالة استحقاقات تنجرف عن حالة المعاملات دون أن يُشار إليها. لا يعني ذلك أن المعالجة اليدوية تكلفك المال دائماً، لكن الخطر حقيقي ويتراكم بصمت.
هل يمكن أتمتة Apple CONSUMPTION_REQUEST؟
نعم، وشكل سير العمل نفسه يدعو إلى ذلك، إذ إن كل خطوة تقريباً حتمية.
يمكن للأتمتة مراقبة الإشعارات والتحقق منها، وتحديد طلبات الاستهلاك على وجه الخصوص، وربط المعاملات بالحسابات، وتجميع الاستجابة من سجلاتك، ومتابعة النافذة الزمنية، والإرسال، وتسجيل النتيجة، وتوثيق القرار، ودفع تحديثات الاستحقاقات.
ما لا تستطيعه هو التأثير على قرار Apple. لا توجد أداة تغيّر ذلك، وأي منتج يوحي بغير ذلك يصف العملية وصفاً خاطئاً. ما تغيّره الأتمتة هو ما إذا كان جانبك يُنفَّذ باستمرار وضمن النافذة الزمنية.
كيف يساعد RefundSensor المطوّرين في التعامل مع سير عمل استردادات Apple
إدارة استردادات App Store هي الفئة التي ينتمي إليها هذا العمل. ويغطي RefundSensor جانب المطوّر منه: مراقبة سير العمل المتعلق باستردادات Apple، ومعالجة مسار الاستجابة المدعوم لـ CONSUMPTION_REQUEST، والاحتفاظ بأحداث الاسترداد ونتائجه في مكان واحد بدلاً من تشتتها عبر لوحات التحكم وجداول البيانات.
عملياً، تُرسل الاستجابات ضمن النافذة الزمنية دون أن يراقب أحد الإشعارات، وتبقى سجلات الاسترداد دقيقة مع نمو الحجم. لا يمنع الاستردادات ولا يمكنه ضمان أي قرار معيّن من Apple. لكنه يقلّل المراقبة اليدوية والخطوات المفوّتة.
أين تُوثَّق هذه القواعد
ثلاثة مصادر من Apple تدعم كل ما سبق. اقرأها مباشرةً، وعُد إليها بانتظام — فقد تغيّر هذا المجال مؤخراً والمصادر الثانوية تتأخر عنه.
Send Consumption Information — نقطة النهاية الحالية. شرط الموافقة، ونافذة الـ 12 ساعة، وجسم الطلب المكوّن من خمسة حقول، وأنواع المنتجات التي تغطيها. ابنِ على هذه لعمليات الشراء داخل التطبيق القياسية.
Send Consumption Information V1 — نقطة النهاية الأقدم بجسم الطلب المكوّن من اثني عشر حقلاً. مفيدة لمعرفة النسخة التي يعمل عليها تكاملك، وللفرق التي تستخدم Advanced Commerce API.
App Store Server Notifications — كيف تصل الإشعارات إلى الواجهة الخلفية لديك، وصيغة الحمولة الموقّعة، وأنواع الإشعارات بما فيها CONSUMPTION_REQUEST ونتائج الاسترداد.
إذا كان هذا لا يزال يُعالَج يدوياً
نافذة 12 ساعة وإشعارات تصل في الثالثة صباحاً لا تتوافقان مع عملية تعتمد على شخص يتفقد لوحة تحكم.
إذا كان هذا هو وضع فريقك، فإن RefundSensor يتولى جانب المطوّر من سير العمل هذا: مراقبة الإشعارات، وإعداد الاستجابات وإرسالها ضمن النافذة الزمنية، ومتابعة النتائج حتى سجلات الاستحقاقات لديك.
الأسئلة الشائعة
إشعار من App Store Server Notifications يُخبر خادمك بأن عميلاً طلب استرداد أمواله وبأن Apple تدعوك إلى إرسال معلومات الاستهلاك المتعلقة بعملية الشراء. إنه ليس إشعاراً بالاسترداد وليس قراراً. تقرر Apple بشكل منفصل، مستخدمةً استجابتك كمدخل واحد من بين عدة عوامل.
لأن Apple لا تستطيع أن ترى ما يجري داخل تطبيقك. فهي تعرف المعاملة وسجل الحساب، لكنها لا تعرف ما إذا كان المحتوى قد سُلِّم، أو ما إذا كان يعمل، أو كم استخدمه العميل. هذا السياق موجود في أنظمتك، وتطلبه Apple قبل إنهاء مراجعتها.
يطلب العميل استرداداً، وتبدأ Apple المراجعة، ويصل إشعار إلى نقطة النهاية التي هيّأتها. تتحقق منه، وتحدد المعاملة، وتؤكد الموافقة، وتجمع بيانات الاستخدام، وترسل معلومات الاستهلاك ضمن النافذة الزمنية. توازن Apple المعلومات، وتقرر، وترسل النتيجة كإشعار منفصل.
في نقطة النهاية الحالية، خمسة حقول. ثلاثة مطلوبة: موافقة العميل، وحالة التسليم، وما إذا تم توفير محتوى تجريبي. واثنان اختياريان: مقدار ما استُهلك من عملية الشراء، ونتيجة الاسترداد التي تفضّلها. أما نقطة النهاية الأقدم V1 فكانت تطلب اثني عشر حقلاً، ولهذا تصف المقالات الأقدم قائمة أطول بكثير.
تصف وثائق Apple الحالية الإشعار في سياق طلبات الاسترداد عبر جميع أنواع المنتجات، وهو نطاق أوسع مما أشارت إليه الوثائق الأقدم. لكن Apple لا تنشر ضماناً لكل حالة، لذا ابنِ معالجاً يستجيب عند وصول طلب بدلاً من منطق يعتمد على وصوله دائماً.
تطلب وثائق Apple الاستجابة في غضون 12 ساعة من الإشعار. وتصل الطلبات في أي ساعة، بما في ذلك عطلات نهاية الأسبوع، لذا فهذه هي الخطوة الأكثر عرضة للتفويت في أي عملية يدوية. راجع صفحة Apple لمعرفة المتطلب الحالي بدلاً من الاعتماد على تكامل أقدم.
يمكنك أن تُثري القرار بالمعلومات، لا أن تتحكم به. فبيانات الاستهلاك الدقيقة تمنح Apple سياقاً لا تملكه بغير ذلك، وتتيح لك نقطة النهاية الحالية التعبير عن تفضيلك للاسترداد. توازن Apple كلاهما مع عوامل أخرى وقد تقرر خلاف ذلك. ولا توجد آلية تسمح للمطوّر بالموافقة على استرداد أو رفضه.
نعم. فالتحقق من الإشعارات، وتحديد المعاملات، وفحص حالة الموافقة، وتجميع البيانات من السجلات، والالتزام بالنافذة الزمنية، والإرسال، وتسجيل النتائج كلها خطوات حتمية. أما ما يبقى بشرياً فهو تصميم تدفق الموافقة في تطبيقك وتحديد سياسة تفضيل الاسترداد لديك.
