واجهة برمجة التطبيقات لعمليات الشراء التي تم إلغاؤها
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
توفِّر واجهة برمجة التطبيقات Google Play Voided Purchases API قائمة بالطلبات التي
ترتبط بعمليات الشراء التي ألغى المستخدم عرضها يمكنك استخدام معلومات
من هذه القائمة لتطبيق نظام إبطال يمنع المستخدم من
الوصول إلى المنتجات من تلك الطلبات.
تنطبق واجهة برمجة التطبيقات هذه على الطلبات داخل التطبيق لمرة واحدة واشتراكات التطبيقات.
يمكن إلغاء عملية شراء بالطرق التالية:
يطلب المستخدم استرداد أموال طلبه.
يلغي المستخدم طلبه.
تم استرداد رسوم أحد الطلبات.
إلغاء الطلب أو ردّ أمواله
تلغي Google الطلب أو تردّ أمواله.
باستخدام واجهة برمجة التطبيقات هذه، تساهمون في توفير تجربة أكثر توازنًا وإنصافًا للجميع
من مستخدمي التطبيق، وخاصةً إذا كان تطبيقك لعبة
الحصول على إمكانية الوصول
للعمل مع واجهة 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
يشير الوقت بالمللي ثانية منذ حقبة يونكس إلى الأقدم
عملية شراء مُلغاة تريد الاطّلاع عليها في الردّ بشكل افتراضي،
تم ضبط startTime على 30 يومًا قبل.
لا يمكن أن تعرض واجهة برمجة التطبيقات سوى عمليات الشراء المُلغاة التي حدثت خلال الماضي.
30 يومًا. لا يتم تضمين عمليات الشراء الأقدم والمُلغاة في الرد، بغض النظر عن
للقيمة التي قدّمتها للسمة startTime.
endTime
الوقت بالمللي ثانية منذ حقبة يونكس لأول مرة
عملية شراء مُلغاة تريد الاطّلاع عليها في الردّ بشكل افتراضي،
تم ضبط endTime على الوقت الحالي.
maxResults
الحد الأقصى لعدد عمليات الشراء المُلغاة والتي تظهر في كل ردّ من
بشكلٍ افتراضي، تكون هذه القيمة 1000. تجدر الإشارة إلى أنّ الحد الأقصى لقيمة هذه المَعلمة هو
أيضًا 1000.
رمز مميز
رمز مميز للمتابعة من رد سابق، مما يسمح لك بعرض المزيد
نتائجك.
كتابة
نوع عمليات الشراء المُلغاة والتي تظهر في كل ردّ في حال الضبط على 0،
لن يتم إرجاع سوى عمليات الشراء داخل التطبيق المُلغاة. في حال ضبط القيمة على 1، سيتم إلغاء كليهما داخل التطبيق.
سيتم إرجاع عمليات الشراء التي تم إجراؤها وعمليات شراء الاشتراكات المُلغاة. القيمة التلقائية هي
0.
includeQuantityBasedPartialRefund
لتحديد ما إذا كان سيتم تضمين عمليات الشراء المُلغاة لعمليات رد الأموال الجزئية المستندة إلى الكمية
التي لا تنطبق إلا على عمليات الشراء بكميات متعدّدة إذا كانت true،
يمكن إرجاع المزيد من المشتريات المُلغاة والمُلغاة من خلال "voidedQuantity".
تشير إلى كمية عملية ردّ الأموال الجزئية المستندة إلى الكمية. تشير رسالة الأشكال البيانية
والقيمة التلقائية هي false.
الاستجابة هي سلسلة JSON تحتوي على قائمة بعمليات الشراء المُلغاة. إذا كان هناك
نتائج أكثر من الرقم المحدّد في معلَمة طلب maxResults
، يتضمن الرد قيمة nextPageToken، والتي يمكنك تمريرها إلى
طلب لاحق لعرض مزيد من النتائج. تعرض النتيجة الأولى في القائمة
أقدم عملية شراء ملغاة
تضبط واجهة Voided Purchases API الحصص التالية على أساس كل حزمة:
6000 طلب بحث في اليوم. (يبدأ اليوم وينتهي في منتصف الليل بتوقيت المحيط الهادئ.)
30 طلب بحث خلال أي فترة تبلغ 30 ثانية.
إرشادات الطلبات الأولية
أثناء طلب البيانات من واجهة برمجة التطبيقات الأولي، يمكنك جلب جميع البيانات المتاحة
تطبيقك. قد تستنفد هذه العملية حصتك اليومية، على الرغم من أنّه غير مرجّح. إلى
للحصول على بيانات عمليات الشراء المُلغاة بطريقة أكثر أمانًا واتساقًا، اتّبِع الخطوات التالية
أفضل الممارسات:
استخدِم القيمة التلقائية للمَعلمة maxResults. بهذه الطريقة، إذا كنت تستخدم
حصة طلبات البحث بأكملها ليوم واحد، فيمكنك استرداد تفاصيل 6,000,000
عمليات الشراء المُلغاة.
إذا كان الردّ يتضمن قيمة لـ nextPageToken، يجب تعيين هذه القيمة إلى
معلَمة token أثناء طلبك التالي.
أفضل الممارسات
عند استخدام واجهة برمجة التطبيقات هذه في تطبيقك، تذكّر أنّ هناك العديد من
أسباب إلغاء عملية الشراء وأنه لا يوجد حل واحد يفي بالغرض
جميع الحالات. يجب أن تضع المستخدمين في الاعتبار عند تصميم الإبطال
والسياسات والاستراتيجيات. ولإجراء ذلك، يمكنك تطبيق الممارسات المقترَحة التالية:
يمكنك استخدام واجهة برمجة التطبيقات هذه باعتبارها أحد العناصر المتعددة في استراتيجية شاملة للتعامل مع
والسلوك غير المرغوب فيه. عادةً ما يكون إلغاء الوصول إلى المنتجات داخل التطبيق أكثر فعالية
عند دمجها مع تطبيق يقدم أسعارًا معقولة لعمليات الشراء داخل التطبيق
تصميم التطبيق الذي يثني السلوك غير المرغوب فيه، وقاعدة المستخدمين القوية التي
الثقافة التي ترفض هذا السلوك، بالإضافة إلى الدعم
سريع الاستجابة والفعّال
بشكل أفضل.
عليك إدارة سياسة الإبطال الخاصة بك بشكل موحّد لضمان العدالة لجميع المستخدمين.
ننصحك بإنشاء سياسة مرحلية عند التعامل مع السلوك غير المرغوب فيه. بالنسبة
على سبيل المثال، ابدأ بتحذيرات داخل التطبيق بشأن المخالفات المبكرة، ثم صعِّد
الردود مع استمرار السلوك غير المرغوب فيه للمستخدم. كحلٍ أخير، يمكنك
تمنع المستخدم من التفاعل مع تطبيقك على الإطلاق.
عند طرح سياسة الإبطال، وفي كل مرة تقوم فيها بتحديثها، استخدم
الخاصة بتطبيقك لإبلاغ المستخدمين بالتغييرات. منح المستخدمين
لفهم هذه التغييرات بوضوح قبل دخولها حيز التنفيذ في تطبيقك.
تحلَّ بالشفافية مع المستخدمين وأخبِرهم متى اتخذت إجراءً، مثل
إبطال وصولهم إلى منتج داخل التطبيق. من الناحية المثالية، يجب أن يكون المستخدمون قادرين على
والنزاع على قراراتك، وينبغي التعامل مع هذه النزاعات بإنصاف.
مراقبة نماذج الملاحظات والمنتديات لفهم ما يدفع المستخدمين إلى
السلوك بطرق غير مرغوب فيها وكيفية تنفيذه لهذا السلوك. اتّخاذ إجراءات استنادًا إلى هذه
الأفكار كخط دفاعي أول.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Google Play Voided Purchases API lets you track voided in-app purchases and subscriptions to implement revocation systems, ensuring a fair user experience.\u003c/p\u003e\n"],["\u003cp\u003eVoided purchases include user refunds, cancellations, chargebacks, and cancellations/refunds by the developer or Google.\u003c/p\u003e\n"],["\u003cp\u003eAccess the API using OAuth or a service account with "View financial reports" permission and make requests with your package name and authorization token.\u003c/p\u003e\n"],["\u003cp\u003eTailor your revocation policies to be fair and transparent, escalating responses as needed while informing users of any actions taken.\u003c/p\u003e\n"],["\u003cp\u003eCombine this API with other strategies and real-time notifications for a comprehensive approach to managing user entitlements and addressing undesirable behaviors.\u003c/p\u003e\n"]]],["The Google Play Voided Purchases API lists orders linked to user-voided purchases, including refunds, cancellations, chargebacks, and developer/Google-initiated voids. This API helps developers implement revocation systems to prevent access to products from voided orders. To use it, developers need \"View financial reports\" permission and can use a `GET` method to request voided purchases, filtering by time, quantity, or type. It has quotas, provides best practices and advises using it along side RTDN.\n"],null,["# Voided Purchases API\n\nThe Google Play Voided Purchases API provides a list of orders that\nare associated with purchases that a user has voided. You can use information\nfrom this list to implement a revocation system that prevents the user from\naccessing products from those orders.\n\nThis API applies to one-time in-app orders and App Subscriptions.\n\nA purchase can be voided in the following ways:\n\n- The user requests a refund for their order.\n- The user cancels their order.\n- An order is charged back.\n- Developer cancels or refunds order.\n\n | **Note:** only revoked orders will be shown in the Voided Purchases API. If a developer refunds a purchase without setting the revoke option, the order will not be returned by the API.\n- Google cancels or refunds order.\n\nBy using this API, you help create a more balanced and fair experience for all\nof your app's users, particularly if your app is a game.\n| **Note:** Unlike other order-related data sources, the Voided Purchases API includes purchases that are charged back by payment processors. Therefore, you might see inconsistencies between the information from this API and information from other order-related data sources.\n| **Note:** The Voided Purchases API returns voided purchases only when they need to be revoked. Developers can use this API as an indication for when to take additional action on their end. However, some purchases may be refunded with reason that the purchase was never acknowledged by the developer, and therefore may not exist in the developer's records.\n\nGaining Access\n--------------\n\nTo work with the Voided Purchases API, you need to have permission to view\nfinancial information. You provide authorization using an OAuth client or a\nservice account. If you're using a service account, enable the \"View financial\nreports\" permission within this account.\n\nTo learn more about gaining authorized access to Google Play Developer APIs, see\nthe following guides:\n\n- [Setting Up API Access Clients](/android-publisher/getting_started#setting_up_api_access_clients)\n- [Add developer account users \\& manage permissions](https://support.google.com/googleplay/android-developer/answer/2528691)\n\nViewing Voided Purchases\n------------------------\n\nUse the `GET` method to request a list of voided purchases. In your request,\ninclude the fully-qualified package name for your app---such as\n`com.google.android.apps.maps`---and the authorization token you\nreceived when [gaining access](#gaining_access) to the API. \n\n```\nGET https://www.googleapis.com/androidpublisher/v3/applications/\nyour_package_name/purchases/voidedpurchases?access_token=your_auth_token\n```\n\nYou can also include the following parameters in your request, each of which is\noptional:\n\nstartTime\n\n: The time, in milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), of the oldest\n voided purchase that you want to see in the response. By default,\n `startTime` is set to 30 days ago.\n\n The API can only show voided purchases that have occurred during the past\n 30 days. Older voided purchases are not included in the response, regardless\n of the value that you've provided for `startTime`.\n | **Note:** The voided purchases within the response are filtered based on the time at which a given record is seen as voided by the API, not by the value of `voidedTimeMillis` returned in the response.\n\nendTime\n\n: The time, in milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), of the newest\n voided purchase of that you want to see in the response. By default,\n `endTime` is set to the current time.\n\n | **Note:** The voided purchases within the response are filtered based on the time at which a given record is seen as voided by the API, not by the value of `voidedTimeMillis` returned in the response.\n\nmaxResults\n: The maximum number of voided purchases that appear in each response. By\n default, this value is 1000. Note that the maximum value for this parameter is\n also 1000.\n\ntoken\n: A continuation token from a previous response, allowing you to view more\n results.\n\ntype\n\n: The type of voided purchases that appear in each response. If set to 0,\n only voided in-app purchases will be returned. If set to 1, both voided in-app\n purchases and voided subscription purchases will be returned. Default value is\n 0.\n\n | **Note:** Before requesting to receive voided subscription purchases, you must switch to use orderId in the response which uniquely identifies one-time purchases and subscriptions. Otherwise, you will receive multiple subscription orders with the same PurchaseToken.\n\nincludeQuantityBasedPartialRefund\n\n: Whether to include voided purchases of quantity-based partial refunds,\n which are applicable only to multi-quantity purchases. If `true`,\n additional voided purchases may be returned with `voidedQuantity`\n that indicates the refund quantity of a quantity-based partial refund. The\n default value is `false`.\n\n | **Note:** When the remaining total quantity of a purchase is refunded, the corresponding voided purchase won't have `voidedQuantity`, which serves as a signal that the purchase has been fully refunded. For example, if a purchase of quantity 10 is refunded 3 times with quantities 2, 3 and 5, there will be 3 voided purchases. The first two voided purchases will have a `voidedQuantity` of 2 and 3, while the third voided purchase *will not* have a `voidedQuantity`.\n\nThe response is a JSON string that contains a list of voided purchases. If there\nare more results than the number specified in the `maxResults` request parameter\n, the response includes a `nextPageToken` value, which you can pass into a\nsubsequent request to view more results. The first result in the list shows the\noldest voided purchase. \n\n```\n{\n \"tokenPagination\": {\n \"nextPageToken\": \"next_page_token\"\n },\n \"voidedPurchases\": [\n {\n \"kind\": \"androidpublisher#voidedPurchase\",\n \"purchaseToken\": \"some_purchase_token\",\n \"purchaseTimeMillis\": \"1468825200000\",\n \"voidedTimeMillis\": \"1469430000000\",\n \"orderId\": \"some_order_id\",\n \"voidedSource\": \"0\",\n \"voidedReason\": \"4\"\n },\n {\n \"kind\": \"androidpublisher#voidedPurchase\",\n \"purchaseToken\": \"some_other_purchase_token\",\n \"purchaseTimeMillis\": \"1468825100000\",\n \"voidedTimeMillis\": \"1470034800000\",\n \"orderId\": \"some_other_order_id\",\n \"voidedSource\": \"2\",\n \"voidedReason\": \"5\"\n },\n ]\n}\n```\n\nQuotas\n------\n\nThe Voided Purchases API sets the following quotas on a per-package basis:\n\n- 6000 queries per day. (The day begins and ends at midnight Pacific Time.)\n- 30 queries during any 30-second period.\n\n### Guidelines for initial requests\n\nDuring your initial API request, you may want to fetch all available data for\nyour app. Although unlikely, this process could exhaust your daily quota. To\nobtain voided purchases data in a safer, more consistent manner, follow these\nbest practices:\n\n- Use the default value for the `maxResults` parameter. That way, if you use your entire query quota for a day, you can retrieve the details of 6,000,000 voided purchases.\n- If a response includes a value for `nextPageToken`, assign this value to the `token` parameter during your next request.\n\nBest Practices\n--------------\n\n| **Note:** In addition to using this API, developers should integrate with [Real-time developer notifications (RTDN)](https://developer.android.com/google/play/billing/getting-ready#configure-rtdn). With RTDN, you receive notifications from Google whenever there is a change in a user's entitlement within your app, including when a user [voids a purchase](https://developer.android.com/google/play/billing/rtdn-reference#voided-purchase).\n\nWhen using this API in your app, remember that there are many\nreasons to void a purchase and that there is no single solution that works in\nall cases. You should keep your users in mind when designing your revocation\npolicies and strategies. To do so, you can apply these recommended practices:\n\n- Use this API as one of many elements in a comprehensive strategy to address undesired behavior. Revoking access to in-app products is usually more effective when combined with an app that has reasonable prices for in-app purchases, an app design that discourages undesirable behavior, a strong user base whose culture rejects such behavior, and responsive and efficient user support channels.\n- Administer your revocation policy uniformly to ensure fairness for all users.\n- Consider creating a staged policy when addressing undesired behavior. For example, start with in-app warnings for early offenses, then escalate your responses as a user's undesired behavior continues. As a last resort, you can prevent a user from interacting with your app at all.\n- When you introduce a revocation policy, and each time you update it, use your app's outreach channels to inform your users about the changes. Give your users time to clearly understand these changes before they take effect in your app.\n- Be transparent to your users and inform them whenever you take action, such as revoking their access to an in-app product. Ideally, users should be able to dispute your decisions, and such disputes should be treated fairly.\n- Monitor feedback forms and community forums to understand what drives users to behave in undesirable ways and how they carry out such behavior. Act on these insights as a first line of defense."]]
