Hướng dẫn này giúp bạn kết nối KiotViet với HexaSync bằng cách tạo KiotViet Connector App và cấp quyền truy cập cửa hàng KiotViet. Sau khi kết nối, HexaSync lấy dữ liệu hàng hóa và tồn kho theo từng chi nhánh, đồng thời nhận các thay đổi từ KiotViet qua webhook theo thời gian thực. Đây là bước chuẩn bị để tích hợp KiotViet với các hệ thống khác thông qua HexaSync.
Chuẩn bị trước khi bắt đầu
- Tài khoản Beehexa để đăng nhập HexaSync Automation Engine. Nếu chưa có tài khoản, hãy làm theo hướng dẫn đăng ký tài khoản Beehexa.
- Tài khoản KiotViet có quyền Admin để truy cập chức năng Kết nối API.
- Tên cửa hàng KiotViet (Retailer), Client ID và Mã bảo mật để dùng khi kết nối. Cách lấy các thông tin này có ở Phần 1.
Lưu ý: Chỉ tài khoản KiotViet có quyền Admin mới truy cập được mục Kết nối API.
Phần 1: Lấy thông tin kết nối từ KiotViet
Bước 1: Xác định tên cửa hàng KiotViet
- Tên cửa hàng (Retailer) là phần đứng trước
.kiotviet.vntrong địa chỉ cửa hàng. Ví dụ: địa chỉ cửa hàng làacmestore.kiotviet.vnthì tên cửa hàng làacmestore.
Bước 2: Mở chức năng Kết nối API
- Đăng nhập KiotViet bằng tài khoản có quyền Admin.
- Mở Thiết lập.
- Trong nhóm Cửa hàng, chọn Kết nối API.
- Chọn Chỉnh sửa.
Bước 3: Xác thực tài khoản KiotViet
- Nhập mã xác thực KiotViet gửi qua Zalo hoặc SMS đến số điện thoại của chủ cửa hàng.
- Chọn Tiếp tục.
Bước 4: Tạo Mã bảo mật
Trong phần Điều khoản sử dụng của KiotViet, thực hiện các thao tác sau:
- Nhập Tên kết nối, ví dụ
HexaSync. - Giữ trạng thái Đang hoạt động.
- Chọn Tạo mã để tạo Mã bảo mật.
- Sao chép Client ID và Mã bảo mật, rồi lưu ở nơi an toàn.
- Chọn Lưu để hoàn tất.
Lưu ý:
- Không cần bật tùy chọn Cho phép truy xuất thông tin khách hàng, hoá đơn, đặt hàng. KiotViet Connector trong hướng dẫn này chỉ dùng dữ liệu hàng hóa và tồn kho.
- Mã bảo mật có giá trị như mật khẩu, không chia sẻ cho người khác. Nếu chọn Tạo mã lần nữa, mã cũ sẽ ngừng hoạt động và bạn cần cập nhật thông tin kết nối trên HexaSync theo Phần 4.
Phần 2: Kết nối KiotViet trên HexaSync
Bước 1: Đăng nhập HexaSync
- Truy cập HexaSync Automation Engine và đăng nhập bằng tài khoản Beehexa.
Bước 2: Bắt đầu kết nối KiotViet
- Mở trang thiết lập kết nối KiotViet trên HexaSync.
- Tiếp tục quy trình thiết lập KiotViet Connector hiển thị trên HexaSync.
Bước 3: Nhập thông tin kết nối KiotViet
- Nhập các thông tin đã chuẩn bị ở Phần 1:
| Trường thông tin | Giá trị cần nhập |
|---|---|
| Store Name (Retailer) | Tên cửa hàng KiotViet, ví dụ acmestore |
| Client ID | Client ID lấy từ mục Kết nối API trên KiotViet |
| Client Secret (Mã bảo mật) | Mã bảo mật đã tạo ở Bước 4 |
- Chọn Continue.
Lưu ý: Bạn có thể dán địa chỉ cửa hàng đầy đủ vào trường Store Name (Retailer), ví dụ
https://acmestore.kiotviet.vn. HexaSync sẽ tự lấy ra tên cửa hàngacmestore.
Bước 4: Hoàn tất kết nối KiotViet
- Khi HexaSync xác thực thông tin thành công, màn hình hiển thị Connected — Your KiotViet Store Is Ready.
- Chọn Continue để chuyển sang bước tiếp theo.
HexaSync tự đăng ký các webhook cần thiết để nhận thay đổi hàng hóa và tồn kho từ KiotViet trong lần lấy dữ liệu đầu tiên. Bạn không cần tự cấu hình Webhook URL trên KiotViet.
Bước 5: Tạo KiotViet Connector
- Kiểm tra KiotViet hiển thị trạng thái Connected.
- Chọn Create KiotViet Connector.
Lưu ý: Nếu cửa hàng đã từng được kết nối bằng cùng thông tin, HexaSync sẽ cập nhật kết nối hiện có thay vì tạo thêm kết nối mới.
Bước 6: Đặt tên KiotViet Connector
- Kiểm tra tên và mô tả Connector do HexaSync đề xuất.
- Chỉnh sửa nếu cần để dễ nhận biết cửa hàng được kết nối.
- Chọn Continue.
- Giữ trang đang mở trong khi HexaSync tạo Connector. Quá trình này có thể mất vài phút. Sau khi hoàn tất, HexaSync tự chuyển đến trang Tasks của KiotViet Connector App vừa tạo.
Phần 3: Kiểm tra kết nối thành công
Mở Connector Apps và chọn KiotViet Connector App vừa tạo. Connector được tạo với ba tác vụ mặc định:
| Tác vụ | Chức năng | Tần suất |
|---|---|---|
| Inventory Items | Lấy dữ liệu hàng hóa từ KiotViet | 15 phút một lần |
| Stock: By Branch | Lấy tồn kho theo từng chi nhánh | Quét toàn bộ 3 giờ một lần |
| Webhooks Registered | Kiểm tra các webhook đã đăng ký trên cửa hàng | Mỗi giờ |
Cập nhật dữ liệu theo thời gian thực
- Bên cạnh lịch lấy dữ liệu định kỳ, KiotViet Connector dùng webhook để nhận thay đổi hàng hóa và tồn kho từ KiotViet theo thời gian thực.
- Khi webhook hoạt động, thay đổi được gửi về HexaSync ngay khi KiotViet phát sinh sự kiện tương ứng, không phải chờ lần lấy dữ liệu định kỳ tiếp theo.
- Nhờ vậy dữ liệu trên HexaSync được cập nhật kịp thời hơn, phục vụ theo dõi tồn kho và chuẩn bị cho các luồng tích hợp với hệ thống khác.
Lưu ý:
- Nếu HexaSync hiển thị Connected — Real-time Updates Are Not Ready, kết nối vẫn dùng được nhưng dữ liệu chỉ cập nhật theo lịch. Hãy liên hệ support@beehexa.com để được hỗ trợ kích hoạt cập nhật qua webhook.
- Theo cấu hình mặc định trong hướng dẫn này, KiotViet Connector chỉ đọc dữ liệu và không tự động thay đổi dữ liệu trong KiotViet.
Phần 4: Cấp lại quyền kết nối KiotViet trên HexaSync
Nếu đã tạo KiotViet Connector App và cần cập nhật quyền truy cập hoặc thông tin xác thực, bạn bắt đầu quy trình cấp lại quyền từ Connector App hiện có.
Bước 1: Mở Settings trong KiotViet Connector App
- Mở Connector Apps, chọn KiotViet Connector App cần cấp lại quyền. Nhấn chọn Settings ở menu bên trái.
Bước 2: Chọn Re-authorize
- Trong Settings, tìm phần thông tin kết nối KiotViet.
- Chọn Re-authorize để bắt đầu quy trình cấp lại quyền.
Bước 3: Cấp lại quyền kết nối
- Làm theo hướng dẫn trên màn hình HexaSync để hoàn tất việc cấp lại quyền cho kết nối KiotViet hiện có.
- Nếu cần cập nhật thông tin xác thực, nhập Client ID và Mã bảo mật hợp lệ của cửa hàng KiotViet.
Lưu ý: Nếu Mã bảo mật đã được tạo lại trong KiotViet, mã cũ không còn hiệu lực. Không dùng mã cũ khi cập nhật thông tin kết nối.
Phần 5: Lỗi thường gặp và cách xử lý
| Thông báo | Cách xử lý |
|---|---|
| KiotViet Did Not Accept Your Details | KiotViet không chấp nhận thông tin kết nối đã nhập. Kiểm tra Store Name, Client ID và Mã bảo mật, rồi chọn Fix my details and try again để nhập lại. |
| This KiotViet Store Is Already Registered By Another User | Cửa hàng đã được người dùng HexaSync khác đăng ký. Nhờ người quản lý kết nối mở Credentials → Manage, chọn KiotViet rồi dùng Team access → Invite member để cấp quyền Editor cho tài khoản Beehexa của bạn. |
| HexaSync Could Not Save This KiotViet Connection | HexaSync không lưu được kết nối. Thử lại sau vài phút. Nếu vẫn lỗi, gửi ảnh chụp màn hình đến support@beehexa.com. |
| HexaSync Could Not Link The Credential To Your Profile | Kết nối đã được lưu nhưng chưa được gắn vào Connector App. Chọn Go to Manage Credentials để xử lý hoặc liên hệ support@beehexa.com. |
| Connected — Real-time Updates Are Not Ready | Kết nối dùng được nhưng cập nhật qua webhook chưa sẵn sàng; dữ liệu vẫn cập nhật theo lịch. Liên hệ support@beehexa.com để được hỗ trợ. |
| The name already exists | Tên đã được sử dụng. Đặt tên KiotViet Connector khác. |
| Profile Quota Reached | Đã đạt hạn mức tạo ứng dụng. Liên hệ support@beehexa.com để được hỗ trợ về hạn mức. |
Lưu ý:
- Nếu cửa hàng đã được người dùng khác đăng ký nhưng không còn ai quản lý kết nối cũ, hãy liên hệ support@beehexa.com để được hỗ trợ gỡ kết nối trước khi thực hiện lại. Không cần thay Client ID hoặc Mã bảo mật chỉ vì lỗi này.
- Với các lỗi khác, liên hệ support@beehexa.com kèm ảnh chụp màn hình thông báo lỗi (đã che thông tin nhạy cảm).
Phần 6: Câu hỏi thường gặp
Sau khi kết nối KiotViet, HexaSync lấy những dữ liệu nào và bao lâu cập nhật một lần?
KiotViet Connector lấy dữ liệu hàng hóa và tồn kho theo chi nhánh.
Tác vụ Inventory Items chạy 15 phút một lần, Stock: By Branch quét toàn bộ 3 giờ một lần, và Webhooks Registered kiểm tra webhook mỗi giờ (xem Phần 3).
Khi webhook hoạt động, các thay đổi hàng hóa và tồn kho được gửi về HexaSync theo thời gian thực mà không cần chờ lần lấy dữ liệu định kỳ.
Tôi có cần tự cấu hình Webhook URL trên KiotViet không?
Không. HexaSync tự đăng ký các webhook cần thiết trong lần lấy dữ liệu đầu tiên.
Nếu màn hình hiển thị Connected — Real-time Updates Are Not Ready, kết nối vẫn dùng được theo lịch. Hãy liên hệ support@beehexa.com để được hỗ trợ cập nhật theo thời gian thực.
Sau khi tạo KiotViet Connector, tôi có thể tích hợp KiotViet với Shopify ngay không?
KiotViet Connector là bước chuẩn bị để tích hợp KiotViet với Shopify thông qua HexaSync.
Để trao đổi dữ liệu giữa hai hệ thống, bạn cần thiết lập thêm luồng tích hợp theo yêu cầu nghiệp vụ. Việc tạo KiotViet Connector không tự động hoàn tất toàn bộ quá trình tích hợp.
HexaSync có ghi hoặc sửa dữ liệu trên KiotViet không?
Không. Theo cấu hình mặc định, KiotViet Connector chỉ đọc dữ liệu hàng hóa và tồn kho, không tự động thay đổi dữ liệu trong KiotViet.