KiotViet

Đọc và ghi dữ liệu cửa hàng KiotViet đã kết nối của workspace (kênh KiotViet ở Hub kết nối → tab Kênh Ứng dụng), qua API công khai hoặc MCP. Siêu trợ lý giữ thông tin đăng nhập KiotViet; bạn chỉ cần API key của Siêu trợ lý.

Đây là dữ liệu sống từ KiotViet, khác với GET /products (bản đồng bộ trong Siêu trợ lý).

Quyền

Scope	Cho phép
kiotviet:read	Thao tác đọc (GET): chi nhánh, nhóm hàng, hàng hóa, tồn kho, khách hàng, đặt hàng, hóa đơn, nhập/chuyển hàng, sổ quỹ…
kiotviet:write	Thao tác ghi (POST/PUT/DELETE): tạo/sửa/xóa thật trên KiotViet

Quyền được xét theo phương thức thật của thao tác, không theo tên công cụ.

Endpoint

GET /kiotviet/operations — kiotviet:read

Trả các kênh KiotViet và danh mục thao tác:

{
  "channels": [ { "channel_id": "…", "name": "Cửa hàng chính", "retailer": "tencuahang", "ready": true, "status": "active" } ],
  "operations": [
    { "operation": "products_list", "group": "Hàng hóa", "label": "Lấy danh sách hàng hóa", "desc": "…", "access": "read",
      "params": [ { "key": "category_id", "label": "Id nhóm hàng", "type": "text", "example": "…" }, { "key": "limit", "type": "number", "default": 20 } ] }
  ]
}

POST /kiotviet/run — kiotviet:read hoặc kiotviet:write

{ "operation": "products_list", "params": { "limit": 20 }, "channel_id": "…" }

• channel_id: bỏ trống khi workspace chỉ có một kênh KiotViet.
• params: theo danh sách params của thao tác. Các ô có đuôi _json (items_json, extra_json…) nhận luôn object/array.
• Trả { "operation", "method", "result" }. result đã chuẩn hoá: danh sách có items, count, total; bản ghi đơn lẻ có các trường chính và dữ liệu gốc.

curl -X POST https://api.sieutroly.ai/api/public/v1/kiotviet/run \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"operation":"order_create","params":{"branch_id":12345,"items_json":[{"productCode":"SP001","quantity":2}],"customer_phone":"0901234567"}}'

Lỗi riêng: 404 unknown_operation (sai tên thao tác), 403 insufficient_scope (thao tác ghi mà key chỉ có kiotviet:read), 409 no_channel (chưa có kênh KiotViet), 400 channel_required (nhiều kênh mà không chọn), lỗi từ KiotViet trả nguyên mã HTTP và thông báo.

Webhook KiotViet

Đăng ký/xóa webhook KiotViet không mở qua API, để key không chuyển được dữ liệu cửa hàng ra địa chỉ tuỳ ý. Dùng bước Quy trình trên web nếu cần.

Thao tác request gọi một endpoint bất kỳ của Public API KiotViet (method, path, query_json, body_json) trong danh sách được phép, dùng được với cả hai quyền tuỳ phương thức. Mỗi lần ghi có nhật ký thao tác trong Siêu trợ lý.

MCP

list_kiotviet_operations, kiotviet_read (chỉ thao tác đọc), kiotviet_write (thao tác ghi). Xem MCP cho AI agent.

Danh sách thao tác

Nhóm	operation	Loại	Việc làm	Tham số (* = bắt buộc)
Chi nhánh	branches_list	đọc	Lấy danh sách chi nhánh	—
Nhóm hàng	categories_list	đọc	Lấy danh sách nhóm hàng	modified_from
Nhóm hàng	category_get	đọc	Xem nhóm hàng	category_id*
Nhóm hàng	category_create	ghi	Tạo nhóm hàng	name*, parent_id
Nhóm hàng	category_update	ghi	Cập nhật nhóm hàng	category_id, name
Nhóm hàng	category_delete	ghi	Xóa nhóm hàng	category_id*
Hàng hóa	products_list	đọc	Lấy danh sách hàng hóa	code, category_id, modified_from, limit, offset
Hàng hóa	product_get	đọc	Xem hàng hóa (theo id)	product_id*
Hàng hóa	product_get_by_code	đọc	Xem hàng hóa (theo mã)	code*
Hàng hóa	product_create	ghi	Tạo hàng hóa	name, code, category_name, unit, base_price, allows_sale, branch_id, on_hand, extra_json
Hàng hóa	product_update	ghi	Cập nhật hàng hóa	product_id*, name, base_price, branch_id, on_hand, extra_json
Hàng hóa	product_delete	ghi	Xóa hàng hóa	product_id*
Hàng hóa	products_on_hand	đọc	Tồn kho hàng hóa	branch_ids, limit, offset
Khách hàng	customers_list	đọc	Lấy danh sách khách hàng	name, contact_number, modified_from, limit, offset
Khách hàng	customer_get	đọc	Xem khách hàng (theo id)	customer_id*
Khách hàng	customer_get_by_code	đọc	Xem khách hàng (theo mã)	code*
Khách hàng	customer_create	ghi	Tạo khách hàng	name, contact_number, address, email, branch_id, extra_json
Khách hàng	customer_update	ghi	Cập nhật khách hàng	customer_id*, contact_number, address, email, comments, extra_json
Khách hàng	customer_delete	ghi	Xóa khách hàng	customer_id*
Khách hàng	customer_groups_list	đọc	Lấy danh sách nhóm khách hàng	—
Đặt hàng	orders_list	đọc	Lấy danh sách đặt hàng	branch_id, status, modified_from, limit, offset
Đặt hàng	order_get	đọc	Xem đặt hàng (theo id)	order_id*
Đặt hàng	order_get_by_code	đọc	Xem đặt hàng (theo mã)	code*
Đặt hàng	order_create	ghi	Tạo đặt hàng	branch_id, items_json, customer_name, customer_phone, description, discount, make_invoice, extra_json
Đặt hàng	order_update	ghi	Cập nhật đặt hàng	order_id*, status, description, total_payment, extra_json
Đặt hàng	order_delete	ghi	Xóa đặt hàng	order_id*
Đặt hàng	order_suppliers_list	đọc	Lấy danh sách đặt hàng nhập	product_codes, limit, offset
Hóa đơn	invoices_list	đọc	Lấy danh sách hóa đơn	branch_id, status, modified_from, limit, offset
Hóa đơn	invoice_get	đọc	Xem hóa đơn	invoice_id*
Hóa đơn	invoice_create	ghi	Tạo hóa đơn	branch_id, items_json, customer_name, method, description, extra_json
Hóa đơn	invoice_update	ghi	Cập nhật hóa đơn	invoice_id*, description, extra_json
Hóa đơn	invoice_delete	ghi	Xóa hóa đơn	invoice_id*, void_payment
Nhập hàng	purchase_orders_list	đọc	Lấy danh sách nhập hàng	branch_id, limit, offset
Nhập hàng	purchase_order_create	ghi	Tạo phiếu nhập hàng	branch_id, supplier_code, lines_json*, is_draft, description, extra_json
Nhập hàng	purchase_order_update	ghi	Cập nhật phiếu nhập hàng	purchase_order_id*, description, extra_json
Chuyển hàng	transfers_list	đọc	Lấy danh sách chuyển hàng	from_branch_id, to_branch_id, limit, offset
Chuyển hàng	transfer_create	ghi	Tạo phiếu chuyển hàng	from_branch_id, to_branch_id, lines_json*, extra_json
Chuyển hàng	transfer_update	ghi	Cập nhật phiếu chuyển hàng	transfer_id*, status, extra_json
Sổ quỹ	cashflow_list	đọc	Lấy danh sách sổ quỹ	start, end, limit, offset
Webhook	webhooks_list	đọc	Lấy danh sách webhook	—
Webhook	webhook_get	đọc	Xem webhook	webhook_id*
Khác	users_list	đọc	Lấy danh sách nhân viên	—
Khác	surcharges_list	đọc	Lấy danh sách thu khác	—
Khác	bank_accounts_list	đọc	Lấy danh sách tài khoản ngân hàng	limit, offset
Khác	returns_list	đọc	Lấy thông tin trả hàng	limit, offset
Khác	locations_get	đọc	Lấy danh sách Tỉnh/Thành — Quận/Huyện	—
Khác	settings_get	đọc	Xem thiết lập cửa hàng	—
Nâng cao	request	đọc/ghi	Gọi API KiotViet tuỳ chọn	method, path*, query_json, body_json