Tổng quan cho nhà phát triển
Siêu trợ lý mở API công khai v1 (server-to-server) và máy chủ MCP để hệ thống bên ngoài và AI agent làm việc với dữ liệu của một workspace: đơn hàng, sản phẩm, tồn kho, nhập hàng, khách hàng, hội thoại, quy trình, đăng bài, giao hàng, KiotViet.
| Base URL | https://api.sieutroly.ai/api/public/v1 |
| MCP | https://api.sieutroly.ai/api/mcp (xem MCP cho AI agent) |
| Định dạng | JSON (UTF-8), thời gian ISO 8601 (UTC), tiền VND (số nguyên) |
| Phạm vi dữ liệu | Đúng một workspace: workspace của API key |
Chỉ gọi từ máy chủ
Không đặt API key trong trình duyệt hay ứng dụng di động. Lưu khóa trong biến môi trường hoặc kho bí mật.
Lấy API key
Chủ workspace (hoặc người có quyền Quản lý API Key) vào app.sieutroly.ai → API Key → Tạo API Key, đặt tên và chọn quyền.
- Khóa dạng
sk_live_…chỉ hiện một lần. Hệ thống chỉ lưu bản băm nên không xem lại được; mất khóa thì bấm Xoay khóa để cấp khóa mới (khóa cũ ngừng hoạt động ngay). - Mỗi key đặt được ngày hết hạn và giới hạn yêu cầu/phút (mặc định 60, tối đa 600).
- Nên tạo key riêng cho từng đối tác/hệ thống và chỉ cấp quyền cần thiết.
- Trang API Key hiện lần dùng gần nhất, số yêu cầu và IP gần nhất của từng key để theo dõi bất thường.
Xác thực
http
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxHoặc header X-API-Key: sk_live_…. Thiếu, sai, hết hạn hay bị tắt → 401.
bash
curl https://api.sieutroly.ai/api/public/v1/whoami -H "Authorization: Bearer $API_KEY"json
{ "workspace": { "id": "…", "name": "Cửa hàng ABC" },
"api_key": { "id": "…", "name": "Website", "prefix": "sk_live_Ab12", "scopes": ["orders:read","orders:write"], "rate_limit_per_min": 60, "expires_at": null } }Quyền (scope)
| Scope | Cho phép |
|---|---|
orders:read | Liệt kê, tìm kiếm, xem chi tiết đơn; chi nhánh; gợi ý địa chỉ, báo giá phí ship; trạng thái đơn giao |
orders:write | Tạo đơn, sửa đơn đang chờ xử lý, đổi trạng thái đơn |
orders:payment | Tạo mã QR chuyển khoản, đánh dấu đơn đã/chưa nhận tiền, ghi nợ đơn |
shipping:write | Gọi giao hàng thật qua Ahamove / AllinGo đã kết nối và huỷ đơn giao (phát sinh phí với hãng) |
products:read | Xem sản phẩm, danh mục, tồn kho theo chi nhánh, thẻ kho |
products:write | Tạo/sửa sản phẩm và danh mục tự tạo; kiểm kê kho |
purchases:read | Xem nhà cung cấp, phiếu nhập hàng, người duyệt phiếu |
purchases:write | Tạo/sửa nhà cung cấp, ghi nhận trả nợ; tạo/sửa/gửi duyệt/hoàn thành/hủy phiếu nhập |
customers:read | Tìm khách theo SĐT hoặc tên/mã; xem hồ sơ, ghi chú, đơn gần đây |
customers:write | Tạo khách, sửa hồ sơ, thêm ghi chú |
conversations:read | Liệt kê hội thoại, xem tin nhắn |
conversations:write | Gửi tin chữ, ảnh, video vào hội thoại và tải tệp lên |
zalo:use | Zalo cá nhân: tìm người theo SĐT, kết bạn, nhắn theo uid |
workflows:read | Liệt kê quy trình, xem các bước và lịch sử chạy |
workflows:run | Chạy một quy trình đã lưu (mọi bước thực thi thật) |
content:read | Xem kênh đăng bài, bài đăng, số liệu thống kê |
content:write | Tải ảnh/video, tạo/sửa/xóa bài, đăng bài thật |
kiotviet:read | Đọc dữ liệu cửa hàng KiotViet đã kết nối |
kiotviet:write | Tạo/sửa/xóa thật trên KiotViet đã kết nối |
Trần quyền: người tạo key chỉ cấp được scope ứng với quyền mà chính họ đang có trên web (ví dụ orders:write cần quyền Quản lý đơn hàng). Chủ workspace không bị giới hạn.
Lỗi
json
{ "error": { "code": "invalid_request", "message": "items[0].quantity phải là số nguyên từ 1 đến 9999" } }| HTTP | code | Ý nghĩa |
|---|---|---|
| 400 | invalid_request, invalid_json, unknown_product, unknown_option, missing_option, missing_field, NO_BANK_ACCOUNT | Dữ liệu sai hoặc thiếu |
| 401 | unauthorized, key_expired | Key thiếu, sai, bị tắt, hết hạn |
| 403 | insufficient_scope | Key thiếu quyền (xem required_scope) |
| 404 | not_found | Không thấy bản ghi hoặc endpoint |
| 409 | order_not_editable, already_paid, … | Trạng thái hiện tại không cho phép thao tác |
| 413 | payload_too_large | Thân yêu cầu quá lớn |
| 429 | rate_limited | Vượt giới hạn — chờ theo Retry-After (giây) |
| 502/503 | unavailable, QR_UNAVAILABLE | Dịch vụ phụ trợ (hãng vận chuyển, KiotViet, ngân hàng…) tạm lỗi — thử lại |
| 500 | internal_error | Lỗi hệ thống |
Giới hạn tần suất
Tính theo từng key, cửa sổ 1 phút. Mọi phản hồi có X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (epoch giây). Bị 429 thì chờ Retry-After rồi thử lại.
Tài liệu chi tiết
- API Đơn hàng: tạo đơn, QR thanh toán, công nợ, gọi giao hàng.
- API Hội thoại & Tin nhắn: đọc và gửi tin vào hội thoại của khách.
- KiotViet: đọc/ghi cửa hàng KiotViet đã kết nối.
- Webhook sự kiện: nhận thông báo khi đơn, tin nhắn thay đổi.
- MCP cho AI agent: kết nối Claude, ChatGPT, Cursor… với cửa hàng.
- Web Chat SDK: nhúng khung chat lên website.
- Chuẩn tích hợp kênh: tự viết bộ kết nối cho một kênh chat mới.
- Webhook vận chuyển: nối đơn vị giao hàng riêng qua webhook.