447 lines
14 KiB
Markdown
447 lines
14 KiB
Markdown
# 🚀 n8n Integration - Complete Implementation
|
|
|
|
## 📋 What's Been Created
|
|
|
|
A complete low-code n8n integration that allows you to fetch data from multiple providers (Zoho, Salesforce, QuickBooks) through a single unified webhook.
|
|
|
|
### ✅ Created Files
|
|
|
|
```
|
|
src/
|
|
├── integrations/
|
|
│ └── n8n/
|
|
│ ├── client.js # n8n webhook HTTP client
|
|
│ ├── handler.js # Request orchestration & token management
|
|
│ ├── mapper.js # Module validation & mapping
|
|
│ └── README.md # Module documentation
|
|
│
|
|
├── services/
|
|
│ └── n8nService.js # Business logic layer
|
|
│
|
|
├── api/
|
|
│ ├── controllers/
|
|
│ │ └── n8nController.js # HTTP request handlers
|
|
│ └── routes/
|
|
│ └── n8nRoutes.js # API route definitions
|
|
│
|
|
└── app.js # Updated with n8n routes
|
|
|
|
docs/
|
|
├── N8N_INTEGRATION.md # Complete integration guide
|
|
└── N8N_SETUP_EXAMPLE.md # Quick start examples
|
|
|
|
README_N8N.md # This file
|
|
```
|
|
|
|
## 🏗️ Architecture
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ Client │
|
|
│ (Frontend) │
|
|
└──────┬──────┘
|
|
│ HTTP Request
|
|
↓
|
|
┌─────────────────────────────────────────────┐
|
|
│ Backend API │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ GET /api/v1/n8n/zoho/crm/leads │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ n8nController │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ n8nService │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ N8nHandler │ │
|
|
│ │ • Gets user's access token │ │
|
|
│ │ • Decrypts token │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ N8nClient │ │
|
|
│ │ • Calls n8n webhook │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
└─────────────────┼──────────────────────────┘
|
|
│
|
|
│ HTTP POST
|
|
↓
|
|
┌─────────────────────────────────────────────┐
|
|
│ n8n Workflow │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ Webhook (receives request) │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ Provider Switch (zoho/salesforce) │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ Service Switch (crm/books/etc) │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ Module Switch (leads/contacts) │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────┐ │
|
|
│ │ HTTP Request to Provider API │ │
|
|
│ └──────────────┬─────────────────────┘ │
|
|
└─────────────────┼──────────────────────────┘
|
|
│
|
|
↓
|
|
┌───────────────┐
|
|
│ Zoho API │
|
|
│ Salesforce API│
|
|
│ QuickBooks API│
|
|
└───────────────┘
|
|
```
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Step 1: Environment Setup
|
|
|
|
Add to `.env`:
|
|
|
|
```env
|
|
# n8n Configuration
|
|
N8N_WEBHOOK_URL=http://localhost:5678
|
|
N8N_WEBHOOK_ID=04e677f5-ec57-4772-bf12-96f2610d4b9c
|
|
```
|
|
|
|
### Step 2: Import n8n Workflow
|
|
|
|
1. Open n8n at `http://localhost:5678`
|
|
2. Import `My_workflow_3 (1).json`
|
|
3. Activate the workflow
|
|
|
|
### Step 3: User Authentication
|
|
|
|
Users must authenticate with providers first:
|
|
|
|
```http
|
|
GET /api/v1/users/oauth/callback?
|
|
authorization_code=ABC123&
|
|
user_uuid=550e8400-e29b-41d4-a716-446655440000&
|
|
service_name=zoho
|
|
```
|
|
|
|
### Step 4: Fetch Data
|
|
|
|
```http
|
|
GET /api/v1/n8n/zoho/crm/leads?limit=100
|
|
Authorization: Bearer <jwt_token>
|
|
```
|
|
|
|
## 📡 API Endpoints
|
|
|
|
### Get Supported Providers
|
|
|
|
```http
|
|
GET /api/v1/n8n/providers
|
|
```
|
|
|
|
### Generic Endpoint (Any Provider)
|
|
|
|
```http
|
|
GET /api/v1/n8n/data/:provider/:service/:module
|
|
```
|
|
|
|
**Examples:**
|
|
```http
|
|
GET /api/v1/n8n/data/zoho/crm/leads
|
|
GET /api/v1/n8n/data/salesforce/crm/accounts
|
|
GET /api/v1/n8n/data/zoho/people/employees
|
|
```
|
|
|
|
### Zoho Shorthand
|
|
|
|
```http
|
|
GET /api/v1/n8n/zoho/:service/:module
|
|
```
|
|
|
|
**Examples:**
|
|
```http
|
|
GET /api/v1/n8n/zoho/crm/leads
|
|
GET /api/v1/n8n/zoho/books/invoices
|
|
GET /api/v1/n8n/zoho/people/employees
|
|
GET /api/v1/n8n/zoho/projects/portals
|
|
```
|
|
|
|
### Salesforce Shorthand
|
|
|
|
```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
|
|
```
|
|
|
|
## 🎯 Supported Providers & Modules
|
|
|
|
### Zoho
|
|
|
|
**CRM:** leads, contacts, accounts, deals, tasks, invoices, purchase_orders, sales_orders
|
|
|
|
**Books:** organizations, contacts, customers, vendors, accounts, invoices, bills, expenses, purchase_orders, sales_orders
|
|
|
|
**People:** employees, departments, timesheets, leaves, attendence, attendence_entries, attendence_report, leave_tracker, leaves_data, goals_data, performance_data
|
|
|
|
**Projects:** portals, projects, tasks, all_tasks, tasklists, all_tasklists, issues, phases
|
|
|
|
### Salesforce
|
|
|
|
**CRM:** leads, accounts, tasks, opportunities, events, reports
|
|
|
|
## 📝 Usage Examples
|
|
|
|
### JavaScript/Node.js
|
|
|
|
```javascript
|
|
const axios = require('axios');
|
|
|
|
const API_URL = 'http://localhost:3000/api/v1';
|
|
const token = 'your_jwt_token';
|
|
|
|
// Fetch Zoho Leads
|
|
async function getZohoLeads() {
|
|
const response = await axios.get(
|
|
`${API_URL}/n8n/zoho/crm/leads?limit=100`,
|
|
{ headers: { Authorization: `Bearer ${token}` }}
|
|
);
|
|
return response.data;
|
|
}
|
|
|
|
// Fetch Salesforce Accounts
|
|
async function getSalesforceAccounts() {
|
|
const response = await axios.get(
|
|
`${API_URL}/n8n/salesforce/crm/accounts?limit=50`,
|
|
{ headers: { Authorization: `Bearer ${token}` }}
|
|
);
|
|
return response.data;
|
|
}
|
|
|
|
// Fetch multiple sources
|
|
async function getDashboardData() {
|
|
const [leads, employees, opportunities] = await Promise.all([
|
|
axios.get(`${API_URL}/n8n/zoho/crm/leads`,
|
|
{ headers: { Authorization: `Bearer ${token}` }}),
|
|
axios.get(`${API_URL}/n8n/zoho/people/employees`,
|
|
{ headers: { Authorization: `Bearer ${token}` }}),
|
|
axios.get(`${API_URL}/n8n/salesforce/crm/opportunities`,
|
|
{ headers: { Authorization: `Bearer ${token}` }})
|
|
]);
|
|
|
|
return {
|
|
leads: leads.data,
|
|
employees: employees.data,
|
|
opportunities: opportunities.data
|
|
};
|
|
}
|
|
```
|
|
|
|
### cURL
|
|
|
|
```bash
|
|
# Get JWT token
|
|
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 Accounts
|
|
curl -X GET "http://localhost:3000/api/v1/n8n/salesforce/crm/accounts" \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
|
|
# Get supported providers
|
|
curl -X GET "http://localhost:3000/api/v1/n8n/providers" \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
## 🔄 Response Format
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "zoho crm leads data fetched successfully",
|
|
"data": {
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": "123",
|
|
"First_Name": "John",
|
|
"Last_Name": "Doe",
|
|
"Email": "john@example.com",
|
|
"Company": "Acme Corp"
|
|
}
|
|
],
|
|
"count": 1,
|
|
"metadata": {}
|
|
},
|
|
"timestamp": "2025-10-09T12:00:00.000Z"
|
|
}
|
|
```
|
|
|
|
## ✨ Key Features
|
|
|
|
### ✅ Benefits
|
|
|
|
- **Low-code Approach**: Most logic in visual n8n workflows
|
|
- **Single Webhook**: One webhook handles all providers
|
|
- **Easy Maintenance**: Add new providers in n8n without backend changes
|
|
- **Token Management**: Automatic token retrieval and decryption
|
|
- **Error Handling**: Comprehensive error handling and logging
|
|
- **Type Safety**: Module validation before API calls
|
|
- **Unified API**: Consistent endpoint structure across providers
|
|
- **Scalable**: n8n workflows can be scaled horizontally
|
|
|
|
### 🎨 Design Patterns Used
|
|
|
|
- **Facade Pattern**: N8nService provides simple interface
|
|
- **Strategy Pattern**: Different handlers for each provider
|
|
- **Factory Pattern**: N8nHandler creates appropriate clients
|
|
- **Repository Pattern**: Token management through repositories
|
|
|
|
## 🛠️ Development
|
|
|
|
### Adding a New Provider
|
|
|
|
1. **Update n8n workflow:**
|
|
```
|
|
- Add switch case in "Provider Switch"
|
|
- Add service switches
|
|
- Add module switches
|
|
- Add HTTP request nodes
|
|
```
|
|
|
|
2. **Update mapper:**
|
|
```javascript
|
|
// src/integrations/n8n/mapper.js
|
|
static getSupportedModules(provider, service) {
|
|
const modules = {
|
|
newprovider: {
|
|
api: ['resource1', 'resource2']
|
|
}
|
|
};
|
|
}
|
|
```
|
|
|
|
3. **Done!** No other backend changes needed.
|
|
|
|
### Adding a New Module
|
|
|
|
1. **Update n8n workflow:**
|
|
- Add switch case in appropriate module switch
|
|
- Add HTTP request node
|
|
|
|
2. **Update mapper:**
|
|
```javascript
|
|
crm: ['leads', 'contacts', 'new_module']
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
### Manual Testing
|
|
|
|
1. Authenticate user with provider
|
|
2. Get JWT token
|
|
3. Call endpoint:
|
|
```bash
|
|
curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads" \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
### Integration Testing
|
|
|
|
```javascript
|
|
const request = require('supertest');
|
|
const app = require('./src/app');
|
|
|
|
describe('n8n Integration', () => {
|
|
it('should fetch Zoho leads', async () => {
|
|
const response = await request(app)
|
|
.get('/api/v1/n8n/zoho/crm/leads')
|
|
.set('Authorization', `Bearer ${token}`)
|
|
.expect(200);
|
|
|
|
expect(response.body.status).toBe('success');
|
|
expect(response.body.data.data).toBeInstanceOf(Array);
|
|
});
|
|
});
|
|
```
|
|
|
|
## 📊 Monitoring
|
|
|
|
All requests are logged with:
|
|
- User ID
|
|
- Provider
|
|
- Service
|
|
- Module
|
|
- Query parameters
|
|
- Execution time
|
|
- Errors
|
|
|
|
Check logs in your logging system.
|
|
|
|
## 🔒 Security
|
|
|
|
- ✅ JWT authentication required
|
|
- ✅ Tokens encrypted in database
|
|
- ✅ Rate limiting applied
|
|
- ✅ Module validation prevents unauthorized access
|
|
- ✅ No tokens in logs
|
|
|
|
## 📚 Documentation
|
|
|
|
- [`docs/N8N_INTEGRATION.md`](docs/N8N_INTEGRATION.md) - Complete integration guide
|
|
- [`docs/N8N_SETUP_EXAMPLE.md`](docs/N8N_SETUP_EXAMPLE.md) - Quick start examples
|
|
- [`docs/SALESFORCE_PAGINATION.md`](docs/SALESFORCE_PAGINATION.md) - Salesforce pagination guide
|
|
- [`src/integrations/n8n/README.md`](src/integrations/n8n/README.md) - Module documentation
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### "n8n workflow execution failed"
|
|
- Check if n8n is running
|
|
- Verify webhook URL in .env
|
|
- Check n8n logs
|
|
|
|
### "Authentication not found"
|
|
- User must authenticate via OAuth first
|
|
- Check if tokens are in database
|
|
|
|
### "Unsupported combination"
|
|
- Check `/api/v1/n8n/providers` for supported modules
|
|
- Verify spelling of provider/service/module
|
|
|
|
## 🎉 Success!
|
|
|
|
You now have a complete n8n integration that:
|
|
- ✅ Supports multiple providers (Zoho, Salesforce)
|
|
- ✅ Uses a single webhook endpoint
|
|
- ✅ Requires minimal backend code
|
|
- ✅ Is easy to extend with new providers
|
|
- ✅ Includes comprehensive documentation
|
|
- ✅ Has proper error handling
|
|
- ✅ Manages tokens automatically
|
|
|
|
## 📞 Next Steps
|
|
|
|
1. Import the n8n workflow
|
|
2. Test with Zoho CRM
|
|
3. Test with Salesforce
|
|
4. Add to your dashboard/UI
|
|
5. Monitor logs for issues
|
|
6. Add more providers as needed
|
|
|
|
Happy coding! 🚀
|
|
|