Hướng dẫn tích hợp Sapo & Shopee với OpsOne AI

Khi anh/chị bán hàng đa kênh (cửa hàng Sapo, Shopee, Zalo, web), việc nhập tay từng đơn vào OpsOne AI rất tốn thời gian và dễ sai. Tài liệu này hướng dẫn anh/chị thiết lập tích hợp 2 chiều để OpsOne AI tự động kéo đơn từ Sapo về, đẩy trạng thái thanh toán ngược lại, và đồng bộ tồn kho — chỉ cấu hình 1 lần, chạy mãi.

1. Tại sao phải tích hợp?

Nếu anh/chị đang dùng Sapo POS hoặc Sapo Omnichannel (cửa hàng + Shopee + Lazada + TikTok Shop), thì Sapo là nơi nhận đơn. Còn OpsOne AI là nơi anh/chị quản trị tổng thể: công nợ, dòng tiền, kế toán, kho, báo cáo lãi lỗ. Hai hệ phải kết nối, nếu không sẽ xảy ra 3 vấn đề:

• Nhập tay đơn 2 lần — nhân viên gõ lại đơn Sapo vào OpsOne, mỗi ngày 50-200 đơn = mất 2-3 giờ và sai sót.
• Tồn kho lệch — Sapo bán ra nhưng OpsOne không trừ kho → kế toán không biết hàng còn bao nhiêu.
• Công nợ lệch — khách thanh toán trên Sapo nhưng OpsOne vẫn ghi "Chưa thu" → đòi nợ nhầm khách.

Tích hợp Sapo + OpsOne giải quyết cả ba: đơn tự sync về OpsOne theo nhịp anh/chị đặt (TBBV đang để 15 phút), thanh toán đẩy ngược lên Sapo, tồn kho cập nhật 2 chiều.

2. Thuật ngữ cần nhớ

3. Tích hợp Sapo từng bước

3.1. Lấy API key + Access Token từ Sapo admin

1. Đăng nhập trang admin Sapo của anh/chị (vd https://abc.mysapo.vn/admin).
2. Vào menu Cấu hình → Thiết lập cửa hàng → API (hoặc Quản lý ứng dụng tuỳ phiên bản Sapo).
3. Bấm Tạo ứng dụng mới → đặt tên (ví dụ "OpsOne AI Integration") → cấp quyền: Đơn hàng (read/write), Khách hàng (read), Sản phẩm (read), Tồn kho (read/write).
4. Sapo sinh ra 2 mã: API Key và Access Token. Copy cả hai vào nơi an toàn (không gửi qua chat).
5. Ghi nhớ thêm tên miền cửa hàng (subdomain trước .mysapo.vn) — đây là sapo_store.

3.2. Điền credentials vào OpsOne

1. Đăng nhập app.opsoneai.com bằng tài khoản admin của project.
2. Vào Cài đặt (bánh răng góc dưới sidebar) → tab Tích hợp.
3. Khu vực Sapo, điền 3 trường:
   • sapo_store — tên miền cửa hàng Sapo (vd abc nếu shop là abc.mysapo.vn).
   • sapo_api_key — API Key vừa lấy.
   • sapo_token — Access Token vừa lấy.
4. Bấm Lưu. OpsOne mã hóa và lưu vào DB, không hiển thị lại token sau khi lưu.

3.3. Bật cờ sapo_enabled

Sau khi điền credentials, anh/chị cần bật cờ sapo_enabled = 1 cho project. Có 2 cách:

• UI: trong tab Tích hợp có toggle "Kích hoạt đồng bộ Sapo" — bật lên.
• Super admin: nếu là tenant mới, super admin (tenant_id=1) sẽ bật giúp.

3.4. Test kết nối

1. Vẫn ở tab Tích hợp, bấm nút "Test kết nối".
2. Nếu trả về OK + số đơn hàng 7 ngày gần nhất → cấu hình đúng.
3. Nếu trả về 401 Unauthorized → token sai hoặc hết hạn, lấy lại từ Sapo.
4. Nếu trả về 403 Forbidden → app Sapo chưa cấp đủ quyền (vào lại bước 3.1, mở thêm scope).
5. Nếu timeout → IP server có thể đang bị Sapo block, liên hệ support OpsOne.

4. Pull đơn từ Sapo

Sau khi bật sapo_enabled, OpsOne tự động chạy Scheduler kéo đơn về theo nhịp sapo_sync_interval. ⚠️ Ô này mặc định 0 = TẮT, nên phải đặt một số phút (TBBV đang để 15) — bật sapo_enabled một mình thì Scheduler chưa kéo gì.

Cơ chế hoạt động

• Scheduler gọi API GET /orders.json của Sapo với filter created_on_min = lần Pull gần nhất.
• Mỗi đơn mới được insert vào bảng orders của OpsOne với:
  • sapo_id = ID đơn trên Sapo (dùng để chống trùng).
  • source = 'sapo' để báo nguồn gốc.
  • payment_status map từ Sapo: paid → "Đã thanh toán", partially_paid → "Thanh toán 1 phần", pending → "Chưa thanh toán".
  • items (JSON) chứa danh sách sản phẩm + giá + số lượng (lưu ý: OpsOne không tách thành order_items riêng).
• Đơn đã sync rồi sẽ bị skip (check sapo_id đã tồn tại) — không sợ duplicate.

Đồng bộ thủ công (nếu cần kéo gấp)

Nếu anh/chị không muốn chờ tới nhịp kế tiếp (ví dụ vừa có đơn cao điểm cần xử lý ngay):

1. Vào module CRM → tab Đơn hàng.
2. Bấm nút "Đồng bộ Sapo ngay" ở góc phải.
3. Hệ thống chạy Pull ngay lập tức, hiện thông báo "Đã sync X đơn mới" trong 5-30 giây.

5. Push transaction (thanh toán) lên Sapo

Đây là phần "2 chiều" quan trọng nhất. Khi anh/chị thu tiền 1 đơn Sapo trong OpsOne, hệ thống sẽ tự đẩy giao dịch thanh toán đó ngược về Sapo để Sapo cập nhật financial_status = paid.

Điều kiện kích hoạt Push

• Phiếu nhận tiền (Receipt) đã được Approve trong OpsOne.
• Đơn liên quan có sapo_id != null (tức đơn nguồn gốc Sapo).
• Project có sapo_enabled = 1 và credentials hợp lệ.

Luồng Push

Push thất bại — xử lý thế nào?

• Nếu Push lỗi (network, token hết hạn), phiếu nhận tiền vẫn được approve thành công trong OpsOne — lỗi push chỉ log lại, không rollback.
• Anh/chị có thể bấm "Đẩy lại lên Sapo" ở chi tiết phiếu (sau khi xử lý nguyên nhân).
• Scheduler retry tự động sau 15 phút nếu lỗi tạm thời.

6. Đồng bộ tồn kho

Khi đơn Sapo về OpsOne, hệ thống đồng thời sinh các bản ghi trong bảng stock_transactions để Module Kho biết phải trừ tồn kho bao nhiêu sản phẩm.

Quy tắc sinh stock_transactions

• Scheduler quét các đơn có sapo_id IS NOT NULL (KHÔNG dùng source = 'sapo' — đây là điểm khác biệt quan trọng).
• Mỗi item trong đơn → 1 dòng stock_transactions (loại "xuất bán").
• Dữ liệu này được Module Phân tích kho dùng để tính tốc độ bán, sản phẩm bán chạy, dự báo cần nhập thêm.

Nếu Module Phân tích kho hiển thị số sai

1. Kiểm tra Scheduler có chạy không: vào Cài đặt → Scheduler status.
2. Chạy thủ công lệnh re-build stock_transactions từ tab Tích hợp.
3. Nếu vẫn sai, liên hệ support — có thể cần backfill từ đơn cũ.

7. Tích hợp Shopee (và các sàn khác)

Cách 1 — Qua Sapo Omnichannel (khuyến nghị)

Đây là cách hoạt động ngay hôm nay:

1. Anh/chị bật Sapo Omnichannel và kết nối shop Shopee/Lazada/TikTok vào Sapo (phía Sapo có hướng dẫn riêng).
2. Mỗi đơn về từ Shopee sẽ được Sapo nhận vào hệ thống, có nhãn channel = 'shopee'.
3. OpsOne Pull từ Sapo về như thường lệ — đơn Shopee tự kèm theo nhãn channel để báo cáo phân tích theo kênh.

Cách 2 — Tích hợp Shopee trực tiếp (roadmap)

Một số anh/chị không dùng Sapo Omnichannel, chỉ có shop Shopee độc lập. OpsOne đang phát triển adapter Shopee Partner API riêng (gọi thẳng Shopee, không qua Sapo). Tiến độ:

• Hiện tại: Beta nội bộ, hỗ trợ Pull đơn + Push trạng thái.
• Q3/2026: Ra mắt công khai, tích hợp Push thanh toán + cập nhật tồn kho 2 chiều.
• Đăng ký dùng sớm: liên hệ [email protected].

8. Cấu hình Webhook (real-time, advanced)

Nhịp 15 phút đã đủ cho hầu hết doanh nghiệp. Nhưng nếu anh/chị bán hàng cao điểm (Sale 12.12, Black Friday, livestream), độ trễ một nhịp có thể quá lâu. Lúc đó cấu hình Webhook để Sapo "gọi" OpsOne ngay khi có đơn.

URL endpoint của OpsOne

Cách cấu hình

1. Vào admin Sapo → Cấu hình → Thông báo Webhook.
2. Bấm Tạo Webhook, chọn sự kiện (ví dụ "Đơn hàng được tạo").
3. Dán URL tương ứng từ bảng trên.
4. Chọn format JSON.
5. Lưu. Sapo sẽ gửi test request — OpsOne trả 200 OK.

9. Xử lý sự cố thường gặp

10. Sapo Disabled — bật/tắt tích hợp

Có khi anh/chị muốn tạm tắt sync (đổi shop Sapo, đang test, hoặc Sapo bảo trì). Vào tab Tích hợp → tắt toggle "Kích hoạt đồng bộ Sapo". Cờ sapo_enabled chuyển về 0.

Khi sync đang tắt

• Scheduler bỏ qua project này, không Pull đơn mới.
• Push thanh toán cũng bị skip.
• Mọi thao tác liên quan Sapo (vd nút "Hủy đơn trên Sapo" trong CRM) sẽ trả lỗi sapo_disabled (HTTP 403).
• Dữ liệu cũ không bị mất — đơn đã sync vẫn nằm trong OpsOne, chỉ là không cập nhật mới.

11. Ba tình huống thực tế

12. Câu hỏi thường gặp