396 lines
8.9 KiB
Markdown
396 lines
8.9 KiB
Markdown
# 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
|
|
|