REST Resource: orders

منبع: سفارش

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

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

برخی از کاربردهای این API به شرح زیر است:

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

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

توجه:

  • فراخوانی‌های API سفارشات جزو سهمیه API توسعه‌دهندگان Play شما محسوب می‌شوند که به‌طور پیش‌فرض روزانه ۲۰۰ هزار است و ممکن است برای همگام‌سازی تاریخچه‌های گسترده سفارشات کافی نباشد.

  • حداکثر ۱۰۰۰ سفارش در هر تماس قابل بازیابی است. برای به حداقل رساندن استفاده از سهمیه، استفاده از صفحات با اندازه بزرگتر توصیه می‌شود. سهمیه خود را در کنسول ابری بررسی کنید و در صورت نیاز درخواست بیشتری دهید.

نمایش 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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

buyerAddress

object ( BuyerAddress )

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

total

object ( Money )

مبلغ نهایی پرداخت شده توسط مشتری، با در نظر گرفتن تخفیف‌ها و مالیات.

tax

object ( Money )

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

orderDetails

object ( OrderDetails )

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

orderHistory

object ( OrderHistory )

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

developerRevenueInBuyerCurrency

object ( Money )

درآمد شما از این سفارش به واحد پول خریدار، شامل کسر بازپرداخت‌های جزئی، مالیات و هزینه‌ها. گوگل هزینه‌های استاندارد تراکنش و شخص ثالث را از هر فروش، از جمله مالیات بر ارزش افزوده در برخی مناطق، کسر می‌کند.

pointsDetails

object ( PointsDetails )

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

ایالت

وضعیت سفارش.

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

آدرس خریدار

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

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

string

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

buyerCountry

string

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

buyerPostcode

string

کد پستی آدرس. وقتی گوگل فروشنده‌ی اصلی سفارش باشد، این اطلاعات شامل نمی‌شود.

جزئیات سفارش

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

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

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

جزئیات خرید یک‌باره

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

نمایش JSON 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  "rentalDetails": {
    object (RentalDetails)
  }
}
فیلدها
quantity

integer

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

offerId

string

شناسه پیشنهاد خرید یک‌باره.

purchaseOptionId

string

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

preorderDetails

object ( PreorderDetails )

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

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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

فاز پیشنهاد

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

انوم‌ها
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 )

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

رویداد پردازش‌شده

جزئیات زمان پردازش سفارش.

نمایش JSON 
{
  "eventTime": string
}
فیلدها
eventTime

string ( Timestamp format)

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

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رویداد لغو

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

نمایش JSON 
{
  "eventTime": string
}
فیلدها
eventTime

string ( Timestamp format)

زمانی که سفارش لغو شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 )

مبلغ مالیات مسترد شده.

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

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

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

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

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

نمایش JSON 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
فیلدها
createTime

string ( Timestamp format)

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

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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_UNSPECIFIED وضعیت نامشخص. این مقدار استفاده نمی‌شود.
PENDING بازپرداخت جزئی ایجاد شده است، اما هنوز پردازش نشده است.
PROCESSED_SUCCESSFULLY بازپرداخت جزئی با موفقیت انجام شد.

جزئیات امتیاز

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

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

string

شناسه منحصر به فرد برای امتیازهای بازی که برای این سفارش استفاده می‌شود.

pointsCouponValue

object ( Money )

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

pointsDiscountRateMicros

string ( int64 format)

نرخ درصدی که طرح تشویقی امتیاز بازی هزینه را کاهش می‌دهد. مثلاً برای یک کوپن ۱۰۰ امتیازی به قیمت ۲ دلار، این مقدار ۵۰۰۰۰۰ است. از آنجایی که ۲ دلار تخمینی ۲۰۰ امتیاز دارد، اما امتیاز واقعی مورد نیاز، ۱۰۰، ۵۰٪ از این مقدار است و ۵۰٪ به صورت میکرو، ۵۰۰۰۰۰ است. بین ۰ تا ۱،۰۰۰،۰۰۰.

pointsSpent

string ( int64 format)

تعداد امتیازهای بازی اعمال شده به این ترتیب. مثلاً برای یک کوپن ۱۰۰ امتیازی ۲ دلاری، این عدد ۱۰۰ است. برای کوپنی که با پیشنهاد پایه ترکیب شده است، این عدد کل امتیازهای خرج شده در هر دو است.

روش‌ها

batchget

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

get

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

refund

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

کدهای خطا

عملیات این منبع، کدهای خطای HTTP زیر را برمی‌گرداند:

کد خطا دلیل وضوح تصویر
5xx خطای عمومی در سرور گوگل پلی. درخواست خود را دوباره امتحان کنید.

اگر مشکل همچنان ادامه داشت، با مدیر حساب Google Play خود تماس بگیرید یا درخواست پشتیبانی ارسال کنید. داشبورد وضعیت Play را برای هرگونه قطعی شناخته شده بررسی کنید.

409 خطای به‌روزرسانی همزمان.

تلاشی برای به‌روزرسانی شیء در حال به‌روزرسانی صورت گرفته است. برای مثال، یک خرید با فراخوانی متد acknowledgePurchase() از کتابخانه‌ی صورتحساب Play و با فراخوانی همزمان purchases.products.acknowledge از API توسعه‌دهنده‌ی Play، تأیید می‌شود.

 درخواست خود را دوباره امتحان کنید.