INTEGRATIONS.md — thegioikeycap.vn
Các hệ thống ngoài đang nối vào site.
| Hệ thống | Vai trò | Trạng thái |
|---|---|---|
| Pancake POS | Quản lý sản phẩm, giá, tồn kho | ✅ Đang chạy — WC REST key + 3 webhook đơn hàng |
| SePay | Cổng thanh toán chuyển khoản QR | ✅ Đang chạy |
| Brevo | Gửi email giao dịch | ✅ Đang chạy qua FluentSMTP — xem MAIL.md |
| Meta | Pixel + Conversions API | ✅ Đang chạy — plugin tgk-tracking, xem TRACKING.md |
| Cloudflare Turnstile | CAPTCHA đăng nhập/đăng ký | ✅ Đang chạy |
| Nextend (Google) | Đăng nhập mạng xã hội | ✅ Đang chạy (Facebook đã bỏ) |
| AllinGo | Tra cước vận chuyển | ⏳ Code sẵn, CHƯA BẬT |
Pancake POS
Ranh giới đồng bộ — chỉ 4 thứ
Theo tài liệu Pancake, kết nối này đồng bộ đúng 4 thứ:
- Tồn kho POS → Woo
- Giá bán POS → Woo
- Đơn hàng Woo → POS
- Tồn kho tổng nhiều kho
KHÔNG đồng bộ: khuyến mại, voucher, mã giảm giá, khách hàng, bài viết.
⚠️ Pancake là nguồn thật của giá và tồn kho. Sửa ở WooCommerce sẽ bị ghi đè ở lần đồng bộ sau.
Khớp sản phẩm bằng SKU
Pancake khớp sản phẩm bằng SKU = trường display_id của biến thể.
Đây cũng là Content ID của Facebook catalog (Pancake đẩy feed lên Meta), nên
TGK_Events::content_id() phải trả đúng SKU — xem TRACKING.md.
Hiện khớp 36/36 biến thể. Lịch sử: 06/09/2026 đã sửa display_id của 3 biến
thể bên Pancake (KC001→KC0002, KC003→KC0003, KC004→KC0004) qua
PUT /products/{id} với custom_id.
Webhook — một lỗ hổng cần biết
Đẩy đơn Woo → POS chạy qua plugin send-app với 3 webhook.
⚠️ order.deleted chưa từng bắn lần nào (date_modified vẫn là ngày tạo
webhook 2025-06-24). Xoá đơn bên Woo thì Pancake vẫn giữ đơn và vẫn trừ kho.
Phải huỷ thủ công: PUT /shops/{shop}/orders/WOO{id} với {"status":6}
(status 6 = Đã huỷ).
Đây là lý do quy trình test đơn có bước 5 và bước 6 — xem TASK_PROTOCOL.md.
Open API
85 endpoint. Không có endpoint tính cước vận chuyển — đó là lý do phải nối AllinGo riêng.
Secret: PANCAKE_API_KEY, PANCAKE_SHOP_ID trong .secrets.env.
Mã giảm giá — Pancake KHÔNG đồng bộ sang WooCommerce
Kiểm chứng 06/09/2026: Pancake có 1 khuyến mại ("Giảm giá", đang tắt), Woo có 0 mã — không cái nào chảy sang cái nào.
Chạy chương trình trên cả web lẫn tin nhắn thì phải tạo mã hai lần, mỗi bên một mã cùng tên cùng mức giảm.
Mã cho khách web tạo ở Marketing → Phiếu giảm giá. Ô nhập mã đã có sẵn ở trang thanh toán (dưới bảng đơn hàng, áp bằng AJAX) và ở giỏ hàng — mã áp ở giỏ vẫn giữ khi sang checkout.
Mã đang có: KEYCAP30 — giảm 30.000đ, fixed_cart, giới hạn 1 lần/người,
individual_use (không cộng dồn).
Đơn có mã giảm hiện thế nào bên Pancake
Đo bằng đơn test thật (350.000 − 30.000 = 320.000đ):
| Trường Pancake | Giá trị | |
|---|---|---|
total_price |
350.000 | giá gốc |
total_discount |
0 | ⚠️ ô tổng giảm giá để trống |
total_price_after_sub_discount |
320.000 | đúng |
cod |
320.000 | đúng — vận đơn thu đúng tiền |
discount_each_product (dòng SP) |
30.000 | giảm giá nằm ở ĐÂY |
note |
Mã ưu đãi: keycap30 |
tên mã chỉ nằm trong ghi chú |
Tiền thì đúng, nhưng hai hệ quả về báo cáo:
- Báo cáo "tổng tiền giảm giá" trong POS không tính đơn từ web vì
total_discount = 0. Muốn biết mã ăn bao nhiêu thì xem ở WooCommerce (Marketing → Phiếu giảm giá có cột số lần dùng). - Không lọc/thống kê được theo mã trong POS — tên mã chỉ là chữ trong ghi chú, không có trường riêng.
Hai cảnh báo khi tạo mã
⚠️ Đừng dùng mã giảm theo phần trăm không giới hạn. Giá đang đồng bộ
Pancake→Woo; đổi giá bên POS là giá Woo tự đổi theo, mã -20% vẫn chạy trên giá
mới và ăn sâu hơn dự tính. Dùng số tiền cố định, hoặc đặt mức giảm tối đa.
⚠️ WooCommerce không có điều kiện "đơn hàng đầu tiên". Tuỳ chọn "Giới hạn sử
dụng cho mỗi người dùng = 1" chỉ chặn dùng lại lần hai — khách đã mua 20 đơn vẫn
xài được lần đầu của họ. Muốn đúng nghĩa đơn đầu tiên thì phải viết thêm code
kiểm lịch sử mua theo cả user_id lẫn billing_email (khách có thể mua lần
đầu với tư cách vãng lai).
Vận chuyển — Bảng giá SPX theo cân nặng (AllinGo)
Website vận hành gửi hàng thực tế bằng SPX Express (Shopee Express). SPX áp dụng chính sách đồng giá toàn quốc không phân biệt cự ly tuyến hay địa giới hành chính.
Hệ thống tính cước trực tiếp từ bảng giá nội bộ theo cân nặng trong code
(inc/shipping.php), KHÔNG gọi API lúc checkout để đảm bảo tốc độ tối đa,
tránh gián đoạn giao dịch khi mạng chập chờn và không bị phụ thuộc vào sự lệch pha
giữa địa giới 34 tỉnh mới (của website) và 63 tỉnh cũ (của các hãng ship).
Bảng cước SPX áp dụng cho khách hàng
| Tổng cân nặng giỏ hàng | Mức cước chuẩn | Ghi chú |
|---|---|---|
| $\le 0,5$ kg (1 bộ keycap) | 15.000 ₫ | Khớp 100% cước SPX AllinGo |
| $0,5 < w \le 2,0$ kg (2 bộ keycap, bàn phím) | 18.000 ₫ | Khớp cước SPX AllinGo |
| $2,0 < w \le 3,0$ kg | 22.000 ₫ | Khớp cước SPX AllinGo |
| $3,0 < w \le 4,0$ kg | 26.000 ₫ | Khớp cước SPX AllinGo |
| $4,0 < w \le 5,0$ kg | 30.000 ₫ | Khớp cước SPX AllinGo |
| $> 5,0$ kg | 30.000 ₫ + 4.000 ₫/kg | Làm tròn lên theo từng kg phát sinh |
| Đơn hàng từ 500.000 ₫ | Miễn phí (0 ₫) | Shop chịu cước theo cam kết Freeship topbar |
| Giao hỏa tốc HCM (2–4h) | 0 ₫ (Shop gọi báo cước) | Đơn $\ge 500K$ giảm 30.000 ₫ cước hỏa tốc |
Thời gian giao hàng dự kiến (ETA)
Bảng ETA theo 34 tỉnh/thành mới được sinh tự động và lưu tại data/spx-eta.json
(bằng script scripts/generate_spx_eta.py, lấy từ API AllinGo Live rồi cộng thêm
+1 ngày chuẩn bị hàng). Nhãn hiển thị: Giao tiêu chuẩn SPX (X–Y ngày).
- TP.HCM, Cần Thơ, Miền Tây: 1–2 ngày.
- Đà Nẵng, Miền Trung, Tây Nguyên: 2–3 ngày.
- Hà Nội, đồng bằng Bắc Bộ: 3–4 ngày.
- Vùng cao / miền núi phía Bắc: 3–5 ngày hoặc 4–6 ngày.
Công cụ đối soát cước AllinGo Live
Khi cần đối chiếu lại biểu phí thực tế mà AllinGo/SPX trừ tiền trong ví với bảng giá trong code:
python3 scripts/check_spx_rates.py
Script sẽ hỏi AllinGo Live (ví wallet) qua 3 tuyến tiêu biểu (Nội thành HCM,
Liên tỉnh Hà Nội, Tỉnh xa Cà Mau) ở các mốc từ 0,5kg đến 6kg và in bảng chênh lệch.
⚠️ Lưu ý kỹ thuật AllinGo:
- AllinGo bắt buộc tham số delivery_payment_method: "wallet" thì mới trả về báo
giá của SPX, GHN, J&T, Best, VNPost. Nếu gửi "cash", AllinGo chỉ trả Viettel Post
và Nhất Tín.
- AllinGo vẫn yêu cầu địa chỉ 3 cấp cũ (Tỉnh/Thành, Quận/Huyện, Phường/Xã) mới báo giá được.
SePay
Cổng thanh toán chuyển khoản QR. Plugin sepay-gateway.
⚠️ Template woocommerce/checkout/thankyou.php phải giữ nguyên cả hai lệnh
do_action — SePay móc mã QR vào đó. Bỏ một cái là khách không thấy QR để trả
tiền.
Việc còn treo
- AllinGo: gửi app duyệt live, giải bài toán geocode
lat/lng, đối chiếu cước thật (đặc biệt tỉnh đã sáp nhập), rồi mới tạo zone. - Cân thử một hộp bàn phím LEOBOG để xác nhận 1,8 / 2,0 kg.
- Xoay key đã đi qua chat: Meta CAPI, Cloudflare, Brevo, AllinGo, Turnstile.
- LEOBOG trong Commerce Manager đang báo Status "Missing" — cần kiểm tra feed.