Kết nối Open API Nhanh.vn

Kết nối gồm những gì

Plugin nói chuyện với Nhanh.vn qua Open API. Để Nhanh.vn chấp nhận, website cần:

• App ID và Secret Key — của một app bạn tạo ở open.nhanh.vn. Tài khoản developer ở đó chỉ để quản lý app, không cần quyền quản trị cửa hàng.
• Business ID — ID doanh nghiệp (cửa hàng) của bạn trên Nhanh.vn.
• Access token — Nhanh.vn cấp sau khi người có quyền quản trị cửa hàng bấm đồng ý ở bước Get accessCode. Plugin tự lưu, bạn không phải chép.

Cửa hàng phải bật "Cho phép kết nối Open API" trong cài đặt doanh nghiệp trên Nhanh.vn, nếu không mọi lần gọi API đều bị từ chối.

Xem video

Bước 1 — Mở tab Nhanh.vn, chọn Version 3

Vào WooCommerce → Nhanh.vn → Nhanh.vn. Tab này tự liệt kê các bước 1–9; ba dòng cần chép sang app nằm ngay trong danh sách.

1. Nhanh.vn — tab thứ hai trên thanh tab.
2. Version 3 — chọn phiên bản API. Website mới luôn chọn Version 3: Nhanh.vn ngừng hỗ trợ webhook 2.0 sau 31/08/2026 và API v2.0 sau 30/11/2026.
3. Thay đổi verify token — plugin tự sinh sẵn một mã 24 ký tự ở ô bên cạnh (ô chỉ đọc). Chỉ bấm khi muốn đổi mã; đổi rồi thì phải bấm Lưu thay đổi và dán mã mới sang app trên Nhanh.vn.

Chép ba thứ sang bước 2:

• Redirect URL (dòng 3) — dạng https://ten-mien-cua-ban.vn/wp-json/nhanhvn/v1/return_url/.
• Webhooks callback URL (dòng 5) — dạng https://ten-mien-cua-ban.vn/wp-json/nhanhvn/v1/webhook/.
• Webhooks verify token (dòng 6) — mã trong ô.

Bước 2 — Tạo app trên open.nhanh.vn

Đăng nhập open.nhanh.vn → Danh sách app → Thêm mới.

1. Tên App — tên bất kỳ, ví dụ "Website WooCommerce". Tên này hiện ra lúc bạn cấp quyền.
2. Trạng thái — Đang hoạt động. Để "Ngừng hoạt động" thì app không gọi được API và không nhận webhook.
3. Redirect URL — dán Redirect URL của plugin.
4. Bật webhooks — bật. Nhanh.vn ghi chú: phải cấp quyền lấy được access token xong thì mới có sự kiện gửi về.
5. Webhooks version — version 3.0. Bản 2.0 đã ghi "Ngừng hỗ trợ sau 31-08-2026".
6. Webhooks callback URL — dán Webhooks callback URL của plugin. Nhanh.vn yêu cầu địa chỉ này chạy https.
7. Webhooks verify token — dán đúng mã trong ô của plugin.
8. Chọn các sự kiện muốn nhận webhooks — tích 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. Plugin không xử lý Thêm sản phẩm, Thêm đơn hàng, Trả hàng 1 phần nên không cần tích. Chi tiết từng sự kiện xem bài webhook.
9. Lưu.

Lưu xong, mở app vừa tạo trong danh sách để lấy App ID và Secret Key.

Bước 3 — Nhập Business ID, App ID, Secret Key

Quay lại tab Nhanh.vn của plugin, cuộn xuống dòng 8.

1. Business ID — ID doanh nghiệp của cửa hàng trên Nhanh.vn (một dãy số). Với API v3, plugin dùng chính số này để gọi API và để kiểm tra webhook gửi đến, nên phải đúng. Không rõ ID là số nào thì hỏi bộ phận hỗ trợ của Nhanh.vn.
2. App ID — chép từ app vừa tạo.
3. Secret Key — chép từ app vừa tạo. Ô này hiện dấu chấm để không lộ mã khi bạn chụp màn hình.
4. Lưu thay đổi — bắt buộc bấm trước bước 4. Bấm xong, dòng 9 với liên kết Get accessCode mới hiện ra.
5. Get accessCode — sang bước 4.

Bước 4 — Get accessCode để cấp quyền

1. Bấm Get accessCode. Trình duyệt mở trang đăng nhập Nhanh.vn.
2. Đăng nhập bằng tài khoản có quyền quản trị cửa hàng, bấm đồng ý và chọn đủ quyền: sản phẩm, tồn kho, kho, đơn hàng, vận chuyển, khách hàng. Quyền cố định lúc cấp; muốn thêm quyền sau này phải cấp quyền lại từ đầu.
3. Nhanh.vn đưa bạn về website. Mã cấp quyền chỉ sống 10 phút nên đừng để trang chờ lâu.

1. ID doanh nghiệp trên Nhanh.vn — đối chiếu với ô Business ID ở bước 3.
2. Token hết hiệu lực vào — ngày giờ phải cấp quyền lại. Ghi lịch nhắc trước ngày này vài hôm.

Tải lại trang: thanh tab giờ có đủ Kho hàng, Vận chuyển, Webhook, Đồng bộ sản phẩm, Đồng bộ khách hàng, Tự động đăng đơn.

Kiểm tra đã kết nối đúng chưa

1. Khung cuối tab Nhanh.vn ghi Kết nối thành công! và ngày hết hạn còn xa.
2. Mở tab Kho hàng, bấm Đồng bộ kho từ Nhanh.vn về web — danh sách kho của bạn hiện ra là API đã chạy.

Chuyển từ API v2 sang v3

Website cài từ trước thường đang chạy v2. Token v2 không gọi được API v3, nên phải cấp quyền lại. Làm theo thứ tự:

1. Trên open.nhanh.vn, sửa app đang dùng: Webhooks version → version 3.0, kiểm tra các sự kiện như bước 2, Lưu.
2. Tab Nhanh.vn của plugin: chọn Version 3, điền Business ID (v2 không cần ô này, v3 thì bắt buộc), bấm Lưu thay đổi.
3. Bấm Get accessCode và cấp quyền lại.
4. Tab Kho hàng: bấm đồng bộ kho lại. Tab Vận chuyển: bấm lấy danh sách hãng lại (logo hãng chỉ có ở v3).
5. Tab Đồng bộ sản phẩm (thay cho tab Đồng bộ thông tin sản phẩm của v2): bấm Khởi tạo bảng ngay. ID Nhanh đã gắn cho sản phẩm từ thời v2 vẫn giữ nguyên.
6. Tab Tự động đăng đơn: chọn Tài khoản nhận tiền chuyển khoản nếu bạn nhận chuyển khoản.

Lỗi thường gặp

Tiếp theo: đồng bộ kho hàng.