Đổ đơn Shopee, TikTok Shop vào MySQL / PostgreSQL

Bài toán: vì sao doanh nghiệp cần đơn sàn trong CSDL của riêng mình?

Vì báo cáo quản trị thật cần ghép đơn sàn với dữ liệu chỉ doanh nghiệp có: giá vốn, kế hoạch bán, công nợ, lương thưởng theo doanh số. Việc ghép đó làm trong cơ sở dữ liệu của bạn, không làm được trên trang của sàn.

Cách phổ biến là thuê người viết script gọi API sàn. Script chạy được vài tuần, rồi dừng vì token hết hạn, vì sàn đổi phiên bản API, hoặc vì người viết nghỉ việc. Một cách khác là nhập file tay mỗi tuần, nghĩa là kho dữ liệu luôn trễ một tuần.

Partner Quantri360 nhận phần giữ app, token và chuẩn hóa. Bạn chỉ giữ bảng.

Tư duy dẫn đường: cần dữ liệu nào, đọc thế nào cho đúng?

Bảng nhận về là dạng phẳng: mỗi dòng một sản phẩm trong đơn, cột của đơn lặp lại ở mọi dòng. Hiểu cấu trúc này trước khi viết câu truy vấn đầu tiên.

Nhóm cột	Ví dụ	Mức
Khóa	`platform`, `platform_shop_id`, `order_id`, `item_line_id`	dòng
Trạng thái, thời điểm	`status`, `created_at`, `delivered_at` (UTC)	đơn
Tiền của đơn	`subtotal`, `platform_fee`, `escrow_amount`	đơn
Tiền của dòng	`item_quantity`, `item_unit_sale_price`, `item_line_voucher`	dòng
Thời điểm ghi	`_synced_at`	dòng

Kiểu cột do hệ thống đặt: tiền DECIMAL(18,2) (PostgreSQL NUMERIC), thời điểm DATETIME(3) / TIMESTAMPTZ / DATETIME2(3), JSON là JSON / JSONB / NVARCHAR(MAX).

Ba bẫy làm sai số trên dashboard:

SUM cột mức đơn là cộng trùng. Đơn có 3 sản phẩm thì escrow_amount lặp 3 dòng. SUM(escrow_amount) trên toàn bảng ra gấp ba. Cột mức đơn phải gộp theo đơn trước (MAX theo order_id), cột mức dòng mới SUM.
Ô trống không phải số 0. platform_fee, escrow_amount để trống khi sàn chưa quyết toán. COALESCE(x, 0) biến "chưa biết" thành "miễn phí", đối soát sẽ báo khớp sai.
Giờ lưu là UTC. Báo cáo theo ngày Việt Nam phải cộng 7 giờ trước khi cắt ngày, nếu không đơn từ 0h tới 7h sáng rơi sang ngày hôm trước.

Khóa dòng dùng item_line_id (mã dòng do sàn cấp), không dùng số thứ tự dòng. Đơn hủy một phần thì "dòng thứ 2" lần sau có thể là sản phẩm khác; khóa theo thứ tự sẽ ghi đè nhầm.

AI bứt tốc: thiết lập trong bao lâu, gồm những bước nào?

Khoảng 30 phút, phần lâu nhất là tạo user CSDL và mở tường lửa. Không cần viết code ghi dữ liệu.

Chuẩn bị CSDL: tạo một database riêng và một user chỉ có quyền trên database đó (CREATE, ALTER, SELECT, INSERT, UPDATE, DELETE). Máy chủ phải có địa chỉ công khai. Gửi tên miền hoặc IP máy chủ để Quantri360 duyệt vào danh sách được phép của brand.
Đăng ký ở Partner Quantri360, ủy quyền gian hàng ở TikTok Shop hoặc Shopee.
Đích nhận → MySQL, PostgreSQL hoặc SQL Server: nhập host, cổng, database, user, mật khẩu, tên bảng, chế độ SSL. Mật khẩu được mã hóa và không hiện lại. Bấm Kiểm tra: hệ thống chỉ đọc phiên bản và quyền, báo thiếu quyền nếu có.
Kết nối: chọn nền tảng → loại đơn → đích → lịch mỗi giờ, hằng ngày hoặc hằng tuần.

Lần chạy đầu tự tạo bảng với khóa chính đúng 4 cột khóa. Các lần sau thêm cột còn thiếu, ghi đè dòng trùng khóa, và xóa dòng hàng không còn trong đơn vừa giao (tắt được ở form đích). Lịch tự động là phần mua thêm, xem bảng giá.

Tình trạng loại dữ liệu: đơn TikTok Shop và Nhanh.vn đã xử lý đã dùng được. Đơn Shopee đã xử lý đang "Sắp có"; loại thô dùng được, mỗi dòng một đơn với cột raw_json giữ nguyên phản hồi Shopee. Có cả đích BigQuery cho ai dùng Google Cloud.

Truy vấn doanh thu theo ngày giờ Việt Nam, đúng mức đơn (MySQL):

SELECT DATE(created_at + INTERVAL 7 HOUR) AS ngay, COUNT(*) AS don, SUM(escrow) AS tien_ve
FROM (SELECT order_id, MIN(created_at) created_at, MAX(escrow_amount) escrow
      FROM don_san WHERE status NOT IN ('cancelled','delivery_failed') GROUP BY order_id) d
GROUP BY ngay ORDER BY ngay;

Dùng AI viết truy vấn. Dán cấu trúc bảng (SHOW CREATE TABLE) cho ChatGPT hoặc Claude kèm luật:

"Bảng này mỗi dòng một SKU, cột subtotal, platform_fee, escrow_amount là mức đơn và lặp ở mọi dòng. Giờ lưu UTC. Viết truy vấn PostgreSQL: tỉ lệ giao thất bại theo tỉnh và theo tuần (giờ Việt Nam), 8 tuần gần nhất. Không thay giá trị NULL bằng 0."

Nêu rõ mức của từng cột là cách đơn giản nhất để AI không cộng trùng.

Kết quả đo được

Ba chỉ số dưới đây đo được ngay trong CSDL của bạn. Không cần số liệu từ bên ngoài.

Độ trễ: NOW() - MAX(_synced_at) cho biết lần ghi gần nhất cách bao lâu. Lịch mỗi giờ thì dưới khoảng một giờ.
Độ đầy đủ: so số đơn trong bảng với số đơn trên trang người bán cùng kỳ; nhật ký chạy của kết nối ghi số đơn và lỗi mỗi lần.
Sai lệch phát hiện: chênh giữa SUM(escrow_amount) thô và tổng theo đơn cho thấy báo cáo cũ đã cộng trùng bao nhiêu.

Không có CSDL riêng? Bắt đầu bằng Google Sheets cho đơn TikTok Shop hoặc Shopee. Cần tự lấy thêm API ngoài bảng đơn, xem Shopee với n8n.

API liên quan

get_order_list (Shopee): nguồn danh sách đơn Shopee thay đổi theo cửa sổ.
get_escrow_detail (Shopee): nguồn của tiền thực nhận và phí từng đơn.
orders/search (TikTok Shop): danh sách đơn TikTok Shop theo khoảng thời gian.
price_detail (TikTok Shop): chiết khấu và voucher theo dòng.
order/list (Nhanh.vn): đơn Nhanh.vn theo ngày cập nhật.

Đọc thêm: tự động hóa quy trình kinh doanh — bài tổng quan của chủ đề này.

Đổ đơn Shopee, TikTok Shop vào MySQL, PostgreSQL, SQL Server tự động