REST Resource: purchases.subscriptions

المورد: SubscriptionPurchase

يشير مورد SubscriptionPurchase إلى حالة عملية شراء اشتراك المستخدم.

تمثيل JSON 
{
  "kind": string,
  "startTimeMillis": string,
  "expiryTimeMillis": string,
  "autoResumeTimeMillis": string,
  "autoRenewing": boolean,
  "priceCurrencyCode": string,
  "priceAmountMicros": string,
  "introductoryPriceInfo": {
    object (IntroductoryPriceInfo)
  },
  "countryCode": string,
  "developerPayload": string,
  "paymentState": integer,
  "cancelReason": integer,
  "userCancellationTimeMillis": string,
  "cancelSurveyResult": {
    object (SubscriptionCancelSurveyResult)
  },
  "orderId": string,
  "linkedPurchaseToken": string,
  "purchaseType": integer,
  "priceChange": {
    object (SubscriptionPriceChange)
  },
  "profileName": string,
  "emailAddress": string,
  "givenName": string,
  "familyName": string,
  "profileId": string,
  "acknowledgementState": integer,
  "externalAccountId": string,
  "promotionType": integer,
  "promotionCode": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string
}
الحقول
kind

string

يمثّل هذا النوع عنصر subscriptionPurchase في خدمة androidpublisher.
startTimeMillis

string (int64 format)

الوقت الذي تم فيه منح الاشتراك، بالمللي ثانية منذ بداية الحقبة
expiryTimeMillis

string (int64 format)

الوقت الذي ستنتهي فيه صلاحية الاشتراك، بالمللي ثانية منذ بداية الحقبة
autoResumeTimeMillis

string (int64 format)

الوقت الذي سيتم فيه استئناف الاشتراك تلقائيًا، بالمللي ثانية منذ بداية الحقبة يظهر هذا الحقل فقط إذا طلب المستخدم إيقاف الاشتراك مؤقتًا.
autoRenewing

boolean

تُستخدَم لتحديد ما إذا كان سيتم تجديد الاشتراك تلقائيًا عند انتهاء صلاحيته.
priceCurrencyCode

string

تمثّل هذه السمة رمز العملة وفقًا لمعيار ISO 4217 لسعر الاشتراك. على سبيل المثال، إذا تم تحديد السعر بالجنيه الإسترليني، ستكون قيمة priceCurrencyCode هي "GBP".
priceAmountMicros

string (int64 format)

سعر الاشتراك، وبالنسبة إلى البلدان التي لا تشمل الضرائب، لا يتضمّن السعر الضريبة. بالنسبة إلى البُلدان التي تضمِّن الضرائب في الأسعار، يكون السعر شاملاً الضرائب. يتم التعبير عن السعر بوحدات ميكرو، حيث يمثّل 1,000,000 وحدة ميكرو وحدة واحدة من العملة. على سبيل المثال، إذا كان سعر الاشتراك 1.99 يورو، تكون قيمة priceAmountMicros هي 1990000.
introductoryPriceInfo

object (IntroductoryPriceInfo)

معلومات السعر التمهيدي للاشتراك لا يظهر هذا الحقل إلا عند شراء الاشتراك بسعر تمهيدي.

لا يشير هذا الحقل إلى أنّ الاشتراك حاليًا في فترة السعر التمهيدي.
countryCode

string

تمثّل هذه السمة رمز البلد/المنطقة الذي يتم فيه تحصيل الرسوم من المستخدِم وفقًا لمعيار ISO 3166-1 alpha-2 في وقت منح الاشتراك.
developerPayload

string

سلسلة يحدّدها المطوّر وتحتوي على معلومات تكميلية حول طلب.
paymentState

integer

حالة الدفع للاشتراك القيم المحتمَلة هي: 0. الدفعة معلَّقة 1 تم استلام الدفعة 2. الفترة التجريبية المجانية 3 في انتظار الترقية أو الرجوع إلى إصدار سابق

لا يظهر هذا الحقل للاشتراكات الملغاة أو المنتهية الصلاحية.
cancelReason

integer

سبب إلغاء الاشتراك أو عدم تجديده تلقائيًا القيم المحتمَلة هي: 0. ألغى المستخدم الاشتراك 1. تم إلغاء الاشتراك من قِبل النظام، على سبيل المثال بسبب مشكلة في الفوترة 2. تم استبدال الاشتراك باشتراك جديد 3. ألغى المطوّر الاشتراك
userCancellationTimeMillis

string (int64 format)

الوقت الذي ألغى فيه المستخدم الاشتراك، بالمللي ثانية منذ بداية الحقبة يظهر هذا الحقل فقط إذا كانت قيمة cancelReason هي 0.
cancelSurveyResult

object (SubscriptionCancelSurveyResult)

المعلومات التي يقدّمها المستخدم عند إكمال عملية إلغاء الاشتراك (استطلاع حول سبب الإلغاء)
orderId

string

معرّف آخر طلب متكرّر مرتبط بشراء الاشتراك إذا تم إلغاء الاشتراك بسبب رفض الدفع، سيكون هذا هو معرّف الطلب من الطلب الذي تم رفض الدفع فيه.
linkedPurchaseToken

string

الرمز المميز لعملية الشراء الأصلية إذا كان هذا الاشتراك أحد ما يلي: 0. إعادة الاشتراك في اشتراك تم إلغاؤه ولكن لم تنتهِ صلاحيته 1. الترقية أو الرجوع إلى إصدار سابق من الاشتراك

على سبيل المثال، لنفترض أنّ أحد المستخدمين اشترك في البداية وتلقّيت الرمز المميز للشراء X، ثم ألغى المستخدم الاشتراك واتّبع خطوات إعادة الاشتراك (قبل انتهاء صلاحية اشتراكه) وتلقّيت الرمز المميز للشراء Y، وأخيرًا رقّى المستخدم اشتراكه وتلقّيت الرمز المميز للشراء Z. إذا طلبت بيانات من واجهة برمجة التطبيقات هذه باستخدام رمز الشراء Z، سيتم ضبط هذا الحقل على Y. إذا طلبت الوصول إلى واجهة برمجة التطبيقات هذه باستخدام رمز الشراء Y، سيتم ضبط هذا الحقل على القيمة X. إذا طلبت الوصول إلى واجهة برمجة التطبيقات هذه باستخدام الرمز المميز لعملية الشراء X، لن يتم ضبط هذا الحقل.
purchaseType

integer

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

object (SubscriptionPriceChange)

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

بعد تجديد الاشتراك بالسعر الجديد أو إلغائه، لن يتم عرض أي معلومات عن تغيير السعر.
profileName

string

اسم الملف الشخصي للمستخدم عند شراء الاشتراك يظهر هذا الحقل فقط لعمليات الشراء التي تتم باستخدام "الاشتراك من خلال Google".
emailAddress

string

عنوان البريد الإلكتروني للمستخدم عند شراء الاشتراك يظهر هذا الحقل فقط لعمليات الشراء التي تتم باستخدام "الاشتراك من خلال Google".
givenName

string

الاسم الأول للمستخدم عند شراء الاشتراك يظهر هذا الحقل فقط لعمليات الشراء التي تتم باستخدام "الاشتراك من خلال Google".
familyName

string

اسم عائلة المستخدم عند شراء الاشتراك يظهر هذا الحقل فقط لعمليات الشراء التي تتم باستخدام "الاشتراك من خلال Google".
profileId

string

معرّف الملف الشخصي للمستخدم على Google عند شراء الاشتراك يظهر هذا الحقل فقط لعمليات الشراء التي تتم باستخدام "الاشتراك من خلال Google".
acknowledgementState

integer

حالة تأكيد المنتج الذي يتضمّنه الاشتراك. القيم المحتمَلة هي: 0. لم يتمّ تأكيد استلامها بعد 1. مواضيع تمت الموافقة عليها
externalAccountId

string

معرّف حساب المستخدم في الخدمة التابعة لجهة خارجية يظهر هذا الحقل فقط إذا تم ربط الحساب كجزء من عملية شراء الاشتراك.
promotionType

integer

نوع العرض الترويجي الذي تم تطبيقه على عملية الشراء هذه لا يتم ضبط هذا الحقل إلا إذا تم تطبيق عرض ترويجي عند شراء الاشتراك. القيم المحتمَلة هي: 0. رمز صالح لمرة واحدة 1 الرمز المخصّص
promotionCode

string

الرمز الترويجي الذي تمّ تطبيقه على عملية الشراء هذه لا يتم ضبط هذا الحقل إلا إذا تم تطبيق عرض ترويجي باستخدام رمز مميّز عند شراء الاشتراك.
obfuscatedExternalAccountId

string

نسخة مشفّرة من المعرّف المرتبط بشكل فريد بحساب المستخدم في تطبيقك، وتظهر في عمليات الشراء التالية: * إذا تم ربط الحساب كجزء من عملية شراء الاشتراك. * تم تحديدها باستخدام https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedaccountid عند إجراء عملية الشراء.
obfuscatedExternalProfileId

string

هو إصدار مشوّش من رقم التعريف المرتبط بشكل فريد بالملف الشخصي للمستخدم في تطبيقك، ولا يظهر إلا إذا تم تحديده باستخدام https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedprofileid عند إجراء عملية الشراء.

IntroductoryPriceInfo

يحتوي على معلومات السعر التمهيدي للاشتراك.

تمثيل JSON 
{
  "introductoryPriceCurrencyCode": string,
  "introductoryPriceAmountMicros": string,
  "introductoryPricePeriod": string,
  "introductoryPriceCycles": integer
}
الحقول
introductoryPriceCurrencyCode

string

تمثّل هذه السمة رمز العملة وفقًا لمعيار ISO 4217 لسعر الاشتراك التمهيدي. على سبيل المثال، إذا تم تحديد السعر بالجنيه الإسترليني، ستكون قيمة priceCurrencyCode هي "GBP".
introductoryPriceAmountMicros

string (int64 format)

السعر التمهيدي للاشتراك، بدون احتساب الضريبة العملة هي نفسها priceCurrencyCode. يتم التعبير عن السعر بوحدات ميكرو، حيث يمثّل 1,000,000 وحدة ميكرو وحدة واحدة من العملة. على سبيل المثال، إذا كان سعر الاشتراك 1.99 يورو، تكون قيمة priceAmountMicros هي 1990000.
introductoryPricePeriod

string

تمثّل هذه السمة فترة السعر التمهيدي المحدّدة بتنسيق ISO 8601. تشمل القيم الشائعة (على سبيل المثال لا الحصر) "P1W" (أسبوع واحد) و"P1M" (شهر واحد) و"P3M" (ثلاثة أشهر) و"P6M" (ستة أشهر) و "P1Y" (سنة واحدة).
introductoryPriceCycles

integer

عدد المدد الزمنية للفوترة التي سيتم تقديم السعر التمهيدي فيها

SubscriptionCancelSurveyResult

المعلومات التي يقدّمها المستخدم عند إكمال عملية إلغاء الاشتراك (استطلاع حول سبب الإلغاء)

تمثيل JSON 
{
  "cancelSurveyReason": integer,
  "userInputCancelReason": string
}
الحقول
cancelSurveyReason

integer

سبب الإلغاء الذي اختاره المستخدم في الاستطلاع القيم المحتمَلة هي: 0. غير ذلك 1 لا أستفيد من هذه الخدمة بقدرٍ كافٍ 2. المشاكل الفنية 3. أسباب تتعلّق بالتكلفة 4. اكتشفت تطبيقًا أفضل.
userInputCancelReason

string

سبب إلغاء الإدخال المخصّص من المستخدم. يظهر هذا الحقل فقط عندما تكون قيمة cancelReason هي 0.

SubscriptionPriceChange

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

تمثيل JSON 
{
  "newPrice": {
    object (Price)
  },
  "state": integer
}
الحقول
newPrice

object (Price)

السعر الجديد الذي سيتم تجديد الاشتراك به إذا وافق المستخدم على تغيير السعر
state

integer

تمثّل هذه السمة الحالة الحالية لتغيير السعر. القيم المحتمَلة هي: 0. في انتظار الموافقة: حالة تغيير السعر المعلّق الذي ينتظر موافقة المستخدم. في هذه الحالة، يمكنك اختياريًا طلب تأكيد من المستخدم باستخدام In-App API. 1. مقبول: حالة تشير إلى أنّ تغيير السعر مقبول وسيتم تجديد الاشتراك بالسعر الجديد ما لم يتم إلغاؤه. يسري تغيير السعر في تاريخ مستقبلي عند تجديد الاشتراك. يُرجى العِلم أنّ التغيير قد لا يحدث عند تجديد الاشتراك في المرة القادمة.

الطُرق

acknowledge

 تُقرّ هذه السمة بعملية شراء اشتراك.

cancel

 تلغي هذه الطريقة عملية شراء اشتراك أحد المستخدمين.

defer

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

get
(deprecated)

 تم إيقاف هذه الطريقة نهائيًا، لذا يُرجى استخدام purchases.subscriptionsv2.get بدلاً منها.

refund
(deprecated)

 تم إيقاف هذه السمة نهائيًا، لذا يُرجى استخدام orders.refund بدلاً منها.

revoke
(deprecated)

 تم إيقاف هذه الطريقة نهائيًا، لذا يُرجى استخدام purchases.subscriptionsv2.revoke بدلاً منها.

رموز الخطأ

تعرض عمليات هذا المرجع رموز خطأ HTTP التالية:

رمز الخطأ السبب الدقة
5xx حدث خطأ عام في خادم Google Play. أعِد محاولة إرسال طلبك.

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

حدثت محاولة لتعديل عنصر قيد التعديل. على سبيل المثال، يتم الإقرار بعملية شراء من خلال استدعاء الطريقة acknowledgePurchase() في Play Billing Library واستدعاء الطريقة purchases.products.acknowledge في Play Developer API في الوقت نفسه.

 أعِد محاولة إرسال طلبك.
410 لم يعُد بإمكانك الاستعلام عن عملية شراء الاشتراك لأنّ صلاحيتها انتهت منذ فترة طويلة. يتم عرض هذا الخطأ عند الاستعلام عن اشتراك انتهت صلاحيته منذ أكثر من 60 يومًا. لن تحتاج إلى طلب هذه الاشتراكات بعد الآن.