← Tất cả tích hợp

Kết nối Nhanh.vn với omniVN

Có thể kết nối

Kết nối OAuth-only (Nhanh Open API v3): nhấn Connect Commerce, cấp quyền trên Nhanh.vn — không dán appId, businessId hay accessToken.

Kết nối Nhanh.vnTạo tài khoản và làm theo hướng dẫn bên dưới — dùng thử 14 ngày.

Cổng sẵn sàng: Open API bật trên Nhanh + NHANH_* / secret store trên Omni0 + quyền channels.connect. Đường chính: OAuth redirect (Connect Commerce).

Giới hạn hiện tại

Những điểm này ảnh hưởng đến khả năng kết nối hoàn chỉnh.
  • OAuth-only: không dán appId / businessId / accessToken trên workspace.
  • Open API phải bật trên Nhanh.vn trước khi Connect Commerce thành công.
  • accessToken ~1 năm, không refresh — phải Connect lại trước khi hết hạn.

Tổng quan

Omni0 kết nối Nhanh Open API v3 qua OAuth redirect. Ứng dụng Nhanh (appId/secret) do operator Omni0 cấu hình sẵn. Người bán chỉ cần bật Open API trên Nhanh.vn, nhấn Connect Commerce trong Omni0, đăng nhập Nhanh và đồng ý cấp quyền. Omni0 đổi accessCode lấy token phía máy chủ và lưu secret-manager. Không có đường dán key trên workspace.

Điều kiện trước khi bắt đầu

  • Tài khoản Nhanh.vn với quyền Giám đốc (hoặc tài khoản được phép cấp quyền Open API).
  • Đã bật “Cho phép kết nối Open API” trong Cài đặt chung → Cài đặt Open API trên Nhanh.vn (bắt buộc — cổng sẵn sàng).
  • Trong Omni0: quyền kết nối kênh trên workspace (channels.connect).
  • Deployment đã cấu hình NHANH_APP_ID / NHANH_SECRET + secret store (operator).

Các bước lấy credential

1. Bật kết nối Open API trên Nhanh.vn

Dùng tài khoản Giám đốc: vào Cài đặt chung → Cài đặt Open API và bật cho phép kết nối. Nếu tắt, bước cấp quyền OAuth sẽ không thành công (readiness gate phía Nhanh).

Bật cài đặt Open API trên trang quản trị Nhanh.vn
Bật cài đặt Open API trên trang quản trị Nhanh.vn · Nhanh.vn Open API

2. Mở Nhanh trong Omni0 và nhấn Connect Commerce

Vào Integrations → Nhanh.vn. OAuth redirect là đường kết nối chính — Omni0 không nhận credential dán tay. Nhấn Connect Commerce; Omni0 mở trang cấp quyền Nhanh trong tab mới. Giữ tab Omni0 mở cho đến khi kết nối xuất hiện.

3. Đăng nhập Nhanh và đồng ý cấp quyền

Trên Nhanh, đăng nhập (nếu cần), chọn quyền (sản phẩm, đơn hàng, kho…) rồi đồng ý. Nhanh trả accessCode về Omni0 (hết hạn ~10 phút, dùng một lần). Omni0 backend đổi accessCode lấy accessToken và businessId — người bán không thấy và không nhập các giá trị này.

Màn hình chọn quyền khi cấp quyền cho app
Màn hình chọn quyền khi cấp quyền cho app · Nhanh.vn Open API

4. Quay lại tab Omni0 và chờ kết nối

Nhanh xác nhận cấp quyền server-to-server — không redirect kèm ?oauth=success. Quay lại tab Omni0 (vẫn mở); khi xong, trang hiện Nhanh account connected và connection active. Token lưu secret-manager phía máy chủ.

Ánh xạ credential với omniVN

Cột "Lấy từ đâu" cho biết giá trị do người dùng nhập, do provider cấp, do omniVN quản lý, hay do OAuth sinh ra.
Field omniVNTên trong tài liệu officialBắt buộcLấy từ đâu
Nhanh app IDapp_idBắt buộcoperator_managed

NHANH_APP_ID trên Convex — không nhập bởi người bán.

Nhanh secret keysecret_keyBắt buộcoperator_managed

NHANH_SECRET trên Convex — không nhập bởi người bán.

Nhanh business IDbusiness_idBắt buộcoauth_authorization

Có sau khi người bán cấp quyền OAuth; Omni0 lưu phía máy chủ.

Nhanh access tokenaccess_tokenBắt buộcoauth_authorization

Đổi từ accessCode sau OAuth; lưu secret-manager, không trả ra trình duyệt.

Người bán: không nhập credential vào form (OAuth-only). Operator Omni0: NHANH_APP_ID / NHANH_SECRET trên Convex. Sau OAuth, Omni0 lưu secret-manager ref (không trả token ra trình duyệt).

Vòng đời token

accessCode hết hạn ~10 phút và chỉ dùng một lần. accessToken v3 ~1 năm; Nhanh chưa hỗ trợ refresh — cần cấp quyền lại trước khi hết hạn. Token mới cùng appId+businessId làm token cũ hết hiệu lực sau ~15 phút.

Lỗi thường gặp

Nút kết nối bị tắt hoặc báo chưa sẵn sàng

Deployment chưa cấu hình đủ secret-store / NHANH_APP_ID + NHANH_SECRET, hoặc thiếu quyền channels.connect. Liên hệ operator Omni0 — không tự dán token để vượt qua.

Lỗi xác thực hoặc ERR_403 sau khi cấp quyền

Thiếu scope khi đồng ý trên Nhanh, Open API chưa bật trên doanh nghiệp, hoặc quyền đã bị thu hồi.

OAuth lỗi / accessCode invalid

accessCode quá 10 phút, đã dùng một lần, hoặc Redirect URL của app Omni0 không khớp cấu hình trên open.nhanh.vn (do operator).

Nguồn chính thức

Khởi tạo app & lấy access token
apidocs.nhanh.vn·Công khai·Đã kiểm chứng 2026-08-31
Giới thiệu Nhanh API v3.0
apidocs.nhanh.vn·Công khai·Đã kiểm chứng 2026-08-31
Nhanh.vn API v3 - Depots
apidocs.nhanh.vn·Công khai·Đã kiểm chứng 2026-08-29
Nhanh.vn API v3 - Products
apidocs.nhanh.vn·Công khai·Đã kiểm chứng 2026-08-29
Nhanh.vn API v3 - Customers
apidocs.nhanh.vn·Công khai·Đã kiểm chứng 2026-08-29
Nhanh.vn API v3 - Orders
apidocs.nhanh.vn·Công khai·Đã kiểm chứng 2026-08-29