Kết nối Nhanh.vn với website: 3 cách và 5 bước nối WooCommerce

Chào anh em! Shop bán ở cửa hàng bằng Nhanh.vn POS, lại có thêm website WooCommerce thì chuyện quen thuộc là: sản phẩm nhập hai lần, một lần trên Nhanh, một lần trên web; cửa hàng bán hết từ trưa mà web vẫn báo còn hàng; có đơn online thì nhân viên chép tên, số điện thoại, địa chỉ sang Nhanh. Kết nối Nhanh.vn với website là để web và cửa hàng dùng chung một nguồn dữ liệu. Có ba đường: dùng website do Nhanh.vn cung cấp (Nhanh.Web), tự code qua Open API của Nhanh.vn, hoặc cài plugin nếu web chạy WordPress/WooCommerce. Đọc xong anh em biết shop mình hợp đường nào, còn web chạy WooCommerce thì làm theo 5 bước ở cách 3 là nối xong.

Plugin ở cách 3 do mình viết và bảo trì, nó kết nối Nhanh.vn qua Open API. Anh em đang cân ba cách với nhau thì nên biết trước chuyện này. Chỗ nào bài nói về Nhanh.Web hay Open API, mình dựa vào trang hướng dẫn, tài liệu Open API và giao diện open.nhanh.vn, mở ra kiểm lại hồi tháng 10/2026. Nhanh đổi giao diện thì tên nút có thể lệch chút, anh em cứ theo ý từng bước.

Kết nối Nhanh.vn với website gồm những việc gì?

• Sản phẩm (tên, giá, ảnh, mô tả, biến thể) nhập một lần trên Nhanh.vn rồi đi về web.
• Cửa hàng bán một món thì số tồn kho trên web giảm theo.
• Đơn đặt trên web vào Nhanh.vn để đóng gói, gửi hãng như mọi đơn khác.
• Trang thanh toán báo phí vận chuyển theo các hãng shop đã nối trên Nhanh.vn.
• Khách online và khách tại cửa hàng nằm chung một danh sách khách hàng.

Chuẩn bị trước khi kết nối

• Mỗi sản phẩm, biến thể trên Nhanh.vn có mã (SKU) riêng; cửa hàng và kho khai đủ. Nhanh sai thì web sai theo.
• Bật Cho phép kết nối Open API trong cài đặt doanh nghiệp trên Nhanh.vn (cần cho cách 2 và 3).
• Cần một tài khoản trên open.nhanh.vn để tạo app. Tài liệu Nhanh ghi tài khoản này chỉ để quản trị app, không cần quyền quản trị trên Nhanh.vn.

Cách 1: Dùng website của Nhanh.vn (Nhanh.Web)

Nhanh.vn có sẵn kênh bán Website, trên trang giới thiệu gọi là Nhanh.Web. Ở trang hướng dẫn kênh Website, Nhanh.vn giới thiệu Nhanh.Web là website bán hàng lấy thẳng sản phẩm, đơn hàng, tồn kho từ hệ thống. Cách bật: vào Kênh bán → Thêm kênh bán → Website, bấm Tạo Website → Dùng thử ngay, rồi chọn tên miền: kết nối tên miền riêng, hoặc dùng tạm tên miền demo của Nhanh dạng testdemo.store.nhanh.vn.

Trên trang giới thiệu Nhanh.Web, Nhanh.vn ghi thêm: hơn 200 mẫu giao diện, không cần biết lập trình; web hiển thị tồn kho theo cửa hàng, chặn đặt hàng khi hết hàng, đồng bộ khuyến mại, coupon, tích điểm giữa online và offline; có cổng thanh toán và hãng vận chuyển. Giá gói xem trên trang đó.

• Cách này hợp với shop chưa có website, hoặc có web nhưng chưa có gì đáng giữ (ít bài viết, chưa có khách tìm tới từ Google).
• Công sức bỏ ra ít vì phần đồng bộ là việc của Nhanh. Đổi lại giao diện và tính năng đi theo nền tảng của Nhanh. Hai trang này không nói việc chuyển bài viết từ WordPress sang; shop có web nhiều nội dung nên hỏi Nhanh.vn trước khi quyết.

Cách 2: Tự code qua Open API của Nhanh.vn

Website tự viết, hoặc dev muốn nối Nhanh.vn với hệ thống riêng thì gọi thẳng Open API. Theo thông báo trên tài liệu, từ 23/09/2026 tài liệu API chuyển sang developers.nhanh.group (thương hiệu vẫn là Nhanh.vn); app quản lý ở open.nhanh.vn, API bán hàng chạy ở pos.open.nhanh.vn. Những việc phải tự lo:

1. Lấy token bằng cách tạo app, đưa người dùng tới trang đăng nhập Nhanh.vn kèm appId và returnLink (https), nhận accessCode (sống 10 phút) rồi đổi cùng secretKey lấy accessToken. Token hạn 1 năm, không có refresh token.
2. Gọi API bằng POST, appId và businessId đặt trên URL, accessToken đặt ở header Authorization; danh sách dài thì phân trang bằng next.
3. Giữ trong giới hạn 150 request mỗi 30 giây cho từng đường dẫn API; vượt thì nhận ERR_429 kèm thời gian khoá, gọi tiếp lúc đang khoá thì bị khoá lâu thêm.
4. Khi nhận webhook, verify token nằm ở header Authorization; web phải trả HTTP 200 nhanh, không thì Nhanh gửi lại tối đa 3 lần, tỉ lệ thành công thấp thì Nhanh có thể tắt webhook của app.
5. Chọn v3, vì open.nhanh.vn ghi webhook version 2.0 “Ngừng hỗ trợ sau 31-08-2026”, còn token v2 gọi API v3 thì nhận ERR_INVALID_VERSION.

Code PHP mẫu trong WordPress cho từng bước mình viết ở bài tích hợp Open API Nhanh.vn.

• Cách này hợp với lập trình viên, web không chạy WooCommerce, hoặc khi chỉ cần một luồng lẻ như kéo tồn kho.
• Viết code gọi được API thì không lâu. Tốn thời gian là phần xung quanh: nhắc hạn token, đếm request, hàng đợi webhook, khớp sản phẩm, màn hình đăng đơn cho nhân viên. Công sức tính bằng ngày tới tuần, và còn sửa tiếp mỗi lần Nhanh đổi phiên bản API.

Cách 3: Cài plugin nối Nhanh.vn với WooCommerce

Web chạy WooCommerce thì không phải viết lại những thứ ở cách 2. Mình lấy ví dụ plugin kết nối Nhanh.vn với WooCommerce của mình, bản 1.6.4. Website cần WooCommerce 5.6 trở lên, PHP 7.2 đến 8.2, hosting bật ionCube Loader. Cài và kích hoạt plugin, vào WooCommerce → Nhanh.vn, tab License dán mã rồi bấm Active License. Xem cài đặt plugin và kích hoạt license. Sau đó kết nối gồm 5 bước.

Toàn bộ quá trình, từ tạo app tới lúc đơn web lên Nhanh.vn, có trong video gần 3 phút dưới đây.

Bước 1: Tạo app trên open.nhanh.vn

Mở tab Nhanh.vn trong plugin: trang liệt kê sẵn các bước kèm đường dẫn của chính website bạn. Trên open.nhanh.vn, mục Danh sách app, bấm Thêm mới rồi điền:

• Tên App (hiện ra lúc cấp quyền), Trạng thái Đang hoạt động.
• Redirect URL chép từ plugin, dạng https://tenmien.com/wp-json/nhanhvn/v1/return_url/.
• Bật webhooks, Webhooks version chọn 3.0, callback URL dạng https://tenmien.com/wp-json/nhanhvn/v1/webhook/, verify token chép từ ô verify token của plugin (plugin tự sinh 24 ký tự).
• Tích các sự kiện Sửa sản phẩm, Xóa sản phẩm, Cập nhật tồn kho, Sửa đơn hàng, Xóa đơn hàng, rồi bấm Lưu.

Bước 2: Nhập Business ID, App ID, Secret Key

Tạo app xong, mở trang chi tiết app để lấy App ID và Secret Key. Quay lại tab Nhanh.vn của plugin, chọn Version 3 ở dòng “Bật webhooks > Chọn version” (cài mới plugin để sẵn Version 2), nhập Business ID (ID doanh nghiệp trên Nhanh.vn), App ID, Secret Key rồi bấm Lưu thay đổi. Bấm lưu cũng là lúc verify token webhook có hiệu lực, đừng bỏ qua. Xem kết nối API Nhanh.vn.

Bước 3: Bấm Get accessCode để cấp quyền

Lưu xong, dòng 9 hiện link Get accessCode. Bấm vào, đăng nhập Nhanh.vn, đồng ý cấp quyền; Nhanh trả về website và plugin tự đổi lấy accessToken. Thành công thì tab hiện khung “Kết nối thành công!” kèm ID doanh nghiệp, dòng “Token hết hiệu lực vào” và danh sách quyền; các tab Kho hàng, Vận chuyển, Webhook, Đồng bộ… cũng hiện ra từ lúc này.

⚠️ Token hạn 1 năm và plugin không tự gia hạn: ghi ngày hết hạn vào lịch, trước hạn bấm Get accessCode lại. Từng bước kèm lỗi hay gặp có ở bài lấy access token Nhanh.vn.

Bước 4: Đồng bộ kho từ Nhanh.vn về web

Tab Kho hàng, bấm Đồng bộ kho từ Nhanh.vn về web. Mỗi kho hiện thành một thẻ có Địa chỉ, Đường dẫn tới bản đồ và ba ô Ẩn khỏi danh sách, Không tính tồn kho, Đặt làm kho chính. Luôn tích một kho chính. Có nhiều kho thì mở Khu vực bán hàng ở từng thẻ, chọn các tỉnh kho đó phụ trách, bấm “Okie” rồi bấm Lưu ở cuối trang: tính phí ship sẽ lấy kho phụ trách tỉnh của khách, không có thì dùng kho chính. Xem kho hàng.

🚨 Đừng bỏ qua bước này: tồn kho trên web chỉ cộng các kho đã đồng bộ về, chưa bấm thì tồn về 0; Nhanh.vn có thêm kho mới thì bấm đồng bộ lần nữa. Cách tồn kho được tính và cách xử lý khi lệch mình viết ở bài đồng bộ tồn kho Nhanh.vn với website.

Bước 5: Kiểm tra webhook đã về web

Khung đỏ trên open.nhanh.vn ghi app phải “đăng nhập cấp quyền, lấy được accessToken thì sau đó mới có các sự kiện bắn về”, nên sau bước 3 webhook mới bắt đầu về. Ở tab Webhook của plugin, ô Chạy nền (Background Queue) bật sẵn: nhận webhook, lưu hàng đợi, trả 200 cho Nhanh ngay rồi xử lý sau bằng Action Scheduler. Lần tới cửa hàng bán hay nhập một món, mở tab Webhook Queue: thấy dòng inventoryChange ở trạng thái Hoàn thành là đường webhook đã thông. Xem webhook.

Theo tài liệu, Nhanh chỉ gửi webhook cho dữ liệu phát sinh sau khi cấp quyền, nên sản phẩm và tồn kho đang có phải kéo về một lần ở tab Đồng bộ sản phẩm; sau đó webhook lo phần thay đổi.

Kết nối xong, hằng ngày làm gì?

• Sản phẩm kéo về ở tab Đồng bộ sản phẩm, gồm Cài đặt (giá, ảnh, mô tả, trọng lượng, kích thước, tồn kho), Bước 1 danh mục, Bước 2 sản phẩm với Mapping / Tạo mới / Bỏ qua cho từng dòng. Dữ liệu chỉ đi một chiều từ Nhanh.vn về web, plugin không xoá sản phẩm. Xem đồng bộ sản phẩm.
• Đơn hàng lên Nhanh.vn bằng nút “Đăng đơn hàng lên Nhanh.vn” trong trang đơn, đăng hàng loạt từ danh sách đơn, hoặc bật tab Tự động đăng đơn (mặc định tắt). Cả ba có sẵn trong plugin, không phải mua addon. Trạng thái giao hàng anh em theo dõi trên Nhanh.vn.
• Muốn hiện phí ship thì vào tab Vận chuyển, bấm “Lấy danh sách các hãng vận chuyển về web” rồi tích hãng muốn dùng. Ô địa chỉ 2 cấp bật ở tab Cài đặt chung (chọn bộ dữ liệu sau sáp nhập, bấm “Cập nhật database”). Nhanh không trả được giá thì hiện “Phí vận chuyển sẽ báo sau.” để khách vẫn đặt được. Xem vận chuyển.
• Phần xem cửa hàng còn hàng ở trang sản phẩm bật ở tab Kho hàng, mặc định tắt (xem kho còn hàng).
• Đồng bộ khách hàng (API v3) mặc định tắt; khách được kéo về bằng tay hoặc theo lịch, không theo thời gian thực (đồng bộ khách hàng).

Ba cách đăng đơn và các lựa chọn trong popup mình viết riêng ở bài đăng đơn lên Nhanh.vn.

• Cách này hợp với chủ shop đã có web WooCommerce và dùng Nhanh.vn ở cửa hàng, hoặc dev, agency làm web cho khách dùng Nhanh.vn.
• Cần hosting có ionCube Loader, tài khoản Nhanh.vn đã bật Open API, license plugin (1 license cho 1 tên miền, gói 1 năm hoặc mãi mãi).
• Công sức là làm theo 5 bước trên, mình hỗ trợ cài đặt miễn phí; Nhanh đổi API thì cập nhật plugin.

Site cũ đang chạy API v2

Webhook version 2.0 đã quá mốc “Ngừng hỗ trợ sau 31-08-2026”, nên site cũ chuyển sang v3: cập nhật plugin, chọn Version 3, nhập Business ID, đổi Webhooks version của app sang 3.0, rồi bấm Get accessCode để lấy token v3 (token v2 gọi API v3 sẽ báo ERR_INVALID_VERSION). Lên v3 có thêm tab Đồng bộ sản phẩm và Đồng bộ khách hàng.

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

Cách	Hợp với	Công sức
Website của Nhanh.vn (Nhanh.Web)	Shop chưa có web, hoặc web cũ không cần giữ	Ít; giao diện theo mẫu của Nhanh
Tự code Open API	Web tự viết, hệ thống riêng, một luồng lẻ	Nhiều; tự lo token, giới hạn gọi, webhook
Plugin WooCommerce	Đã có web WooCommerce, muốn giữ nội dung	Làm theo 5 bước; cần ionCube, license

Anh em đang phân vân bỏ WordPress sang Nhanh.Web thì nhìn vào chính website hiện tại. Web có nhiều bài viết, có đơn đều từ Google thì giữ nó và kết nối với Nhanh.vn. Web chỉ là trang giới thiệu ít người vào thì Nhanh.Web cho gọn, một chỗ quản lý.

Lỗi hay gặp khi kết nối

• Không thấy link Get accessCode thường do chưa nhập App ID, Secret Key hoặc chưa bấm Lưu thay đổi.
• Cấp quyền xong mà không thấy “Kết nối thành công!” thì kiểm Secret Key, xem Redirect URL trên app có khớp đường dẫn plugin đưa không, app có ở trạng thái Đang hoạt động không, doanh nghiệp đã bật Open API chưa.
• Báo ERR_INVALID_VERSION là đang dùng token v2 cho API v3: chọn Version 3, lưu, rồi bấm Get accessCode lại.
• Tồn kho trên web về 0 hàng loạt thường do chưa đồng bộ kho, hoặc Nhanh vừa thêm kho mới mà chưa kéo về.
• Webhook Queue trống dù trên Nhanh có thay đổi có thể do chưa có accessToken, app chưa bật webhook hoặc chưa tích sự kiện, verify token chưa lưu hoặc lệch, web ở máy local, tường lửa chặn đường dẫn /wp-json/, hoặc license hết hạn (đường dẫn webhook trả 404).

Dùng plugin thì xem thêm trang hỏi đáp về plugin Nhanh.vn.

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

Kết nối có phải chờ Nhanh.vn duyệt hay cấp gì không?

Không phải chờ ai. Shop tự bật “Cho phép kết nối Open API”, tự tạo app trên open.nhanh.vn và tự cấp quyền. Plugin của mình kết nối qua đúng con đường đó, không phải ứng dụng do Nhanh.vn phát hành.

Dữ liệu đi hai chiều hay một chiều?

Sản phẩm, giá, ảnh, tồn kho đi một chiều từ Nhanh.vn về web. Đơn hàng đi từ web lên Nhanh.vn. Khách hàng (API v3) chọn được chỉ kéo về, chỉ đẩy lên hoặc hai chiều.

Website không dùng WooCommerce thì sao?

Dùng Nhanh.Web hoặc tự code qua Open API. Plugin trong bài chỉ chạy với WooCommerce.

Anh em đang kết nối mà vướng chỗ nào cứ để lại bình luận, nhớ che Secret Key, token và số điện thoại trước khi dán ảnh nhé. Dù anh em chọn cách nào, chúc shop sớm hết cảnh nhập một sản phẩm hai lần 🚀