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 التالية:

رمز الخطأ السبب الوصف الدقة
400 / 410 subscriptionExpired انتهت صلاحية الاشتراك ولا يمكن تنفيذ العملية المطلوبة. تحقَّق من وقت انتهاء صلاحية الاشتراك. لا يُسمح بهذه العملية في الاشتراكات المنتهية الصلاحية.
400 subscriptionInvalidArgument تم تقديم وسيطة غير صالحة في طلب الاشتراك. راجِع مستندات واجهة برمجة التطبيقات وتأكَّد من توفير جميع الحقول المطلوبة وتنسيقها بشكلٍ صحيح.
400 invalidPurchaseState عملية الشراء ليست في حالة صالحة لتنفيذ العملية المطلوبة. على سبيل المثال، قد تحاول تأكيد عملية شراء تم استهلاكها من قبل أو إلغاء اشتراك غير نشط. تحقَّق من الحالة الحالية للمورد باستخدام واجهة برمجة التطبيقات Get المناسبة قبل محاولة تنفيذ العملية. تأكَّد من أنّ المرجع في حالة مناسبة للإجراء.
400 invalidValue تم إدخال قيمة غير صالحة في الطلب. يتم عرض هذا الرمز غالبًا عند تقديم رمز مميّز غير صالح أو غير مكتمل لعملية الشراء. صحِّح قيمة الحقل غير الصالحة في نص الطلب أو المَعلمات استنادًا إلى مرجع واجهة برمجة التطبيقات.
400 prepaidSubscriptionNotSupported العملية المطلوبة غير متاحة للاشتراكات المدفوعة مسبقًا. تأكَّد من أنّ العملية تنطبق على نوع الاشتراك. هذا الخطأ خاص بطُرق مثل الإلغاء أو التأجيل أو ردّ الأموال أو الإبطال.
400 productNotOwnedByUser رمز الشراء المقدَّم صالح، ولكن المستخدم لا يملك المنتج حاليًا. يمكن أن يحدث ذلك إذا تم ردّ الأموال المدفوعة مقابل عملية الشراء أو تم إبطالها أو انتهت صلاحيتها قبل تأكيدها. تحقَّق من الحالة الحالية للمورد باستخدام واجهة برمجة التطبيقات Get المناسبة قبل محاولة تنفيذ العملية. تأكَّد من أنّ المرجع في حالة مناسبة للإجراء.
400 purchaseTokenMismatch لا يتطابق رمز الشراء المقدَّم مع عملية الشراء أو اسم الحزمة أو رقم تعريف الاشتراك أو رقم تعريف المنتج. تأكَّد من صحة جميع التفاصيل الواردة في الطلب ومن تطابقها مع بعضها البعض.
400 required لم يتم إدخال حقل أو مَعلمة مطلوبة في الطلب. راجِع مستندات واجهة برمجة التطبيقات للتأكّد من تضمين جميع الحقول والمَعلمات الإلزامية.
400 unsupportedIabType لا تتوفّر هذه العملية لنوع الفوترة داخل التطبيق المحدّد. تأكَّد من أنّ طريقة واجهة برمجة التطبيقات متوافقة مع نوع العنصر الذي تتم إدارته.
403 userInsufficientPermission لا يملك المستخدم الإذن الكافي لتنفيذ العملية المطلوبة. تأكَّد من أنّ المستخدم المصادَق عليه لديه الأذونات اللازمة في Google Play Console. لمزيد من التفاصيل، يُرجى الاطّلاع على استخدام حساب خدمة.
404 notFound تعذَّر العثور على المورد المطلوب. تأكَّد من صحة المعرّفات (مثل رمز الشراء أو اسم الحزمة أو معرّف المنتج أو معرّف الاشتراك).
409 concurrentUpdate تمت محاولة تعديل عنصر يتم تعديله في الوقت نفسه. أعِد محاولة إرسال الطلب باستخدام خوارزمية الرقود الأسي الثنائي. تجنَّب إجراء تعديلات متزامنة على المرجع نفسه.
410 purchaseTokenNoLongerValid رمز الشراء غير صالح نهائيًا لأنّه تم حذف حساب المستخدم المرتبط به أو لم يعُد سجلّ الشراء متوفّرًا. أوقِف استخدام رمز الشراء هذا.
410 subscriptionNoLongerAvailable لم يعُد بإمكانك الاستعلام عن عملية شراء الاشتراك لأنّ صلاحيتها انتهت منذ فترة طويلة. يشير هذا الخطأ إلى أنّ صلاحية الاشتراك انتهت منذ أكثر من 60 يومًا. لن تحتاج إلى طلب هذه الاشتراكات بعد الآن.
5xx Generic error حدث خطأ عام في خادم Google Play. أعِد محاولة إرسال طلبك.

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