REST Resource: orders

المورد: الطلب

يحتوي مورد "الطلب" على معلومات شاملة عن معاملة تم إجراؤها على Google Play. وتتضمّن مجموعة متنوّعة من السمات التي توفّر تفاصيل حول الطلب نفسه والمنتجات التي تم شراؤها وسجلّ الأحداث المرتبطة بالطلب.

توفّر واجهات برمجة التطبيقات الخاصة بالطلبات إمكانية الوصول في الوقت الفعلي إلى بيانات طلباتك ضمن منظومة Google Play المتكاملة. يمكنك استرداد معلومات وبيانات وصفية مفصّلة لكلّ من الطلبات لمرة واحدة والطلبات المتكرّرة، بما في ذلك تفاصيل المعاملات مثل الرسوم والضرائب وعمليات ردّ الأموال، بالإضافة إلى البيانات الوصفية مثل مراحل التسعير للاشتراكات. تتيح لك واجهات برمجة التطبيقات الخاصة بالطلبات إمكانية إعداد مهام مبرمَجة ذات صلة بإدارة الطلبات، ما يقلّل الحاجة إلى إجراء عمليات تحقّق يدوية من خلال Play Developer Console.

في ما يلي بعض حالات استخدام واجهة برمجة التطبيقات هذه:

  • استرداد بيانات الطلبات في الوقت الفعلي: يمكنك استخدام مُعرّف الطلب لاسترداد تفاصيل الطلب والبيانات الوصفية فور إتمام عملية الشراء باستخدام طريقة orders.get.

  • مزامنة تعديلات الطلبات: تتم مزامنة تعديلات الطلبات بشكل دوري للحفاظ على سجلّ محدّث لمعلومات الطلبات.

ملاحظة:

  • يتم احتساب عدد طلبات البيانات من واجهة Orders API ضمن حصة Play Developer API، والتي تبلغ تلقائيًا 200 ألف طلب يوميًا، وقد لا تكون كافية لمزامنة سجلات الطلبات الكبيرة.

  • يمكن استرداد 1,000 طلب كحدّ أقصى لكل مكالمة. يُنصح باستخدام أحجام صفحات أكبر لتقليل استخدام الحصة. تحقَّق من حصتك في 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-normalized ويستخدم 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-normalized ويستخدم 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 Points المطبَّقة على الطلب، بما في ذلك معلومات العرض ونسبة الخصم وقيم النقاط

الحالة

تمثّل هذه السمة حالة الطلب.

عمليات التعداد
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"، وقد يشمل الضريبة أو لا يشملها. يُستثنى من هذا السعر أي خصومات أو عروض ترويجية.
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)

تمثّل هذه السمة تفاصيل عملية شراء استئجار. يتم ضبط هذا الحقل فقط إذا كانت عملية الشراء عبارة عن استئجار.

RentalDetails

لا يتضمّن هذا النوع أي حقول.

تفاصيل عملية شراء المحتوى المؤجَّر

SubscriptionDetails

تفاصيل عملية شراء اشتراك

تمثيل 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 ويستخدم 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-normalized ويستخدم 0 أو 3 أو 6 أو 9 أرقام كسرية. يتم أيضًا قبول الإزاحات غير "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"

OfferPhase

مرحلة الأسعار لفترة الاستحقاق التي يموّلها هذا الطلب

عمليات التعداد
OFFER_PHASE_UNSPECIFIED لم يتم تحديد مرحلة العرض. لا يتم استخدام هذه القيمة.
BASE يوفّر الطلب الأموال اللازمة لمدة السعر الأساسي.
INTRODUCTORY يوفّر الطلب الأموال اللازمة لفترة السعر التمهيدي.
FREE_TRIAL يوفّر الطلب فترة تجريبية مجانية.

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-normalized ويستخدم 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-normalized ويستخدم 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-normalized ويستخدم 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

سبب ردّ الأموال المدفوعة في الطلب

عمليات التعداد
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-normalized ويستخدم 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-normalized ويستخدم 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_UNSPECIFIED لم يتم تحديد الولاية. لا يتم استخدام هذه القيمة.
PENDING تم إنشاء ردّ جزء من الأموال، ولكن لم تتم معالجته بعد.
PROCESSED_SUCCESSFULLY تمت معالجة عملية ردّ جزء من الأموال بنجاح.

PointsDetails

تفاصيل تتعلّق بأي نقاط في Play Points تم تطبيقها على طلب

تمثيل JSON 
{   "pointsOfferId": string,   "pointsCouponValue": {     object (Money)   },   "pointsDiscountRateMicros": string,   "pointsSpent": string }
الحقول
pointsOfferId

string

معرّف فريد لعرض Play Points المستخدَم في هذا الطلب.
pointsCouponValue

object (Money)

القيمة النقدية لقسيمة Play Points هذا هو الخصم الذي توفّره القسيمة، وقد لا يكون المبلغ الإجمالي. يتم ضبط هذا الحقل فقط عند استخدام قسائم Play Points. على سبيل المثال، إذا كانت القسيمة بقيمة 100 نقطة مقابل دولارَين أمريكيَّين، تكون القيمة هي دولارَين أمريكيَّين.
pointsDiscountRateMicros

string (int64 format)

النسبة المئوية التي يخفّض بها العرض الترويجي في Play Points التكلفة. على سبيل المثال، إذا كانت القسيمة تمنح 100 نقطة مقابل دولارَين أمريكيَّين، يكون هذا الرقم 500,000. بما أنّ الدولار الأمريكي الواحد يساوي 200 نقطة، ولكن النقاط الفعلية المطلوبة هي 100 نقطة، أي% 50 من هذا المبلغ، و% 50 من الميكرو هي 500,000. بين 0 و1,000,000
pointsSpent

string (int64 format)

عدد نقاط Play Points المستخدَمة في هذا الطلب على سبيل المثال، إذا كانت القسيمة بقيمة 100 نقطة مقابل دولارَين أمريكيَّين، تكون القيمة 100. بالنسبة إلى القسيمة المجمّعة مع العرض الأساسي، يشير هذا الحقل إلى إجمالي النقاط التي تم إنفاقها على كليهما.

الطُرق

batchget

 الحصول على تفاصيل الطلبات لقائمة من الطلبات

get

 الحصول على تفاصيل طلب واحد

refund

 ردّ الأموال المدفوعة مقابل اشتراك المستخدم أو طلب الشراء داخل التطبيق