DevVN Docs Đồng bộ KiotViet

Danh sách kiểm tra khi cài đặt

Tab Bắt đầu tự dò website đã cấu hình tới đâu và còn thiếu gì. Thấy đồng bộ không chạy thì mở tab này trước. Bài này cũng hướng dẫn luôn bước 2, cập nhật dữ liệu địa chỉ.

Bước 2 / 10 nằm trong bài này Cập nhật 12.10.2026 Đọc khoảng 5 phút

Tab Bắt đầu dùng để làm gì

Trạng thái trong tab này đọc thẳng từ cấu hình thật của website, bạn không tự đánh dấu. Bước nào báo xanh là bước đó đã xong thật.

Tab Bắt đầu với thanh tiến trình và ba vị trí được đánh số
Tab Bắt đầu nằm ngoài cùng bên trái. Bấm vào ảnh để phóng to.
  1. Tab Bắt đầu nằm đầu thanh tab. Còn bước bắt buộc chưa xong thì tên tab kèm số bước còn thiếu, và menu Đồng bộ KiotViet trong WooCommerce cũng hiện số đó.
  2. Con số dạng 7/8 là số bước đã xong trên số bước đang áp dụng. Bước "Không áp dụng" không tính vào.
  3. Bấm Kiểm tra lại sau khi vừa sửa cấu hình để plugin dò lại từ đầu, thay vì hiện kết quả cũ.

Chưa xong các bước bắt buộc thì trang quản trị hiện thông báo "Đồng bộ KiotViet chưa sẵn sàng" với hai nút Hoàn tất cài đặt và Để sau. Bấm Để sau thì thông báo ẩn 7 ngày.

Đọc một dòng bước

Mỗi bước hiện theo cùng một khuôn, quen mắt rồi thì liếc là biết.

Ba dòng bước đầu tiên với bốn vị trí được đánh số
Ba bước đầu trong danh sách. Bấm vào ảnh để phóng to.
  1. Biểu tượng bên trái cho biết trạng thái. Tích xanh là Hoàn thành, dấu vàng là Cần kiểm tra, gạch xám là Không áp dụng, dấu đỏ là Chưa làm.
  2. Nhãn Bắt buộc nghĩa là thiếu bước này thì plugin không chạy, nhãn Tuỳ chọn là bật khi cần.
  3. Dòng trạng thái nói rõ hiện đang thế nào, ví dụ "Đã chọn 2 chi nhánh" hoặc "Chưa chọn khoản thu khác cho phí vận chuyển".
  4. Nút bên phải (Thiết lập, Chỉnh sửa hoặc Xem) đưa bạn tới đúng tab cần sửa. Bước phụ thuộc vào bước phía trên chưa xong thì hiện dòng "Cần làm bước trên trước".

Mười bước và bước nào bắt buộc

SốBướcPhân loại
1Kích hoạt License. Chưa kích hoạt thì mọi lệnh gọi sang KiotViet bị chặn.Bắt buộc
2Cập nhật dữ liệu địa chỉ, xem mục ngay bên dưới.Bắt buộc khi cửa hàng đặt ở Việt Nam
3Kết nối API KiotVietBắt buộc
4Chọn chi nhánh. Để trống là lấy tồn của tất cả chi nhánh.Tuỳ chọn
5Ánh xạ danh mụcTuỳ chọn
6Đồng bộ sản phẩm lần đầuBắt buộc
7Đồng bộ đơn hàngTuỳ chọn
8Phí vận chuyển & phụ thuTuỳ chọn
9Đồng bộ khách hàngTuỳ chọn
10Đăng ký Webhook. Không có thì thay đổi bên KiotViet không tự về.Bắt buộc
Bước tuỳ chọn báo màu xám là bình thường

Đang tắt đồng bộ đơn hàng thì bước 7 hiện "Không áp dụng"; chưa bật Đồng bộ phụ thu thì bước 8 cũng vậy. Plugin chỉ báo bước đó không liên quan tới cấu hình hiện tại, không phải lỗi.

Bước 2: cập nhật dữ liệu địa chỉ

Từ 01/07/2025 Việt Nam bỏ cấp quận/huyện. Địa chỉ đơn gửi lên KiotViet lấy theo bộ đơn vị hành chính mà trang thanh toán đang dùng, nên bộ dữ liệu trong website phải đúng với cách bạn đang ghi địa chỉ. Khi mới cài, plugin dùng bộ 3 cấp (v2.0).

Nhóm Công cụ ở tab Cài đặt chung, dòng Cập nhật dữ liệu địa chỉ với ba vị trí được đánh số
Cuối tab Cài đặt chung, nhóm Công cụ. Trong ảnh đang chọn Mới nhất.
  1. Mở tab Cài đặt chung, kéo xuống nhóm Công cụ. tới dòng Cập nhật dữ liệu địa chỉ.
  2. Ở mục Đơn vị hành chính, chọn Mới nhất nếu dùng địa chỉ 2 cấp (Tỉnh/Thành, Phường/Xã). Vẫn dùng 3 cấp có Quận/Huyện thì chọn v2.0 - trước 01.07.2025. Website đang bật plugin VNPost, Nhanh.vn hoặc SuperShip của DevVN thì ô Mới nhất bị khoá.
  3. Bấm Cập nhật database. Chỉ chọn mà không bấm nút này thì dữ liệu cũ vẫn giữ nguyên, và tab Bắt đầu báo Cần kiểm tra.

Xong thì quay lại tab Bắt đầu, bấm Kiểm tra lại. Bước 2 hiện tích xanh kèm tên bộ dữ liệu đang dùng.

Trang thanh toán dạng block chỉ có ô chọn địa chỉ 2 cấp. Website không bán cho khách ở Việt Nam thì bước này hiện "Không áp dụng"; cửa hàng đặt ở nước khác nhưng có bán cho Việt Nam thì bước này là tuỳ chọn.

Phần kiểm tra môi trường

Dưới danh sách bước còn khối Kiểm tra môi trường. Đây là cấu hình của website, nằm ngoài plugin, nhưng hay làm đồng bộ cài xong mà không chạy. Khối này báo vàng thì sửa trước, sửa cấu hình plugin không giải quyết được.

MụcBáo vàng khi nào, sửa thế nào
Đường dẫn tĩnh (Permalink)Đang để Plain thì link webhook có dạng ?rest_route=..., nhiều hệ thống gọi không ổn định. Đổi sang dạng khác ở Cài đặt → Đường dẫn tĩnh.
HTTPSWebsite chưa chạy HTTPS thì KiotViet có thể không gọi được webhook. Cài chứng chỉ SSL cho tên miền.
WP-CronHằng DISABLE_WP_CRON đang bật. Phải có cron thật trên máy chủ, nếu không đồng bộ nền và hàng đợi webhook đứng yên.
Action SchedulerKhông tìm thấy bộ chạy việc nền đi kèm WooCommerce. Webhook khi đó được xử lý trực tiếp, chậm khi dữ liệu nhiều. Cập nhật WooCommerce thường là hết.

Nhờ hỗ trợ nhanh hơn

Cuối tab có khối Cần hỗ trợ? với nút Sao chép báo cáo. Báo cáo gồm phiên bản plugin, WordPress, WooCommerce, PHP, trạng thái từng bước và kết quả kiểm tra môi trường; không chứa Client Secret hay license key. Dán báo cáo đó khi bấm Liên hệ hỗ trợ qua Zalo.

Xong phần này thì sang License và cập nhật.

Hỗ trợ Zalo