# n8n Integration Guide

## Overview

The n8n integration provides a low-code approach to fetch data from multiple providers (Zoho, Salesforce, QuickBooks) through a single unified webhook endpoint in n8n.

## Architecture

```
Backend API → n8n Client → n8n Webhook → Provider APIs (Zoho/Salesforce/etc.)
```

### Benefits
- ✅ Single webhook handles multiple providers
- ✅ Less code maintenance in backend
- ✅ Easy to add new providers in n8n without backend changes
- ✅ Visual workflow management
- ✅ Built-in error handling and retry logic

## Setup

### 1. Environment Variables

Add these to your `.env` file:

```env
# n8n Configuration
N8N_WEBHOOK_URL=http://localhost:5678
N8N_WEBHOOK_ID=04e677f5-ec57-4772-bf12-96f2610d4b9c
```

### 2. Import n8n Workflow

1. Open your n8n instance
2. Import the workflow from `My_workflow_3 (1).json`
3. The webhook will be automatically created with ID: `04e677f5-ec57-4772-bf12-96f2610d4b9c`
4. Activate the workflow

### 3. Webhook Endpoint

The n8n webhook URL will be:
```
POST http://localhost:5678/webhook/04e677f5-ec57-4772-bf12-96f2610d4b9c
```

## API Usage

### Authentication

All endpoints require JWT authentication. Include the `Authorization` header:

```
Authorization: Bearer <your_jwt_token>
```

### Endpoints

#### 1. Get Supported Providers

```http
GET /api/v1/n8n/providers
```

**Response:**
```json
{
  "status": "success",
  "message": "Supported providers retrieved",
  "data": {
    "zoho": {
      "crm": ["leads", "contacts", "accounts", "deals", "tasks", ...],
      "books": ["organizations", "contacts", "customers", ...],
      "people": ["employees", "departments", ...],
      "projects": ["portals", "projects", "tasks", ...]
    },
    "salesforce": {
      "crm": ["leads", "accounts", "tasks", "opportunities", "events"]
    }
  },
  "timestamp": "2025-10-09T12:00:00.000Z"
}
```

#### 2. Generic Data Fetch (Any Provider)

```http
GET /api/v1/n8n/data/:provider/:service/:module
```

**Parameters:**
- `provider` - zoho, salesforce, intuit
- `service` - crm, books, people, projects
- `module` - leads, contacts, accounts, etc.

**Query Parameters:**
- `limit` (optional) - Number of records (default: 200, max: 1000)
- `page` (optional) - Page number (default: 1)
- `offset` (optional) - Offset for pagination (default: 0)

**Examples:**

```http
# Fetch Zoho CRM Leads
GET /api/v1/n8n/data/zoho/crm/leads?limit=100&page=1

# Fetch Salesforce Accounts
GET /api/v1/n8n/data/salesforce/crm/accounts?limit=50

# Fetch Zoho People Employees
GET /api/v1/n8n/data/zoho/people/employees?limit=200
```

#### 3. Zoho Shorthand Routes

```http
GET /api/v1/n8n/zoho/:service/:module
```

**Examples:**

```http
# CRM
GET /api/v1/n8n/zoho/crm/leads
GET /api/v1/n8n/zoho/crm/contacts
GET /api/v1/n8n/zoho/crm/accounts
GET /api/v1/n8n/zoho/crm/deals

# Books
GET /api/v1/n8n/zoho/books/invoices
GET /api/v1/n8n/zoho/books/customers
GET /api/v1/n8n/zoho/books/vendors

# People
GET /api/v1/n8n/zoho/people/employees
GET /api/v1/n8n/zoho/people/departments

# Projects
GET /api/v1/n8n/zoho/projects/portals
GET /api/v1/n8n/zoho/projects/projects
```

#### 4. Salesforce Shorthand Routes

```http
GET /api/v1/n8n/salesforce/:service/:module
```

**Examples:**

```http
GET /api/v1/n8n/salesforce/crm/leads
GET /api/v1/n8n/salesforce/crm/accounts
GET /api/v1/n8n/salesforce/crm/opportunities
GET /api/v1/n8n/salesforce/crm/tasks
GET /api/v1/n8n/salesforce/crm/events
```

### Response Format

All endpoints return data in this format:

```json
{
  "status": "success",
  "message": "zoho crm leads data fetched successfully",
  "data": {
    "success": true,
    "data": [
      {
        "id": "123",
        "name": "John Doe",
        ...
      }
    ],
    "count": 1,
    "metadata": {}
  },
  "timestamp": "2025-10-09T12:00:00.000Z"
}
```

### Error Responses

```json
{
  "status": "error",
  "message": "Unsupported combination: zoho/crm/invalid_module",
  "errorCode": "N8N_FETCH_ERROR",
  "timestamp": "2025-10-09T12:00:00.000Z"
}
```

## Workflow Structure

### Input Payload to n8n

The backend sends this payload to the n8n webhook:

```json
{
  "body": {
    "provider": "zoho",
    "service": "crm",
    "module": "leads",
    "acces_token": "1000.xxxxx",
    "instance_url": null
  },
  "query": {
    "per_page": 200,
    "page": 1
  }
}
```

### Workflow Flow

1. **Webhook** receives the request
2. **Provider Switch** routes based on `provider` (zoho, salesforce, intuit)
3. **Service Switch** routes based on `service` (crm, books, people, projects)
4. **Module Switch** routes based on `module` (leads, contacts, etc.)
5. **HTTP Request** calls the provider API
6. **Response** returns data to backend

## Supported Modules

### Zoho CRM
- `leads` - Leads data
- `contacts` - Contacts data
- `accounts` - Accounts data
- `deals` - Deals/Opportunities data
- `tasks` - Tasks data
- `purchase_orders` - Purchase Orders (disabled in workflow)
- `sales_orders` - Sales Orders (disabled in workflow)
- `invoices` - Invoices (disabled in workflow)

### Zoho Books
- `organizations` - Organizations
- `contacts` - All contacts
- `customers` - Customer contacts
- `vendors` - Vendor contacts
- `accounts` - Bank accounts
- `purchase_orders` - Purchase Orders
- `sales_orders` - Sales Orders
- `invoices` - Invoices
- `bills` - Bills
- `expenses` - Expenses

### Zoho People
- `employees` - Employee records
- `departments` - Departments (disabled in workflow)
- `timesheets` - Timesheets (disabled in workflow)
- `leaves` - Leave records (disabled in workflow)
- `attendence` - Attendance (disabled in workflow)
- `attendence_entries` - Attendance entries
- `attendence_report` - Attendance reports
- `leave_tracker` - Leave balance tracker
- `leaves_data` - Leave data
- `goals_data` - Goals data
- `performance_data` - Performance data (disabled in workflow)

### Zoho Projects
- `portals` - Portals
- `projects` - Projects
- `tasks` - Project-specific tasks
- `all_tasks` - All tasks across projects
- `tasklists` - Task lists for specific project
- `all_tasklists` - All task lists
- `issues` - Issues
- `phases` - Project phases

### Salesforce CRM
- `leads` - Leads data
- `accounts` - Accounts data
- `tasks` - Tasks data
- `opportunities` - Opportunities data
- `events` - Events/Meetings data
- `reports` - Reports (not yet implemented in workflow)

## Code Examples

### Using in Your Service

```javascript
const n8nService = require('./services/n8nService');

// Fetch Zoho CRM Leads
async function getZohoLeads(userId) {
  try {
    const result = await n8nService.fetchZohoCrmData(
      userId, 
      'leads', 
      { limit: 100, page: 1 }
    );
    
    console.log('Leads:', result.data);
    console.log('Count:', result.count);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

// Fetch Salesforce Accounts
async function getSalesforceAccounts(userId) {
  try {
    const result = await n8nService.fetchSalesforceCrmData(
      userId,
      'accounts',
      { limit: 50, offset: 0 }
    );
    
    console.log('Accounts:', result.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
}
```

### Using with cURL

```bash
# Get your JWT token first
TOKEN="your_jwt_token"

# Fetch Zoho CRM Leads
curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads?limit=100" \
  -H "Authorization: Bearer $TOKEN"

# Fetch Salesforce Opportunities
curl -X GET "http://localhost:3000/api/v1/n8n/salesforce/crm/opportunities?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

## Error Handling

The integration includes comprehensive error handling:

1. **Token Validation** - Checks if user has authenticated with the provider
2. **Module Validation** - Validates provider/service/module combination
3. **n8n Timeout** - 60-second timeout for webhook calls
4. **Logging** - All requests and errors are logged

## Adding New Providers

To add a new provider (e.g., QuickBooks):

1. **Update n8n workflow:**
   - Add new switch case in "Provider Switch"
   - Create service and module switches
   - Add HTTP request nodes

2. **Update backend mapper:**
   - Add modules to `N8nMapper.getSupportedModules()`

3. **Add environment variables** (if needed):
   ```env
   QUICKBOOKS_CLIENT_ID=xxx
   QUICKBOOKS_CLIENT_SECRET=xxx
   ```

4. No other backend code changes required! 🎉

## Performance Considerations

- Default timeout: 60 seconds
- Default page size: 200 records
- Maximum page size: 1000 records
- Use pagination for large datasets
- n8n workflow can be scaled horizontally

## Troubleshooting

### Common Issues

1. **"n8n workflow execution failed"**
   - Check if n8n is running
   - Verify webhook URL and ID in .env
   - Check n8n workflow logs

2. **"Authentication not found"**
   - User must authenticate via OAuth first
   - Use `/api/v1/users/oauth/callback` endpoint

3. **"Unsupported combination"**
   - Check supported modules via `/api/v1/n8n/providers`
   - Verify module name spelling

4. **Timeout errors**
   - Reduce page size
   - Check provider API status
   - Increase timeout in n8n client

## License

MIT