REST Resource: orders

Tài nguyên: Đơn đặt hàng

Tài nguyên Order (Đơn đặt hàng) bao gồm thông tin toàn diện về một giao dịch được thực hiện trên Google Play. Đối tượng này bao gồm nhiều thuộc tính cung cấp thông tin chi tiết về đơn đặt hàng, các sản phẩm đã mua và nhật ký sự kiện liên quan đến đơn đặt hàng.

Orders API cung cấp quyền truy cập theo thời gian thực vào dữ liệu đơn đặt hàng của bạn trong hệ sinh thái Google Play. Bạn có thể truy xuất thông tin chi tiết và siêu dữ liệu cho cả đơn đặt hàng một lần và định kỳ, bao gồm cả thông tin chi tiết về giao dịch như phí, thuế và khoản tiền hoàn lại, cũng như siêu dữ liệu như giai đoạn định giá cho gói thuê bao. Orders API (API Đơn đặt hàng) cho phép bạn tự động hoá các tác vụ liên quan đến việc quản lý đơn đặt hàng, nhờ đó bạn không cần phải kiểm tra theo cách thủ công thông qua Play Console.

Sau đây là một số trường hợp sử dụng API này:

  • Truy xuất dữ liệu đơn đặt hàng theo thời gian thực – orders.get thông tin chi tiết và siêu dữ liệu về đơn đặt hàng ngay sau khi giao dịch mua được thực hiện bằng mã đơn đặt hàng.

  • Đồng bộ hoá thông tin cập nhật về đơn đặt hàng – Định kỳ đồng bộ hoá thông tin cập nhật về đơn đặt hàng để duy trì bản ghi thông tin mới nhất về đơn đặt hàng.

Lưu ý:

  • Số lệnh gọi Orders API được tính vào hạn mức API Nhà phát triển trên Play (mặc định là 200.000 lệnh gọi mỗi ngày) và có thể không đủ để đồng bộ hoá nhật ký đơn đặt hàng mở rộng.

  • Bạn có thể truy xuất tối đa 1.000 đơn đặt hàng cho mỗi lệnh gọi. Bạn nên sử dụng kích thước trang lớn hơn để giảm thiểu mức sử dụng hạn mức. Kiểm tra hạn mức của bạn trong Cloud Console và yêu cầu thêm nếu cần.

Biểu diễn dưới dạng 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)   } }
Trường
lineItems[]

object (LineItem)

Các mục hàng riêng lẻ tạo nên đơn đặt hàng này.
orderId

string

Mã đơn đặt hàng.
purchaseToken

string

Mã thông báo được cung cấp cho thiết bị của người dùng khi người dùng mua gói thuê bao hoặc mặt hàng.
state

enum (State)

Trạng thái của đơn đặt hàng.
createTime

string (Timestamp format)

Thời điểm đơn đặt hàng được tạo.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
lastEventTime

string (Timestamp format)

Thời gian của sự kiện gần đây nhất xảy ra trên đơn đặt hàng.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
buyerAddress

object (BuyerAddress)

Thông tin địa chỉ của khách hàng, dùng để tính thuế. Khi Google là Bên bán hàng đã đăng ký cho đơn đặt hàng, chỉ có quốc gia xuất hiện.
total

object (Money)

Số tiền cuối cùng mà khách hàng trả, có tính đến chiết khấu và thuế.
tax

object (Money)

Tổng số thuế đã thanh toán trong đơn đặt hàng này.
orderDetails

object (OrderDetails)

Thông tin chi tiết về đơn đặt hàng tại thời điểm tạo.
orderHistory

object (OrderHistory)

Thông tin chi tiết về những sự kiện đã sửa đổi thứ tự.
developerRevenueInBuyerCurrency

object (Money)

Doanh thu bạn nhận được từ đơn đặt hàng này bằng loại tiền tệ của người mua, bao gồm cả các khoản khấu trừ như tiền hoàn lại một phần, thuế và phí. Với mỗi lượt bán hàng, Google sẽ khấu trừ phí giao dịch tiêu chuẩn và phí của bên thứ ba, bao gồm cả thuế GTGT tại một số khu vực.
pointsDetails

object (PointsDetails)

Điểm Play được áp dụng cho đơn đặt hàng, bao gồm thông tin về ưu đãi, tỷ lệ chiết khấu và giá trị điểm.

Tiểu bang

Trạng thái của đơn đặt hàng.

Enum
STATE_UNSPECIFIED Chưa chỉ định tiểu bang. Giá trị này không được sử dụng.
PENDING Đơn đặt hàng đã được tạo và đang chờ xử lý.
PROCESSED Đơn đặt hàng đã được xử lý thành công.
CANCELED Đơn đặt hàng đã bị huỷ trước khi được xử lý.
PENDING_REFUND Yêu cầu hoàn tiền đang chờ xử lý.
PARTIALLY_REFUNDED Một phần số tiền của đơn đặt hàng đã được hoàn lại.
REFUNDED Toàn bộ số tiền của đơn đặt hàng đã được hoàn lại.

BuyerAddress

Thông tin địa chỉ của khách hàng, dùng để tính thuế.

Biểu diễn dưới dạng JSON 
{   "buyerState": string,   "buyerCountry": string,   "buyerPostcode": string }
Trường
buyerState

string

Phân khu hành chính cấp cao nhất của quốc gia trong địa chỉ người mua. Khi Google là Bên bán chính thức của đơn đặt hàng, thông tin này sẽ không được đưa vào.
buyerCountry

string

Mã quốc gia gồm 2 chữ cái dựa trên ISO-3166-1 Alpha-2 (mã quốc gia của Liên Hợp Quốc).
buyerPostcode

string

Mã bưu chính của địa chỉ. Khi Google là Bên bán chính thức của đơn đặt hàng, thông tin này sẽ không được đưa vào.

OrderDetails

Thông tin chi tiết về đơn đặt hàng tại thời điểm tạo.

Biểu diễn dưới dạng JSON 
{   "taxInclusive": boolean }
Trường
taxInclusive

boolean

Cho biết giá niêm yết đã bao gồm thuế hay chưa.

LineItem

Thông tin chi tiết về một mục hàng.

Biểu diễn dưới dạng 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. }
Trường
productTitle

string

Tên của sản phẩm do nhà phát triển chỉ định. Hiển thị theo ngôn ngữ của người mua. Ví dụ: tiền xu, gói thuê bao hằng tháng, v.v.
productId

string

Mã sản phẩm hoặc SKU trong ứng dụng của sản phẩm đã mua (ví dụ: "monthly001" hoặc "com.some.thing.inapp1").
listingPrice

object (Money)

Giá niêm yết của mặt hàng trên Cửa hàng Play, giá này có thể bao gồm hoặc không bao gồm thuế. Không bao gồm khoản chiết khấu hay ưu đãi khuyến mãi.
total

object (Money)

Tổng số tiền mà người dùng đã trả cho mặt hàng này, có tính đến chiết khấu và thuế.
tax

object (Money)

Thuế đã trả cho mục hàng này.

Trường nhóm details.

details chỉ có thể là một trong những trạng thái sau:
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

Thông tin chi tiết về giao dịch mua một lần.
subscriptionDetails

object (SubscriptionDetails)

Thông tin chi tiết về giao dịch mua gói thuê bao.
paidAppDetails

object (PaidAppDetails)

Thông tin chi tiết về giao dịch mua ứng dụng có tính phí.

OneTimePurchaseDetails

Thông tin chi tiết về giao dịch mua một lần.

Biểu diễn dưới dạng JSON 
{   "quantity": integer,   "offerId": string,   "purchaseOptionId": string,   "rentalDetails": {     object (RentalDetails)   } }
Trường
quantity

integer

Số lượng mặt hàng đã mua (đối với giao dịch mua nhiều mặt hàng).
offerId

string

Mã ưu đãi của ưu đãi mua một lần.
purchaseOptionId

string

Mã của lựa chọn mua. Trường này được đặt cho cả lựa chọn mua và sản phẩm biến thể. Đối với lựa chọn mua, mã này xác định chính lựa chọn mua đó. Đối với các mặt hàng biến thể, mã nhận dạng này đề cập đến lựa chọn mua có liên quan và cùng với offerId, mã nhận dạng này xác định mặt hàng biến thể.
rentalDetails

object (RentalDetails)

Thông tin chi tiết về giao dịch thuê. Chỉ đặt nếu đó là giao dịch mua để thuê.

RentalDetails

Loại này không có trường nào.

Thông tin chi tiết về giao dịch mua phim để thuê.

SubscriptionDetails

Thông tin chi tiết về giao dịch mua gói thuê bao.

Biểu diễn dưới dạng JSON 
{   "basePlanId": string,   "offerId": string,   "offerPhase": enum (OfferPhase),   "servicePeriodStartTime": string,   "servicePeriodEndTime": string }
Trường
basePlanId

string

Mã gói cơ bản của gói thuê bao.
offerId

string

Mã ưu đãi của ưu đãi gói thuê bao hiện tại.
offerPhase

enum (OfferPhase)

Giai đoạn định giá cho kỳ thanh toán được tài trợ bởi đơn đặt hàng này.
servicePeriodStartTime

string (Timestamp format)

Ngày bắt đầu của kỳ thanh toán được tài trợ bằng đơn đặt hàng này. Đây là thông tin về thời điểm bắt đầu kỳ thanh toán/dịch vụ tại thời điểm đơn đặt hàng được xử lý và chỉ nên được dùng cho mục đích kế toán.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
servicePeriodEndTime

string (Timestamp format)

Ngày kết thúc kỳ thanh toán được tài trợ bởi đơn đặt hàng này. Đây là thông tin về thời điểm kết thúc kỳ thanh toán/dịch vụ tại thời điểm đơn đặt hàng được xử lý và chỉ được dùng cho mục đích kế toán. Để lấy thời gian kết thúc hiện tại của kỳ hạn dịch vụ thuê bao, hãy sử dụng purchases.subscriptionsv2.get.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

OfferPhase

Giai đoạn định giá cho thời hạn hưởng quyền được tài trợ bởi đơn đặt hàng này.

Enum
OFFER_PHASE_UNSPECIFIED Chưa chỉ định giai đoạn gửi thư mời nhận việc. Giá trị này không được sử dụng.
BASE Đơn đặt hàng này tài trợ cho một khoảng thời gian có giá cơ bản.
INTRODUCTORY Đơn đặt hàng này tài trợ cho một giai đoạn giá ưu đãi.
FREE_TRIAL Đơn đặt hàng này dùng để thanh toán cho một thời gian dùng thử miễn phí.

PaidAppDetails

Loại này không có trường nào.

Thông tin chi tiết về giao dịch mua ứng dụng có tính phí.

OrderHistory

Thông tin chi tiết về những sự kiện đã sửa đổi thứ tự.

Biểu diễn dưới dạng JSON 
{   "partialRefundEvents": [     {       object (PartialRefundEvent)     }   ],   "processedEvent": {     object (ProcessedEvent)   },   "cancellationEvent": {     object (CancellationEvent)   },   "refundEvent": {     object (RefundEvent)   } }
Trường
partialRefundEvents[]

object (PartialRefundEvent)

Thông tin chi tiết về các sự kiện hoàn tiền một phần cho đơn đặt hàng này.
processedEvent

object (ProcessedEvent)

Thông tin chi tiết về thời điểm đơn đặt hàng được xử lý.
cancellationEvent

object (CancellationEvent)

Thông tin chi tiết về thời điểm đơn đặt hàng bị huỷ.
refundEvent

object (RefundEvent)

Thông tin chi tiết về thời điểm đơn đặt hàng được hoàn tiền đầy đủ.

ProcessedEvent

Thông tin chi tiết về thời điểm đơn đặt hàng được xử lý.

Biểu diễn dưới dạng JSON 
{   "eventTime": string }
Trường
eventTime

string (Timestamp format)

Thời điểm đơn đặt hàng được xử lý.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

CancellationEvent

Thông tin chi tiết về thời điểm đơn đặt hàng bị huỷ.

Biểu diễn dưới dạng JSON 
{   "eventTime": string }
Trường
eventTime

string (Timestamp format)

Thời điểm đơn đặt hàng bị huỷ.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

RefundEvent

Thông tin chi tiết về thời điểm đơn đặt hàng được hoàn tiền đầy đủ.

Biểu diễn dưới dạng JSON 
{   "eventTime": string,   "refundDetails": {     object (RefundDetails)   },   "refundReason": enum (RefundReason) }
Trường
eventTime

string (Timestamp format)

Thời điểm đơn đặt hàng được hoàn tiền toàn bộ.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
refundDetails

object (RefundDetails)

Thông tin chi tiết về việc hoàn tiền toàn bộ.
refundReason

enum (RefundReason)

Lý do đơn đặt hàng được hoàn tiền.

RefundDetails

Thông tin chi tiết về việc hoàn tiền một phần hoặc toàn bộ.

Biểu diễn dưới dạng JSON 
{   "total": {     object (Money)   },   "tax": {     object (Money)   } }
Trường
total

object (Money)

Tổng số tiền hoàn lại, bao gồm cả thuế.
tax

object (Money)

Số tiền thuế được hoàn lại.

RefundReason

Lý do đơn đặt hàng được hoàn tiền.

Enum
REFUND_REASON_UNSPECIFIED orders.refund reason chưa xác định. Giá trị này không được sử dụng.
OTHER Đơn đặt hàng đã được hoàn tiền vì một lý do khác ngoài những lý do được nêu ở đây.
CHARGEBACK Đơn đặt hàng đã được hoàn tiền.

PartialRefundEvent

Thông tin chi tiết về các sự kiện hoàn tiền một phần cho đơn đặt hàng này.

Biểu diễn dưới dạng JSON 
{   "createTime": string,   "processTime": string,   "state": enum (State),   "refundDetails": {     object (RefundDetails)   } }
Trường
createTime

string (Timestamp format)

Thời điểm tạo khoản hoàn tiền một phần.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
processTime

string (Timestamp format)

Thời điểm giao dịch hoàn tiền một phần được xử lý.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".
state

enum (State)

Trạng thái của khoản hoàn tiền một phần.
refundDetails

object (RefundDetails)

Thông tin chi tiết về khoản hoàn tiền một phần.

Tiểu bang

Trạng thái của khoản hoàn tiền một phần.

Enum
STATE_UNSPECIFIED Chưa chỉ định tiểu bang. Giá trị này không được sử dụng.
PENDING Giao dịch hoàn tiền một phần đã được tạo nhưng chưa được xử lý.
PROCESSED_SUCCESSFULLY Giao dịch hoàn tiền một phần đã được xử lý thành công.

PointsDetails

Thông tin chi tiết liên quan đến Điểm Play được áp dụng cho một đơn đặt hàng.

Biểu diễn dưới dạng JSON 
{   "pointsOfferId": string,   "pointsCouponValue": {     object (Money)   },   "pointsDiscountRateMicros": string,   "pointsSpent": string }
Trường
pointsOfferId

string

Mã nhận dạng riêng biệt của ưu đãi Điểm Play đang được sử dụng cho đơn đặt hàng này.
pointsCouponValue

object (Money)

Giá trị tiền tệ của phiếu giảm giá Play Points. Đây là mức chiết khấu mà phiếu giảm giá cung cấp, có thể không phải là tổng số tiền. Chỉ đặt khi bạn đã sử dụng phiếu giảm giá Điểm Play. Ví dụ: đối với phiếu giảm giá 20.000 VND cho 100 điểm, giá trị này là 20. 000 VND.
pointsDiscountRateMicros

string (int64 format)

Tỷ lệ phần trăm mà chương trình khuyến mãi Play Points giảm giá. Ví dụ: đối với phiếu giảm giá 2 đô la cho 100 điểm, giá trị này là 500.000. Vì 2 USD có mức ước tính là 200 điểm, nhưng số điểm thực tế cần có là 100, tức là 50% của mức ước tính này và 50% tính bằng đơn vị vi mô là 500.000. Từ 0 đến 1.000.000.
pointsSpent

string (int64 format)

Số điểm Play Points được áp dụng trong đơn đặt hàng này. Ví dụ: đối với phiếu giảm giá 20.000 VND cho 100 điểm, giá trị này là 100. Đối với phiếu giảm giá được kết hợp với ưu đãi cơ bản, đây là tổng số điểm đã chi tiêu cho cả hai.

Phương thức

batchget

 Lấy thông tin chi tiết về đơn đặt hàng cho một danh sách đơn đặt hàng.

get

 Lấy thông tin chi tiết về một đơn đặt hàng.

refund

 Hoàn tiền cho đơn đặt hàng gói thuê bao hoặc giao dịch mua hàng trong ứng dụng của người dùng.