VI | EN
Nhắn Messenger
Dành cho developer

Danh sách đơn theo cửa sổ thời gian — API Shopee

v2.order.get_order_list · gọi qua Quantri360 bằng một API key cho chính tài khoản / tài sản bạn đã kết nối và ủy quyền — 360 lo việc ký request và làm mới phiên đăng nhập bạn đã cấp.

v2.order.get_order_list

GET/api/v2/order/get_order_listGọi qua 360: GET https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_list
Mô tả API

Lấy danh sách mã đơn (order_sn) được tạo hoặc cập nhật trong một cửa sổ thời gian. Điểm bắt đầu của mọi luồng đồng bộ đơn: API chỉ trả mã đơn (và trạng thái nếu yêu cầu); nội dung đơn lấy bằng get_order_detail.

  • Quét gối 5–10 phút theo update_time để không lọt đơn đổi trạng thái muộn.
  • Gộp mã đơn thành nhóm ≤ 50 rồi gọi get_order_detail.
  • Đơn đã giao một phần / đang hoàn có thể mang trạng thái TO_CONFIRM_RECEIVE hoặc TO_RETURN — lưu nguyên giá trị, không ép về danh sách trên.

Request

Địa chỉ

GET https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_list

Xác thực & gian hàng

TênVị tríKiểuMẫuMô tả
AuthorizationheaderheaderBearer q360_live_ab12cd34_…Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_idquerystring100001Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp.

Tham số request

TênVị tríKiểuBắt buộcMẫuMô tả
time_range_fieldquerystringCócreate_timecreate_time (ngày tạo) hoặc update_time (lần cập nhật cuối — dùng để bắt đơn đổi trạng thái).
time_fromquerytimestampCó1760893200Unix giây. Khoảng time_from → time_to tối đa 15 ngày (giới hạn của Shopee).
time_toquerytimestampCó1760979600Unix giây. Khoảng time_from → time_to tối đa 15 ngày (giới hạn của Shopee).
page_sizequeryintCó50Số đơn mỗi trang, 1–100.
cursorquerystringKhông50next_cursor của trang trước; bỏ trống ở trang đầu.
order_statusquerystringKhôngREADY_TO_SHIPLọc một trạng thái: UNPAID · READY_TO_SHIP · PROCESSED · SHIPPED · TO_CONFIRM_RECEIVE · COMPLETED · IN_CANCEL · CANCELLED · TO_RETURN · INVOICE_PENDING.
response_optional_fieldsquerystringKhôngorder_statusorder_status để nhận trạng thái kèm mã đơn (khuyến nghị).
logistics_channel_idqueryintKhông91007Lọc theo kênh vận chuyển; chỉ có hiệu lực tại Brazil, shop VN bỏ trường này.
request_order_status_pendingqueryboolKhôngfalsetrue để nhận thêm trạng thái PENDING (đơn đang chờ Shopee xác nhận).

Phân trang

Lặp khi response.more = true, truyền cursor = response.next_cursor cho lần kế. Muốn quét dài hơn 15 ngày: chia nhiều cửa sổ.

Ví dụ request

curl -s "https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_list?time_range_field=update_time&time_from=1760893200&time_to=1760979600&page_size=50&response_optional_fields=order_status" \
  -H "Authorization: Bearer $KEY"
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_list",
    params={
        "time_range_field": "update_time",
        "time_from": 1760893200,
        "time_to": 1760979600,
        "page_size": 50,
        "response_optional_fields": "order_status"
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())
Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_list');
for (const [k, v] of Object.entries({"time_range_field":"update_time","time_from":1760893200,"time_to":1760979600,"page_size":50,"response_optional_fields":"order_status"})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/shopee/api/v2/order/get_order_list' . '?' . http_build_query(['time_range_field' => 'update_time', 'time_from' => 1760893200, 'time_to' => 1760979600, 'page_size' => 50, 'response_optional_fields' => 'order_status']);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Tham số phản hồi (nguyên của Shopee)

TênKiểuMẫuMô tả
request_idstringd52ca43b277a4f9292fb8be658bfd33dMã request của Shopee để tra lỗi.
errorstringMã lỗi Shopee; rỗng = thành công.
messagestringMô tả lỗi.
responseobjectDữ liệu.
morebooltrueCòn trang kế.
next_cursorstring50Con trỏ trang kế.
order_listobject[]Danh sách đơn.
order_snstring2610220ABCDE01Mã đơn.
order_statusstringREADY_TO_SHIPTrạng thái (khi có response_optional_fields=order_status).
booking_snstringMã đặt chỗ (chỉ đơn đặt trước của một số kênh); thường rỗng.

Mẫu phản hồi

{
  "error": "",
  "message": "",
  "response": {
    "more": true,
    "next_cursor": "50",
    "order_list": [
      {
        "order_sn": "2610220ABCDE01",
        "booking_sn": "",
        "order_status": "SHIPPED"
      },
      {
        "order_sn": "2610220ABCDE02",
        "booking_sn": "",
        "order_status": "READY_TO_SHIP"
      }
    ]
  },
  "request_id": "e3e3e7f35e8f6a9a…"
}

Mã lỗi của Shopee (12)

Bấm để xem
MãÝ nghĩa
error_not_foundKhông tìm thấy đơn / gói / yêu cầu theo mã đã gửi.
error_paramTham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào.
error_permissionGian hàng không có quyền xem dữ liệu này (vd yêu cầu trả / đơn không thuộc gian hàng).
error_serverLỗi hệ thống Shopee — thử lại sau ít phút.
order.order_list_invalid_timetime_from phải nhỏ hơn time_to và cách nhau không quá 15 ngày.
error_dataDữ liệu không tồn tại hoặc không hợp lệ cho thao tác (vd mã không có, loại yêu cầu không cho phép).
error_shopGian hàng không hợp lệ — kiểm tra platform_shop_id.
error_authỦy quyền gian hàng cho 360 đã hết hạn hoặc bị thu hồi (360 đã tự làm mới token một lần) — chủ gian hàng kết nối lại Shopee trong Partner.
error_limitChạm hạn mức gọi Shopee trong ngày của kết nối — 360 trả kèm thời điểm thử lại; giảm tần suất gọi.
error_rate_limitGọi quá nhanh — chờ vài giây rồi gọi lại (360 cũng giới hạn theo key: 429 + Retry-After).
shop_bannedGian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa.
error_kyc_authGian hàng chưa hoàn tất đăng ký người bán trên Kênh Người Bán.

Bắt đầu dùng

  1. Đăng ký tài khoản Partner
  2. Mở loại dữ liệu thuộc nhóm Đơn hàng ở trang nền tảng
  3. Tạo API key (tick kênh Shopee)
  4. Gọi theo ví dụ ở trên