Hướng dẫn này trình bày cách kết nối Acumatica ERP với HexaSync lần đầu, kiểm tra dữ liệu sau khi kết nối và cấp lại quyền khi cần. Sau khi hoàn tất, bạn sẽ có một Acumatica Connector App để kiểm tra dữ liệu tồn kho trước khi kết nối với hệ thống khác.
Chuẩn bị trước khi bắt đầu
Trong HexaSync, một Connector App là một ứng dụng kết nối với Acumatica ERP. HexaSync kết nối qua một Connected Application do bạn tạo trên instance Acumatica (hệ thống Acumatica riêng của doanh nghiệp, truy cập qua một địa chỉ web riêng) của mình và đăng nhập bằng OAuth 2.0. Xem thêm tài liệu hướng dẫn chính thức của Acumatica.
- Tài khoản Beehexa để truy cậ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.
- Địa chỉ instance Acumatica: địa chỉ bạn dùng để mở Acumatica, bắt đầu bằng
https://, ví dụhttps://acme.acumatica.com. - Người dùng Acumatica mở được Connected Applications (SM303010), thường là quản trị viên Acumatica.
- Tài khoản Acumatica có quyền xem stock item và tồn kho theo kho. HexaSync sẽ có cùng quyền với tài khoản dùng để cấp quyền; có thể dùng cùng tài khoản ở trên.
- Giấy phép Acumatica cho phép dùng API. Nếu dùng bản dùng thử, đăng xuất khỏi các ứng dụng khác đang kết nối với Acumatica trước khi bắt đầu.
Lưu ý bảo mật: Client Secret có giá trị như mật khẩu. Chỉ nhập Client Secret trực tiếp trên màn hình cấp quyền HexaSync.
Phần 1: Cấp quyền kết nối Acumatica 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 Acumatica
- Mở trang thiết lập kết nối Acumatica trên HexaSync.
- Trên màn hình Check connection details, tại thẻ Acumatica đang hiển thị Not connected, chọn Connect.
- Nếu trước đây bạn đã kết nối instance này: Connected Application đã được chọn sẵn trên màn hình Choose an app to connect to Acumatica. Chọn Continue rồi chuyển đến Bước 6.
- Nếu đây là lần đầu kết nối: HexaSync hiển thị màn hình Connect HexaSync to your Acumatica instance. Giữ màn hình này mở và thực hiện Bước 3, Bước 4, Bước 5 trong Acumatica ở một tab khác.
Bước 3: Tạo Connected Application trong Acumatica
- Mở tab mới, đăng nhập Acumatica và chọn công ty (tenant) mà HexaSync cần đọc dữ liệu.
- Gõ
SM303010vào ô Search, hoặc mở Integration › Preferences › Connected Applications, rồi chọn dấu + (Add New Record). - Tại Client Name, nhập HexaSync. Giữ Active được chọn. Tại Flow, chọn Authorization Code.
- Tại mục Refresh Tokens, chọn Mode là Sliding Expiration và chọn Infinite.
- Mở tab Secrets, chọn Add Shared Secret, nhập Description là HexaSync và để trống Expires On (UTC).
- Sao chép Value hiển thị ngay, vì Acumatica chỉ hiển thị giá trị này một lần. Sao chép xong chọn OK.
- Mở tab Redirect URIs, chọn dấu + (Add Row) và dán đúng giá trị dưới đây, không thêm khoảng trắng hay dấu
/ở cuối:
https://app.hexasync.com/callback/install/third-party
Lưu ý:
- Không chọn No Refresh Tokens: HexaSync không duy trì được kết nối nếu không có refresh token.
- Acumatica chỉ hiển thị Value của shared secret một lần. Nếu chưa sao chép, hãy tạo shared secret mới.
Bước 4: Lưu và sao chép Client ID
- Chọn nút Save trên thanh công cụ.
- Acumatica sẽ tự động điền Client ID, ví dụ
1A2B3C4D-0000-4000-8000-ACME00000001@Company. Sao chép toàn bộ giá trị, kể cả phần sau dấu@.
Lưu ý: Ô Client ID có thể không hiển thị hết phần sau dấu
@. Chọn vào ô và chọn toàn bộ nội dung trước khi sao chép.
Bước 5: Nhập thông tin vào HexaSync
- Quay lại màn hình cấp quyền trên HexaSync.
- Tại Instance URL, nhập địa chỉ instance. Tại Client ID, dán giá trị vừa sao chép. Tại Client Secret, dán Value của shared secret.
- Tại Webhook Secret (optional):
- Chọn Continue.
Bước 6: Đăng nhập Acumatica và cho phép truy cập
- Màn hình You’re about to authorize HexaSync on Acumatica hiển thị instance sẽ mở. Chọn Continue to Acumatica.
- Đăng nhập Acumatica bằng người dùng xem được stock item và tồn kho. HexaSync có cùng quyền với người dùng này.
- Khi Acumatica hỏi, nhấn Yes, Allow. Acumatica đưa bạn về HexaSync để hoàn tất kết nối.
Lưu ý: Nếu Acumatica không hỏi đăng nhập, Acumatica tự động chọn tài khoản đã đăng nhập vào Acumatica. Để dùng người dùng khác, đăng xuất khỏi Acumatica ở tab đó trước bước này.
- Khi HexaSync hiển thị Connected — Save Your HexaSync Webhook URL, sao chép Webhook URL trên màn hình và lưu lại để dùng ở Bước 9, rồi chọn Continue.
Bước 7: Tạo Acumatica Connector
- Khi thẻ Acumatica chuyển sang Connected, chọn Create Acumatica Connector.
- Trên màn hình Enter Connector Name, tên mặc định là [Địa chỉ instance] Acumatica Connector, ví dụ
[acme.acumatica.com] Acumatica Connector. Phần Description đã được điền sẵn. - Chọn Continue. HexaSync hiển thị Creating Connector… trong lúc tạo Connector App; quá trình này có thể mất vài phút.
Sau khi tạo xong, hệ thống tự động chuyển bạn đến Acumatica Connector App vừa tạo.
Bước 8: Kiểm tra Connector App trên HexaSync
Mở danh sách Connector Apps và chọn Acumatica Connector App vừa tạo.
Kiểm tra thông tin kết nối
- Tại Connector App vừa tạo, vào Settings. Thông tin kết nối Acumatica có trạng thái Connected.
Kiểm tra dữ liệu
- Mở tác vụ [Acumatica] Stock Item Warehouse Details. Tác vụ lấy số lượng tồn (Qty On Hand) của từng stock item theo từng kho, mỗi giờ một lần, và chỉ lấy lại các stock item có thay đổi.
- Chờ tác vụ chạy hoặc chọn chạy tác vụ. Quá trình kiểm tra và hiển thị kết quả diễn ra trong vòng 30 phút.
- Đối chiếu một vài stock item với Acumatica, ví dụ Inventory ID, kho và số lượng tồn.
Lưu ý: HexaSync chỉ đọc dữ liệu, không thay đổi gì trong Acumatica.
Bước 9: Thiết lập webhook
Webhook cho phép Acumatica tự gửi dữ liệu đến HexaSync ngay khi dữ liệu thay đổi. Để thiết lập, bạn tạo trong Acumatica:
- Generic Inquiry (GI): chọn dữ liệu Acumatica cần theo dõi.
- Push Notification: gửi dữ liệu của GI đến HexaSync khi dữ liệu thay đổi.
Trước khi bắt đầu, chuẩn bị:
- Webhook URL đã được lưu ở Bước 6. Nếu chưa lưu, cấp lại quyền theo Phần 2.
- Webhook Secret đã nhập ở Bước 5, nếu có.
- Một Generic Inquiry (GI) chứa dữ liệu cần theo dõi. Push Notification chỉ gửi được dữ liệu có trong GI, nên cần tạo GI trước.
- Một người dùng Acumatica mở được Generic Inquiry (SM208000) và Push Notifications (SM302000), thường là quản trị viên Acumatica.
Ví dụ dưới đây tạo GI gửi số lượng tồn của từng mặt hàng theo kho. Làm theo các bước ở phần Tạo Generic Inquiry và Tạo Push Notification với các giá trị sau.
Tạo Generic Inquiry
-
Gõ
SM208000vào ô Search để mở Generic Inquiry, rồi chọn dấu + (Add New Record). -
Tại Inquiry Title, nhập tên theo mong muốn, ví dụ
inventorysite. Để trống các ô còn lại.
-
Mở tab Data Sources và thêm từng bảng dữ liệu cần dùng như sau:
- Chọn dấu + (Add Row).
- Ở ô Source Name, bấm biểu tượng kính lúp, gõ tên bảng cần thêm vào ô Search, rồi bấm đúp vào bảng cần chọn.
- Description và Alias được điền tự động; giữ nguyên.
Ví dụ: thêm 3 bảng
INSiteStatus,InventoryItemvàINSite.
-
Mở tab Relations. Với mỗi liên kết:
- Chọn dấu + ở bảng Table Relations, chọn Parent Table, Join Type và Child Table.
- Với mỗi dòng vừa thêm, nhấn chọn dòng đó. Bảng Data Field Links For Active Relation phía dưới chỉ hiển thị điều kiện liên kết của dòng đang được chọn.
- Chọn dấu + ở bảng Data Field Links For Active Relation phía dưới, chọn Parent Field, Condition là Equals và Child Field.
Ví dụ:
- Chọn dòng INSiteStatus – Inner – InventoryItem, rồi thêm ở bảng Data Field Links:
- Parent Field:
INSiteStatus.InventoryID - Condition:
Equals - Child Field:
InventoryItem.InventoryID
- Parent Field:
- Chọn dòng INSiteStatus – Inner – INSite, rồi thêm ở bảng Data Field Links:
- Parent Field:
INSiteStatus.SiteID - Condition:
Equals - Child Field:
INSite.SiteID
- Parent Field:
Lưu ý: Mỗi quan hệ cần có liên kết riêng. Nếu thiếu, Acumatica ghép mọi dòng của bảng này với mọi dòng của bảng kia. Khi đó, mỗi lần một mặt hàng thay đổi, Acumatica gửi dữ liệu của tất cả mặt hàng sang HexaSync.
-
Mở tab Results Grid. Với mỗi hàng, chọn dấu +, chọn bảng ở Object và trường ở Data Field. Giữ nguyên Caption mặc định.
Ví dụ:
- InventoryItem –
inventoryCD - INSite –
siteCD - INSiteStatus –
qtyOnHand - InventoryItem –
descr
Lưu ý:
- Nếu bạn không chọn được Data Field, tick Visible ngay bên cạnh để hiển thị các trường dữ liệu cần chọn.
- Không đổi Caption của
inventoryCD. HexaSync dùng cột này để nhận biết mặt hàng và sẽ bỏ qua dữ liệu nếu cột bị đổi tên.
- InventoryItem –
-
Không thiết lập tab Parameters, Grouping và không dùng công thức trong Results Grid. Acumatica không đảm bảo gửi đúng dữ liệu khi GI có các thiết lập này. Tab Sort Order có thể hiện dấu cảnh báo; không cần xử lý.
-
Chọn Save. Không cần chọn Publish to the UI.
-
Chọn View Inquiry và kiểm tra:
- Mọi dòng đều có kho.
- Mỗi mặt hàng chỉ xuất hiện một lần trong mỗi kho.
- Số lượng tồn khác nhau giữa các mặt hàng.
Lưu ý: Nếu mặt hàng nào cũng có cùng số lượng tồn, hoặc nhiều dòng không có kho, nghĩa là một liên kết chưa có điều kiện hoặc điều kiện đang nằm ở dòng liên kết khác. Quay lại tab Relations và kiểm tra từng dòng.
Tạo Push Notification
- Gõ
SM302000vào ô Search để mở Push Notifications, rồi chọn dấu + (Add New Record). - Điền phần đầu màn hình như sau:
| Trường | Giá trị |
|---|---|
| Destination Name | HexaSync |
| Destination Type | Webhook |
| Address | Webhook URL đã lưu ở Bước 6 |
| Header Name | x-hexasync-webhook-secret |
| Header Value | Webhook Secret đã nhập ở Bước 5 |
| Active | Chọn |
Lưu ý: Nếu không nhập Webhook Secret ở Bước 5, để trống Header Name và Header Value.
- Mở tab Generic Inquiries. Ở bảng Inquiries, chọn dấu +, tại Inquiry Title chọn GI vừa tạo ở trên. Giữ Active được chọn và bỏ chọn Track All Fields.
- Chọn dòng vừa thêm. Ở bảng Fields bên phải, với mỗi trường cần theo dõi, chọn dấu +, chọn Table Name và Field Name. Acumatica chỉ gửi dữ liệu khi các trường này thay đổi.
- InventoryItem –
inventoryCD - INSite –
siteCD - INSiteStatus –
qtyOnHand - InventoryItem –
descr
- InventoryItem –
- Chọn Save.
Nếu có nhiều GI, tạo từng GI theo phần Tạo Generic Inquiry, rồi thêm tất cả vào cùng Push Notification HexaSync ở thao tác 3–4.
Kiểm tra webhook
- Trong Acumatica, thay đổi một bản ghi thuộc GI ở trường đang được theo dõi và lưu. Với chứng từ, Acumatica chỉ gửi dữ liệu khi giá trị thật sự thay đổi, thường là sau khi chọn Release.
- Trên HexaSync, kiểm tra dữ liệu mới xuất hiện trong vài phút.
Phần 2: Cấp lại quyền kết nối cho Acumatica
Thực hiện cấp lại quyền khi tác vụ báo lỗi xác thực, khi đổi người dùng Acumatica mà HexaSync dùng, hoặc khi đội ngũ Beehexa yêu cầu. Cập nhật trên đúng Connector App đang sử dụng; không tạo Connector App mới chỉ để xử lý lỗi đăng nhập.
Bước 1: Mở Settings trong Acumatica Connector
- Mở Acumatica Connector tương ứng trong Connector Apps, sau đó chọn Settings.
Bước 2: Chọn Re-authorize
- Trong Settings, tìm thông tin kết nối Acumatica và chọn Re-authorize.
Không thực hiện được Re-authorize? Chỉ chủ sở hữu thông tin kết nối mới có quyền cấp lại quyền. Hãy liên hệ người đã tạo kết nối Acumatica.
Bước 3: Kiểm tra Connected Application trên Acumatica
- Trên Connected Applications (SM303010), kiểm tra Connected Application HexaSync vẫn Active, Refresh Tokens vẫn là Sliding Expiration, và shared secret chưa hết hạn.
Bước 4: Kết nối lại
- Quay lại trang Re-authorize trên HexaSync và chọn Connect trên thẻ Acumatica.
- Chọn Continue to Acumatica, đăng nhập bằng người dùng xem được stock item và cho phép truy cập như Bước 6 ở Phần 1.
Lưu ý:
- Đã tạo shared secret mới: mở lại link thiết lập ở Bước 2 ở Phần 1, chọn Connect, chọn I will provide my Acumatica app và nhập lại thông tin như Bước 5 ở Phần 1. Khi thẻ Acumatica chuyển sang Connected, dừng lại: không chọn Create Acumatica Connector.
- Chuyển sang Connected Application khác (Client ID khác): liên hệ Beehexa.
Phần 3: Kiểm tra trước khi sử dụng dữ liệu
- Kiểm tra đúng instance và đúng công ty (tenant) trong Acumatica.
- Chạy tác vụ [Acumatica] Stock Item Warehouse Details và đối chiếu một vài bản ghi mẫu với Acumatica.
- Kiểm tra số lượng stock item và kho. Nếu thiếu, kiểm tra quyền của người dùng đã đăng nhập ở Bước 6 ở Phần 1.
Lưu ý: Nếu chưa biết nên kiểm tra tác vụ nào, hãy liên hệ đầu mối Beehexa đang hỗ trợ doanh nghiệp.
Phần 4: Lỗi thường gặp và cách xử lý
We Couldn’t Finish Connecting Your Acumatica Instance
- Acumatica không nhận Client ID hoặc Client Secret: kiểm tra Client ID đã sao chép đủ, kể cả phần sau dấu
@, và Connected Application đang Active. Nếu không chắc giá trị shared secret, chọn Add Shared Secret để tạo secret mới, rồi kết nối lại. - Acumatica không cấp refresh token: đổi Refresh Tokens › Mode sang Sliding Expiration, chọn Save, rồi kết nối lại.
- Mã cấp quyền hết hạn hoặc Redirect URI không khớp: kiểm tra tab Redirect URIs có đúng
https://app.hexasync.com/callback/install/third-party, chọn Save, rồi kết nối lại và đăng nhập Acumatica ngay. - Chọn Back to installation để thử lại.
Dữ liệu từ webhook cập nhật chậm
- Chỉ một thay đổi trong Acumatica nhưng Acumatica gửi hàng trăm, hàng nghìn dòng sang HexaSync, nên HexaSync mất nhiều giờ mới xử lý xong. Nguyên nhân thường gặp là một liên kết trong Generic Inquiry chưa có điều kiện.
- Mở
SM208000, chọn GI đang dùng, kiểm tra từng dòng ở tab Relations như Tạo Generic Inquiry ở Bước 9, rồi chọn View Inquiry để kiểm tra lại. - Không cần tạo lại Push Notification.
Các lỗi khác
| Thông báo | Cách xử lý |
|---|---|
| HexaSync Could Not Build Your Acumatica Authorization Link | Chọn Choose another app, chọn I will provide my Acumatica app, kiểm tra Instance URL, rồi nhập lại thông tin. |
| Trang Acumatica không mở được sau khi chọn Continue to Acumatica | Kiểm tra Instance URL đúng địa chỉ bạn dùng để mở Acumatica, và tab Redirect URIs đã được lưu. |
| We Could Not Find Your Installation Details | Chọn Back to installation và kết nối lại trên cùng trình duyệt. |
| Connected — Webhook URL Not Available | Kết nối đã hoàn tất. Nếu cần Webhook URL, liên hệ Beehexa và gửi kèm phần Technical details trên màn hình. |
| Tác vụ không có dữ liệu | Người dùng đã đăng nhập ở Bước 6 không có quyền xem stock item. Cấp lại quyền theo Phần 2 bằng người dùng có quyền. |
| Tác vụ báo lỗi không tìm thấy endpoint | Instance Acumatica chưa có endpoint Default phiên bản 20.200.001 trên Web Service Endpoints (SM207060). Liên hệ Beehexa. |
| The name already exists | Đặt tên khác cho Connector App. |
| Connector Quota Reached | Xóa một Connector App không còn dùng, hoặc liên hệ Beehexa để tăng hạn mức. |
Phần 5: Bảo vệ thông tin và ngừng kết nối
- Nhập Client ID và Client Secret trực tiếp trên màn hình cấp quyền HexaSync. Không đưa Client Secret vào nhóm chat, email thông thường hoặc ảnh chụp màn hình.
- Che dữ liệu bảo mật trước khi gửi ảnh chụp cho bộ phận hỗ trợ.
Để ngừng kết nối:
- Đề nghị Beehexa tắt lịch chạy và ngắt kết nối trong HexaSync.
- Quản trị viên Acumatica bỏ chọn Active hoặc xóa shared secret của Connected Application HexaSync trên SM303010.
Lưu ý: Tắt lịch chạy không đồng nghĩa với thu hồi quyền, và ngừng kết nối không xóa dữ liệu đã đồng bộ.
Phần 6: Thông tin gửi Beehexa khi cần hỗ trợ
- Tên công ty, tên Connector App và loại kết nối: Acumatica.
- Địa chỉ instance, công ty (tenant), bước đang thực hiện, thời điểm xảy ra lỗi và thông báo lỗi.
- Những thay đổi gần đây về Connected Application, shared secret, người dùng hoặc quyền truy cập trong Acumatica.
Ảnh chụp cần che Client Secret và dữ liệu bảo mật. Hãy liên hệ đầu mối Beehexa đang hỗ trợ doanh nghiệp, hoặc support@beehexa.com. Xem thêm Chính sách bảo mật của Beehexa và Chính sách hỗ trợ của Beehexa.
Phần 7: Câu hỏi thường gặp
HexaSync kết nối với Acumatica bằng cách nào?
HexaSync kết nối qua một Connected Application do bạn tạo trên instance Acumatica (màn hình SM303010) và đăng nhập bằng OAuth 2.0 (Authorization Code). Bạn cần Instance URL, Client ID và Client Secret (Value của shared secret). HexaSync có cùng quyền với người dùng Acumatica đã cấp quyền ở Bước 6.
Vì sao phải chọn Sliding Expiration cho Refresh Tokens?
Nếu chọn No Refresh Tokens, Acumatica không cấp refresh token và HexaSync không duy trì được kết nối. Hãy chọn Mode là Sliding Expiration và Infinite như Bước 3.
Webhook giúp gì khi kết nối Acumatica với HexaSync?
Webhook cho phép Acumatica gửi dữ liệu sang HexaSync ngay khi dữ liệu thay đổi. Bạn tạo một Generic Inquiry chứa dữ liệu cần theo dõi và một Push Notification gửi dữ liệu đó tới Webhook URL mà HexaSync hiển thị khi kết nối xong, theo Bước 9. Nếu chưa thiết lập webhook, để trống Webhook Secret ở Bước 5.
Khi kết nối báo lỗi xác thực có cần tạo Connector App mới không?
Không. Hãy cấp lại quyền trên đúng Connector App đang sử dụng theo Phần 2.
HexaSync có ghi hoặc sửa dữ liệu trên Acumatica không?
Không. Acumatica Connector App chỉ đọc dữ liệu stock item và tồn kho theo kho, không thay đổi gì trong Acumatica. Khi dùng webhook, Acumatica là bên gửi dữ liệu sang HexaSync.