واجهة برمجة التطبيقات لعمليات الشراء التي تم إلغاؤها

توفّر واجهة برمجة التطبيقات Voided Purchases API في Google Play قائمة بالطلبات المرتبطة بعمليات شراء ألغاها المستخدم. يمكنك استخدام المعلومات الواردة في هذه القائمة لتنفيذ نظام إبطال يمنع المستخدم من الوصول إلى المنتجات من تلك الطلبات.

تنطبق واجهة برمجة التطبيقات هذه على الطلبات لمرة واحدة داخل التطبيق والاشتراكات في التطبيقات.

يمكن إبطال عملية شراء بالطرق التالية:

• يطلب المستخدم استرداد الأموال المدفوعة مقابل طلبه.
• يلغي المستخدم طلبه.
• تمت المطالبة بردّ الأموال المدفوعة في طلب.

• يلغي المطوّر الطلب أو يردّ الأموال المدفوعة.

  ملاحظة: لن يتم عرض سوى الطلبات التي تم إبطالها في Voided Purchases API. إذا ردّ المطوّر الأموال المدفوعة مقابل عملية شراء بدون ضبط خيار الإلغاء، لن تعرض واجهة برمجة التطبيقات الطلب.

• تلغي Google الطلب أو تردّ الأموال المدفوعة.

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

ملاحظة: على عكس مصادر بيانات أخرى ذات صلة بالطلبات، يتضمّن Voided Purchases API عمليات الشراء التي تم ردّ أموالها من خلال الجهات المسؤولة عن معالجة الدفعات. لذلك، قد تلاحظ اختلافات بين المعلومات الواردة من واجهة برمجة التطبيقات هذه والمعلومات الواردة من مصادر بيانات أخرى ذات صلة بالطلبات.

ملاحظة: تعرض واجهة برمجة التطبيقات Voided Purchases API عمليات الشراء الملغاة فقط عندما يكون من الضروري إبطالها. يمكن للمطوّرين استخدام واجهة برمجة التطبيقات هذه كمؤشر لتحديد الوقت المناسب لاتّخاذ إجراءات إضافية من جانبهم. ومع ذلك، قد يتم ردّ أموال بعض عمليات الشراء بسبب عدم إقرار المطوّر بها، وبالتالي قد لا تكون مسجّلة في سجلاته.

الحصول على إذن الوصول

لاستخدام واجهة برمجة التطبيقات Voided Purchases API، يجب أن يكون لديك إذن بعرض المعلومات المالية. يمكنك تقديم التفويض باستخدام عميل OAuth أو حساب خدمة. إذا كنت تستخدم حساب خدمة، فعِّل الإذن "عرض التقارير المالية" ضمن هذا الحساب.

لمزيد من المعلومات حول الحصول على إذن بالوصول إلى واجهات Google Play Developer API، يُرجى الاطّلاع على الأدلة التالية:

• إعداد برامج واجهة برمجة التطبيقات
• إضافة مستخدمي حساب المطوِّر وإدارة الأذونات

الاطّلاع على عمليات الشراء الملغاة

استخدِم طريقة GET لطلب قائمة بعمليات الشراء الملغاة. في طلبك، أدرِج اسم الحزمة المؤهَّل بالكامل لتطبيقك، مثل com.google.android.apps.maps، ورمز الموافقة المميز الذي تلقّيته عند الحصول على إذن الوصول إلى واجهة برمجة التطبيقات.

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

يمكنك أيضًا تضمين المَعلمات الاختيارية التالية في طلبك:

startTime

الوقت، بالملّي ثانية منذ حقبة Unix، لأقدم عملية شراء تم إبطالها تريد الاطّلاع عليها في الرد. يتم تلقائيًا ضبط startTime على 30 يومًا مضت.

لا يمكن لواجهة برمجة التطبيقات عرض عمليات الشراء الملغاة التي حدثت خلال آخر 30 يومًا إلا. لا يتم تضمين عمليات الشراء القديمة التي تم إبطالها في الرد، بغض النظر عن القيمة التي قدّمتها لـ startTime.

ملاحظة: يتم فلترة عمليات الشراء الملغاة ضمن الردّ استنادًا إلى الوقت الذي تعتبر فيه واجهة برمجة التطبيقات سجلاً معيّنًا ملغيًا، وليس استنادًا إلى قيمة voidedTimeMillis التي يتم عرضها في الردّ.

endTime

الوقت، بالملّي ثانية منذ حقبة Unix، لآخر عملية شراء تم إبطالها وتريد الاطّلاع عليها في الرد. يتم ضبط endTime تلقائيًا على الوقت الحالي.

ملاحظة: يتم فلترة عمليات الشراء الملغاة ضمن الردّ استنادًا إلى الوقت الذي رصدت فيه واجهة برمجة التطبيقات إلغاء سجلّ معيّن، وليس استنادًا إلى قيمة voidedTimeMillis التي تم عرضها في الردّ.

maxResults

الحدّ الأقصى لعدد عمليات الشراء الملغاة التي تظهر في كل ردّ. تكون هذه القيمة تلقائيًا 1000. يُرجى العِلم أنّ الحد الأقصى لقيمة هذه المَعلمة هو 1000 أيضًا.

رمز مميز

رمز مميز للمتابعة من ردّ سابق، ما يتيح لك الاطّلاع على المزيد من النتائج.

النوع

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

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

includeQuantityBasedPartialRefund

تحديد ما إذا كان سيتم تضمين عمليات الشراء الملغاة التي تم ردّ جزء من الأموال المدفوعة مقابلها استنادًا إلى الكمية، والتي تنطبق فقط على عمليات الشراء بكميات متعدّدة إذا true، قد يتم إرجاع عمليات شراء إضافية ملغاة مع voidedQuantity الذي يشير إلى كمية ردّ الأموال في عملية ردّ جزء من الأموال استنادًا إلى الكمية. القيمة التلقائية هي false.

ملاحظة: عند ردّ الأموال مقابل إجمالي الكمية المتبقية من عملية شراء، لن تتضمّن عملية الشراء الملغاة voidedQuantity، ما يشير إلى أنّه تم ردّ الأموال بالكامل مقابل عملية الشراء. على سبيل المثال، إذا تم ردّ الأموال المدفوعة مقابل عملية شراء بكمية 10 مرات 3 مرات بكميات 2 و3 و5، سيتم إلغاء 3 عمليات شراء. سيكون للعمليتَين الملغيتَين الأوليَين قيمة voidedQuantity تبلغ 2 و3، بينما لن يكون لعملية الشراء الملغاة الثالثة قيمة voidedQuantity.

الاستجابة هي سلسلة JSON تحتوي على قائمة بعمليات الشراء الملغاة. إذا كان عدد النتائج أكبر من العدد المحدّد في مَعلمة الطلب maxResults، ستتضمّن الاستجابة القيمة nextPageToken، والتي يمكنك إدخالها في طلب لاحق لعرض المزيد من النتائج. تعرض النتيجة الأولى في القائمة أقدم عملية شراء تم إبطالها.

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

الحصص

تفرض واجهة Voided Purchases API الحصص التالية على مستوى كل حزمة:

• ‫6000 طلب في اليوم (يبدأ اليوم وينتهي في منتصف الليل بتوقيت المحيط الهادئ).
• 30 طلب بحث خلال أي فترة مدتها 30 ثانية

إرشادات بشأن الطلبات الأولية

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

• استخدِم القيمة التلقائية للمَعلمة maxResults. بهذه الطريقة، إذا استخدمت حصة طلبات البحث بالكامل ليوم واحد، يمكنك استرداد تفاصيل 6,000,000 عملية شراء تم إبطالها.
• إذا تضمّنت الاستجابة قيمة nextPageToken، عليك تعيين هذه القيمة للمَعلمة token خلال طلبك التالي.

أفضل الممارسات

ملاحظة: بالإضافة إلى استخدام واجهة برمجة التطبيقات هذه، على المطوّرين الدمج مع الإشعارات في الوقت الفعلي الخاصة بالمطوّرين (RTDN). باستخدام الإشعارات في الوقت الفعلي الخاصة بالمطوّرين، ستتلقّى إشعارات من Google عند حدوث أي تغيير في إذن الوصول الممنوح للمستخدم داخل تطبيقك، بما في ذلك عندما يلغي المستخدم عملية شراء.

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

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