Kết nối KiotViet với omniVN
Có thể kết nốiKết nối theo ngành hàng: Retail/F&B dùng OAuth client credentials; Salon/Hotel dùng PublicApiKey.
Tổng quan
KiotViet có bốn Public API riêng theo ngành hàng (Retail, F&B, Salon, Hotel). Host và cách xác thực khác nhau — không dùng chung một client. Retail/F&B: OAuth2 client credentials + header Retailer + Authorization Bearer. Salon/Hotel: header PublicApiKey, không gọi id.kiotviet.vn.
Điều kiện trước khi bắt đầu
- Quyền quản trị cửa hàng KiotViet và gói Cao cấp (Salon/Hotel).
- Chọn đúng ngành hàng trong Omni0 trước khi điền credential.
Các bước lấy credential
1. Chọn ngành hàng (industry)
Retail (bán lẻ/sỉ): public.kiotapi.com. F&B (quán/cafe/nhà hàng): publicfnb.kiotapi.com. Salon (spa/làm đẹp): api-integration-booking.kiotviet.vn. Hotel: api-integration-hotel.kiotviet.vn. Chọn đúng giá trị trong Omni0 — mặc định là retail nếu bỏ trống.
2. Retail / F&B — retailer và OAuth
Retailer là mã cửa hàng (subdomain đăng nhập). Lấy client_id và client_secret từ Thiết lập kết nối API trong admin. POST token URL theo ngành: Retail → id.kiotviet.vn/connect/token (scope PublicApi.Access); F&B → api.fnb.kiotviet.vn/identity/connect/token (scope PublicApi.Access.FNB). Gọi API với header Retailer và Authorization: Bearer {access_token}. F&B: doanh thu/GMV lấy qua GET publicfnb.kiotapi.com/invoices (invoiceDetails); không có GET /orders — POST /orders/create chỉ để tạo đơn.
3. Salon / Hotel — PublicApiKey
Lấy PublicApiKey trong cài đặt API của cửa hàng Salon/Hotel. Gửi header PublicApiKey và Accept: application/json tới host tích hợp tương ứng (đường dẫn /public/...). Không dùng OAuth và không POST id.kiotviet.vn.
4. Điền vào Omni0
Integrations → KiotViet. Chọn Industry. Retail/F&B: Retailer code + client_id/client_secret hoặc access_token. Salon/Hotel: Public API key. Base URL tùy chọn (chỉ khi KiotViet hướng dẫn override).
Ánh xạ credential với omniVN
| Field omniVN | Tên trong tài liệu official | Bắt buộc | Lấy từ đâu |
|---|---|---|---|
| Industry | Ngành hàng KiotViet | Tùy chọn | user_entered |
| Retailer code | Mã cửa hàng (retailer) | Tùy chọn | user_entered |
| Client ID | client_id | Tùy chọn | user_entered |
| Client secret | client_secret | Tùy chọn | user_entered |
| Access token | access_token | Tùy chọn | provider_generated |
| Public API key | PublicApiKey | Tùy chọn | user_entered |
| Base URL | API base URL | Tùy chọn | user_entered |
industry → ngành hàng (retail | fnb | salon | hotel); retailer → Retailer code (Retail/F&B); clientId/clientSecret → OAuth; accessToken → token sẵn có (Retail/F&B); publicApiKey → PublicApiKey (Salon/Hotel); baseUrl → Base URL (tùy chọn).
Vòng đời token
Retail/F&B: access_token có TTL; khi 401, lấy lại bằng client credentials. Salon/Hotel: PublicApiKey tĩnh, không có token URL.
Lỗi thường gặp
Lỗi xác thực 401 với Salon/Hotel
Sai industry (đang để retail), dùng OAuth thay vì PublicApiKey, hoặc gửi PublicApiKey tới public.kiotapi.com.
Lỗi xác thực 401 với Retail/F&B
Retailer sai, client_secret không khớp, access_token hết hạn, hoặc thiếu scope Public API.