REST Resource: purchases.subscriptions

משאב: SubscriptionPurchase

הוצא משימוש: במקומו צריך להשתמש ב-SubscriptionPurchaseV2. משאב 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)

הזמן שבו תוקף המינוי יפוג, באלפיות השנייה מאז ראשית זמן יוניקס (Epoch).
autoResumeTimeMillis

string (int64 format)

השעה שבה המינוי יחודש אוטומטית, באלפיות שנייה מאז ראשית זמן יוניקס (Unix epoch). הפרמטר הזה מופיע רק אם המשתמש ביקש להשהות את המינוי.
autoRenewing

boolean

האם המינוי יחודש אוטומטית כשהוא יגיע למועד התפוגה הנוכחי שלו.
priceCurrencyCode

string

קוד המטבע של מחיר המינוי לפי תקן ISO 4217. לדוגמה, אם המחיר מצוין בלירות שטרלינג בריטיות, הערך של priceCurrencyCode הוא GBP.
priceAmountMicros

string (int64 format)

מחיר המינוי. במדינות שבהן המחירים לא כוללים מס, המחיר לא כולל מס. במדינות שבהן המחירים כוללים מס, המחיר כולל מס. המחיר מבוטא ביחידות מיקרו, כאשר מיליון יחידות מיקרו מייצגות יחידה אחת של המטבע. לדוגמה, אם מחיר המינוי הוא 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)

השעה שבה המשתמש ביטל את המינוי, באלפיות השנייה מאז תקופת ה-Epoch. המאפיין הזה מוצג רק אם cancelReason הוא 0.
cancelSurveyResult

object (SubscriptionCancelSurveyResult)

מידע שהמשתמש מספק כשהוא משלים את תהליך ביטול המינוי (סקר סיבות לביטול).
orderId

string

מזהה ההזמנה של ההזמנה החוזרת האחרונה שמשויכת לרכישת המינוי. אם המינוי בוטל כי התשלום נדחה, זה יהיה מזהה ההזמנה של ההזמנה שבה התשלום נדחה.
linkedPurchaseToken

string

טוקן הרכישה של הרכישה המקורית אם המינוי הזה הוא אחד מהסוגים הבאים: 0. הרשמה מחדש למינוי שבוטל אבל לא פג תוקפו 1. שדרוג או שדרוג לאחור ממינוי קודם

לדוגמה, נניח שמשתמש נרשם למינוי ואתם מקבלים את אסימון הרכישה X. לאחר מכן המשתמש מבטל את המינוי ועובר את תהליך ההרשמה מחדש (לפני שהמינוי שלו פג) ואתם מקבלים את אסימון הרכישה Y. לבסוף, המשתמש משדרג את המינוי ואתם מקבלים את אסימון הרכישה Z. אם תשלחו קריאה ל-API הזה עם טוקן הרכישה Z, השדה הזה יוגדר ל-Y. אם תשלחו קריאה ל-API הזה עם אסימון הרכישה Y, השדה הזה יוגדר לערך X. אם תפעילו את ה-API הזה עם טוקן הרכישה 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.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. אושר: מצב של שינוי מחיר שאושר. המינוי יתחדש במחיר החדש אלא אם הוא יבוטל. שינוי המחיר ייכנס לתוקף בתאריך עתידי, כשהמינוי יתחדש. שימו לב: יכול להיות שהשינוי לא יתרחש בחידוש המינוי הבא.

Methods

acknowledge

 אישור רכישת מינוי.

cancel
(deprecated)

 הוצא משימוש: במקום זאת, צריך להשתמש ב-purchases.subscriptionsv2.cancel.

defer
(deprecated)

 הוצאה משימוש: במקום זאת, צריך להשתמש ב-purchases.subscriptionsv2.defer.

קודי שגיאה

הפעולות של המשאב הזה מחזירות את קודי שגיאות ה-HTTP הבאים:

קוד שגיאה סיבה תיאור רזולוציה
400 / 410 subscriptionExpired המינוי פג ואי אפשר לבצע את הפעולה המבוקשת. בודקים את תאריך התפוגה של המינוי. אי אפשר לבצע את הפעולה הזו במינויים שפג תוקפם.
400 subscriptionInvalidArgument בבקשה למינוי סופק ארגומנט לא תקין. כדאי לעיין במסמכי התיעוד בנושא API ולוודא שציינתם את המידע בכל שדות החובה ושהזנתם את הנתונים בפורמט הנכון.
400 invalidPurchaseState הרכישה לא במצב שמאפשר לבצע את הפעולה המבוקשת. לדוגמה, יכול להיות שאתם מנסים לאשר רכישה שכבר נעשה בה שימוש או לבטל מינוי שלא פעיל. לפני שמנסים לבצע את הפעולה, כדאי לבדוק את המצב הנוכחי של המשאב באמצעות ה-API המתאים מסוג Get. מוודאים שהמשאב נמצא במצב המתאים לפעולה.
400 invalidValue צוין ערך לא חוקי בבקשה. השגיאה הזו מוחזרת בדרך כלל אם טוקן הרכישה פגום או לא תקין. מתקנים את הערך הלא תקין של השדה בגוף הבקשה או בפרמטרים על סמך הפניה ל-API.
400 prepaidSubscriptionNotSupported הפעולה שביקשת לא נתמכת במינויים בתשלום מראש. מוודאים שהפעולה רלוונטית לסוג המינוי. השגיאה הזו ספציפית לשיטות כמו Cancel,‏ Defer,‏ Refund או Revoke.
400 productNotOwnedByUser אסימון הרכישה שסופק תקין, אבל המשתמש לא מחזיק כרגע במוצר. מצב כזה יכול לקרות אם הרכישה בוטלה, בוטלה או שפג תוקפה לפני האישור. לפני שמנסים לבצע את הפעולה, כדאי לבדוק את המצב הנוכחי של המשאב באמצעות ה-API המתאים מסוג Get. מוודאים שהמשאב נמצא במצב המתאים לפעולה.
400 purchaseTokenMismatch אסימון הרכישה שסיפקת לא תואם לרכישה, לשם החבילה, למזהה המינוי או למזהה המוצר. מוודאים שכל הפרטים בבקשה נכונים ותואמים זה לזה.
400 required חסר שדה או פרמטר חובה בבקשה. כדאי לעיין במסמכי התיעוד בנושא API כדי לוודא שכללתם את כל שדות החובה והפרמטרים הנדרשים.
400 unsupportedIabType הפעולה לא נתמכת בסוג החיוב מתוך האפליקציה שצוין. מוודאים ששיטת ה-API תואמת לסוג הפריט שמנוהל.
403 userInsufficientPermission למשתמש אין מספיק הרשאות לביצוע הפעולה המבוקשת. מוודאים שלמשתמש המאומת יש את ההרשאות הנדרשות ב-Google Play Console. פרטים נוספים מופיעים במאמר בנושא שימוש בחשבון שירות.
404 notFound לא הצלחנו למצוא את המשאב המבוקש. מוודאים שהמזהים (למשל, טוקן הרכישה, שם החבילה, מזהה המוצר, מזהה המינוי) נכונים.
409 concurrentUpdate היה ניסיון לעדכן אובייקט שנמצא בתהליך עדכון בו-זמני. מנסים לשלוח שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). מומלץ להימנע משינויים בו-זמניים באותו משאב.
410 purchaseTokenNoLongerValid טוקן הרכישה לא תקף באופן קבוע כי חשבון המשתמש המשויך נמחק או שרשומת הרכישה כבר לא קיימת. להפסיק את השימוש באסימון הרכישה הזה.
410 subscriptionNoLongerAvailable אי אפשר יותר לשלוח שאילתה לגבי רכישת המינוי כי תוקף המינוי פג לפני זמן רב מדי. השגיאה הזו מציינת שתוקף המינוי פג לפני יותר מ-60 יום. לא כדאי יותר לשלוח שאילתות לגבי המינויים האלה.
5xx Generic error שגיאה כללית בשרת Google Play. אפשר לנסות לשלוח את הבקשה שוב.

אם הבעיה נמשכת, אפשר לפנות למנהל החשבון שלכם ב-Google Play או לשלוח בקשת תמיכה. כדאי לבדוק בלוח הבקרה של סטטוס Play אם יש הפסקות שירות ידועות.