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_no1-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_idlà 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ên | Vị trí | Kiểu | Mẫu | Mô tả |
|---|---|---|---|---|
| Authorization | header | header | Bearer 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_id | query | string | 100001 | Gian 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ên | Vị trí | Kiểu | Bắt buộc | Mẫu | Mô tả |
|---|---|---|---|---|---|
| page_no | query | int | Có | 1 | Trang, bắt đầu từ 1 (gửi 0 cũng ra trang 1 — xem ghi chú). |
| page_size | query | int | Có | 100 | Số giao dịch mỗi trang, tối đa 100. |
| create_time_from | query | timestamp | Không | 1792602000 | Từ thời điểm (Unix giây). |
| create_time_to | query | timestamp | Không | 1793250000 | Đế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_flow | query | string | Không | MONEY_OUT | MONEY_IN = chỉ khoản cộng · MONEY_OUT = chỉ khoản trừ; bỏ trống = cả hai. |
| transaction_type | query | string | Không | ESCROW_VERIFIED_ADD | Lọc theo một loại giao dịch (xem transaction_type ở phản hồi). |
| transaction_tab_type | query | string | Không | wallet_order_income | Lọc theo tab: wallet_order_income · wallet_adjustment_filter · wallet_wallet_payment · wallet_refund_from_order · wallet_withdrawals… CHỈ một giá trị. |
| wallet_type | query | string | Không | shopee_pay | Loạ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ên | Kiểu | Mẫu | Mô tả |
|---|---|---|---|
| request_id | string | d52ca43b277a4f9292fb8be658bfd33d | Mã request của Shopee để tra lỗi. |
| error | string | Mã lỗi Shopee; rỗng = thành công. | |
| message | string | Mô tả lỗi. | |
| response | object | ||
| more | bool | true | Còn trang sau. |
| transaction_list | object[] | Mới nhất trước. | |
| transaction_id | int64 | 255438473064878370 | Mã giao dịch — số 18 chữ số (xem ghi chú về số lớn). |
| transaction_type | string | ESCROW_VERIFIED_ADD | Loạ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)… |
| amount | float | 187264 | Số tiền (VND): dương = cộng vào ví, âm = trừ. |
| current_balance | float | 1580000 | Số dư ví sau giao dịch. |
| money_flow | string | MONEY_IN | MONEY_IN · MONEY_OUT. |
| transaction_tab_type | string | wallet_order_income | Tab trên Kênh Người Bán. |
| status | string | COMPLETED | COMPLETED · PENDING · FAILED · INITIAL. |
| create_time | timestamp | 1793248394 | Thời điểm giao dịch. |
| order_sn | string | 2610230ABCDE15 | Mã đơn (rỗng với giao dịch cấp ví: quảng cáo, rút tiền…). |
| refund_sn | string | Mã trả hàng (nếu có). | |
| description | string | Doanh Thu từ Đơn Hàng #2610230ABCDE15 | Mô tả tiếng Việt. |
| buyer_name | string | nguoimua123 | Tên tài khoản người mua. |
| wallet_type | string | shopee_pay | Loại ví. |
| reason | string | Lý do (điều chỉnh). | |
| withdrawal_id | int | 0 | Mã lệnh rút (giao dịch WITHDRAWAL_*). |
| withdrawal_type | string | ||
| root_withdrawal_id | int | 0 | Lệnh rút gốc khi một lệnh bị tách nhiều phần. |
| transaction_fee | float | 0 | Phí giao dịch. |
| pay_order_list | object[] | [] | … |
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_data | Dữ 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_param | Tham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào. |
| error_server | Lỗi hệ thống Shopee — thử lại sau ít phút. |
| error_shop | Gian hàng không hợp lệ — kiểm tra platform_shop_id. |
| time_period_too_large | The param error: time period too large. |
| time_invalid | The 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_limit | Chạ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_limit | Gọ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_banned | Gian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa. |
| error_kyc_auth | Gian 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
- Đăng ký tài khoản Partner
- Mở loại dữ liệu thuộc nhóm Tài chính / đối soát ở trang nền tảng
- Tạo API key (tick kênh Shopee)
- Gọi theo ví dụ ở trên