REST Resource: orders

منبع: سفارش

منبع Order اطلاعات جامعی درباره تراکنش انجام شده در Google Play در خود گنجانده است. این شامل ویژگی های مختلفی است که جزئیات مربوط به خود سفارش، محصولات خریداری شده و تاریخچه رویدادهای مربوط به سفارش را ارائه می دهد.

APIهای Orders دسترسی هم‌زمان به داده‌های سفارش شما در اکوسیستم Google Play را فراهم می‌کنند. می‌توانید اطلاعات و فراداده‌های دقیق را برای سفارش‌های یک‌باره و تکراری، از جمله جزئیات تراکنش مانند هزینه‌ها، مالیات‌ها، و بازپرداخت‌ها، و همچنین فراداده‌هایی مانند مراحل قیمت‌گذاری برای اشتراک‌ها، بازیابی کنید. APIهای Orders به شما امکان می‌دهند کارهای مربوط به مدیریت سفارش را خودکار کنید و نیاز به بررسی دستی از طریق کنسول برنامه‌نویس Play را کاهش دهید.

موارد زیر برخی از موارد استفاده برای این API هستند:

  • بازیابی اطلاعات سفارش در زمان واقعی - با استفاده از شناسه سفارش، بلافاصله پس از خرید، جزئیات سفارش و فراداده را دریافت کنید.

  • همگام‌سازی به‌روزرسانی سفارش - به‌طور دوره‌ای به‌روزرسانی‌های سفارش را همگام‌سازی کنید تا رکوردی به‌روز از اطلاعات سفارش نگهداری کنید.

توجه:

  • فراخوان‌های Orders API در سهمیه Play Developer API شما به حساب می‌آیند، که به طور پیش‌فرض روزانه 200 هزار نفر است و ممکن است برای همگام‌سازی تاریخچه‌های سفارش گسترده کافی نباشد.

  • حداکثر 1000 سفارش در هر تماس قابل بازیابی است. استفاده از صفحات بزرگتر برای به حداقل رساندن استفاده از سهمیه توصیه می شود. سهمیه خود را در Cloud Console بررسی کنید و در صورت نیاز بیشتر درخواست کنید.

نمایندگی JSON 
{
  "lineItems": [
    {
      object (LineItem)
    }
  ],
  "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 )

اقلام خط منفرد این سفارش را تشکیل می دهند.

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 )

امتیاز بازی اعمال شده برای سفارش، از جمله اطلاعات پیشنهاد، نرخ تخفیف و ارزش امتیاز.

ایالت

وضعیت دستور.

Enums
STATE_UNSPECIFIED وضعیت نامشخص این مقدار استفاده نمی شود.
PENDING سفارش ایجاد شده است و در انتظار پردازش است.
PROCESSED سفارش با موفقیت پردازش شد.
CANCELED سفارش قبل از پردازش لغو شد.
PENDING_REFUND بازپرداخت درخواستی در انتظار پردازش است.
PARTIALLY_REFUNDED بخشی از مبلغ سفارش بازپرداخت شد.
REFUNDED کل مبلغ سفارش بازپرداخت شد.

آدرس خریدار

اطلاعات آدرس برای مشتری، برای استفاده در محاسبه مالیات.

نمایندگی JSON 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
فیلدها
buyerState

string

زیربخش اداری سطح بالای کشور آدرس خریدار. وقتی Google تاجر ثبت سفارش است، این اطلاعات شامل نمی‌شود.

buyerCountry

string

کد کشور دو حرفی بر اساس ISO-3166-1 Alpha-2 (کدهای کشور سازمان ملل).

buyerPostcode

string

کد پستی یک آدرس وقتی Google تاجر ثبت سفارش است، این اطلاعات شامل نمی‌شود.

جزئیات سفارش

اطلاعات دقیق در مورد سفارش در زمان ایجاد.

نمایندگی JSON 
{
  "taxInclusive": boolean
}
فیلدها
taxInclusive

boolean

نشان می دهد که آیا قیمت ذکر شده شامل مالیات بوده است یا خیر.

آیتم خط

جزئیات یک آیتم خط.

نمایندگی 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

شناسه محصول خریداری‌شده یا SKU درون برنامه‌ای (به عنوان مثال، «monthly001» یا «com.some.thing.inapp1»).

listingPrice

object ( Money )

قیمت فهرست‌شده مورد در فروشگاه Play، ممکن است شامل مالیات باشد یا نباشد. شامل هرگونه تخفیف یا تبلیغات نمی شود.

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,
  "rentalDetails": {
    object (RentalDetails)
  }
}
فیلدها
quantity

integer

تعداد اقلام خریداری شده (برای خریدهای چندتایی).

offerId

string

شناسه پیشنهاد پیشنهاد خرید یکبار مصرف.

purchaseOptionId

string

شناسه گزینه خرید این فیلد هم برای گزینه های خرید و هم برای پیشنهادات مختلف تنظیم شده است. برای گزینه های خرید، این شناسه خود گزینه خرید را مشخص می کند. برای پیشنهادهای مختلف، این شناسه به گزینه خرید مرتبط اشاره دارد و در ارتباط با offerId پیشنهاد نوع را مشخص می‌کند.

rentalDetails

object ( RentalDetails )

جزئیات خرید اجاره. فقط در صورتی تنظیم کنید که خرید اجاره ای باشد.

جزئیات اجاره

این نوع هیچ فیلدی ندارد.

جزئیات خرید اجاره ای.

جزئیات اشتراک

جزئیات خرید اشتراک.

نمایندگی JSON 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
فیلدها
basePlanId

string

شناسه طرح پایه اشتراک.

offerId

string

شناسه پیشنهاد برای پیشنهاد اشتراک فعلی.

offerPhase

enum ( OfferPhase )

مرحله قیمت‌گذاری برای دوره صورت‌حساب که توسط این سفارش تامین می‌شود.

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

مرحله قیمت‌گذاری برای دوره استحقاق که توسط این سفارش تامین می‌شود.

Enums
OFFER_PHASE_UNSPECIFIED فاز پیشنهاد نامشخص این مقدار استفاده نمی شود.
BASE این سفارش یک دوره قیمت پایه را تامین می کند.
INTRODUCTORY این سفارش یک دوره قیمت گذاری اولیه را تأمین می کند.
FREE_TRIAL این سفارش یک دوره آزمایشی رایگان را تأمین می کند.

جزئیات برنامه پرداخت

این نوع هیچ فیلدی ندارد.

جزئیات خرید اپلیکیشن پولی.

تاریخچه سفارش

جزئیات مربوط به رویدادهایی که سفارش را تغییر دادند.

نمایندگی 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" .

رویداد بازپرداخت

جزئیات زمان بازپرداخت کامل سفارش.

نمایندگی 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 )

دلیل بازپرداخت سفارش

جزئیات بازپرداخت

جزئیات بازپرداخت جزئی یا کامل.

نمایندگی JSON 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
فیلدها
total

object ( Money )

کل مبلغ بازپرداخت شده با احتساب مالیات.

tax

object ( Money )

مبلغ مالیات بازپرداخت شده.

دلیل بازپرداخت

دلیل بازپرداخت سفارش

Enums
REFUND_REASON_UNSPECIFIED سفارشات. دلیل بازپرداخت مشخص نشده است. این مقدار استفاده نمی شود.
OTHER سفارش به دلیلی غیر از دلایل ذکر شده در اینجا بازپرداخت شد.
CHARGEBACK سفارش پس گرفته شد.

رویداد بازپرداخت جزئی

جزئیات رویدادهای بازپرداخت جزئی برای این سفارش.

نمایندگی 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 )

جزئیات بازپرداخت جزئی.

ایالت

وضعیت بازپرداخت جزئی.

Enums
STATE_UNSPECIFIED وضعیت نامشخص این مقدار استفاده نمی شود.
PENDING بازپرداخت جزئی ایجاد شده است، اما هنوز پردازش نشده است.
PROCESSED_SUCCESSFULLY بازپرداخت جزئی با موفقیت پردازش شد.

PointsDetails

جزئیات مربوط به هر امتیاز Play اعمال شده در یک سفارش.

نمایندگی JSON 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
فیلدها
pointsOfferId

string

شناسه منحصر به فرد برای پیشنهاد امتیاز بازی در حال استفاده برای این سفارش.

pointsCouponValue

object ( Money )

ارزش پولی کوپن Play Points. این تخفیفی است که کوپن ارائه می دهد، که ممکن است کل مبلغ نباشد. فقط زمانی تنظیم می شود که از کوپن های Play Points استفاده شده باشد. به عنوان مثال برای 100 امتیاز برای کوپن 2 دلاری، این 2 دلار است.

pointsDiscountRateMicros

string ( int64 format)

نرخ درصدی که تبلیغات Play Points هزینه را کاهش می دهد. به عنوان مثال برای 100 امتیاز برای کوپن 2 دلاری، این 500000 است. از آنجایی که 2 دلار تخمینی 200 امتیاز دارد، اما امتیاز واقعی مورد نیاز، 100، 50 درصد این امتیاز است و 50 درصد در میکرو، 500000 است. بین 0 تا 1,000,000.

pointsSpent

string ( int64 format)

تعداد امتیازهای Play اعمال شده در این ترتیب. به عنوان مثال برای 100 امتیاز برای کوپن 2 دلاری، این 100 است. برای کوپن انباشته شده با پیشنهاد پایه، این مجموع امتیازهای صرف شده در هر دو است.

روش ها

batchget

 جزئیات سفارش را برای لیستی از سفارشات دریافت کنید.

get

 جزئیات سفارش را برای یک سفارش دریافت کنید.

refund

 اشتراک یا سفارش خرید درون برنامه ای کاربر را بازپرداخت می کند.