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)

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

 ביטול רכישת מינוי של משתמש.

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