REST Resource: purchases.subscriptions

منبع: خرید اشتراک

منبع 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)

زمان اعطای اشتراک، بر حسب میلی‌ثانیه از زمان Epoch.

expiryTimeMillis

string ( int64 format)

زمان انقضای اشتراک، بر حسب میلی‌ثانیه از زمان شروع اشتراک.

autoResumeTimeMillis

string ( int64 format)

زمانی که اشتراک به طور خودکار از سر گرفته می‌شود، بر حسب میلی‌ثانیه از زمان Epoch. فقط در صورتی نمایش داده می‌شود که کاربر درخواست توقف اشتراک را داده باشد.

autoRenewing

boolean

اینکه آیا اشتراک پس از رسیدن به زمان انقضای فعلی، به طور خودکار تمدید شود یا خیر.

priceCurrencyCode

string

کد ارزی ISO 4217 برای قیمت اشتراک. برای مثال، اگر قیمت به پوند استرلینگ بریتانیا مشخص شده باشد، کد ارزی priceCurrencyCode برابر با "GBP" است.

priceAmountMicros

string ( int64 format)

قیمت اشتراک، برای کشورهای مشمول مالیات، قیمت شامل مالیات نمی‌شود. برای کشورهای مشمول مالیات، قیمت شامل مالیات می‌شود. قیمت بر حسب واحدهای خرد بیان می‌شود، که در آن ۱,۰۰۰,۰۰۰ واحد خرد نشان دهنده یک واحد از ارز است. برای مثال، اگر قیمت اشتراک ۱.۹۹ یورو باشد، مقدار قیمت (priceAmountMicros) برابر با ۱۹۹۰۰۰۰ است.

introductoryPriceInfo

object ( IntroductoryPriceInfo )

اطلاعات قیمت اولیه اشتراک. این اطلاعات فقط زمانی نمایش داده می‌شود که اشتراک با قیمت اولیه خریداری شده باشد.

این فیلد نشان نمی‌دهد که اشتراک در حال حاضر در دوره قیمت مقدماتی است.

countryCode

string

کد کشور/منطقه‌ی صدور صورتحساب ISO 3166-1 alpha-2 مربوط به کاربر در زمان اعطای اشتراک.

developerPayload

string

رشته‌ای مشخص‌شده توسط توسعه‌دهنده که حاوی اطلاعات تکمیلی در مورد یک سفارش است.

paymentState

integer

وضعیت پرداخت اشتراک. مقادیر ممکن عبارتند از: ۰. پرداخت در انتظار ۱. پرداخت دریافت شد ۲. دوره آزمایشی رایگان ۳. ارتقاء/تنزل سطح در انتظار تعویق

برای اشتراک‌های لغو شده یا منقضی شده ارائه نمی‌شود.

cancelReason

integer

دلیل لغو اشتراک یا عدم تمدید خودکار آن. مقادیر ممکن عبارتند از: ۰. کاربر اشتراک را لغو کرده است. ۱. اشتراک توسط سیستم لغو شده است، مثلاً به دلیل مشکل صورتحساب. ۲. اشتراک با یک اشتراک جدید جایگزین شده است. ۳. اشتراک توسط توسعه‌دهنده لغو شده است.

userCancellationTimeMillis

string ( int64 format)

زمانی که اشتراک توسط کاربر لغو شده است، بر حسب میلی‌ثانیه از زمان شروع. فقط در صورتی نمایش داده می‌شود که cancelReason برابر با ۰ باشد.

cancelSurveyResult

object ( SubscriptionCancelSurveyResult )

اطلاعاتی که کاربر هنگام تکمیل فرآیند لغو اشتراک (نظرسنجی دلیل لغو) ارائه می‌دهد.

orderId

string

شناسه سفارش آخرین سفارش تکرارشونده مرتبط با خرید اشتراک. اگر اشتراک به دلیل رد پرداخت لغو شده باشد، این شناسه سفارش از سفارش رد پرداخت خواهد بود.

linkedPurchaseToken

string

توکن خرید خرید اولیه در صورتی که این اشتراک یکی از موارد زیر باشد: ۰. ثبت نام مجدد اشتراک لغو شده اما منقضی نشده ۱. ارتقا/تنزل از اشتراک قبلی

برای مثال، فرض کنید کاربری در ابتدا ثبت‌نام می‌کند و شما توکن خرید X را دریافت می‌کنید، سپس کاربر انصراف می‌دهد و (قبل از انقضای اشتراکش) مراحل انصراف را طی می‌کند و شما توکن خرید Y را دریافت می‌کنید، و در نهایت کاربر اشتراک خود را ارتقا می‌دهد و شما توکن خرید Z را دریافت می‌کنید. اگر این API را با توکن خرید Z فراخوانی کنید، این فیلد روی Y تنظیم می‌شود. اگر این API را با توکن خرید Y فراخوانی کنید، این فیلد روی X تنظیم می‌شود. اگر این API را با توکن خرید X فراخوانی کنید، این فیلد تنظیم نمی‌شود.

purchaseType

integer

نوع خرید اشتراک. این فیلد فقط در صورتی تنظیم می‌شود که این خرید با استفاده از جریان استاندارد پرداخت درون‌برنامه‌ای انجام نشده باشد. مقادیر ممکن عبارتند از: ۰. آزمایشی (یعنی از یک حساب آزمایشی لایسنس خریداری شده است) ۱. تبلیغاتی (یعنی با استفاده از کد تبلیغاتی خریداری شده است)

priceChange

object ( SubscriptionPriceChange )

آخرین اطلاعات تغییر قیمت موجود است. این اطلاعات فقط زمانی نمایش داده می‌شود که تغییر قیمت قریب‌الوقوعی برای اشتراک وجود داشته باشد و هنوز اعمال نشده باشد.

پس از تمدید اشتراک با قیمت جدید یا لغو اشتراک، هیچ گونه اطلاعات تغییر قیمت بازگردانده نخواهد شد.

profileName

string

نام پروفایل کاربر هنگام خرید اشتراک. فقط برای خریدهای انجام شده با «اشتراک با گوگل» ارائه می‌شود.

emailAddress

string

آدرس ایمیل کاربر هنگام خرید اشتراک. فقط برای خریدهایی که با «اشتراک با گوگل» انجام شده‌اند، ارائه می‌شود.

givenName

string

نام کاربری که هنگام خرید اشتراک استفاده شده است. فقط برای خریدهایی که با «اشتراک با گوگل» انجام شده باشد، نمایش داده می‌شود.

familyName

string

نام خانوادگی کاربر هنگام خرید اشتراک. فقط برای خریدهایی که با «اشتراک با گوگل» انجام شده باشد.

profileId

string

شناسه نمایه گوگل کاربر هنگام خرید اشتراک. فقط برای خریدهای انجام شده با «اشتراک با گوگل» ارائه می‌شود.

acknowledgementState

integer

وضعیت تأیید محصول اشتراک. مقادیر ممکن عبارتند از: ۰. هنوز تأیید نشده ۱. تأیید شده

externalAccountId

string

شناسه حساب کاربری در سرویس شخص ثالث. فقط در صورتی ارائه می‌شود که اتصال حساب به عنوان بخشی از جریان خرید اشتراک انجام شده باشد.

promotionType

integer

نوع تخفیف اعمال شده روی این خرید. این فیلد فقط در صورتی تنظیم می‌شود که هنگام خرید اشتراک، تخفیف اعمال شده باشد. مقادیر ممکن عبارتند از: ۰. کد یکبار مصرف ۱. کد تخفیف Vanity

promotionCode

string

کد تخفیف اعمال شده برای این خرید. این فیلد فقط در صورتی تنظیم می‌شود که هنگام خرید اشتراک، کد تخفیف Vanity اعمال شده باشد.

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 مشخص شده باشد.

اطلاعات قیمت مقدماتی

شامل اطلاعات قیمت مقدماتی برای اشتراک است.

نمایش JSON 
{
  "introductoryPriceCurrencyCode": string,
  "introductoryPriceAmountMicros": string,
  "introductoryPricePeriod": string,
  "introductoryPriceCycles": integer
}
فیلدها
introductoryPriceCurrencyCode

string

کد ارزی ISO 4217 برای قیمت اشتراک مقدماتی. برای مثال، اگر قیمت به پوند استرلینگ بریتانیا مشخص شده باشد، کد ارزی priceCurrencyCode برابر با "GBP" است.

introductoryPriceAmountMicros

string ( int64 format)

قیمت اولیه اشتراک، بدون احتساب مالیات. واحد پول همان priceCurrencyCode است. قیمت بر حسب واحدهای خرد بیان می‌شود، که در آن ۱,۰۰۰,۰۰۰ واحد خرد نشان دهنده یک واحد از ارز است. برای مثال، اگر قیمت اشتراک ۱.۹۹ یورو باشد، priceAmountMicros برابر با ۱۹۹۰۰۰۰ است.

introductoryPricePeriod

string

دوره قیمت مقدماتی، مشخص شده در قالب ISO 8601. مقادیر رایج (اما نه محدود به) عبارتند از: "P1W" (یک هفته)، "P1M" (یک ماه)، "P3M" (سه ماه)، "P6M" (شش ماه) و "P1Y" (یک سال).

introductoryPriceCycles

integer

تعداد دوره‌های صورتحساب برای ارائه قیمت‌گذاری مقدماتی.

اشتراکلغونظرسنجینتیجه

اطلاعاتی که کاربر هنگام تکمیل فرآیند لغو اشتراک (نظرسنجی دلیل لغو) ارائه می‌دهد.

نمایش JSON 
{
  "cancelSurveyReason": integer,
  "userInputCancelReason": string
}
فیلدها
cancelSurveyReason

integer

دلیل لغو انتخاب شده توسط کاربر در نظرسنجی. مقادیر ممکن عبارتند از: ۰. سایر ۱. من به اندازه کافی از این سرویس استفاده نمی‌کنم ۲. مشکلات فنی ۳. دلایل مربوط به هزینه ۴. من یک برنامه بهتر پیدا کردم

userInputCancelReason

string

دلیل لغو ورودی سفارشی از کاربر. فقط زمانی نمایش داده می‌شود که cancelReason برابر با ۰ باشد.

اشتراکقیمتتغییر

شامل اطلاعات تغییر قیمت برای یک اشتراک است که می‌تواند برای کنترل سفر کاربر برای تغییر قیمت در برنامه استفاده شود. این می‌تواند به شکل درخواست تأیید از کاربر یا تنظیم تجربه برای یک تبدیل موفق باشد.

نمایش JSON 
{
  "newPrice": {
    object (Price)
  },
  "state": integer
}
فیلدها
newPrice

object ( Price )

قیمت جدیدی که در صورت پذیرش تغییر قیمت توسط کاربر، اشتراک با آن تمدید خواهد شد.

state

integer

وضعیت فعلی تغییر قیمت. مقادیر ممکن عبارتند از: ۰. برجسته: وضعیت تغییر قیمت در حال بررسی و منتظر موافقت کاربر را نشان می‌دهد. در این وضعیت، می‌توانید به صورت اختیاری با استفاده از API درون برنامه‌ای از کاربر تأیید بگیرید. ۱. پذیرفته شده: وضعیت تغییر قیمت پذیرفته شده‌ای که اشتراک با آن تمدید می‌شود، مگر اینکه لغو شود. تغییر قیمت در تاریخ آینده، زمانی که اشتراک تمدید می‌شود، اعمال می‌شود. توجه داشته باشید که ممکن است این تغییر در زمان تمدید بعدی اشتراک اعمال نشود.

روش‌ها

acknowledge

 خرید اشتراک را تأیید می‌کند.

cancel

 خرید اشتراک کاربر را لغو می‌کند.

defer

 خرید اشتراک کاربر را تا زمان انقضای مشخصی در آینده به تعویق می‌اندازد.

get
(deprecated)

 منسوخ شده: به جای آن از purchases.subscriptionsv2.get استفاده کنید.

refund
(deprecated)

 منسوخ شده: به جای آن از orders.refund استفاده کنید.

revoke
(deprecated)

 منسوخ شده: به جای آن از purchases.subscriptionsv2.revoke استفاده کنید.

کدهای خطا

عملیات این منبع، کدهای خطای HTTP زیر را برمی‌گرداند:

کد خطا دلیل توضیحات وضوح تصویر
400 / 410 subscriptionExpired اشتراک منقضی شده است و عملیات درخواستی قابل انجام نیست. زمان انقضای اشتراک را بررسی کنید. این عملیات برای اشتراک‌های منقضی شده مجاز نیست.
400 subscriptionInvalidArgument یک استدلال نامعتبر در درخواست اشتراک ارائه شده است. مستندات API را بررسی کنید و مطمئن شوید که تمام فیلدهای مورد نیاز ارائه شده و به درستی قالب‌بندی شده‌اند.
400 invalidPurchaseState خرید در وضعیت معتبری برای انجام عملیات درخواستی نیست. برای مثال، ممکن است بخواهید خریدی را که قبلاً انجام شده است تأیید کنید یا اشتراکی را که فعال نیست لغو کنید. قبل از انجام عملیات، وضعیت فعلی منبع را با استفاده از Get API مربوطه بررسی کنید. مطمئن شوید که منبع در وضعیت مناسبی برای انجام عملیات قرار دارد.
400 invalidValue مقدار نامعتبری در درخواست ارائه شده است. این اغلب به عنوان یک توکن خرید ناقص یا نامعتبر برگردانده می‌شود. مقدار فیلد نامعتبر را در بدنه درخواست یا پارامترها بر اساس مرجع API اصلاح کنید.
400 prepaidSubscriptionNotSupported عملیات درخواستی برای اشتراک‌های پیش‌پرداخت پشتیبانی نمی‌شود. مطمئن شوید که عملیات مربوط به نوع اشتراک باشد. این خطا مختص روش‌هایی مانند لغو، تعویق، بازپرداخت یا لغو اشتراک است.
400 productNotOwnedByUser توکن خرید ارائه شده معتبر است، اما کاربر در حال حاضر مالک محصول نیست. این اتفاق می‌تواند در صورتی رخ دهد که خرید قبل از تأیید، بازپرداخت، لغو یا منقضی شده باشد. قبل از انجام عملیات، وضعیت فعلی منبع را با استفاده از Get API مربوطه بررسی کنید. مطمئن شوید که منبع در وضعیت مناسبی برای انجام عملیات قرار دارد.
400 purchaseTokenMismatch توکن خرید ارائه شده با خرید، نام بسته، شناسه اشتراک یا شناسه محصول مطابقت ندارد. تأیید کنید که تمام جزئیات موجود در درخواست صحیح و با یکدیگر مطابقت دارند.
400 required یک فیلد یا پارامتر الزامی در درخواست وجود ندارد. برای اطمینان از وجود تمام فیلدها و پارامترهای اجباری، به مستندات API مراجعه کنید.
400 unsupportedIabType این عملیات برای نوع پرداخت درون‌برنامه‌ای ارائه شده پشتیبانی نمی‌شود. مطمئن شوید که متد API با نوع آیتمی که مدیریت می‌شود سازگار است.
403 userInsufficientPermission کاربر مجوز کافی برای انجام عملیات درخواستی را ندارد. مطمئن شوید که کاربر احراز هویت شده مجوزهای لازم را در کنسول گوگل پلی دارد. برای جزئیات بیشتر به بخش «استفاده از حساب کاربری سرویس» مراجعه کنید.
404 notFound منبع مورد نظر یافت نشد. تأیید کنید که شناسه‌ها (مثلاً توکن خرید، نام بسته، شناسه محصول، شناسه اشتراک) صحیح باشند.
409 concurrentUpdate تلاشی برای به‌روزرسانی شیء‌ای که به‌طور همزمان به‌روزرسانی می‌شود، صورت گرفته است. درخواست را با backoff نمایی دوباره امتحان کنید. از تغییرات همزمان در همان منبع خودداری کنید.
410 purchaseTokenNoLongerValid توکن خرید به طور دائم نامعتبر است زیرا حساب کاربری مرتبط حذف شده است یا سابقه خرید دیگر وجود ندارد. استفاده از این توکن خرید را متوقف کنید.
410 subscriptionNoLongerAvailable خرید اشتراک دیگر برای استعلام در دسترس نیست زیرا مدت زیادی است که منقضی شده است. این خطا نشان می‌دهد که اشتراک بیش از ۶۰ روز منقضی شده است. دیگر نباید این اشتراک‌ها را درخواست کنید.
5xx Generic error خطای عمومی در سرور گوگل پلی. درخواست خود را دوباره امتحان کنید.

اگر مشکل همچنان ادامه داشت، با مدیر حساب Google Play خود تماس بگیرید یا درخواست پشتیبانی ارسال کنید. داشبورد وضعیت Play را برای هرگونه قطعی شناخته شده بررسی کنید.