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

Lấy lịch sử giao dịch ví người bán — API Shopee

v2.payment.get_wallet_transaction_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.payment.get_wallet_transaction_list

GET/api/v2/payment/get_wallet_transaction_listGọi qua 360: GET https://partner.quantri360.com/v1/shopee/api/v2/payment/get_wallet_transaction_list
Mô tả API

Sổ giao dịch VÍ NGƯỜI BÁN Shopee (Số dư → Giao dịch): mọi bút toán cộng / trừ — tiền đơn về, tiền Shopee đòi lại khi khách hoàn hàng, phí quảng cáo, điều chỉnh, rút tiền… kèm số dư sau giao dịch. Nguồn đầy đủ nhất để đối soát tiền thật (get_income_detail chỉ có bút toán cộng). Chỉ gian hàng nội địa.

  • Khoảng thời gian quá dài → error: "wallet.time_invalid", message "The param error: time period too large." — chia đoạn ≤ 13 ngày.
  • page_no 1-BASED: page_no = 0 và 1 trả Y HỆT một trang. Bắt đầu từ 0 rồi tăng dần sẽ lấy trùng trang 1 và dừng sớm.
  • Không lọc theo danh sách transaction_type cố định: thực tế có nhiều loại ngoài danh sách thường gặp (ADJUSTMENT_FOR_RR_AFTER_ESCROW_VERIFIED, SPM_DEDUCT…). Lưu thô mọi loại.
  • Một đơn có thể có NHIỀU bút toán (cộng khi quyết toán, trừ khi hoàn hàng) — khử trùng theo transaction_id, KHÔNG theo order_sn.
  • WITHDRAWAL_* là shop rút tiền của mình về ngân hàng, không phải chi phí — loại ra khi tính lãi lỗ.
  • transaction_id là số 18 chữ số, vượt giới hạn số nguyên an toàn của JavaScript (2^53): 360 trả nguyên văn phản hồi của Shopee, nhưng phía bạn parse bằng JSON.parse thông thường sẽ làm tròn các chữ số cuối (…549369 → …549380) — dùng bộ phân tích giữ số lớn hoặc đọc trường này dạng chuỗi.
  • Chỉ gian hàng nội địa (gian hàng xuyên biên giới dùng get_payout_info).

Request

Địa chỉ

GET https://partner.quantri360.com/v1/shopee/api/v2/payment/get_wallet_transaction_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ả
page_noqueryintCó1Trang, bắt đầu từ 1 (gửi 0 cũng ra trang 1 — xem ghi chú).
page_sizequeryintCó100Số giao dịch mỗi trang, tối đa 100.
create_time_fromquerytimestampKhông1792602000Từ thời điểm (Unix giây).
create_time_toquerytimestampKhông1793250000Đến thời điểm (Unix giây) — khoảng tối đa khoảng 2 tuần (dùng ≤ 13 ngày cho chắc).
money_flowquerystringKhôngMONEY_OUTMONEY_IN = chỉ khoản cộng · MONEY_OUT = chỉ khoản trừ; bỏ trống = cả hai.
transaction_typequerystringKhôngESCROW_VERIFIED_ADDLọc theo một loại giao dịch (xem transaction_type ở phản hồi).
transaction_tab_typequerystringKhôngwallet_order_incomeLọc theo tab: wallet_order_income · wallet_adjustment_filter · wallet_wallet_payment · wallet_refund_from_order · wallet_withdrawals… CHỈ một giá trị.
wallet_typequerystringKhôngshopee_payLoại ví.

Phân trang

Tăng page_no (1, 2, 3…) khi response.more = true; khử trùng theo transaction_id.

Ví dụ request

curl -s "https://partner.quantri360.com/v1/shopee/api/v2/payment/get_wallet_transaction_list?page_no=1&page_size=100&create_time_from=1792602000&create_time_to=1793250000" \
  -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/payment/get_wallet_transaction_list",
    params={
        "page_no": 1,
        "page_size": 100,
        "create_time_from": 1792602000,
        "create_time_to": 1793250000
    },
    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/payment/get_wallet_transaction_list');
for (const [k, v] of Object.entries({"page_no":1,"page_size":100,"create_time_from":1792602000,"create_time_to":1793250000})) 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/payment/get_wallet_transaction_list' . '?' . http_build_query(['page_no' => 1, 'page_size' => 100, 'create_time_from' => 1792602000, 'create_time_to' => 1793250000]);
$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.
responseobject
morebooltrueCòn trang sau.
transaction_listobject[]Mới nhất trước.
transaction_idint64255438473064878370Mã giao dịch — số 18 chữ số (xem ghi chú về số lớn).
transaction_typestringESCROW_VERIFIED_ADDLoại: ESCROW_VERIFIED_ADD (tiền đơn về) · ESCROW_VERIFIED_MINUS (đơn quyết toán âm) · ADJUSTMENT_FOR_RR_AFTER_ESCROW_VERIFIED (đòi lại khi hoàn hàng sau quyết toán) · SPM_DEDUCT (trừ tiền quảng cáo) · AMS_COMMISSION_FEE_DEDUCT · FSF_COST_PASSING_DEDUCT · ADJUSTMENT_CENTER_ADD / _DEDUCT · WITHDRAWAL_CREATED / _COMPLETED / _CANCELLED (rút tiền)…
amountfloat187264Số tiền (VND): dương = cộng vào ví, âm = trừ.
current_balancefloat1580000Số dư ví sau giao dịch.
money_flowstringMONEY_INMONEY_IN · MONEY_OUT.
transaction_tab_typestringwallet_order_incomeTab trên Kênh Người Bán.
statusstringCOMPLETEDCOMPLETED · PENDING · FAILED · INITIAL.
create_timetimestamp1793248394Thời điểm giao dịch.
order_snstring2610230ABCDE15Mã đơn (rỗng với giao dịch cấp ví: quảng cáo, rút tiền…).
refund_snstringMã trả hàng (nếu có).
descriptionstringDoanh Thu từ Đơn Hàng #2610230ABCDE15Mô tả tiếng Việt.
buyer_namestringnguoimua123Tên tài khoản người mua.
wallet_typestringshopee_payLoại ví.
reasonstringLý do (điều chỉnh).
withdrawal_idint0Mã lệnh rút (giao dịch WITHDRAWAL_*).
withdrawal_typestring
root_withdrawal_idint0Lệnh rút gốc khi một lệnh bị tách nhiều phần.
transaction_feefloat0Phí giao dịch.
pay_order_listobject[][]…

Mẫu phản hồi

{
  "request_id": "e3e3e7f35ef6ccdf…",
  "error": "",
  "message": "",
  "response": {
    "more": true,
    "transaction_list": [
      {
        "transaction_id": 255438473064878370,
        "status": "COMPLETED",
        "wallet_type": "shopee_pay",
        "transaction_type": "ESCROW_VERIFIED_ADD",
        "amount": 187264,
        "current_balance": 1580000,
        "create_time": 1793248394,
        "reason": "",
        "order_sn": "2610230ABCDE15",
        "refund_sn": "",
        "withdrawal_type": "",
        "transaction_fee": 0,
        "description": "Doanh Thu từ Đơn Hàng #2610230ABCDE15",
        "buyer_name": "nguoimua123",
        "pay_order_list": [],
        "withdrawal_id": 0,
        "root_withdrawal_id": 0,
        "transaction_tab_type": "wallet_order_income",
        "money_flow": "MONEY_IN",
        "outlet_shop_name": "",
        "txn_title": ""
      },
      {
        "transaction_id": 255374970748670980,
        "status": "COMPLETED",
        "wallet_type": "shopee_pay",
        "transaction_type": "ESCROW_VERIFIED_MINUS",
        "amount": -2700,
        "current_balance": 1590000,
        "create_time": 1793210544,
        "reason": "",
        "order_sn": "2610190ABCDE09",
        "refund_sn": "",
        "withdrawal_type": "",
        "transaction_fee": 0,
        "description": "Doanh Thu từ Đơn Hàng #2610190ABCDE09",
        "buyer_name": "nguoimua456",
        "pay_order_list": [],
        "withdrawal_id": 0,
        "root_withdrawal_id": 0,
        "transaction_tab_type": "wallet_order_income",
        "money_flow": "MONEY_OUT",
        "outlet_shop_name": "",
        "txn_title": ""
      }
    ]
  }
}

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

Bấm để xem
MãÝ nghĩa
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_paramTham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào.
error_serverLỗi hệ thống Shopee — thử lại sau ít phút.
error_shopGian hàng không hợp lệ — kiểm tra platform_shop_id.
time_period_too_largeThe param error: time period too large.
time_invalidThe param error: create_time_from bigger than create_time_to.
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 Tài chính / đối soát ở trang nền tảng
  3. Tạo API key (tick kênh Shopee)
  4. Gọi theo ví dụ ở trên