Kết nối Nhanh.vn với omniVN
Có thể kết nốiDoanh nghiệp tự tạo app trên open.nhanh.vn, rồi chủ hoặc admin workspace dán App ID và Secret Key vào trang Nhanh.vn trong omniVN. Sau đó nhấn Connect Commerce và cấp quyền trên Nhanh.vn.
Cổng sẵn sàng: workspace đã lưu app Nhanh của doanh nghiệp + Open API bật trên Nhanh + quyền channels.connect. Đường chính: OAuth redirect (Connect Commerce).
Các bước lấy credential
1. Tạo app trên open.nhanh.vn
Đăng nhập open.nhanh.vn, mở Danh sách app và tạo app mới: đặt Tên App (người cấp quyền sẽ thấy tên này trên Nhanh), chọn Trạng thái Hoạt động và nhập Redirect URL đúng từng ký tự: https://oauth.omnivn.com/connectors/nhanh/callback. Nhanh không duyệt app; app dùng được ngay sau khi tạo. Chưa bật webhooks ở bước này.
2. Dán App ID và Secret Key vào omniVN
Mở chi tiết app để lấy App ID và Secret Key. Trong omniVN, vào Integrations → Nhanh.vn: khi workspace chưa có app, trang hiện khung “Register your Nhanh app”; nếu đã có, dùng Settings → Nhanh app → Update app. Dán App ID và Secret Key rồi nhấn Save app. Có thể thêm ngay webhook verify token (16–128 chữ và số, tự đặt) hoặc thêm sau. omniVN mã hoá các giá trị này và không bao giờ hiện lại; đừng gửi Secret Key qua chat hay email. Nhanh không có cách kiểm tra app khi chưa đăng nhập, nên omniVN kiểm tra App ID và Secret Key ở lần Connect đầu tiên.
3. 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 → Cài đặt chung, cuộn tới khối Cài đặt Open API, bật “Cho phép kết nối Open API” và chọn vai trò được phép cấp quyền (thường là Giám đốc). Bảng bên dưới liệt kê các ứng dụng đã được cấp quyền cùng ngày bắt đầu / hết hạn accessToken; sau khi kết nối, app bạn tạo ở bước 1 cũng xuất hiện ở đây. Nếu công tắc tắt, bước cấp quyền OAuth sẽ không thành công (readiness gate phía Nhanh).
4. Mở Nhanh trong omniVN và nhấn Connect Commerce
Sau khi lưu app, trang Integrations → Nhanh.vn hiện nút Connect Commerce. OAuth redirect là đường kết nối chính; accessToken không dán tay. Nhấn Connect Commerce; omniVN mở trang cấp quyền Nhanh trong tab mới. Giữ tab omniVN mở cho đến khi kết nối xuất hiện.
5. Đăng nhập Nhanh và đồng ý cấp quyền
Trên Nhanh, đăng nhập (nếu cần), kiểm tra đúng Tên App bạn đã đặt, chọn quyền (sản phẩm, đơn hàng, kho…; có thể giới hạn kho) rồi nhấn Đồng ý. Tài khoản nhân viên chỉ cấp được những quyền chính nó đang có. Nhanh chuyển trình duyệt về callback của omniVN kèm accessCode (hết hạn 10 phút, dùng một lần). omniVN 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.
6. Quay lại tab omniVN và chờ kết nối
omniVN đổi accessCode lấy token phía máy chủ. Quay lại tab omniVN (vẫn mở); khi xong, trang Nhanh.vn trong omniVN hiện trạng thái Healthy cùng thời điểm đồng bộ gần nhất. Token lưu secret-manager phía máy chủ. Muốn thu hồi quyền, dùng menu của ứng dụng trong bảng Cài đặt Open API trên Nhanh.vn.
7. Bật webhooks sau khi đã lưu verify token
Chỉ làm bước này khi verify token đã được lưu trong omniVN (Settings → Nhanh app) và kết nối Nhanh đang Healthy. Trên open.nhanh.vn, sửa app → Bật webhooks, chọn version 3.0, nhập Webhooks callback URL do omniVN cung cấp (liên hệ omniVN để nhận) và đúng verify token đã lưu. Nếu bật sớm hơn, omniVN sẽ từ chối webhooks của doanh nghiệp bạn; Nhanh có thể tự tắt webhooks hoặc khoá app khi lỗi lặp lại. Đặt app sang Ngừng hoạt động sẽ dừng cả API lẫn webhooks.