Overview
This node manages customer information in the KiotViet system. It supports creating new customers, retrieving customer details by ID, listing multiple customers with optional filters, and updating existing customer records. This node is useful for automating customer data synchronization, enrichment, or retrieval within workflows that integrate with KiotViet's retail management platform.
Practical examples include:
- Automatically adding new customers collected from a web form into KiotViet.
- Fetching detailed customer info to personalize marketing campaigns.
- Updating customer contact details after receiving updated information.
- Retrieving lists of customers filtered by group or last modification date for reporting or segmentation.
Properties
| Name | Meaning |
|---|---|
| Thao Tác (operation) | The action to perform: Create, Get by ID, Get Many, or Update customer information. |
| ID Khách Hàng (customerId) | Unique identifier of the customer; required for "get" and "update" operations. |
| Tên Khách Hàng (name) | Full name of the customer; required for "create" and "update" operations. |
| Trường Bổ Sung (additionalFields) | Optional additional fields when creating or updating a customer, including: - Số Điện Thoại (contactNumber): Customer phone number - Email: Customer email address - Địa Chỉ (address): Customer address - Giới Tính (gender): Gender as boolean (true = male, false = female) - Ngày Sinh (birthDate): Birthdate in YYYY-MM-DD format - Nhóm Khách Hàng (groupIds): Comma-separated list of customer group IDs |
| Lấy toàn Bộ (returnAll) | Boolean flag to return all results when listing customers ("getAll" operation). |
| Giới Hạn (limit) | Maximum number of customers to return when not returning all (used in "getAll"). |
| Bộ Lọc (filters) | Filters for listing customers ("getAll"), including: - Từ khóa Tìm Kiếm (searchTerm): Search by name, phone, or customer code - ID Nhóm (groupId): Filter by customer group ID - Sửa đổi Từ Ngày (lastModifiedFrom): Filter customers modified since this date (YYYY-MM-DD) |
Output
The node outputs JSON data representing customer information returned from KiotViet API calls. Depending on the operation:
- Create: Returns the newly created customer object.
- Get: Returns the customer object identified by the given ID.
- Get Many: Returns an object containing:
data: Array of customer objects.total: Total number of customers matching the query.pageSize: Number of customers per page.currentItem: Current offset in pagination.
- Update: Returns the updated customer object.
No binary data output is produced by this node.
Dependencies
- Requires an API key credential for authenticating with the KiotViet API.
- Uses an internal KiotViet API helper class to handle requests.
- No additional external dependencies beyond the KiotViet API access.
Troubleshooting
Common issues:
- Invalid or missing customer ID when performing "get" or "update" operations will cause errors.
- Incorrect formatting of
groupIds(should be comma-separated integers) may lead to unexpected behavior. - Network or authentication failures with the KiotViet API can cause request errors.
Error messages:
"Failed to fetch customers: <error message>"indicates problems retrieving customer lists; check API connectivity and credentials."Update operation is not supported by the KiotViet API"means the API client does not support updates, possibly due to version mismatch.- General API errors will propagate with their messages; ensure all required parameters are provided and valid.
Resolution tips:
- Verify that the API key credential is correctly configured and has necessary permissions.
- Ensure required parameters like
customerIdandnameare set when needed. - Validate input formats, especially for fields like dates and group IDs.
- Use the "continue on fail" option to handle partial failures gracefully in batch operations.
Links and References
- KiotViet Official Website
- KiotViet API Documentation (for detailed API capabilities and data models)