Kết nối KiotViet

Menu (danh mục, món, giá, topping) và tồn kho được lấy từ KiotViet về hệ thống. Bước đầu: khai báo kết nối API và ghép chi nhánh.

Sổ kho chính là hệ thống này (chốt 16/10/2026). KiotViet không tự trừ kho được theo đơn của hệ thống, nên tồn trên KiotViet chỉ để tham khảo / đối chiếu. Mỗi chi nhánh làm bước Chuyển kho về hệ thống (cuối trang) trước khi bán thật; từ đó nhập hàng, chuyển kho, hủy, kiểm kê đều làm ở Kho của hệ thống, không cần cập nhật tồn trên KiotViet.

1. Lấy thông tin API trên KiotViet

Đăng nhập KiotViet bằng tài khoản chủ cửa hàng → Thiết lập cửa hàng → Thiết lập kết nối API → ghi lại Client ID và Mã bảo mật. Tên gian hàng (Retailer) là phần đầu của địa chỉ, VD quancuatoi.kiotviet.vn → quancuatoi.

2. Khai báo ở Admin

Admin → Kết nối KiotViet: nhập Tên gian hàng, Client ID, Mã bảo mật → Lưu → Kiểm tra kết nối.

• Mã bảo mật được mã hóa khi lưu, chỉ hiện dạng che. Lần sau sửa thông tin khác thì để trống ô này (giữ mã cũ).
• Đổi Tên gian hàng / Client ID / Mã bảo mật → phải bấm Kiểm tra kết nối lại.
• Báo "từ chối xác thực": sai một trong 3 thông tin trên.

3. Ghép chi nhánh

Mỗi chi nhánh của hệ thống chọn 1 chi nhánh KiotViet tương ứng → Lưu ghép chi nhánh. Một chi nhánh KiotViet chỉ ghép được với 1 chi nhánh.

4. Đồng bộ menu

Bật "Bật đồng bộ từ KiotViet" → Lưu → ở mục Đồng bộ menu bấm Đồng bộ (lần đầu đọc toàn bộ, các lần sau chỉ đọc phần thay đổi; Đồng bộ toàn bộ để đọc lại hết).

KiotViet	Trong hệ thống	Lấy từ KiotViet mỗi lần đồng bộ
Nhóm hàng	Danh mục	Tên
Hàng hóa (trừ topping)	Món — mã KiotViet thành SKU (chữ hoa, ký tự lạ → -)	Mã, ảnh; tên, nhóm, giá gốc, mô tả, đang bán theo quy tắc "ưu tiên bên mình" bên dưới
Topping của món	Nhóm tùy chọn "Topping · " gắn vào món	Tên, giá topping
Hàng hóa bị xóa	Món bị gỡ khỏi menu (đơn cũ vẫn giữ)	—
Hàng không bán (nguyên liệu…)	Vào Kho → Mặt hàng (không vào menu): tên, nhóm, đơn vị, giá vốn; món đã có từ trước mà KiotViet chuyển sang không bán thì được tắt	Bên mình sửa mặt hàng sau lần đồng bộ trước → giữ bên mình
Hàng đơn vị phụ của nguyên liệu (vd Bao = 50 kg)	Quy đổi đơn vị của mặt hàng gốc	—
Thành phần của món (định lượng KiotViet)	Định lượng nháp của món (chưa áp dụng)	Định lượng bên mình đang dùng giữ nguyên

Sửa ở cả 2 nơi — ưu tiên bên mình

Tên món, giá gốc, đang bán / ngừng bán, nhóm hàng, mô tả sửa được ở KiotViet hoặc ở hệ thống (trang Món & combo, nhập Excel). Khi đồng bộ, xét từng trường:

• KiotViet không đổi trường đó → giữ giá trị bên mình.
• KiotViet có đổi → lấy theo KiotViet, trừ khi bên mình cũng sửa trường đó sau lần đồng bộ trước → bên mình thắng.

VD: 9h tắt món "Trà đào" ở Admin → đồng bộ lúc 10h vẫn tắt (KiotViet không đổi). 14h trên KiotViet đổi giá Trà đào → lần đồng bộ sau giá theo KiotViet, món vẫn tắt.

Mục Khác KiotViet liệt kê các trường bên mình đang khác KiotViet (bên mình / KiotViet / sửa lúc). Bấm Theo KiotViet để bỏ thay đổi bên mình.

KiotViet chưa có API cho phép sửa hàng hóa từ bên ngoài, nên thay đổi bên mình chưa tự sang KiotViet — muốn 2 bên giống nhau thì sửa tay trên KiotViet. Hệ thống đã ghi lại các thay đổi này để tự đẩy sang khi KiotViet mở API.

Không bị ghi đè (làm ở hệ thống): khu chế biến, loại đơn, thời gian làm, thứ tự, ảnh đã tự thay, tùy chọn tự gắn, bật/tắt hết món theo chi nhánh. Món đã tạo tay trùng mã với KiotViet sẽ được ghép (giữ khu chế biến).

Khu chế biến

Món mới từ KiotViet chưa biết làm ở khu nào nên tạm tắt:

• Khu chế biến mặc định theo nhóm hàng: chọn khu cho từng nhóm → món chờ của nhóm nhận khu và bật; món mới sau này tự nhận khu.
• Món chờ gắn khu: chọn khu cho từng món lẻ.

Đổi khu của món đã có khu: Menu → Món & combo.

Tự cập nhật (webhook)

Bấm Đăng ký webhook trên KiotViet → mỗi khi sửa/xóa hàng hóa trên KiotViet, hệ thống tự đồng bộ phần thay đổi sau vài giây. Nếu máy chủ chưa có địa chỉ công khai, trang báo rõ — khi đó bấm Đồng bộ sau mỗi lần sửa menu trên KiotViet.

Bỏ qua

Kết quả đồng bộ liệt kê mục bỏ qua: thiếu mã/tên, mã trùng món khác, không tải được ảnh. Sửa trên KiotViet rồi đồng bộ lại.

5. Tồn kho theo KiotViet

Mục Tồn kho theo KiotViet (theo chi nhánh đang chọn) — lấy tồn của các chi nhánh KiotViet đã ghép:

• Còn bán = tồn KiotViet − đang giữ − số đã bán ở hệ thống từ lúc lấy tồn. Còn dưới 1 → món tự tắt trên trang đặt món QR và POS của chi nhánh (hiện "Hết"); có hàng lại → tự bật.
• Tự lấy lại khi KiotViet báo đổi tồn (webhook stock.update — bấm Đăng ký webhook ở mục Đồng bộ menu) và 5 giờ sáng mỗi ngày; bấm Lấy tồn ngay khi cần.
• Theo dõi: mặc định (Tự động) áp dụng các loại hàng hóa của KiotViet (nước đóng chai, bánh gói…), trừ combo đóng gói, dịch vụ và các loại 4, 5. Món chế biến/pha chế (tồn tính theo nguyên liệu) không bị tắt theo tồn. Đổi từng món: Có / Không.
• Tắt món tay khi hết nguyên liệu vẫn dùng nút Hết món như cũ.

Đơn bán ở hệ thống chưa tự về KiotViet (chờ KiotViet có API tạo hóa đơn), nên tồn trên KiotViet không tự giảm theo đơn của mình — hệ thống tự trừ số đã bán để tính "còn bán". Khi nhập/kiểm kho trên KiotViet, tồn mới được lấy về ở lần kế tiếp.

Nguyên liệu và định lượng từ KiotViet

Mục đích: sau này ngừng dùng KiotViet thì kho và định lượng đã có sẵn ở hệ thống.

• Nguyên liệu (hàng KiotViet không bán) được tạo/cập nhật ở Kho → Mặt hàng, ghép theo id KiotViet, lần đầu theo mã hàng (mặt hàng đã nhập tay trùng mã được ghép, không tạo trùng). Kho mặc định Nóng — chỉnh lại Lạnh nếu cần.
• Đơn vị: mặt hàng mới lấy đơn vị KiotViet làm đơn vị gốc. Mặt hàng có sẵn tính theo đơn vị khác (vd bên mình g, KiotViet kg) được quy đổi tự động theo quy đổi đã khai báo (hoặc kg→g, l→ml); giá vốn cũng quy về đơn vị gốc (25.000đ/kg → 25đ/g). Các cách viết đơn vị thường gặp (gram/Gam/g, Kilogram (kg)/Kilogam/kg, Lít/l, Mililit/ml) được coi là một, không tạo đơn vị trùng. Không quy đổi được → mục Bỏ qua báo tên hàng; thêm quy đổi ở Kho → Mặt hàng rồi đồng bộ lại.
• Định lượng: thành phần món trên KiotViet thành phiên bản nháp ở Menu → Món → Định lượng (ghi chú Định lượng từ KiotViet), số lượng đã quy về đơn vị gốc. Bản nháp chưa áp dụng: chưa trừ kho, chưa chặn bán — vì kho bên mình chưa có tồn, áp dụng ngay sẽ làm món báo hết nguyên liệu. Khi chuyển kho sang hệ thống: nhập tồn đầu kỳ, mở bản nháp, kiểm tra và Lưu để áp dụng.
• KiotViet đổi thành phần → thêm bản nháp mới; không đổi thì không tạo thêm.

Tự đồng bộ trong ngày

Ngoài lần chạy 5 giờ sáng, hệ thống tự đồng bộ menu (phần thay đổi) và lấy tồn KiotViet mỗi 10 phút — dùng thay webhook khi API chưa có địa chỉ https. Đổi chu kỳ: Cài đặt tham số → kiotviet.poll_minutes (0 = tắt, chỉ chạy 5h sáng / bấm tay / webhook). Lần nào lỗi thì chờ hết chu kỳ mới thử lại; xem kết quả lần gần nhất ở trang Kết nối KiotViet.

Đơn vị nhập hàng khác đơn vị định lượng (ống hút, quai xách…)

Trên KiotViet đặt đơn vị cơ bản = đơn vị nhỏ nhất dùng trong định lượng (vd Cái), rồi thêm đơn vị quy đổi để nhập hàng (vd Bịch = 100 cái, Kg = số cái trong 1 kg — cân thử 1 kg rồi đếm). Thành phần món ghi theo Cái. Hệ thống tự lấy cả đơn vị quy đổi; nguyên liệu bên mình chưa dùng (chưa có tồn, định lượng) thì đổi đơn vị gốc theo KiotViet khi đồng bộ lại.

Chuyển kho về hệ thống (T200)

Admin → Kết nối KiotViet → Mở màn Chuyển kho (giám đốc / quyền Cài đặt). Mỗi chi nhánh làm một lần:

1. Kiểm kê tồn trên KiotViet, sửa định lượng cho đúng, bấm Đồng bộ toàn bộ.
2. Mở màn Chuyển kho: bảng Tồn đầu kỳ lấy tồn KiotViet hiện tại của nguyên liệu và hàng bán nguyên chiếc (nước chai…), đã quy về đơn vị gốc, kèm giá vốn. Kho nhận gợi ý: nguyên liệu chỉ 1 khu dùng → kho khu đó; còn lại → Kho Nóng / Kho Lạnh. Sửa được số lượng, giá vốn, kho từng dòng. Tồn KiotViet âm tính 0.
3. Mục Định lượng từ KiotViet: bản nháp mới nhất sẽ được áp dụng (chung mọi chi nhánh); món đang dùng định lượng bên mình giữ nguyên.
4. Bấm Chuyển kho về hệ thống → tạo phiếu tồn đầu kỳ, hàng bán nguyên chiếc có mặt hàng kho + định lượng 1 phần = 1 đơn vị, áp dụng định lượng, tắt tồn theo KiotViet của chi nhánh. Từ đó bán món trừ kho bên mình; hết nguyên liệu ở kho khu thì món tự tắt.
5. Sau khi chuyển, mục Tồn kho theo KiotViet hiện thông báo chỉ để tham khảo: vẫn lấy số KiotViet về để đối chiếu, nhưng không còn tự tắt món.