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)

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

string (int64 format)

השעה שבה המינוי יחודש אוטומטית, במילי-שניות מאז תקופת ה-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

שם הפרופיל של המשתמש בזמן רכישת המינוי. המאפיין הזה מופיע רק ברכישות שבוצעו באמצעות 'Subscribe with Google'.
emailAddress

string

כתובת האימייל של המשתמש בזמן רכישת המינוי. המאפיין הזה מופיע רק ברכישות שבוצעו באמצעות 'Subscribe with Google'.
givenName

string

השם הפרטי של המשתמש בזמן רכישת המינוי. המאפיין הזה מופיע רק ברכישות שבוצעו באמצעות 'Subscribe with Google'.
familyName

string

שם המשפחה של המשתמש בזמן רכישת המינוי. המאפיין הזה מופיע רק ברכישות שבוצעו באמצעות 'Subscribe with Google'.
profileId

string

מזהה הפרופיל ב-Google של המשתמש בזמן רכישת המינוי. המאפיין הזה מופיע רק ברכישות שבוצעו באמצעות 'Subscribe with 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.

get
(deprecated)

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

refund
(deprecated)

 הוצאה משימוש: במקום זאת, צריך להשתמש ב-orders.refund.

revoke
(deprecated)

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

קודי שגיאה

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

קוד שגיאה סיבה תיאור רזולוציה
400 / 410 subscriptionExpired המינוי פג ואי אפשר לבצע את הפעולה המבוקשת. בודקים את תאריך התפוגה של המינוי. אי אפשר לבצע את הפעולה הזו במינויים שפג התוקף שלהם.
400 subscriptionInvalidArgument בבקשה למינוי סופק ארגומנט לא תקין. כדאי לעיין במאמרי העזרה של ה-API ולוודא שציינתם את המידע בכל שדות החובה ושהזנתם את הנתונים בפורמט הנכון.
400 invalidPurchaseState הרכישה לא במצב שמאפשר לבצע את הפעולה המבוקשת. לדוגמה, יכול להיות שאתם מנסים לאשר רכישה שכבר נעשה בה שימוש או לבטל מינוי שלא פעיל. לפני שמנסים לבצע את הפעולה, כדאי לבדוק את המצב הנוכחי של המשאב באמצעות ה-API המתאים מסוג Get. מוודאים שהמשאב נמצא במצב המתאים לפעולה.
400 invalidValue צוין ערך לא תקין בבקשה. השגיאה הזו מוחזרת לעיתים קרובות אם טוקן הרכישה פגום או לא תקין. מתקנים את הערך הלא תקין של השדה בגוף הבקשה או בפרמטרים על סמך הפניה ל-API.
400 prepaidSubscriptionNotSupported הפעולה שביקשת לא נתמכת במינויים בתשלום מראש. מוודאים שהפעולה רלוונטית לסוג המינוי. השגיאה הזו ספציפית לשיטות כמו ביטול, דחייה, החזר כספי או ביטול הרשאה.
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 Status Dashboard אם יש הפסקות זמניות ידועות בשירות.