UNPKG

@arathron/n8n-nodes-zoho-books

Version:

n8n community nodes for Zoho Books and Zoho Inventory API integration - Complete CRUD operations for Sales Orders, Invoices, Items, Vendors, Credit Notes, Payments, Purchase Orders, Bills, Composite Items, Tax Management, Tax Groups, and Tax Exemptions

537 lines (435 loc) 27.2 kB
# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [2.8.0] - 2025-01-08 ### Added - **Tax Resource**: Complete CRUD operations for managing tax rates in Zoho Books - **CREATE**: Add new taxes with percentage validation (0-100%, up to 2 decimal places) - **READ**: Get tax details by ID and list all taxes with pagination - **UPDATE**: Modify existing tax rates and settings - **DELETE**: Remove tax configurations - **VALIDATION**: Tax percentage validation, name validation, compound/non-recoverable flags - **CACHING**: 1-hour TTL cache for loadOptions with automatic invalidation - **Tax Group Resource**: Manage tax groups that combine multiple tax rates - **CREATE**: Build tax groups from selected taxes (up to 50 taxes per group) - **READ**: Retrieve tax group details and list all groups - **UPDATE**: Modify tax group composition and settings - **DELETE**: Remove tax groups - **VALIDATION**: Prevents duplicate tax IDs, validates group size limits - **UI**: Multi-select dropdown for tax selection with caching - **Tax Exemption Resource (US only)**: Handle tax exemptions for customers - **EDITION GUARD**: Automatic detection of US edition before API calls - **CREATE/UPDATE/DELETE**: Full CRUD for tax exemption management - **VALIDATION**: Code format validation, type restrictions, percentage limits - **ERROR HANDLING**: Clear messages for non-US organizations with upgrade guidance - **CACHING**: Smart caching that respects edition detection - **Enhanced Error Handling**: Improved rate limiting and API error management - **RATE LIMIT DETAILS**: Surface Retry-After, rate limit headers in error messages - **429 HANDLING**: Enhanced rate limit error reporting with actionable tips - **API VALIDATION**: Better error messages for tax-specific validation failures - **Caching System**: New TTL cache utility for better performance - **LOADOPTIONS CACHING**: 1-hour cache for dynamic dropdowns (taxes, tax groups, exemptions) - **CACHE INVALIDATION**: Automatic cache clearing after create/update/delete operations - **MEMORY MANAGEMENT**: Built-in cleanup and statistics tracking - **Documentation**: Comprehensive updates for new tax resources - **README**: Added tax resource documentation with examples and US edition warnings - **EXAMPLES**: 5 new usage examples covering all tax operations - **METADATA**: Updated keywords and descriptions for better discoverability ### Technical Improvements - **Code Organization**: Separated UI descriptions into dedicated files for better maintainability - **Type Safety**: Enhanced TypeScript interfaces for tax-related operations - **Testing Ready**: All resources include comprehensive validation and error handling - **Performance**: Optimized API calls with intelligent caching and pagination ## [2.7.9] - 2025-01-08 ### Fixed - **Sales Order Date After Filter**: Fixed date handling for n8n datetime format - **DATETIME SUPPORT**: Now properly handles full datetime strings from n8n (e.g., '2025-07-01 00:00:00') - **AUTOMATIC EXTRACTION**: Automatically extracts date part from datetime strings - **ROBUST PARSING**: Added fallback date parsing for various input formats - **DEBUG LOGGING**: Added console logging to help troubleshoot filtering issues - **TESTING**: Updated tests to reflect new date handling logic ## [2.7.8] - 2025-01-08 ### Added - **Sales Order Date After Filter**: Added "Date After" filter to Sales Order Get Many operation - **NEW FILTER**: Added "Date After" parameter to filter sales orders by order date - **API INTEGRATION**: Uses Zoho Books API `date_after` parameter for efficient filtering - **DATE FORMAT**: Automatically formats dates to YYYY-MM-DD for API compatibility - **USER EXPERIENCE**: Clear description and optional field for easy workflow setup - **PERFORMANCE**: Reduces unnecessary processing by filtering at API level - **TESTING**: Comprehensive unit tests for date filtering functionality ## [2.7.7] - 2025-01-08 ### Added - **Reason Field for Sent Invoice Updates**: Added required reason field when updating sent invoices to comply with Zoho Books API requirements - **NEW FIELD**: Added "Reason for Update" field in invoice update operation UI - **VALIDATION**: Automatically validates reason is provided when updating sent invoices - **ERROR HANDLING**: Enhanced error messages for Zoho error code 110701 (reason required for sent invoice updates) - **USER EXPERIENCE**: Clear guidance when reason is missing for sent invoice updates ### Fixed - **Form-data Encoding**: Requests that only contain `JSONString` are now sent as form data (URL-encoded / multipart) instead of raw JSON. - Automatically handled in `zohoApiRequest` when the body shape is `{ JSONString: ... }`. - Ensures Zoho Books interprets payload correctly on create/update endpoints. ## [2.7.6] - 2025-08-04 ### Fixed - **Form-data Encoding**: Requests that only contain `JSONString` are now sent as form data (URL-encoded / multipart) instead of raw JSON. - Automatically handled in `zohoApiRequest` when the body shape is `{ JSONString: ... }`. - Ensures Zoho Books interprets payload correctly on create/update endpoints. ## [2.7.5] - 2025-01-28 ### Fixed - **Invoice Date Update Issue**: Fixed critical bug where invoice date updates were being silently ignored by Zoho API - **ROOT CAUSE**: Zoho Books API requires complete payload with all mandatory fields for successful updates - **COMPREHENSIVE SOLUTION**: Implemented fetch-then-update pattern that includes all required fields: - `customer_id` (required at all times) - `currency_id` (required for foreign currency invoices) - `line_items` (at least one item required) - `date` and `due_date` (must be a valid pair) - All other fields being updated - **REMOVED ARTIFICIAL LIMITS**: Eliminated 100-character JSONString limit that was preventing proper updates - **ENHANCED ERROR HANDLING**: Added proper validation for missing invoices and line items - **BACKWARD COMPATIBLE**: Maintains existing behavior while ensuring date updates work correctly - **COMPREHENSIVE TESTS**: Updated both unit and integration tests to reflect new behavior ## [2.7.4] - 2025-01-28 ### Fixed - **Invoice Update JSONString Limit**: Fixed "JSONString has more than 100 characters" error (Zoho API error code 15) - **100-CHARACTER LIMIT**: Implemented smart payload sizing to stay under Zoho's JSONString character limit - **MINIMAL PAYLOAD**: Creates optimal payload with essential fields (customer_id) and update fields only - **ADAPTIVE LOGIC**: Dynamically adjusts payload size by removing optional fields when approaching limit - **ERROR HANDLING**: Clear error messages when update data exceeds limit constraints - **MAINTAINED FIX**: Preserves the date update fix while complying with API character restrictions - **COMPREHENSIVE TESTS**: Updated all tests to verify 100-character limit compliance ## [2.7.3] - 2025-01-28 ### Fixed - **Invoice Update Date Issue**: Fixed critical bug where invoice date updates were being silently ignored - **MANDATORY FIELDS**: Modified invoice update to fetch existing invoice data first and include all mandatory fields (customer_id, line_items) - **API COMPLIANCE**: Ensures Zoho Books API requirements are met for successful date updates - **DATA PRESERVATION**: Existing line items and essential fields are preserved during updates - **BACKWARD COMPATIBLE**: Maintains existing behavior while fixing the date update issue - **COMPREHENSIVE TESTS**: Updated test suite to verify the new fetch-then-update pattern - **ERROR HANDLING**: Added proper error handling when invoice is not found during update ## [2.7.2] - 2025-01-28 ### Fixed - **Invoice Update Date Handling**: Fixed timezone-related date issues for IST (India Standard Time) - **DATE PROCESSING**: Improved date field processing to avoid timezone conversion issues - **IST SUPPORT**: All dates now properly handled assuming India Time zone (IST +05:30) - **TIMEZONE SAFETY**: Prevents off-by-one day errors when updating invoices with ISO datetime strings - **STRING EXTRACTION**: Uses string slicing instead of Date constructor to maintain calendar date accuracy - **COMPREHENSIVE TESTS**: Added unit tests covering various date input formats ## [2.7.1] - 2025-01-26 ### Fixed - **UI Configuration**: Fixed "Mark as Sent" operation to only appear for Invoice resources - **RESOURCE FILTERING**: Separated Invoice operations from general operations list - **USER EXPERIENCE**: "Mark as Sent" operation now only shows when Invoice resource is selected - **INVOICE ID FIELD**: Invoice ID parameter now properly displays for markAsSent operation ## [2.7.0] - 2025-01-26 ### Added - **Invoice Mark as Sent Operation**: Added ability to mark invoices as sent - **NEW OPERATION**: "Mark as Sent" operation for invoices to track delivery status - **API ENDPOINT**: POST `/invoices/{invoice_id}/status/sent` integration - **STATUS TRACKING**: Changes invoice status to "sent" for workflow management - **DOCUMENTATION**: Complete operation guide with examples in OPERATIONS.md - **TESTING**: Full unit test coverage for markAsSent functionality ### Enhanced - **Invoice Resource**: Added markAsSent method to Invoice.resource.ts - **Node Interface**: Updated ZohoBooks.node.ts with new operation option - **User Experience**: Clear field descriptions and validation - **API Integration**: Maintains backward compatibility while adding powerful new capabilities ## [2.6.0] - 2025-01-08 ### Added - **Invoice Update Operations**: Enhanced update functionality with comprehensive field support - **NEW FIELDS**: Added editable fields for invoice updates: - Date (invoice date in YYYY-MM-DD format) - Invoice Number (custom invoice numbering) - Place of Supply (for tax calculations) - GST Treatment (business_gst, consumer, overseas, sezwp, sez, unregistered) - GST Number (GSTIN) for tax compliance - Due Date, Reference Number, Notes, and Terms - **LINE ITEMS**: Added support for updating invoice line items during update operation - **FLEXIBLE UPDATES**: All update fields are optional - only provide fields you want to change - **GST COMPLIANCE**: Enhanced support for Indian tax requirements with GST treatment options - **DOCUMENTATION**: Comprehensive examples and workflow guides for invoice updates - **TESTING**: Full unit and integration test coverage for all new update fields ### Enhanced - **Invoice Resource**: Improved update method to handle new field collection seamlessly - **User Experience**: Clear field descriptions and validation messages - **API Integration**: Maintains backward compatibility while adding powerful new capabilities ## [2.5.5] - 2025-01-08 ### Fixed - **Invoice Operations**: ULTIMATE FIX for "Create invoice from sales order" operation - **CRITICAL CHANGE**: Changed `salesorder_id` from request body to query parameter as per Zoho API documentation - Now sends `salesorder_id` as URL query parameter: `/invoices/fromsalesorder?salesorder_id=123456` - This resolves the "Invalid value passed for salesorder_id" error (code 4) - Enhanced sales order validation to check status before invoice creation - Improved error handling with more specific validation messages - Updated all test cases to reflect the correct API usage ## [2.5.4] - 2025-01-08 ### Fixed - **Invoice Operations**: Previous attempt using body parameters (superseded by 2.5.5) ## [2.5.3] - 2025-01-08 ### Fixed - **Invoice Operations**: Previous iteration (superseded by 2.5.4) ## [2.5.2] - 2025-01-08 ### Fixed - **Invoice Operations**: Incorrect attempt using `salesorder_ids` parameter (superseded by 2.5.3) ## [2.5.1] - 2025-01-08 ### Fixed - **Invoice Operations**: Partial fix for "Create invoice from sales order" operation (superseded by 2.5.2) ## [2.4.0] - 2025-01-22 ### Added - **Invoice Operations**: Complete invoice management functionality - Added new Invoice resource with full CRUD operations (create, get, getAll, update, delete, list) - **Create Instant Invoice from Sales Order**: New operation to convert sales orders to invoices instantly - Uses Zoho's `/invoices/fromsalesorder` endpoint for efficient conversion - Supports additional fields like due date, notes, terms, discount, and exchange rate - Includes automatic sales order validation before invoice creation - Provides detailed error handling and user-friendly error messages - Added comprehensive invoice utility functions for validation and data normalization - Full test coverage with 26+ unit tests and 5 integration tests - Enhanced error handling with context-aware error messages ### Enhanced - **Node Structure**: Updated ZohoBooks node to properly handle invoice operations - Added dynamic Invoice resource importing for better performance - Integrated invoice operations with existing node architecture - Improved parameter validation for invoice-specific fields ## [2.3.2] - 2025-03-08 ### Fixed - **Contact Date Filtering**: Fixed Contact getAll operation with proper Zoho API parameters - Added `filter_by: 'Last Modified Time'` parameter required by Zoho Books API - Updated date formatting to use ISO-8601 timestamps instead of plain dates - Fixed "Invalid value passed for last_modified_time" error when using "Updated After" filter - Enhanced date handling to support both date-only and full timestamp inputs - Improved empty/whitespace parameter validation to prevent API errors ### Enhanced - **Date Formatting**: Added new `formatDateTime()` function for ISO-8601 timestamp conversion - Converts any valid date/time input to proper ISO-8601 format - Handles plain dates (YYYY-MM-DD) by adding time component - Removes milliseconds for Zoho API compatibility - Maintains backward compatibility with existing `formatDate()` function ### Technical - **API Compatibility**: Updated Contact getAll operation to use correct Zoho Books API parameters - **Test Coverage**: Updated all Contact-related tests to reflect new API parameter structure - **Error Handling**: Improved validation to prevent empty parameter errors - **Type Safety**: Enhanced type checking for date parameters and API responses ## [2.3.1] - 2025-03-08 ### Fixed - **Contact Date Filtering**: Fixed Contact getAll operation error with empty `last_modified_time` parameter - **Parameter Validation**: Improved date filtering logic to only include `last_modified_time` when valid date is provided - **Error Handling**: Added proper validation for empty and whitespace `updatedAfter` parameters - **Date Formatting**: Enhanced `formatDate` function to handle edge cases better - **Test Coverage**: Fixed test expectations to match actual function call signatures - **Edge Cases**: Added comprehensive tests for empty and invalid date parameter handling ### Technical - **Test Suite**: All 27 ContactsUtils tests now passing with proper error handling - **Validation**: Enhanced parameter validation in getAllContacts function - **Type Safety**: Improved type checking for date parameters ## [2.3.0] - 2025-03-08 ### Added - **Contact Search by Name**: New search operation for Contact resource - Search contacts by full or partial name using Zoho Books search API - Returns normalized contact data in camelCase format - Includes raw API response for advanced processing - Supports partial name matching (e.g., "John" finds "John Doe", "John Smith") - Auto-pagination for complete search results - Comprehensive error handling and validation ### Enhanced - **Contact Operations**: Extended Contact resource with search functionality - Added "Search" operation to Contact resource options - New "Search Name" parameter for contact name search - Integrated with existing Contact utilities and normalization - Maintains consistency with other Contact operations ### Documentation - **Search Documentation**: Added search operation to OPERATIONS.md Contact section - **JSON Guide Update**: Enhanced CONTACT_JSON_GUIDE.md with search examples - **Response Examples**: Detailed examples of search request and response formats - **Best Practices**: Guidelines for effective contact searching ### Testing - **Search Tests**: Comprehensive unit tests for search functionality - Tests for successful search with multiple results - Error handling tests for empty search terms - Mock coverage for search API calls and response handling ## [2.2.1] - 2025-03-08 ### Fixed - **Contact Date Filtering**: Fixed Contact getAll operation error with empty `last_modified_time` parameter - Improved date filtering logic to only include `last_modified_time` when valid date is provided - Added proper validation for empty and whitespace `updatedAfter` parameters - Prevents API errors when no date filter is specified ## [2.2.0] - 2025-01-15 ### Added - **NEW FEATURE**: Contact Resource with Full CRUD Operations - Complete Contact management with Create, Read, Update, Delete operations - Support for all Contact fields: name, company, email, phone, website, currency, balance - Billing and Shipping address management with structured address fields - Custom fields support for flexible contact data - Pagination support with "Return All" and "Limit" options - Date filtering with "Updated After" parameter - Normalized response format with camelCase keys for easier integration - Comprehensive error handling and validation - Full TypeScript support with proper type definitions ### Enhanced - **Contact Utilities**: New `ContactsUtils.ts` with helper functions - `buildContactPayload()` for parameter to API payload conversion - `normalizeContact()` for response normalization - `createContact()`, `getContact()`, `getAllContacts()`, `updateContact()`, `deleteContact()` API functions - Proper error handling with NodeApiError for validation failures - Support for address structures and custom fields ### Documentation - **Contact Operations Guide**: Added comprehensive Contact section to OPERATIONS.md - **Contact JSON Guide**: New CONTACT_JSON_GUIDE.md with detailed examples - **Field Descriptions**: Complete documentation of all Contact fields and their usage - **Integration Examples**: CRM and e-commerce integration examples - **Best Practices**: Contact naming, email validation, address formatting guidelines - **Troubleshooting**: Common issues and validation checklist ### Testing - **Unit Tests**: Comprehensive test coverage for ContactsUtils functions - **Resource Tests**: Full test suite for Contact resource operations - **Error Handling**: Tests for validation errors, API errors, and edge cases - **Mock Coverage**: Proper mocking of API calls and response handling ### Technical Changes - Added Contact resource to node JSON configuration - Extended execute method with Contact operation handling - Added Contact fields with proper displayOptions and validation - Implemented dynamic import for ContactsUtils to maintain performance - Added Contact to resource options and operation display conditions ## [2.1.1] - 2025-01-15 ### Fixed - **Customer Dropdown Population**: Improved customer field loading in Form and Hybrid modes - Now specifically queries for `contact_type=customer` to ensure proper customer list - Added fallback to all contacts if no customers found - Enhanced error handling to prevent UI issues when API calls fail - Better reliability for customer dropdown pre-population ## [2.1.0] - 2025-01-15 ### Added - **Enhanced Form Fields**: Added Sales Order Date and Sales Order Number fields to Form and Hybrid input methods - Sales Order Date: Document date field with automatic YYYY-MM-DD formatting - Sales Order Number: Custom sales order number field (auto-numbered if left blank) - Both fields are available in Form and Hybrid input methods - In Hybrid mode, form fields override corresponding JSON values for better user control - **Date Formatting Utility**: New `formatDate` helper function for consistent date formatting across input methods ### Enhanced - **Hybrid Method**: Form fields now take precedence over JSON data for date and sales order number - **Customer Field**: Pre-populated customer dropdown now consistently available in Hybrid mode - **Documentation**: Updated sales order guide with new field descriptions and usage examples ## [1.4.1] - 2024-12-19 ### Fixed - **Sales Order Search by Number**: Fixed exact matching issue where partial matches were returned - Now performs client-side filtering to ensure exact sales order number matches - Uses dual approach: criteria search first, then fallback to search_text with exact filtering - Prevents returning wrong sales orders with similar numbers (e.g., searching for "404-3495320-8661951" no longer returns "408-0914562-5185938") - Enhanced test coverage for exact matching scenarios ## [1.4.0] - 2024-12-19 ### Added - **Enhanced Sales Order Get Operation**: Added flexible search capabilities - New "Search Type" option allows searching by Sales Order ID or Sales Order Number - Search by Sales Order Number uses Zoho's criteria API for exact matches - Graceful "not found" handling: Returns `{ sales_order_found: false }` instead of throwing errors - Backward compatible: Existing workflows using ID search continue to work unchanged - New utility function `findSalesOrderByNumber()` for reusable number-based lookups - Comprehensive test coverage for both search modes and edge cases ### Fixed - Added legacy compatibility exports for existing test infrastructure - Improved error handling for resource not found scenarios - Added missing `getTaxes` load options method for form dropdowns ## [1.3.11] - 2024-08-02 ### Added - **NEW FEATURE**: Get Item by SKU operation for both Zoho Books and Zoho Inventory - Added `getBySku` operation to Item resource in both nodes - Supports case-insensitive SKU code lookup - Comprehensive error handling for edge cases: - Empty or whitespace SKU codes - SKU not found scenarios - Multiple items with duplicate SKUs - Invalid API response handling - Performance optimized with single API call and client-side filtering - Full test coverage with 40+ unit tests covering all scenarios ### Enhanced - Added Item resource support to ZohoInventory node with full CRUD operations - Improved error messages with specific HTTP status codes - Added support for special characters and Unicode in SKU codes - Enhanced documentation with usage examples and troubleshooting guide ### Technical Changes - Created `getItemBySku` helper function in GenericFunctions for both nodes - Added comprehensive TypeScript type definitions - Implemented proper error wrapping with NodeApiError - Added SKU input field with validation and placeholder text - Extended execute methods to handle new getBySku operation ## [1.2.7] - 2024-12-19 ### Fixed - **CRITICAL**: Fixed parameter dependency resolution error for Bill Create Record operation - Resolved "Could not resolve parameter dependencies. Max iterations reached!" error - Split single additionalFields collection into resource-specific collections to eliminate displayOptions on child parameters - Updated all execute method references to use new parameter names - Added proper TypeScript type casting for all additionalFields parameters ### Technical Changes - Replaced single additionalFields collection with separate collections for each resource: - billAdditionalFields - invoiceAdditionalFields - salesOrderAdditionalFields - purchaseOrderAdditionalFields - itemAdditionalFields - compositeItemAdditionalFields - vendorAdditionalFields - paymentAdditionalFields - creditNoteAdditionalFields - Removed all displayOptions from child parameters in collection/fixedCollection types - Added proper IDataObject type casting for all additionalFields parameters ## [Unreleased] ### Added - Bill: Exposed full create UI (vendor, line items with item picker, additional fields) and fields for get/update/getAll and attachments. - Bill: Added JSON and Hybrid input methods for Create, enabling large/multi-line item payloads via raw JSON with optional vendor selection. ### Fixed - Zoho Books: Vendor → Get Many returned empty output due to missing vendor filter and header. Implemented vendor listing via `/contacts` with `contact_type=vendor` and ensured `X-com-zoho-books-organizationid` header is sent on every request. - Bill: Add Attachment now sends multipart form-data correctly (uses formData instead of JSON), fixing 33003 Attachment not found when payload was sent in wrong format. - Attachment responses are parsed when API returns JSON as a string, so the node outputs structured `documents` instead of a raw JSON string. ### Changed - Added Vendor loadOptions fix to use query params rather than path query strings. ### Added - Initial release of n8n-nodes-zoho-books - OAuth2 authentication support for all Zoho data centers - Support for 6 main resources: - Sales Orders - Create, read, update, and void operations - Invoices - Full CRUD operations with line items support - Items - Complete product/service management - Payments - Customer payment recording and tracking - Vendors - Supplier management functionality - Credit Notes - Returns and adjustments handling - Rate limiting with automatic retry and exponential backoff - Comprehensive error handling with detailed messages - Load options for dynamic dropdowns (customers, items, taxes) - Pagination support for all list operations - Filtering capabilities for date ranges and status - Additional fields support for extended functionality - Full test coverage with unit and integration tests ### Security - Secure OAuth2 implementation - Organization ID validation - Proper credential handling ## [0.1.0] - 2024-01-XX ### Added - Beta release for testing - Core functionality for all 6 resources - Basic documentation and examples ### Known Issues - Some advanced Zoho Books features not yet implemented - Custom fields support is limited ## Roadmap ### Version 0.2.0 (Planned) - [ ] Purchase Order support - [ ] Bill management - [ ] Bank transaction reconciliation - [ ] Journal entries - [ ] Enhanced custom field support ### Version 0.3.0 (Planned) - [ ] Bulk operations support - [ ] Webhook trigger node - [ ] Report generation - [ ] Tax configuration management - [ ] Multi-currency support ### Version 1.0.0 (Planned) - [ ] Complete API coverage - [ ] Performance optimizations - [ ] Advanced filtering options - [ ] Comprehensive error recovery - [ ] Production-ready release ## Contributing Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project. ## Support For issues and feature requests, please use the [GitHub issue tracker](https://github.com/your-username/n8n-nodes-zoho-books/issues).