@arathron/n8n-nodes-zoho-books/README.md

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, and Assemblies

# n8n-nodes-zoho-books

This is an n8n community node package that provides nodes for Zoho Books and Zoho Inventory in your n8n workflows.

Zoho Books is a cloud-based accounting software that helps you manage your finances, automate business workflows, and work collectively across departments.

Zoho Inventory is an inventory management software that helps you manage your stock, create assemblies, track inventory movements, and streamline order fulfillment.

[n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation platform.

## Table of Contents

- [Installation](#installation)
- [Authentication](#authentication)
- [Operations](#operations)
- [Resources](#resources)
- [Usage Examples](#usage-examples)
- [Common Workflows](#common-workflows)
- [Troubleshooting](#troubleshooting)
- [Resources](#resources-1)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

### Using npm

1. Navigate to your n8n installation directory
2. Install the node:
   ```bash
   npm install n8n-nodes-zoho-books
   ```
3. Restart n8n

### Manual Installation

1. Clone or download this repository
2. Copy the `n8n-nodes-zoho-books` folder to your n8n custom nodes folder
3. Install dependencies:
   ```bash
   cd /path/to/n8n-custom-nodes/n8n-nodes-zoho-books
   npm install
   ```
4. Build the node:
   ```bash
   npm run build
   ```
5. Restart n8n

## Authentication

These nodes use OAuth2 authentication to connect to Zoho Books and Zoho Inventory. Follow these steps to set up authentication:

### 1. Create Zoho OAuth Client

1. Go to [Zoho API Console](https://api-console.zoho.com/)
2. Click on "Add Client"
3. Choose "Server-based Applications"
4. Fill in the details:
   - **Client Name**: n8n Zoho Books Integration (or any name you prefer)
   - **Homepage URL**: Your n8n instance URL
   - **Authorized Redirect URIs**: `https://your-n8n-instance.com/rest/oauth2-credential/callback`
5. Click "Create"
6. Note down the **Client ID** and **Client Secret**

### 2. Get Organization ID

1. Log in to your Zoho Books account
2. Go to **Settings** > **Organization Profile**
3. Copy your **Organization ID**

### 3. Configure Credentials in n8n

#### For Zoho Books:
1. In n8n, go to **Credentials** > **New**
2. Select **Zoho Books OAuth2 API**
3. Configure the following:
   - **Data Center**: Select your Zoho data center (COM, EU, IN, AU, or CN)
   - **Organization ID**: Paste your Organization ID
   - **Client ID**: Paste from Zoho API Console
   - **Client Secret**: Paste from Zoho API Console
4. Click **Save** to create the credentials
5. Click **Connect** to authenticate

#### For Zoho Inventory:
1. In n8n, go to **Credentials** > **New**
2. Select **Zoho Inventory OAuth2 API**
3. Configure the following:
   - **Data Center**: Select your Zoho data center (COM, EU, IN, AU, or CN)
   - **Organization ID**: Paste your Organization ID (same as Zoho Books if using the same organization)
   - **Client ID**: Paste from Zoho API Console (can use the same OAuth client)
   - **Client Secret**: Paste from Zoho API Console
4. Click **Save** to create the credentials
5. Click **Connect** to authenticate
6. Authorize the requested permissions in the Zoho popup

![Authentication Setup Screenshot](docs/images/auth-setup.png)
*Screenshot: Zoho Books OAuth2 credential configuration in n8n*

## Operations

The Zoho Books node supports the following operations across different resources:

### Standard Operations
- **Create**: Create a new record
- **Get**: Retrieve a single record by ID
- **Get Many**: Retrieve multiple records with optional filtering
- **Update**: Update an existing record
- **Delete**: Delete or void a record

## Resources

### 1. Sales Order
Manage sales orders in your Zoho Books account.

**Operations:**
- Create sales order
- Get sales order details
- List all sales orders
- Update sales order
- Void sales order

### 2. Invoice
Handle customer invoices and billing.

**Operations:**
- Create invoice
- Get invoice details
- List all invoices
- Update invoice
- Void invoice

### 3. Item
Manage products and services.

**Operations:**
- Create item
- Get item details
- Get item by SKU code
- List all items
- Update item
- Delete item

**New Feature**: The **Get by SKU** operation allows you to retrieve items using their SKU code instead of the item ID, making it easier to integrate with external systems that use SKU-based references.

### 4. Payment
Track customer payments.

**Operations:**
- Record payment
- Get payment details
- List all payments
- Update payment
- Delete payment

### 5. Vendor
Manage vendor/supplier information.

**Operations:**
- Create vendor
- Get vendor details
- List all vendors
- Update vendor
- Delete vendor

### 6. Credit Note
Handle credit notes for returns and adjustments.

**Operations:**
- Create credit note
- Get credit note details
- List all credit notes
- Update credit note
- Void credit note

## Usage Examples

### Example 1: Create an Invoice

```json
{
  "resource": "invoice",
  "operation": "create",
  "customerId": "{{$node.Customer.json.contact_id}}",
  "lineItems": {
    "item": [
      {
        "item_id": "{{$node.Item.json.item_id}}",
        "quantity": 2,
        "rate": 99.99
      }
    ]
  },
  "additionalFields": {
    "date": "2024-01-15",
    "notes": "Thank you for your business!"
  }
}
```

### Example 2: List Recent Sales Orders

```json
{
  "resource": "salesOrder",
  "operation": "getAll",
  "returnAll": false,
  "limit": 10,
  "filters": {
    "status": "open",
    "fromDate": "2024-01-01"
  }
}
```

### Example 3: Record a Payment

```json
{
  "resource": "payment",
  "operation": "create",
  "customerId": "{{$node.Customer.json.contact_id}}",
  "paymentMode": "creditcard",
  "amount": 199.98,
  "additionalFields": {
    "date": "2024-01-15",
    "referenceNumber": "PAY-2024-001"
  }
}
```

### Example 4: Get Item by SKU Code

```json
{
  "resource": "item",
  "operation": "getBySku",
  "skuCode": "LAPTOP-001"
}
```

This operation will return the complete item details including stock levels, pricing, and warehouse information based on the SKU code. This is particularly useful when:
- Integrating with external systems that use SKU references
- Processing inventory from barcode scans
- Updating stock levels from supplier feeds
- Creating invoices where you know the SKU but not the item ID

**Response example:**
```json
{
  "item_id": "123456789",
  "name": "Premium Laptop",
  "sku": "LAPTOP-001",
  "description": "High-performance laptop for professionals",
  "rate": 1299.99,
  "stock_on_hand": 25,
  "available_stock": 23,
  "status": "active",
  "item_type": "inventory"
}
```

## Zoho Inventory Resources

### 1. Composite Item
Manage composite items (bundled products) in your Zoho Inventory account.

**Operations:**
- Create composite item with line items
- Get composite item details
- List all composite items
- Update composite item and line items
- Delete composite item

**Key Fields:**
- `name`: Name of the composite item
- `sku`: Stock Keeping Unit
- `rate`: Selling price
- `lineItems`: Component items and quantities

### 2. Assembly
Create and manage assemblies for composite items.

**Operations:**
- Create assembly: Assemble composite items from components
- Get assembly details
- Get assembly history: View all assemblies for a composite item
- Delete assembly

**Key Fields:**
- `compositeItemId`: ID of the composite item to assemble
- `quantity`: Quantity to assemble
- `date`: Assembly date
- `referenceNumber`: Reference for tracking

### 3. Item
Manage inventory items in your Zoho Inventory account.

**Operations:**
- Create item
- Get item details by ID
- Get item by SKU code
- List all items with filtering
- Update item
- Delete item

**Key Features:**
- **SKU-based lookup**: Find items using their SKU code for easier integration
- **Stock tracking**: Access stock levels, warehouse information, and availability
- **Multi-warehouse support**: Handle items across multiple warehouse locations
- **Serial/batch tracking**: Support for items with serial numbers or batch numbers

## Common Workflows

### 1. Order to Invoice Automation
**Workflow**: Automatically create invoices from confirmed sales orders

1. **Trigger**: Webhook or schedule trigger
2. **Zoho Books - Get Sales Orders**: Fetch confirmed orders
3. **Zoho Books - Create Invoice**: Convert each order to invoice
4. **Email**: Send invoice to customer

### 2. Payment Reconciliation
**Workflow**: Match bank transactions with customer payments

1. **Bank API**: Fetch new transactions
2. **Zoho Books - Get Customers**: Match by reference
3. **Zoho Books - Create Payment**: Record matched payments
4. **Slack**: Notify finance team

### 3. Inventory Management
**Workflow**: Update item stock levels from external system

1. **External System**: Get stock levels
2. **Zoho Books - Get Items**: Fetch current items
3. **Compare**: Calculate differences
4. **Zoho Books - Update Items**: Update stock levels

### 4. Vendor Bill Processing
**Workflow**: Automate vendor bill creation from emails

1. **Email Trigger**: New vendor email
2. **Extract Data**: Parse bill details
3. **Zoho Books - Create Vendor**: Create if new
4. **Zoho Books - Create Bill**: Record the bill

### 5. Monthly Reporting
**Workflow**: Generate monthly sales reports

1. **Schedule Trigger**: First day of month
2. **Zoho Books - Get Invoices**: Last month's invoices
3. **Aggregate Data**: Calculate totals
4. **Create Report**: Format data
5. **Email/Slack**: Send to stakeholders

### 6. SKU-based Inventory Sync
**Workflow**: Synchronize inventory from external system using SKU codes

1. **External System API**: Fetch inventory updates with SKU codes
2. **Zoho Books/Inventory - Get by SKU**: Find items by SKU code
3. **Compare Data**: Check stock levels and pricing differences
4. **Zoho Books/Inventory - Update Item**: Update stock levels and prices
5. **Notification**: Alert inventory manager of changes

**Benefits of SKU-based approach:**
- No need to maintain item ID mappings
- Works with barcode systems that use SKU
- Easier integration with external inventory systems
- More reliable for bulk operations

## Troubleshooting

### Common Issues

#### Authentication Errors
- **Invalid Organization ID**: Verify the Organization ID in Zoho Books Settings
- **Token Expired**: Re-authenticate by clicking "Connect" in credentials
- **Insufficient Permissions**: Ensure the OAuth app has `ZohoBooks.fullaccess.all` scope

#### API Errors
- **Rate Limiting**: The node implements automatic retry with exponential backoff
- **Invalid Data**: Check required fields and data formats
- **Resource Not Found**: Verify IDs are correct and resources exist

#### Data Issues
- **Missing Line Items**: Line items are required for invoices and sales orders
- **Currency Mismatch**: Ensure currency matches organization settings
- **Tax Calculation**: Configure tax settings in Zoho Books first

#### SKU-Related Issues
- **SKU Not Found**: Verify the SKU code exists and is spelled correctly (case-insensitive search)
- **Multiple Items with Same SKU**: Ensure SKU codes are unique across your organization
- **Empty SKU Code**: Provide a valid, non-empty SKU code for the search
- **Special Characters in SKU**: SKU codes with special characters are supported

### Error Messages

| Error Code | Description | Solution |
|------------|-------------|----------|
| 1002 | Invalid data | Check field formats and required fields |
| 1001 | Resource not found | Verify the ID exists |
| 4000 | Rate limit exceeded | Wait and retry, node handles automatically |
| 1000 | Invalid Organization ID | Check credentials configuration |
| 400 | SKU code is required | Provide a valid, non-empty SKU code |
| 404 | Item with SKU not found | Verify the SKU code exists in your system |
| 409 | Multiple items with same SKU | Ensure SKU codes are unique |
| 500 | Invalid API response format | Contact support if this persists |

### Debug Mode

To enable detailed logging:
1. Set n8n log level to `debug`
2. Check execution data for API responses
3. Use "Console" node to inspect data structure

## Resources

- **[Zoho Books API Documentation](https://www.zoho.com/books/api/v3/)** - Official API reference
- **[n8n Documentation](https://docs.n8n.io)** - Learn about n8n and workflow automation
- **[n8n Community Forum](https://community.n8n.io)** - Get help from the community
- **[GitHub Repository](https://github.com/your-username/n8n-nodes-zoho-books)** - Report issues and contribute

## Version History

See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## License

[MIT](LICENSE)