Hướng dẫn kết nối KiotViet với Cam Check

🔌

Tổng quan

KiotViet Public API sử dụng cơ chế xác thực OAuth 2.0. Cam Check sử dụng Client ID và Client Secret của bạn để tự động lấy Access Token mỗi khi cần truy vấn đơn hàng — bạn không cần can thiệp thủ công sau khi thiết lập xong.

Bạn cần chuẩn bị 3 thông tin sau:

Thông tin	Mô tả	Ví dụ
Tên gian hàng (Retailer)	Slug cửa hàng KiotViet	`mycoffee`
Client ID	Mã định danh ứng dụng	`abc123xyz`
Client Secret	Mật khẩu bí mật của ứng dụng	`secret_xxxxxxxx`

⚠️ Lưu ý bảo mật:Client Secret chỉ hiển thị một lần duy nhất khi tạo ứng dụng. Hãy sao chép và lưu lại ngay lập tức.

🔑

Bước 1 — Lấy Client ID & Client Secret

KiotViet cấp Client ID và Client Secret trực tiếp qua Thiết lập cửa hàng — không cần đăng ký tài khoản Developer riêng.

Đăng nhập KiotViet bằng tài khoản Admin

Truy cập phần mềm KiotViet trên máy tính (bản desktop hoặc web) và đăng nhập bằng tài khoản quản trị viên (admin) của cửa hàng.

Vào Thiết lập → Thiết lập kết nối API

Từ màn hình chính, chọn Thiết lập cửa hàng (biểu tượng bánh răng) → tìm mục Thiết lập kết nối API.

Nếu không thấy mục này, liên hệ bộ phận CSKH KiotViet để được hỗ trợ kích hoạt.

Sao chép Client ID và Client Secret

Trang thiết lập kết nối API sẽ hiển thị:

Client ID — mã định danh ứng dụng của cửa hàng bạn.
Mã bảo mật (Client Secret) — hãy sao chép và lưu trữ an toàn ngay.

Quan trọng: Nếu bạn đã lỡ đóng trang mà chưa lưu Client Secret, cần tạo lại mã mới trong phần cài đặt.

Màn hình Thiết lập kết nối API hiển thị Client ID và Client Secret

🏪

Bước 2 — Lấy tên gian hàng (Retailer)

Tên gian hàng là slug (phần tên ngắn) trong URL quản lý KiotViet của bạn. Đây là định danh duy nhất được dùng trong mọi request gửi đến KiotViet API qua header Retailer.

Kiểm tra URL khi đăng nhập

Khi bạn đăng nhập vào KiotViet, URL trên trình duyệt sẽ có dạng:

https://tengianhang.kiotviet.vn/

Phần tengianhang chính là Retailer bạn cần nhập vào Cam Check.

Tên gian hàng (Retailer) nằm ngay trên thanh địa chỉ trình duyệt

Ví dụ URL

https://mycoffee.kiotviet.vn/

→ Retailer: mycoffee

Lưu ý

Chỉ nhập phần tên, không nhập https:// hay .kiotviet.vn.

🔗

Bước 3 — Kết nối KiotViet trong Cam Check

Bước 1: Mở Cam Check tại app.quayvideodongdon.com và đăng nhập.

Bước 2: Vào Cài đặt → Nền tảng thương mại điện tử → chọn KiotViet.

Bước 3: Điền đầy đủ 3 trường sau và nhấn Lưu cài đặt:

Trường	Giá trị cần nhập
Tên gian hàng (Retailer)	Slug cửa hàng KiotViet (VD: `mycoffee`)
Client ID	Lấy từ Thiết lập kết nối API của KiotViet
Client Secret	Lấy từ Thiết lập kết nối API của KiotViet

Chọn KiotViet và nhập Retailer, Client ID, Client Secret trong Cài đặt Cam Check

Sau khi lưu, Cam Check sẽ tự động xin Access Token và đồng bộ đơn hàng từ KiotViet. Bạn không cần thao tác thêm.

⚙️

Thông tin API

Cam Check sử dụng các endpoint sau của KiotViet Public API:

🔐

Lấy Access Token (OAuth 2.0)

POSThttps://id.kiotviet.vn/connect/token

Header: Content-Type: application/x-www-form-urlencoded

Body gồm: grant_type=client_credentials, scopes=PublicApi.Access, client_id, client_secret

Token có hiệu lực 86.400 giây (24 giờ) và được Cam Check tự động gia hạn.

📦

Lấy danh sách đơn hàng

GEThttps://public.kiotapi.com/orders

Header: Retailer: <tên_gian_hàng> và Authorization: Bearer <access_token>

🔍

Lấy chi tiết đơn hàng

GEThttps://public.kiotapi.com/orders/code/{mã_đơn}

Tra cứu đơn hàng theo mã code để lấy danh sách sản phẩm, giúp Cam Check hiển thị checklist đóng gói.

Giới hạn: KiotViet Public API cho phép tối đa 5.000 request GET/giờ. Với lượng đơn hàng thông thường, giới hạn này sẽ không bị vượt.

📌

Lưu ý quan trọng

Client Secret chỉ hiển thị một lần khi tạo. Nếu mất, phải tạo lại mã mới trong Thiết lập kết nối API của KiotViet.
Cam Check tự động lấy và gia hạn token — bạn không cần thao tác thủ công.
Nếu cửa hàng đổi tên slug KiotViet, cần cập nhật lại trường Tên gian hàng trong Cam Check.
Mọi request API đều yêu cầu header Retailer và Authorization: Bearer. Cam Check tự động xử lý điều này.
Giới hạn 5.000 request GET/giờ — phù hợp cho hầu hết shop vừa và nhỏ.

🛠️

Xử lý sự cố

Vấn đề	Nguyên nhân có thể	Cách xử lý
Không tìm thấy đơn hàng	Mã đơn sai hoặc nhập sai Tên gian hàng	Kiểm tra lại slug cửa hàng trong URL KiotViet
Lỗi xác thực (401)	Client ID hoặc Client Secret sai	Vào KiotViet → Thiết lập kết nối API để kiểm tra lại
Lỗi kết nối	Ứng dụng chưa được cấp quyền truy cập `PublicApi.Access`	Liên hệ CSKH KiotViet để kích hoạt quyền API
Token hết hạn	Token có thời hạn 24 giờ	Cam Check tự động gia hạn — không cần xử lý thủ công
Vượt giới hạn rate limit	Quá 5.000 request GET/giờ	Giảm tần suất đồng bộ hoặc liên hệ KiotViet nâng giới hạn

Tài liệu API chính thức của KiotViet: KiotViet Public API

Cần hỗ trợ thêm?

Nếu bạn gặp khó khăn trong quá trình sử dụng phần mềm, vui lòng liên hệ:

Hỗ trợ qua Zalo

Hỗ trợ qua Facebook