Overview
This node manages invoices from the KiotViet system, allowing users to create, retrieve, update, list, and delete invoices. It is useful for automating invoice management workflows such as generating new invoices after sales, fetching invoice details for reporting or processing, updating invoice information, listing multiple invoices with filters, and deleting invoices when necessary.
Practical examples include:
- Automatically creating an invoice in KiotViet when a new order is placed.
- Retrieving invoice details by ID to verify payment status.
- Updating invoice products or payment details after changes.
- Listing all invoices within a date range for accounting purposes.
- Deleting obsolete or test invoices from the system.
Properties
| Name | Meaning |
|---|---|
| operation | The action to perform on invoices. Options: Create, Get (by ID), Get By Code, Get Many, Update, Delete |
| invoiceId | The unique identifier of the invoice (required for get, update, delete operations) |
| invoiceCode | The code of the invoice (required for getByCode operation) |
| branchId | The branch ID where the invoice is created (required for create operation) |
| returnAll | Whether to return all results or limit the number when listing invoices (getAll operation) |
| limit | Maximum number of invoices to return when not returning all (getAll operation) |
| invoiceDetails | List of products in the invoice, each with product ID, code, name, quantity, price, discount, discount ratio, note, and serial numbers (used in create and update) |
| filters | Filters for listing invoices including page size, current page, branch ID, date range, and status (getAll operation) |
| additionalFields | Additional invoice fields such as total payment, customer ID, purchase date, discount, payment method, account ID, COD usage, seller ID, order ID, sales channel ID, and voucher application (create and update) |
Output
The node outputs JSON data representing the result of the performed operation:
- For create, get, getByCode, and update operations, it returns the detailed invoice object as received from the KiotViet API.
- For getAll, it returns an object containing:
data: Array of invoice objects.total: Total number of invoices matching the filter.pageSize: Number of invoices per page.currentPage: Current page number.
- For delete, it returns a success confirmation object with
success: trueand a message indicating successful deletion.
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.
- Uses the KiotViet API client implemented in the shared module to perform HTTP requests.
- No other external services or environment variables are required beyond the API authentication.
Troubleshooting
Common issues:
- Missing or invalid API credentials will cause authentication failures.
- Providing non-integer values for IDs (e.g., invoiceId, branchId) may cause errors.
- Attempting unsupported operations if the KiotViet API does not support them (e.g., update or delete might be unavailable).
- Pagination parameters incorrectly set can lead to incomplete or empty results when listing invoices.
Error messages:
"Update operation is not supported by the KiotViet API"or"Delete operation is not supported by the KiotViet API"indicate that these actions are not available; check API capabilities.- Errors related to invalid parameters usually mention which field is incorrect; ensure all required fields are provided and correctly typed.
- Network or authentication errors typically suggest checking API credentials and network connectivity.
Resolution tips:
- Verify all required input properties are set and valid.
- Confirm API credentials are correct and have sufficient permissions.
- Use the "returnAll" option carefully to avoid large data loads.
- Handle errors gracefully using the node's "Continue On Fail" option if needed.