Centralized_Reporting_Backend/docs/N8N_INTEGRATION.md

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:

# 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

GET /api/v1/n8n/providers

Response:

{
  "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)

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:

# 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

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

Examples:

# 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

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

Examples:

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:

{
  "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

{
  "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:

{
  "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

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

# 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):

   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