Kết nối KiotViet với website: 3 cách và 6 bước nối WooCommerce

Cửa hàng bán bằng KiotViet, website chạy WooCommerce, và đứng giữa hai bên là một người chép tay. Có lô hàng mới thì tạo sản phẩm hai lần. Đổi giá trên KiotViet xong phải nhớ sửa thêm trên web. Đơn online lại gõ từng dòng vào KiotViet. Kết nối KiotViet với website là để hai bên dùng chung một nguồn: hàng hoá, giá, tồn kho đi từ KiotViet ra web, còn đơn web đi ngược về KiotViet. Hiện có ba đường: dùng website dựng sẵn của KiotViet (KiotViet Web), tự code theo Public API, hoặc cài plugin khi web chạy WordPress với WooCommerce. Bài này đặt ba đường cạnh nhau, nói điều kiện chung, rồi đi từng bước với đường thứ ba.

Kết nối KiotViet với website: KiotViet Web, tự code Public API hoặc plugin cho WooCommerce

Đường thứ ba dùng plugin do mình viết và bán, nên phần đó anh em đọc bằng con mắt của người mua. DevVN không phải đối tác của KiotViet; plugin gọi Public API của KiotViet bằng bộ mã do chủ gian hàng tự tạo. Phần về KiotViet mình lấy từ tài liệu trên kiotviet.vn (Kết nối API, Public API, KiotViet Web), đọc lại tháng 10/2026. Năm 2026 KiotViet đang đổi dần sang giao diện quản lý mới, nên tên menu bạn thấy có thể khác chữ trong bài.

🔗 Kết nối KiotViet với website gồm những luồng nào?

  • 📦 Hàng hoá tạo trên KiotViet (tên, ảnh, mô tả, biến thể) lên web, không phải nhập lần hai.
  • 💰 Giá và tồn kho trên web đi theo KiotViet: cửa hàng bán ra hay đổi giá thì web nhận số mới.
  • 🧾 Đơn khách đặt trên web vào KiotViet, nhân viên xử lý chung chỗ với đơn tại quầy.
  • 👥 Khách mua ở quầy và khách đặt online gom về một danh sách khách hàng.

📋 Điều kiện chung: gian hàng bán lẻ, bán buôn có Public API

Tự code hay dùng plugin đều đi qua Public API, nên gian hàng cần:

Để duy trì blog nên mình có làm aff cho 1 số bên hosting. Nhưng dù aff mình cũng chọn 1 số nhà cung cấp uy tín về chất lượng và support nên các bạn cứ yên tâm nhé.

Nếu có mua hosting mà có trong list dưới đây các bạn click vào link trước khi mua để ủng hộ mình nhé. Mình cảm ơn nhiều

  • 🏪 Gian hàng ngành bán buôn hoặc bán lẻ. KiotViet FnB có tài liệu API riêng, plugin của mình không hỗ trợ FnB.
  • 💳 Gói có Public API. Bảng phí của KiotViet (mình xem tháng 10/2026) chỉ đặt Public API ở gói Cao cấp; gian hàng ở gói thấp hơn thì hỏi KiotViet chuyện lên gói.
  • 🔑 Chủ gian hàng dùng tài khoản admin, nhận mã xác thực qua số điện thoại trên hợp đồng rồi tạo Client ID và Mã bảo mật ở mục Kết nối API. Hướng dẫn bấm từng bước, có ảnh, nằm trong bài lấy Client ID, Client Secret KiotViet.

KiotViet Web chạy ngay trong KiotViet nên không cần tạo mã API. Còn KiotViet Sync, plugin WordPress miễn phí KiotViet từng đưa lên WordPress.org, đã đóng từ 04/11/2025 và không cài mới được nữa. Web đang chạy nó thì đọc bài KiotViet Sync đã đóng để biết nên xử lý thế nào.

🌐 Cách 1: dùng KiotViet Web, website dựng sẵn trong KiotViet

Theo tài liệu KiotViet Web, đường vào là Bán Online → Website bán hàng → Tạo website; chọn giao diện mẫu rồi xuất bản. Hàng hoá lấy thẳng từ gian hàng nên không có bước nối nào. Đơn đặt trên web hiện trong KiotViet dưới dạng phiếu Đặt hàng. Web lấy sản phẩm, tồn kho, giá và nhận đơn theo đúng một “Chi nhánh đồng bộ”, giá bán là bảng giá chung (KiotViet ghi “chưa hỗ trợ thay đổi”). Về phí, web.kiotviet.vn ghi miễn phí, còn bảng phí kiotviet.vn đặt “Tạo website bán hàng” ở gói Chuyên nghiệp và gói Cao cấp; hỏi KiotViet cho chắc.

Đường này hợp với shop chưa có website, cần lên bán sớm mà không lo hosting. Web WordPress đã có nhiều trang lên Google thì phải tính chuyện đổi nền tảng, đổi đường dẫn. Hai đường được so từng việc ở bài KiotViet Web hay WooCommerce.

🧑‍💻 Cách 2: tự code theo Public API

Web tự viết, web không có WooCommerce, hay chỉ cần kéo một thứ như số tồn để hiện trên trang giới thiệu, thì gọi thẳng Public API. Lập trình viên tự lo các phần này:

  • 🔑 Xin access token bằng Client ID và Mã bảo mật theo OAuth 2.0 kiểu client_credentials; token sống 24 giờ.
  • 📨 Gửi header Retailer và Authorization: Bearer ở mọi lệnh gọi; các hàm GET giới hạn 5.000 request mỗi giờ.
  • 🔔 Đăng ký webhook qua API vì bán lẻ không có màn hình bật webhook. KiotViet chờ phản hồi mỗi tin tối đa 5 giây, và thôi gửi khi gặp mã 400, 401, 403, 404, 405.
  • 🧩 Gom hàng hoá cùng loại thành biến thể, cộng tồn theo chi nhánh, xử lý địa chỉ phường/xã KiotViet không nhận khi gửi đơn.

Đoạn gọi API thì ngắn. Việc kéo dài là phần quanh nó: hàng đợi cho webhook, màn hình cho nhân viên đăng đơn, sửa code mỗi lần KiotViet đổi tài liệu. Code PHP chạy trong WordPress mình viết ở bài KiotViet Public API.

🔌 Cách 3: kết nối KiotViet với WordPress bằng plugin cho WooCommerce

Web chạy WooCommerce thì phần việc ở cách 2 đã có người viết sẵn. Ví dụ ở đây là plugin đồng bộ KiotViet cho WooCommerce mình viết, bản 1.3.4. Web cần WordPress từ 5.0, WooCommerce từ 6.0, PHP từ 7.2, MySQL từ 5.7; WP-Cron phải chạy, vì webhook, đồng bộ nền và tự động đăng đơn đều đi qua Action Scheduler.

Cả 6 bước, từ kích hoạt license tới cài đơn hàng, có trong video khoảng ba phút dưới đây.

Plugin nằm ở WooCommerce → Đồng bộ KiotViet. Tab ngoài cùng bên trái là “Bắt đầu”: 10 bước gắn nhãn Bắt buộc hoặc Tuỳ chọn, trạng thái do plugin tự dò từ cấu hình thật. Dưới danh sách có khối “Kiểm tra môi trường” (đường dẫn tĩnh, HTTPS, WP-Cron, Action Scheduler) và nút “Sao chép báo cáo” để gửi khi cần hỗ trợ. Cách đồng bộ KiotViet với web WooCommerce bên dưới đi theo thứ tự đó; đơn hàng để ra sau vì là tuỳ chọn.

Tab Bắt đầu của plugin đồng bộ KiotViet cho WooCommerce: thanh tiến độ 7/8, nút Kiểm tra lại, danh sách 10 bước có nhãn Bắt buộc, Tuỳ chọn và nút Chỉnh sửa, Thiết lập, Xem
Tab Bắt đầu: bước nào chưa làm hiện vòng tròn đỏ kèm nút Thiết lập (dữ liệu mẫu).

Bước 1: kích hoạt license

Tab “License”, dán mã vào ô “License Key”, bấm “Kích hoạt License”. Chưa có license hợp lệ thì plugin không gọi được KiotViet, nên làm bước này trước. Một license dùng cho một tên miền; gói 1 năm hết hạn thì plugin ngừng chạy tới khi gia hạn. Xem trang kích hoạt license.

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

Tab “Cài đặt chung”, dòng “Cập nhật dữ liệu địa chỉ”: ở mục “Đơn vị hành chính” tích lựa chọn đầu, bộ 2 cấp Tỉnh/Thành → Phường/Xã (34 tỉnh, 3.321 phường/xã), rồi bấm “Cập nhật database”. Plugin mới cài đang tích “v2.0 – trước 01.07.2025”, bộ 3 cấp cũ. Checklist ghi lý do phải đổi: địa chỉ đơn hàng phải khớp đơn vị hành chính bên KiotViet, không thì địa chỉ đăng lên bị sai. Chuyện WooCommerce chuyển sang địa chỉ 2 cấp có ở bài WooCommerce địa chỉ 2 cấp.

Bước 3: nhập API KiotViet, chọn chi nhánh

Tab “Cài đặt API”: ô “Retailer” là tên gian hàng (phần đứng trước .kiotviet.vn), “Client ID” chép nguyên, “Client Secret” là Mã bảo mật. Bấm “Lưu cài đặt” rồi “Kiểm tra kết nối”: kết nối đúng thì danh sách bảng giá cũng được tải về để dùng ở bước 5. Token plugin tự xin, tự làm mới. Ô “Chi nhánh” quyết định web cộng tồn từ đâu: để trống là mọi chi nhánh, chọn tay thì chỉ các chi nhánh đã chọn; kho hàng lỗi hay chi nhánh không bán online thì đừng chọn. Web từng chạy KiotViet Sync có nút “Chuyển ID từ plugin cũ” ở cùng tab. Xem trang cài đặt API.

Tab Cài đặt API: ô Retailer, Client ID và Client Secret đã che, danh sách Chi nhánh đang mở, ô Ghi log, Xóa cache, nút Lưu cài đặt và khối Chuyển dữ liệu từ plugin cũ (kvsync)
Bước 3: ô Chi nhánh đang mở. Tên gian hàng và hai chi nhánh là dữ liệu mẫu.

Bước 4: ánh xạ danh mục

Tab “Ánh xạ danh mục”, bấm “Tải danh mục Kiotviet”. Mỗi danh mục KiotViet chọn “Tạo mới” (tạo trên web), “Ánh xạ có sẵn” (ghép với danh mục web đang có) hoặc “Bỏ qua”, rồi bấm “Lưu cấu hình” và “Đồng bộ danh mục ngay”. Ô “Bỏ qua sản phẩm thuộc danh mục Skip” mặc định bật: hàng trong danh mục để “Bỏ qua” không về web, kể cả qua webhook. Checklist xếp bước này vào Tuỳ chọn, nhưng web có cây danh mục riêng thì làm trước bước 5. Plugin không nhận webhook danh mục, nên KiotViet thêm nhóm hàng thì quay lại tab này. Xem trang ánh xạ danh mục.

Tab Ánh xạ danh mục: khối Cài đặt đồng bộ danh mục, nút Tải danh mục Kiotviet, bảng danh mục KiotViet với hành động Ánh xạ có sẵn, Tạo mới, Bỏ qua, cột Danh mục WooCommerce và trạng thái
Bước 4: mỗi danh mục KiotViet chọn một hành động. Tên danh mục là dữ liệu mẫu.

Bước 5: đồng bộ sản phẩm lần đầu

Ở tab “Đồng bộ sản phẩm”, khối “Tùy chọn đồng bộ” cho bật tắt từng trường (tên, giá, ảnh, mô tả đầy đủ, tồn kho…), mỗi trường có ô “Ghi đè … nếu sản phẩm đã có …”. “Mapping Giá” chọn nguồn cho “Giá thường:” và “Giá khuyến mãi:”. Bấm “Lưu tùy chọn”, rồi:

  1. Sao lưu database, vì bước ghi vào WooCommerce không có nút hoàn tác.
  2. Bấm “Tải từ API KiotViet”: hàng hoá kèm tồn kho, bảng giá về nằm ở bảng tạm, sản phẩm WooCommerce chưa bị đụng tới.
  3. Web đã có sản phẩm thì bấm “Auto Mapping” để ghép theo ID và SKU, kẻo một món thành hai bản. Không chung mã hàng thì dùng “Auto Mapping theo tên”.
  4. Thử trước với vài dòng: đặt “Tạo mới” hoặc “Cập nhật”, bấm “Đồng bộ đã chọn”, xong ra ngoài web soát tên, giá, tồn của mấy món đó.
  5. Đúng rồi thì chọn phần còn lại, bấm “Đồng bộ đã chọn trong nền”.

Từng ô của khối tuỳ chọn có giải thích ở trang đồng bộ sản phẩm.

Khối Đồng bộ sản phẩm với các nút Đồng bộ đã chọn, Đồng bộ đã chọn trong nền, Đồng bộ tồn kho, Auto Mapping, Auto Mapping theo tên, bộ lọc bên trái và bảng sản phẩm có cột Giá, Tồn kho, WooCommerce Product, Hành động
Bước 5: mỗi dòng chọn Cập nhật, Tạo mới hoặc Bỏ qua lần này. Tên hàng, giá, tồn kho là dữ liệu mẫu.

Bước 6: đăng ký webhook

Ở tab “Webhook” chỉ cần một nút: “Đăng ký tất cả webhook”. Plugin đăng ký với KiotViet 11 sự kiện về hàng hoá, tồn, bảng giá, khách và đơn; từ đây thay đổi trên KiotViet tự về web. Tin về được xếp hàng đợi rồi xử lý nền theo WP-Cron, nên web đổi số sau bao lâu thì tuỳ nhịp gửi của KiotViet và cron của hosting; mình không đưa con số. Ô “Tự động đăng ký lại khi bị vô hiệu hóa” bật sẵn, mặc định kiểm mỗi 1 giờ: cứ để nguyên.

⚠️ Hàng tạo mới trên KiotViet sau lúc này không tự lên web, vì ô “Tự động tạo sản phẩm mới” để tắt sẵn. Bật ô đó, hoặc tải về như bước 5. Xem trang webhook.

Tab Webhook: Mã bí mật Webhook và Link Webhook đã che, ô Tự động đăng ký lại khi bị vô hiệu hóa đang bật, nút Đăng ký tất cả webhook và các sự kiện đầu danh sách ở trạng thái Active
Bước 6: bảng liệt kê từng sự kiện đã đăng ký. Tên miền là dữ liệu mẫu, mã bí mật đã che.

Đơn hàng, khách hàng: bật khi cần

Tab “Đồng bộ đơn hàng” phải chọn “Chi nhánh mặc định”, để trống thì không đăng được đơn. Đơn web sang KiotViet là phiếu Đặt hàng, không phải hoá đơn; xử lý phiếu, xuất hoá đơn vẫn làm trên KiotViet. Đăng tay bằng popup “Đăng đơn lên KiotViet” trong trang sửa đơn, hoặc bật “Tự động đăng đơn” (mặc định tắt) với “Quy tắc tự động đăng” theo trạng thái đơn và hình thức thanh toán. Đơn có một sản phẩm chưa liên kết KiotViet là cả đơn bị chặn. Khách hàng ở tab “Đồng bộ khách hàng”, mặc định “Tắt”. Xem trang đồng bộ đơn hàng.

Nối xong, thử một vòng

Trên KiotViet, sửa tồn một mặt hàng đã liên kết. Ở tab “Webhook”, khối “Thống kê” cuối trang, ô “Hoàn tất” tăng là tin đã về và xử lý xong; tin nằm ở “Chờ xử lý” lâu thì xem lại WP-Cron trong “Kiểm tra môi trường”. Rồi mở sản phẩm ngoài web: trang quản trị đúng mà trang ngoài còn số cũ là do cache trang, bật ô “Xóa cache” ở tab “Cài đặt API”.

Giới hạn của plugin: hàng hoá, giá, tồn kho chỉ chạy một hướng, từ KiotViet sang web. Không có lịch quét lại toàn bộ theo giờ hay theo đêm: ngoài nút bấm tay chỉ có webhook, web mất webhook một lúc thì phải đối soát tay. Xoá hàng hoá trên KiotViet thì sản phẩm trên web bị xoá vĩnh viễn, không qua thùng rác; món nào muốn tự quản thì bật “Không đồng bộ từ KiotViet” trong trang sửa sản phẩm.

⚖️ Nên chọn cách nào?

CáchHợp vớiCần có
KiotViet WebShop chưa có web, cần lên bán sớmGói KiotViet có tạo website; giao diện theo mẫu
Tự code Public APIWeb tự viết, không chạy WooCommerce, luồng lẻLập trình viên, gói có Public API
Plugin WooCommerceWeb WooCommerce đã có nội dung, nhiều chi nhánh, bảng giá riêngGói có Public API, license plugin

Nói thẳng: shop chưa có website và muốn có trang bán sớm thì KiotViet Web đủ dùng. Đường WooCommerce đáng công khi web đang có thứ cần giữ (trang đã lên Google, theme đã chỉnh, plugin thanh toán, vận chuyển), hoặc khi shop muốn cộng tồn từ vài chi nhánh, dùng bảng giá riêng cho online.

Shop mới mở, còn so KiotViet với Nhanh.vn và Sapo thì chọn phần mềm trước, nối web sau. Bài Nhanh.vn, KiotViet hay Sapo so ba phần mềm này cho shop đã có web WooCommerce.

Chọn cách 3 thì mình hỗ trợ cài đặt miễn phí qua Zalo 0965 419 096; giá gói 1 năm và gói Mãi mãi xem ở trang plugin KiotViet cho WooCommerce.

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

Có cần KiotViet duyệt hay cấp phép gì không?

Không. Chủ gian hàng tự tạo Client ID, Mã bảo mật rồi đưa cho bên làm web. Plugin của mình là phần mềm bên thứ ba, không phải ứng dụng do KiotViet phát hành.

Đồng bộ KiotViet với website đi một chiều hay hai chiều?

Với plugin của mình, KiotViet là nguồn của hàng hoá, giá, tồn kho, web chỉ nhận. Chiều ngược lại có đơn hàng, lên KiotViet thành phiếu Đặt hàng. Trạng thái đơn trên KiotViet (Hoàn thành, Đã hủy…) về được web nếu bật. Khách hàng chọn được một chiều hoặc hai chiều. Hai phần sau mặc định tắt.

Web WordPress không dùng WooCommerce thì tích hợp KiotViet vào website thế nào?

Plugin trong bài cần WooCommerce. Không có WooCommerce thì tự code theo Public API, hoặc dùng KiotViet Web làm trang bán rồi đặt link từ WordPress sang.

Gian hàng của bạn đang ở cách nào trong ba cách trên, và vướng ở đâu? Viết xuống bình luận, càng cụ thể (số chi nhánh, số mã hàng, web đang chạy theme gì) thì mình trả lời càng sát. Có dán ảnh thì che Client ID, Mã bảo mật trước nhé.

Bài viết trong series

Kết nối WooCommerce với KiotViet

0/5đã đọc
  1. 1 KiotViet Sync đã đóng: web WooCommerce đang dùng nên làm gì? Đang đọc Đã đọc
  2. 2 Kết nối KiotViet với website: 3 cách và 6 bước nối WooCommerce Đang đọc Đã đọc
  3. 3 Đồng bộ tồn kho KiotViet với website: cơ chế và cách xử lý khi lệch Đang đọc Đã đọc
  4. 4 Đồng bộ sản phẩm KiotViet về WooCommerce: biến thể, ảnh, bảng giá Đang đọc Đã đọc
  5. 5 Đồng bộ đơn hàng KiotViet: đẩy đơn website thành phiếu Đặt hàng Đang đọc Đã đọc
Sản phẩm nổi bật của Toản
x