Hướng dẫn bắt đầu với Xero trên HexaSync

Q: Tôi có cần tạo lại Xero Connector khi quyền truy cập Xero hết hiệu lực không?

Không. Bạn có thể cấp lại quyền cho Xero Connector hiện có: mở Settings, tìm Integration Apps & Credentials và chọn Re-authorize. HexaSync dùng lại thông tin Xero App đã lưu và giữ nguyên dữ liệu đã lấy trước đó.

Hướng dẫn này trình bày cách kết nối Xero với HexaSync: tạo Xero Connector bằng cách cấp quyền kết nối thông qua Xero App. Sau khi hoàn tất, bạn có thể lấy dữ liệu Contacts, Invoices, Invoice Lines, Items, Accounts và Payments từ Xero về HexaSync để khai thác và tích hợp dữ liệu.

Theo cấu hình mặc định, Xero Connector chỉ đọc dữ liệu và không chỉnh sửa dữ liệu trong Xero. Nếu cần ghi dữ liệu vào Xero, đội ngũ HexaSync sẽ tư vấn chi tiết cho bạn trong quá trình triển khai.

Chuẩn bị trước khi bắt đầu

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.
Một Xero Organisation và tài khoản Xero có quyền cấp phép kết nối ứng dụng.
Một Xero App đã được tạo trên Xero Developer Portal. Nếu chưa có, hãy làm theo hướng dẫn tạo Xero App trên Xero Developer Portal trước khi tiếp tục.
Ba thông tin xác thực của Xero App: Client ID, Client Secret và Webhooks Key.

Lưu ý: Mỗi Xero App chỉ được dùng để kết nối một Xero Organisation trên HexaSync.

Phần 1: Kết nối Xero với 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 xác thực Xero App trên HexaSync

Mở trang thiết lập kết nối Xero trên HexaSync.
Tiếp tục quy trình thiết lập Xero Connector hiển thị trên HexaSync.

Bước 3: Cung cấp thông tin Xero App

Nếu HexaSync hiển thị lựa chọn ứng dụng, chọn I will provide my Xero app.
Nhập thông tin theo bảng sau:

Trường thông tin	Giá trị cần nhập
Client ID	Client ID đã sao chép từ Xero App (Bước 2 của hướng dẫn tạo Xero App)
Client Secret	Client Secret của cùng Xero App
Webhooks Key	Webhooks Key lấy từ phần Webhooks của cùng Xero App (Bước 3 của hướng dẫn tạo Xero App)

Chọn Continue.
Chọn Continue to Xero để chuyển đến trang cấp quyền của Xero.

Lưu ý: Cả ba thông tin phải thuộc cùng một Xero App. Không dùng thông tin từ các App khác nhau.

Bước 4: Cấp quyền truy cập Xero Organisation

Đăng nhập Xero nếu được yêu cầu.
Chọn đúng một Xero Organisation cần kết nối.
Kiểm tra các phạm vi dữ liệu hiển thị trên trang cấp quyền:
- Contacts
- Organisation settings
- Invoices and related documents
- Payments
Chọn Allow access để cấp quyền cho ứng dụng.

Lưu ý: Chỉ chọn một Xero Organisation cho mỗi lần kết nối. Nếu chọn nhiều Organisation, HexaSync sẽ báo lỗi và bạn phải kết nối lại.

Bước 5: Cấu hình Webhook URL chính thức

Sau khi Xero cấp quyền thành công, bạn được chuyển trở lại HexaSync. Hệ thống hiển thị Webhook URL chính thức dành cho kết nối này.

Sao chép Webhook URL do HexaSync hiển thị.
Quay lại Xero Developer Portal.
Mở Xero App đã dùng để kết nối.
Chọn Webhooks.
Cập nhật cấu hình:
- Delivery URL: thay URL tạm https://app.hexasync.com/webhook bằng Webhook URL chính thức vừa sao chép từ HexaSync.
- Events: giữ nguyên Contacts và Invoices.
Chọn Save.
Chọn Send “Intent to receive”.
Chờ đến khi trạng thái Webhook hiển thị OK.

Webhook URL chính thức có định dạng như ví dụ dưới đây:

https://gateway.hexasync.com/api/v3/messages/your-webhook-url-is-shown-here/

Lưu ý:

Địa chỉ trên chỉ minh họa định dạng URL. Bạn phải sao chép Webhook URL thực tế mà HexaSync cung cấp cho kết nối của mình, không dùng URL ví dụ.

Nếu trạng thái không chuyển sang OK, hãy kiểm tra Delivery URL đã nhập chính xác và xác minh lại. Nếu vẫn không thành công, liên hệ support@beehexa.com kèm ảnh chụp màn hình lỗi. Không tiếp tục tạo Connector khi Webhook chưa được xác minh thành công.

Bước 6: Hoàn tất kết nối Xero

Quay lại HexaSync.
Chọn I have saved the webhook URL — continue.
Kiểm tra Xero hiển thị trạng thái Connected.
Chọn Create Xero Connector.

Bước 7: Tạo Xero Connector

Kiểm tra tên Connector do HexaSync gợi ý, ví dụ [Acme Trading Ltd] Xero Connector.
Chỉnh sửa tên nếu cần để dễ nhận biết Xero Organisation được kết nối.
Chọn Continue.
Chờ HexaSync hoàn tất quá trình tạo Connector.

Khi hoàn tất, bạn được chuyển đến Xero Connector vừa tạo trong Connector Apps. Kiểm tra kết nối theo Phần 3.

Phần 2: Cấp lại quyền cho Xero Connector

Cấp lại quyền khi HexaSync không còn truy cập được dữ liệu Xero, chẳng hạn ứng dụng bị ngắt kết nối trong Xero hoặc Connector hiển thị lỗi kết nối.

Bước 1: Mở Settings trong Xero Connector

Mở Connector Apps, chọn Xero Connector cần cấp lại quyền. Nhấn chọn Settings ở menu bên trái.
Trong Integration Apps & Credentials, chọn Re-authorize tại dòng Xero.

Không thực hiện được Re-authorize? Chỉ người tạo hoặc admin của Xero Connector App mới nhìn thấy nút Re-authorize. Hãy liên hệ người tạo hoặc admin của Connector App.

Bước 2: Cấp lại quyền trên Xero

Đăng nhập Xero nếu được yêu cầu.
Chọn đúng Xero Organisation đã liên kết với Connector.
Chọn Allow access.

HexaSync dùng lại thông tin Xero App đã lưu. Trong quy trình cấp lại quyền thông thường, bạn không cần nhập lại Client ID, Client Secret hoặc Webhooks Key.

Bước 3: Kiểm tra Webhook

Kiểm tra trạng thái Webhook trên Xero Developer Portal.
Nếu Webhook vẫn có trạng thái OK, quay lại HexaSync và chọn I have saved the webhook URL — continue.
Nếu Webhook không ở trạng thái OK, kiểm tra lại Delivery URL như Bước 5 ở Phần 1 và xác minh lại.

Lưu ý: Nếu sau khi kiểm tra lại Delivery URL và xác minh lại, Webhook của Xero App trên Xero Developer Portal vẫn không hiển thị trạng thái OK, hãy liên hệ support@beehexa.com kèm ảnh chụp màn hình lỗi. Không chọn I have saved the webhook URL — continue khi Webhook chưa được xác minh thành công.

Bước 4: Kiểm tra kết nối

Xác nhận Xero hiển thị trạng thái Connected.
Kiểm tra Connector tiếp tục lấy dữ liệu từ Xero theo Phần 3.

Dữ liệu đã lấy trước đó được giữ lại sau khi cấp lại quyền.

Phần 3: Kiểm tra kết nối thành công

Mở Connector Apps và chọn Xero Connector vừa tạo.

Kiểm tra thông tin kết nối

Trong Settings, mục Integration Apps & Credentials, Xero hiển thị trạng thái Connected.
Kiểm tra đúng Xero Organisation cần kết nối.
Trên Xero Developer Portal, Webhook của Xero App có trạng thái OK.

Kiểm tra dữ liệu

Kiểm tra Connector có sáu tác vụ mặc định:
- Contacts
- Invoices
- Invoice Lines
- Items
- Accounts
- Payments
Trong lần lấy dữ liệu đầu tiên, HexaSync lấy toàn bộ dữ liệu hiện có theo phạm vi được cấp quyền.
Sau đó, dữ liệu được làm mới theo chu kỳ 15 phút. Các thay đổi liên quan đến Contacts và Invoices được cập nhật gần thời gian thực qua Webhook khi Webhook có trạng thái OK.

Lưu ý: Xero Connector mặc định chỉ đọc dữ liệu từ Xero.

Phần 4: Lỗi thường gặp và cách xử lý

Thông báo	Cách xử lý
Invalid redirect_uri	Kiểm tra OAuth 2.0 redirect URI trong Configuration của Xero App, theo Bước 1 của hướng dẫn tạo Xero App.
You selected more than one organisation	Kết nối lại và chỉ chọn một Xero Organisation.
This Xero app is already connected to several organisations	Ngắt kết nối Xero hiện có trước khi kết nối với Organisation khác.
Xero returned no organisation for this approval	Kiểm tra tài khoản Xero và Organisation được chọn khi cấp quyền.
Xero rejected the Client ID or Client Secret	Kiểm tra lại thông tin trong Configuration của Xero App, theo Bước 2 của hướng dẫn tạo Xero App.
Xero did not accept the authorization	Kiểm tra OAuth 2.0 redirect URI và thực hiện lại quá trình cấp quyền.
HexaSync Could Not Register Your Xero App	Kiểm tra Client ID, Client Secret và Webhooks Key.
Your Webhook URL Is Not Ready Yet	Chờ khoảng 30 giây và chọn Try again.
We Could Not Get Your Webhook URL	Liên hệ support@beehexa.com và cung cấp mã lỗi được hiển thị.
The provider did not grant the authorization	Chọn Resume the installation và cấp quyền bằng Allow access.
We Could Not Find Your Installation Details	Bắt đầu lại quá trình kết nối từ HexaSync.
The name already exists	Chọn tên Xero Connector khác.
You’ve reached your app limit	Liên hệ support@beehexa.com hoặc xóa Connector App không còn sử dụng.

Với các trường hợp khác, hãy gửi ảnh chụp màn hình thông báo lỗi (đã che thông tin nhạy cảm) đến support@beehexa.com.

Phần 5: Câu hỏi thường gặp

Sau khi kết nối Xero thành công, HexaSync lấy những dữ liệu nào và bao lâu cập nhật một lần?

Xero Connector mặc định lấy dữ liệu qua sáu tác vụ: Contacts, Invoices, Invoice Lines, Items, Accounts và Payments.

Lần đầu, HexaSync lấy toàn bộ dữ liệu hiện có theo phạm vi được cấp quyền. Sau đó dữ liệu được làm mới mỗi 15 phút. Các thay đổi liên quan đến Contacts và Invoices được cập nhật gần thời gian thực qua Webhook khi Webhook có trạng thái OK.

Tôi có thể tiếp tục kết nối nếu Webhook chưa hiển thị trạng thái OK không?

Không. Bạn phải xác minh Webhook thành công trước khi tiếp tục. Hãy kiểm tra Delivery URL đã được thay bằng Webhook URL chính thức do HexaSync cung cấp, chọn Save, sau đó chọn Send “Intent to receive” như Bước 5 ở Phần 1.

Nếu trạng thái vẫn không chuyển sang OK, hãy liên hệ support@beehexa.com kèm ảnh chụp màn hình lỗi.

Tôi có cần tạo lại Xero Connector khi quyền truy cập Xero hết hiệu lực không?

Không. Bạn có thể cấp lại quyền cho Xero Connector hiện có theo Phần 2: mở Settings, tìm Integration Apps & Credentials và chọn Re-authorize. HexaSync dùng lại thông tin Xero App đã lưu và giữ nguyên dữ liệu đã lấy trước đó.

HexaSync có ghi hoặc sửa dữ liệu trên Xero không?

Không. Theo cấu hình mặc định, Xero Connector App chỉ đọc dữ liệu, không ghi hoặc sửa dữ liệu trên Xero. Nếu cần ghi dữ liệu vào Xero, đội ngũ HexaSync sẽ tư vấn chi tiết trong quá trình triển khai.