Overview
This node manages orders in the KiotViet system, a popular Vietnamese retail and inventory management platform. It supports operations such as creating new orders, retrieving orders by ID or code, listing multiple orders with filters, updating existing orders, and canceling orders.
A common use case is automating order workflows: for example, automatically creating orders from an e-commerce platform, fetching order details for processing or reporting, updating orders based on customer changes, or canceling orders with specified reasons.
Practical examples:
- Automatically create a new order when a customer places an order on your website.
- Retrieve detailed information about a specific order to verify its status.
- Cancel an order programmatically if payment fails or the customer requests cancellation, providing a reason for audit purposes.
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 by ID), "Lấy Theo Mã" (get by code), "Lấy Danh Sách" (get all), "Cập Nhật" (update). |
| Trả Về Tất Cả (returnAll) | Whether to return all results when listing orders (only for "getAll" operation). Boolean. |
| Giới Hạn (limit) | Maximum number of orders to return when not returning all (only for "getAll"). Number. |
| ID ĐƠN Hàng (orderId) | The unique identifier of the order (required for get, update, cancel operations). String. |
| Mã ĐƠN Hàng (orderCode) | The code of the order (required for getByCode operation). String. |
| Lý Do Hủy (cancelReason) | Reason for canceling the order (used only in cancel operation). String. |
| ID Chi Nhánh (branchId) | Branch ID where the order is created (required for create operation). Number. |
| Sản Phẩm Trong ĐƠN (orderProducts) | List of products in the order, each with product ID, quantity, price, discount, and note (used in create and update). |
| Bộ Lọc (filters) | Filters for listing orders, including page size, current page, branch ID, date range, and status (used in getAll). |
| Trường Bổ Sung (additionalFields) | Additional optional fields like customer ID, description, and total discount (used in create and update). |
Output
The node outputs JSON data representing the result of the performed operation:
- For create, update, get, and getByCode operations, it returns the detailed order object as received from the KiotViet API.
- For getAll, it returns an object containing:
data: an array of order objects,total: total number of orders matching the filter,pageSize: number of orders per page.
- For cancel, it returns the response from the cancel API call, typically confirmation of cancellation.
No binary data output is produced by this node.
Dependencies
- Requires an active connection to the KiotViet API via an API key credential configured in n8n.
- The node uses a shared KiotViet API helper class to handle authentication and API requests.
- Network access to KiotViet's endpoints is necessary.
Troubleshooting
Common issues:
- Invalid or missing API credentials will cause authentication failures.
- Providing non-numeric values for IDs (orderId, branchId, productId) may cause errors since these are parsed as integers.
- Using unsupported operations or missing required parameters for an operation will throw errors.
- Pagination parameters must be correctly set when using "getAll" to avoid incomplete data retrieval.
Error messages:
"Cancel operation is not supported by the KiotViet API"or"Update operation is not supported by the KiotViet API"indicate that the API client does not support these actions, possibly due to API version or permissions.- Errors related to invalid input parameters usually specify which parameter is incorrect; ensure all required fields are provided and correctly typed.
Resolution tips:
- Double-check API credentials and permissions.
- Validate all numeric IDs before running the node.
- Use the correct operation name and provide all required properties.
- When fetching large datasets, consider enabling "returnAll" or adjusting pagination filters properly.
Links and References
- KiotViet Official Website
- KiotViet API Documentation (may require login)
- n8n documentation on creating custom nodes