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

Q: Có bắt buộc phải thêm webhook không?

Không. Nếu bỏ qua webhook, tác vụ Inventory vẫn lấy dữ liệu tồn kho 15 phút một lần. Webhook là tùy chọn để Pancake POS gửi thay đổi đến HexaSync ngay khi phát sinh.

Hướng dẫn này trình bày cách kết nối Pancake POS với HexaSync Automation Engine và tạo Pancake POS Connector để lấy dữ liệu tồn kho của từng biến thể sản phẩm tại từng kho trên Pancake POS.

Pancake POS dùng API Key để kết nối với HexaSync, không cần đăng nhập và cấp quyền qua cửa sổ xác thực riêng. Bạn nên chuẩn bị API Key trước khi thiết lập trên HexaSync. Sau khi kết nối, bạn có thể thiết lập thêm webhook để Pancake POS gửi thay đổi đến HexaSync ngay khi phát sinh. Webhook không bắt buộc.

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 Pancake POS là chủ cửa hàng hoặc quản trị viên của cửa hàng cần kết nối, để tạo API Key.
Xác định đúng cửa hàng Pancake POS cần kết nối.

Lưu ý: Mỗi lần thiết lập Connector tương ứng với một cửa hàng Pancake POS.

Phần 1: Kết nối Pancake POS và tạo Pancake POS Connector

Bước 1: Tạo API Key trong Pancake POS

Truy cập Pancake POS, đăng nhập và chọn đúng cửa hàng cần kết nối.
Chọn biểu tượng Cấu hình ở menu bên trái. Trong nhóm Nâng cao, chọn Tích hợp bên thứ 3.
Trong thẻ Webhook/API, chọn Chi tiết.
Trong cửa sổ Webhook - API, mở tab API Key và chọn Thêm mới.
Kiểm tra công tắc Bật/Tắt của API Key mới đang bật. Bạn có thể nhập HexaSync vào ô Ghi chú để dễ nhận biết.
Chọn biểu tượng sao chép bên cạnh API Key và lưu giá trị ở nơi an toàn để dùng khi kết nối trên HexaSync.

Lưu ý: Nên tạo API Key riêng cho HexaSync thay vì dùng chung với hệ thống khác. Không tắt, xóa hoặc công khai API Key đang dùng để kết nối.

Bước 2: Mở trang thiết lập trên HexaSync

Truy cập HexaSync Automation Engine và đăng nhập bằng tài khoản Beehexa.
Mở trang thiết lập Pancake POS Connector.
Trên màn hình Check connection details, kiểm tra thẻ Pancake POS có trạng thái Not connected, sau đó chọn Connect.

Quy trình trên HexaSync có ba giai đoạn: Check connection details, Connect your systems và Create Pancake POS Connector.

Lưu ý: Giữ tab HexaSync mở cho tới khi hoàn tất, vì đóng tab có thể hủy quy trình kết nối.

Bước 3: Nhập API Key và Shop ID (nếu cần)

Trên màn hình Connect HexaSync to your Pancake POS shop, nhập thông tin theo bảng dưới đây:

Trường	Cách nhập
API Key	Dán API Key đã sao chép ở Bước 1.
Shop ID (only if your key has several shops)	Để trống nếu API Key chỉ truy cập một cửa hàng. Chỉ điền nếu API Key truy cập nhiều cửa hàng.

Chọn Continue. HexaSync kiểm tra API Key và chuyển đến màn hình chọn cách cập nhật dữ liệu khi kết nối thành công.

Cách lấy Shop ID khi cần nhập: Mở cửa hàng tương ứng trong Pancake POS và xem dãy số ngay sau /shop/ trên URL. Ví dụ, với URL https://pos.pancake.vn/shop/408121324/overview, Shop ID là 408121324.

Bước 4: Chọn phương thức cập nhật dữ liệu

Trên màn hình Connected — Turn On Real-Time Updates?, kiểm tra cửa hàng đã kết nối. HexaSync thông báo lịch cập nhật định kỳ 15 phút một lần và đưa ra hai lựa chọn:

Skip — scheduled sync is enough for now: không cấu hình webhook, tiếp tục đồng bộ theo lịch 15 phút. Chọn lựa chọn này nếu bạn chưa cần cập nhật ngay hoặc Webhook URL của cửa hàng đang phục vụ hệ thống khác. Sau đó chuyển đến Bước 6.
Set up real-time updates now: thiết lập webhook để thay đổi được gửi đến HexaSync ngay khi phát sinh. Tiếp tục với Bước 5.

Bước 5: Thiết lập webhook trong Pancake POS (không bắt buộc)

Chỉ thực hiện bước này nếu bạn đã chọn Set up real-time updates now ở Bước 4.

Trên màn hình Add The Webhook In Pancake POS của HexaSync, sao chép Webhook URL và giá trị của header X-HexaSync-Webhook-Secret bằng nút sao chép tương ứng.
Trong Pancake POS, mở Cấu hình > Nâng cao > Tích hợp bên thứ 3. Tại thẻ Webhook/API, chọn Chi tiết, rồi mở tab Webhook URL.
Bật Gửi dữ liệu.
Dán địa chỉ đã sao chép từ HexaSync vào trường Webhook URL.
Tại Đối tác, chọn Không có.
Tại Dữ liệu, chọn đủ bốn loại: Đơn hàng, Khách hàng, Tồn kho và Sản phẩm.
Nếu muốn nhận cảnh báo khi Pancake POS gửi webhook thất bại, chọn Thêm email ở mục Email thông báo lỗi và nhập địa chỉ email. Đây là tùy chọn không bắt buộc.
Tại Request Headers, chọn Thêm mới và nhập một dòng: Key là X-HexaSync-Webhook-Secret, Value là giá trị secret đã sao chép từ HexaSync.
Chọn Lưu bên cạnh Request Headers để lưu header.
Quay lại tab HexaSync và chọn I have added the webhook in Pancake POS — continue.

Lưu ý về lưu cấu hình: Các trường trong phần Webhook URL của Pancake POS tự động lưu. Riêng Request Headers cần chọn Lưu.

Lưu ý quan trọng:

Mỗi cửa hàng Pancake POS chỉ có một Webhook URL. Dán Webhook URL của HexaSync sẽ thay thế URL đang được hệ thống khác sử dụng. Hãy kiểm tra với người quản lý tích hợp trước khi thay đổi.

Giữ giá trị X-HexaSync-Webhook-Secret như mật khẩu. HexaSync từ chối webhook nếu header này không hợp lệ.

Bước 6: Tạo Pancake POS Connector

Khi HexaSync quay lại màn hình Set up Pancake POS Connector, kiểm tra thẻ Pancake POS có trạng thái Connected và thông tin kết nối [Pancake POS] Shop Credential đã được tạo.
Chọn Create Pancake POS Connector.

Bước 7: Đặt tên Connector

Trên màn hình Enter Connector App Name, kiểm tra Name mặc định có dạng [Tên cửa hàng] Pancake POS Connector. Bạn có thể đổi thành tên dễ phân biệt.
Kiểm tra trường Description đã được điền sẵn.
Chọn Continue và đợi HexaSync tạo Connector. Quá trình này có thể mất vài phút.
Sau khi tạo xong, HexaSync mở trang Tasks. Tác vụ mặc định [Pancake POS] Inventory đã sẵn sàng để kiểm tra dữ liệu.

Kết quả: Nếu cửa hàng có dữ liệu phù hợp và các bản ghi xuất hiện trong Data, HexaSync đã lấy được dữ liệu tồn kho từ Pancake POS. Bạn có thể mở lại Connector trong Connector Apps.

Phần 2: Kết nối lại Pancake POS

Bạn cần kết nối lại khi API Key bị tắt hoặc bị xóa, khi HexaSync báo thông tin kết nối không còn hợp lệ, hoặc khi bạn muốn đổi API Key.

Bước 1: Mở Settings của Connector

Mở Connector Apps, chọn Pancake POS Connector tương ứng. Nhấn chọn Settings ở menu bên trái.

Bước 2: Chọn Re-authorize

Trong Integration Apps & Credentials, tại thông tin kết nối [Pancake POS] Shop Credential, chọn Re-authorize.

Bước 3: Nhập lại API Key

Màn hình Connect HexaSync to your Pancake POS shop xuất hiện. Nếu cần, tạo API Key mới theo Phần 1, Bước 1.
Dán API Key hợp lệ. Chỉ nhập Shop ID nếu API Key truy cập nhiều cửa hàng, cách lấy Shop ID xem tại Phần 1, Bước 3.
Chọn Continue để kết nối lại.

Bước 4: Cập nhật webhook nếu đang sử dụng

Nếu cửa hàng đang dùng webhook:

Chọn Set up real-time updates now rồi chọn Submit.
Sao chép giá trị mới của X-HexaSync-Webhook-Secret trên HexaSync.
Trong Pancake POS, mở Cấu hình > Nâng cao > Tích hợp bên thứ 3 > Webhook/API > Chi tiết > Webhook URL.
Đối chiếu Webhook URL với địa chỉ HexaSync hiển thị. URL này giữ nguyên khi kết nối lại.
Tìm dòng X-HexaSync-Webhook-Secret trong Request Headers, thay Value bằng giá trị mới rồi chọn Lưu.
Quay lại HexaSync và hoàn tất màn hình kết nối lại.

Lưu ý: Kết nối lại tạo giá trị header mới. Nếu không cập nhật, webhook do Pancake POS gửi đi có thể bị HexaSync từ chối. Nếu không dùng webhook, chọn Skip — scheduled sync is enough for now để tiếp tục đồng bộ định kỳ.

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

Thông báo	Cách xử lý
Pancake POS rejected the API key	Sao chép lại API Key, kiểm tra key có bị tắt hoặc bị xóa trong Pancake POS không.
This API key sees several shops (…)	Nhập Shop ID của cửa hàng muốn kết nối, xem cách lấy tại Bước 3.
This API key cannot see the shop …	Kiểm tra Shop ID có thuộc cửa hàng mà API Key được quyền truy cập không.
HexaSync Could Not Prepare Your Webhook Settings	Lỗi khi HexaSync chuẩn bị thông tin webhook. Liên hệ support@beehexa.com để được hỗ trợ.

Với các trường hợp khác, hãy gửi ảnh chụp màn hình lỗi đến support@beehexa.com. Không gửi API Key hay giá trị X-HexaSync-Webhook-Secret.

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

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

Không. Pancake POS Connector chỉ đọc dữ liệu, không ghi hoặc sửa dữ liệu trên Pancake POS. Các thay đổi Webhook URL và Request Headers trong Pancake POS do người dùng tự thực hiện.

HexaSync lấy những dữ liệu nào từ Pancake POS?

Pancake POS Connector lấy tồn kho theo mẫu mã tại từng kho, gồm số lượng có thể bán, tồn thực tế, tổng, hàng đang về (đơn nhập), hàng chờ và hàng đang hoàn, kèm tên sản phẩm, mẫu mã, SKU, mã vạch và giá bán lẻ.

API Key có hết hạn không?

Theo quy trình kết nối hiện tại, API Key Pancake POS không có thời hạn hết hạn đặt sẵn. Bạn cần kết nối lại theo Phần 2 khi key bị tắt, bị xóa hoặc HexaSync báo thông tin kết nối không còn hợp lệ.

Có bắt buộc phải thêm webhook không?

Không. Nếu bỏ qua webhook, tác vụ Inventory vẫn lấy dữ liệu tồn kho 15 phút một lần. Webhook là tùy chọn để Pancake POS gửi thay đổi đến HexaSync ngay khi phát sinh.

Khi nào cần nhập Shop ID?

Chỉ khi API Key truy cập nhiều cửa hàng. Nếu key chỉ truy cập một cửa hàng, hãy để trống. Shop ID là dãy số nằm sau /shop/ trong URL Pancake POS, ví dụ 408121324 trong https://pos.pancake.vn/shop/408121324/overview.