REST Resource: orders

משאב: הזמנה

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

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

הנה כמה תרחישי שימוש ב-API הזה:

  • אחזור נתוני הזמנות בזמן אמת – אפשר לאחזר פרטים ומטא-נתונים של הזמנות מיד אחרי רכישה באמצעות מזהה הזמנה.

  • סנכרון עדכוני הזמנות – סנכרון תקופתי של עדכוני הזמנות כדי לשמור על רשומה עדכנית של פרטי ההזמנות.

הערה:

  • הקריאות ל-Orders API נספרות במכסה שלכם ב-Play Developer API, שהיא 200, 000 ביום כברירת מחדל. יכול להיות שהמכסה הזו לא תספיק לכם לסנכרון של היסטוריית הזמנות נרחבת.

  • אפשר לאחזר עד 1,000 הזמנות לכל קריאה. מומלץ להשתמש בגדלים גדולים יותר של דפים כדי לצמצם את השימוש במכסת המכסות. בודקים את המכסה במסוף Cloud ומבקשים להגדיל אותה אם צריך.

ייצוג ב-JSON 
{
  "lineItems": [
    {
      object (LineItem)
    }
  ],
  "salesChannel": enum (SalesChannel),
  "orderId": string,
  "purchaseToken": string,
  "state": enum (State),
  "createTime": string,
  "lastEventTime": string,
  "buyerAddress": {
    object (BuyerAddress)
  },
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  },
  "orderDetails": {
    object (OrderDetails)
  },
  "orderHistory": {
    object (OrderHistory)
  },
  "developerRevenueInBuyerCurrency": {
    object (Money)
  },
  "pointsDetails": {
    object (PointsDetails)
  }
}
שדות
lineItems[]

object (LineItem)

הפריטים הבודדים שמרכיבים את ההזמנה הזו.
salesChannel

enum (SalesChannel)

ערוץ המכירות שדרכו בוצעה ההזמנה.
orderId

string

מזהה ההזמנה.
purchaseToken

string

האסימון שסופק למכשיר של המשתמש כשנרכש המינוי או הפריט.
state

enum (State)

מצב ההזמנה.
createTime

string (Timestamp format)

המועד שבו ההזמנה נוצרה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

השעה של האירוע האחרון שהתרחש בהזמנה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

פרטי הכתובת של הלקוח, לשימוש בחישוב מס. כש-Google היא הגוף האחראי על עיבוד התשלום של ההזמנה, מוצגת רק המדינה.
total

object (Money)

הסכום הסופי שמשלם הלקוח, כולל הנחות ומיסים.
tax

object (Money)

המס הכולל ששולם כחלק מההזמנה הזו.
orderDetails

object (OrderDetails)

מידע מפורט על ההזמנה בזמן היצירה.
orderHistory

object (OrderHistory)

פרטים על אירועים ששינו את ההזמנה.
developerRevenueInBuyerCurrency

object (Money)

ההכנסה שלך מההזמנה הזו במטבע של הקונה, כולל ניכויים של החזרים כספיים חלקיים, מיסים ועמלות. ‫Google מנכה מכל מכירה עמלות סטנדרטיות על עסקאות ותשלומים לצדדים שלישיים, כולל מע"מ באזורים מסוימים.
pointsDetails

object (PointsDetails)

נקודות Play שמומשו בהזמנה, כולל פרטי המבצע, שיעור ההנחה וערכי הנקודות.

מדינה (State)

מצב ההזמנה.

טיפוסים בני מנייה (enum)
STATE_UNSPECIFIED הסטטוס לא צוין. הערך הזה לא נמצא בשימוש.
PENDING ההזמנה נוצרה והיא ממתינה לעיבוד.
PROCESSED ההזמנה עובדה בהצלחה.
CANCELED ההזמנה בוטלה לפני העיבוד.
PENDING_REFUND הבקשה להחזר כספי נמצאת בהמתנה לעיבוד.
PARTIALLY_REFUNDED בוצע החזר כספי על חלק מסכום ההזמנה.
REFUNDED הסכום המלא של ההזמנה הוחזר.

BuyerAddress

פרטי הכתובת של הלקוח, לשימוש בחישוב מס.

ייצוג ב-JSON 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
שדות
buyerState

string

חלוקה מנהלית ברמה העליונה של המדינה שבה נמצאת כתובת הקונה. אם Google היא הגוף האחראי על עיבוד התשלום של ההזמנה, המידע הזה לא נכלל.
buyerCountry

string

קוד מדינה בן שתי אותיות לפי תקן ISO-3166-1 Alpha-2 (קודי מדינה של האו"ם).
buyerPostcode

string

המיקוד של הכתובת. אם Google היא הגוף האחראי על עיבוד התשלום של ההזמנה, המידע הזה לא נכלל.

OrderDetails

מידע מפורט על ההזמנה בזמן היצירה.

ייצוג ב-JSON 
{
  "taxInclusive": boolean
}
שדות
taxInclusive

boolean

השדה מציין אם המחיר שמופיע כולל מס או לא.

LineItem

פרטים של פריט.

ייצוג ב-JSON 
{
  "productTitle": string,
  "productId": string,
  "listingPrice": {
    object (Money)
  },
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  },

  // Union field details can be only one of the following:
  "oneTimePurchaseDetails": {
    object (OneTimePurchaseDetails)
  },
  "subscriptionDetails": {
    object (SubscriptionDetails)
  },
  "paidAppDetails": {
    object (PaidAppDetails)
  }
  // End of list of possible types for union field details.
}
שדות
productTitle

string

השם של המוצר שצוין על ידי המפתח. מוצג באזור המקומי של הקונה. דוגמה: מטבעות, מינוי חודשי וכו'.
productId

string

מזהה המוצר שנרכש או המק"ט של המוצר מתוך האפליקציה (לדוגמה, monthly001 או com.some.thing.inapp1).
listingPrice

object (Money)

המחיר שבו הפריט מוצע בחנות Play. יכול להיות שהמחיר כולל מס או לא. לא כולל הנחות שממומנות על ידי Google בלבד.
total

object (Money)

הסכום הכולל ששולם על ידי המשתמש עבור פריט השורה הזה, כולל הנחות ומס.
tax

object (Money)

המס ששולם על פריט ההזמנה הזה.

שדה איחוד details.

הערך details יכול להיות רק אחד מהבאים:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

פרטים על רכישה חד-פעמית.
subscriptionDetails

object (SubscriptionDetails)

פרטים על רכישת מינוי.
paidAppDetails

object (PaidAppDetails)

הפרטים של רכישת אפליקציה בתשלום.

OneTimePurchaseDetails

פרטים על רכישה חד-פעמית.

ייצוג ב-JSON 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  },
  "rentalDetails": {
    object (RentalDetails)
  }
}
שדות
quantity

integer

מספר הפריטים שנרכשו (ברכישות של פריטים בכמות גדולה).
offerId

string

מזהה המבצע של הרכישה החד-פעמית.
purchaseOptionId

string

המזהה של אפשרות הרכישה. השדה הזה מוגדר גם לאפשרויות רכישה וגם למוצרים עם וריאציות. במקרה של אפשרויות רכישה, המזהה הזה מציין את אפשרות הרכישה עצמה. במוצרים עם וריאציות, המזהה הזה מתייחס לאפשרות הרכישה המשויכת, ובשילוב עם מזהה המוצר הוא מזהה את הווריאציה.
preorderDetails

object (PreorderDetails)

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

object (RentalDetails)

פרטי רכישה של השכרה. הגדרה רק אם מדובר ברכישת השכרה.

PreorderDetails

בסוג הזה אין שדות.

פרטים של רכישה בהזמנה מראש.

RentalDetails

בסוג הזה אין שדות.

פרטים על רכישת השכרה.

SubscriptionDetails

פרטים על רכישת מינוי.

ייצוג ב-JSON 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "offerPhaseDetails": {
    object (OfferPhaseDetails)
  },
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
שדות
basePlanId

string

מזהה המינוי הבסיסי.
offerId

string

מזהה המבצע של המינוי הנוכחי.
offerPhase
(deprecated)

enum (OfferPhase)

הוצא משימוש: במקום זאת, צריך להשתמש ב-offerPhaseDetails. שלב התמחור לתקופת החיוב שממומנת על ידי ההזמנה הזו.
offerPhaseDetails

object (OfferPhaseDetails)

פרטי שלב התמחור לתקופת ההרשאה שממומנת על ידי ההזמנה הזו.
servicePeriodStartTime

string (Timestamp format)

תחילת תקופת החיוב שממומנת על ידי ההזמנה הזו. זהו צילום מסך של שעת ההתחלה של תקופת החיוב או השירות בזמן עיבוד ההזמנה, והוא צריך לשמש רק למטרות חשבונאיות.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

סיום תקופת החיוב שממומנת על ידי ההזמנה הזו. זו תמונת מצב של שעת הסיום של תקופת החיוב או השירות בזמן עיבוד ההזמנה, והיא מיועדת לשימוש לצורכי הנהלת חשבונות בלבד. כדי לקבל את שעת הסיום הנוכחית של תקופת המינוי, משתמשים בשיטה purchases.subscriptionsv2.get.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

OfferPhase

שלב התמחור לתקופת הזכאות שממומנת על ידי ההזמנה הזו.

טיפוסים בני מנייה (enum)
OFFER_PHASE_UNSPECIFIED לא צוין שלב המבצע. הערך הזה לא נמצא בשימוש.
BASE ההזמנה מממנת תקופה במחיר בסיסי.
INTRODUCTORY ההזמנה מממנת תקופת מחיר היכרות.
FREE_TRIAL ההזמנה מממנת תקופת ניסיון בחינם.

OfferPhaseDetails

פרטים של שלב תמחור לתקופת ההרשאה שממומנת על ידי ההזמנה הזו.

ייצוג ב-JSON 
{

  // Union field phase_details can be only one of the following:
  "freeTrialDetails": {
    object (FreeTrialDetails)
  },
  "introductoryPriceDetails": {
    object (IntroductoryPriceDetails)
  },
  "baseDetails": {
    object (BaseDetails)
  },
  "prorationPeriodDetails": {
    object (ProrationPeriodDetails)
  }
  // End of list of possible types for union field phase_details.
}
שדות
שדה איחוד phase_details. פרטים על שלב התמחור. הערך phase_details יכול להיות רק אחד מהבאים:
freeTrialDetails

object (FreeTrialDetails)

ההזמנה מממנת תקופת ניסיון בחינם.
introductoryPriceDetails

object (IntroductoryPriceDetails)

ההזמנה מממנת תקופת מחיר היכרות.
baseDetails

object (BaseDetails)

ההזמנה מממנת תקופה במחיר בסיסי.
prorationPeriodDetails

object (ProrationPeriodDetails)

ההזמנה מממנת תקופת חיוב יחסי.

FreeTrialDetails

בסוג הזה אין שדות.

פרטים של שלב תמחור של תקופת ניסיון בחינם.

IntroductoryPriceDetails

בסוג הזה אין שדות.

פרטים על שלב תמחור של מחיר היכרות.

BaseDetails

בסוג הזה אין שדות.

פרטים של שלב תמחור עם מחיר בסיסי.

ProrationPeriodDetails

פרטים על תקופת החישוב היחסי.

תקופת החישוב היחסי יכולה להיות תקופה שמחושבת במהלך שינוי תוכנית כדי לכסות זכויות קיימות (למידע נוסף, ראו מתן אפשרות למשתמשים לשדרג, לשנמך או לשנות את המינוי), או תקופה יחסית כדי להתאים את תאריכי החידוש של חבילות הערוצים לתאריך החידוש של המינוי הבסיסי (למידע נוסף, ראו כללים שחלים על פריטים ברכישה).

ייצוג ב-JSON 
{
  "originalOfferPhase": enum (OfferPhase)
}
שדות
originalOfferPhase

enum (OfferPhase)

אם תקופת החישוב היחסי כוללת את השלב המקורי של המבצע שבו נרכשה שורת הפריט, צריך לציין את השלב הזה. לדוגמה, תקופת חיוב יחסי משינוי תוכנית CHARGE_FULL_PRICE עשויה למזג את שלב המבצע הראשון של מבצע המינוי של המוצר החדש שהמשתמש רכש. במקרה כזה, שלב המבצע המקורי יוגדר כאן.

PaidAppDetails

בסוג הזה אין שדות.

הפרטים של רכישת אפליקציה בתשלום.

OrderHistory

פרטים על אירועים ששינו את ההזמנה.

ייצוג ב-JSON 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
שדות
partialRefundEvents[]

object (PartialRefundEvent)

פרטים של אירועי החזר כספי חלקי בהזמנה הזו.
processedEvent

object (ProcessedEvent)

פרטים על המועד שבו ההזמנה עובדה.
cancellationEvent

object (CancellationEvent)

פרטים על המועד שבו ההזמנה בוטלה.
refundEvent

object (RefundEvent)

פרטים על המועד שבו ההזמנה קיבלה החזר כספי מלא.

ProcessedEvent

פרטים על המועד שבו ההזמנה עובדה.

ייצוג ב-JSON 
{
  "eventTime": string
}
שדות
eventTime

string (Timestamp format)

המועד שבו ההזמנה עובדה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

CancellationEvent

פרטים על המועד שבו ההזמנה בוטלה.

ייצוג ב-JSON 
{
  "eventTime": string
}
שדות
eventTime

string (Timestamp format)

המועד שבו ההזמנה בוטלה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

RefundEvent

פרטים על המועד שבו ההזמנה קיבלה החזר כספי מלא.

ייצוג ב-JSON 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
שדות
eventTime

string (Timestamp format)

המועד שבו ההזמנה קיבלה החזר כספי מלא.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

פרטים לגבי ההחזר הכספי המלא.
refundReason

enum (RefundReason)

הסיבה להחזר הכספי על ההזמנה.

RefundDetails

פרטים על החזר כספי חלקי או מלא.

ייצוג ב-JSON 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
שדות
total

object (Money)

הסכום הכולל שניתן בהחזר כספי, כולל מס.
tax

object (Money)

סכום המס שהוחזר.

RefundReason

הסיבה להחזר הכספי על ההזמנה.

טיפוסים בני מנייה (enum)
REFUND_REASON_UNSPECIFIED orders.refund reason unspecified. הערך הזה לא נמצא בשימוש.
OTHER בוצע החזר כספי על ההזמנה מסיבה אחרת שלא מופיעה כאן.
CHARGEBACK ההזמנה חויבה מחדש.

PartialRefundEvent

פרטים של אירועי החזר כספי חלקי בהזמנה הזו.

ייצוג ב-JSON 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
שדות
createTime

string (Timestamp format)

השעה שבה נוצר ההחזר הכספי החלקי.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

השעה שבה בוצע העיבוד של ההחזר הכספי החלקי.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה העשרונית. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
state

enum (State)

המצב של ההחזר הכספי החלקי.
refundDetails

object (RefundDetails)

פרטים על ההחזר הכספי החלקי.

מדינה (State)

המצב של ההחזר הכספי החלקי.

טיפוסים בני מנייה (enum)
STATE_UNSPECIFIED הסטטוס לא צוין. הערך הזה לא נמצא בשימוש.
PENDING ההחזר הכספי החלקי נוצר, אבל עדיין לא עבר עיבוד.
PROCESSED_SUCCESSFULLY ההחזר הכספי החלקי עובד בהצלחה.

PointsDetails

פרטים שקשורים לנקודות Play שמומשו בהזמנה.

ייצוג ב-JSON 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
שדות
pointsOfferId

string

מזהה ייחודי למבצע של נקודות Play שבו נעשה שימוש בהזמנה הזו.
pointsCouponValue

object (Money)

הערך הכספי של שובר של נקודות Play. זו ההנחה שניתנת באמצעות השובר, ויכול להיות שהיא לא הסכום הכולל. הערך מוגדר רק כשמשתמשים בשוברים של מועדון Play. לדוגמה, אם יש לכם שובר הנחה של 100 נקודות בשווי 2$, הערך הזה יהיה 2$.
pointsDiscountRateMicros

string (int64 format)

שיעור ההנחה שניתנת במסגרת מבצע Play Points. לדוגמה, אם שובר הנחה בשווי 2 $מקנה 100 נקודות, הערך שצריך להזין הוא 500,000. ההערכה היא ש-2 $שווים ל-200 נקודות, אבל בפועל נדרשות 100 נקודות, שהן 50% מההערכה. 50% במיקרו הם 500,000. בין 0 ל-1,000,000.
pointsSpent

string (int64 format)

מספר נקודות Play שמומשו בהזמנה הזו. לדוגמה, אם מדובר בשובר הנחה של 100 נקודות על רכישה בסך 2$, הערך הוא 100. אם השובר מצורף למבצע בסיסי, זהו סך הנקודות שהוצאו על שניהם.

SalesChannel

ערוץ המכירות שדרכו בוצעה ההזמנה.

טיפוסים בני מנייה (enum)
SALES_CHANNEL_UNSPECIFIED לא צוין ערוץ מכירות. הערך הזה לא נמצא בשימוש.
IN_APP הזמנות רגילות שהתחילו מתוך האפליקציה.
PC_EMULATOR הזמנות שנוצרו מאמולטור למחשב לצורך רכישות באפליקציה.
NATIVE_PC הזמנות שנוצרו מאפליקציית מחשב מקורית לרכישות באפליקציה.
PLAY_STORE הזמנות שנוצרו בחנות Google Play.
OUTSIDE_PLAY_STORE הזמנות שנוצרו מחוץ לחנות Google Play.

Methods

batchget

 קבלת פרטי הזמנה לרשימה של הזמנות.

get

 קבלת פרטי הזמנה של הזמנה יחידה.

refund

 מחזיר כספים על הזמנה של מינוי או רכישה באפליקציה של משתמש.

קודי שגיאה

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

קוד שגיאה סיבה תיאור פתרון