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)

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

קודי שגיאה

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

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