Overview
This node integrates with the KiotViet order management system to perform various operations on orders. It allows users to create new orders, retrieve orders by ID or code, list multiple orders with filtering options, update existing orders, and cancel orders. This node is useful for automating order workflows, synchronizing order data between KiotViet and other systems, or managing orders programmatically within n8n.
A practical example: You can use this node to fetch an order by its unique code ("Mã Đơn Hàng") to verify its status before proceeding with shipment or customer notification.
Properties
| Name | Meaning |
|---|---|
| Thao Tác (operation) | The action to perform on orders. Options: Hủy (cancel), Tạo Mới (create), Lấy Theo ID (get), Lấy Theo Mã (getByCode), Lấy Danh Sách (getAll), Cập Nhật (update) |
| Trả Về Tất Cả (returnAll) | Whether to return all results when listing orders (only for "Lấy Danh Sách" operation). True or False. |
| Giới Hạn (limit) | Maximum number of orders to return when not returning all (only for "Lấy Danh Sách"). Number ≥ 1. |
| ID ĐƠN Hàng (orderId) | The unique numeric ID of the order (required for get, update, cancel operations). |
| Mã ĐƠN Hàng (orderCode) | The unique code string of the order (required for "Lấy Theo Mã" operation). |
| Lý Do Hủy (cancelReason) | Reason for canceling the order (optional for cancel operation). |
| ID Chi Nhánh (branchId) | Branch ID where the order is created (required for create operation). |
| Sản Phẩm Trong ĐƠN (orderProducts) | List of products in the order, each with: ID Sản Phẩm (productId), Số Lượng (quantity), Giá Bán (price), Giảm Giá (discount), Ghi Chú (note). Used in create and update operations. |
| Bộ Lọc (filters) | Filters for listing orders (getAll), including: Trang (pageSize), Số Trang (currentPage), ID Chi Nhánh (branchId), Từ Ngày (fromDate), Đến Ngày (toDate), Trạng Thái (status: Completed, Cancelled, Processing). |
| Trường Bổ Sung (additionalFields) | Additional optional fields for create and update operations: ID Khách Hàng (customerId), Mô Tả (description), Giảm Giá (discount). |
Output
The node outputs JSON data representing the order(s) returned or affected by the operation:
- For getByCode (Lấy Theo Mã), the output JSON contains the detailed information of the order identified by the given code.
- For get, it returns the order details by ID.
- For getAll, it returns a paginated list of orders with metadata such as total count and page size.
- For create, update, and cancel, it returns the result of the respective API call, typically the updated order data or confirmation of cancellation.
If an error occurs during processing, and if "Continue On Fail" is enabled, the output will include an error message object instead of halting execution.
The node does not output binary data.
Dependencies
- Requires an API key credential for authenticating with the KiotViet API.
- Uses the KiotViet API client implemented in the shared module.
- No additional external dependencies beyond the KiotViet API service.
Troubleshooting
Common issues:
- Invalid or missing API credentials will cause authentication failures.
- Providing incorrect order IDs or codes will result in "not found" errors.
- Attempting unsupported operations (e.g., update or cancel if not supported by the API) will throw explicit errors.
- Pagination parameters must be valid numbers; otherwise, the API may reject requests.
Error messages:
"Update operation is not supported by the KiotViet API"or"Cancel operation is not supported by the KiotViet API"indicate that the current API client version or account permissions do not allow these actions.- Network or API errors will propagate as exceptions; enabling "Continue On Fail" allows workflow continuation with error details in output.
To resolve errors:
- Verify API credentials and permissions.
- Confirm that order IDs and codes exist in the KiotViet system.
- Use correct parameter types and required fields.
- Check API documentation or support for feature availability.
Links and References
- KiotViet Official Website
- KiotViet API Documentation (for detailed API usage and capabilities)