n8n Integration - Quick Start Example

Complete Example Flow

1. User Authentication (First Time)

Before using n8n integration, users must authenticate with the provider:

# Frontend redirects user to OAuth
# After OAuth success, frontend calls:

GET /api/v1/users/oauth/callback?
  authorization_code=ABC123&
  user_uuid=550e8400-e29b-41d4-a716-446655440000&
  service_name=zoho

This stores the access token and instance URL in the database.

2. Fetch Data via n8n

Now you can fetch data without worrying about tokens:

GET /api/v1/n8n/zoho/crm/leads?limit=100
Authorization: Bearer <jwt_token>

3. Behind the Scenes

Your Request
    ↓
Backend API (n8nController)
    ↓
N8nHandler (gets user's access token from DB)
    ↓
N8nClient (calls n8n webhook)
    ↓
n8n Workflow
    ├─ Provider Switch (zoho)
    ├─ Service Switch (crm)
    ├─ Module Switch (leads)
    └─ HTTP Request (calls Zoho API)
    ↓
Response back to your app

Real-World Example: Dashboard Integration

// In your frontend or service layer

const API_URL = 'http://localhost:3000/api/v1';
const token = localStorage.getItem('jwt_token');

// Fetch Zoho CRM Summary
async function getDashboardData() {
  try {
    // Fetch Leads
    const leadsRes = await fetch(
      `${API_URL}/n8n/zoho/crm/leads?limit=10`,
      { headers: { 'Authorization': `Bearer ${token}` }}
    );
    const leads = await leadsRes.json();

    // Fetch Contacts
    const contactsRes = await fetch(
      `${API_URL}/n8n/zoho/crm/contacts?limit=10`,
      { headers: { 'Authorization': `Bearer ${token}` }}
    );
    const contacts = await contactsRes.json();

    // Fetch Deals
    const dealsRes = await fetch(
      `${API_URL}/n8n/zoho/crm/deals?limit=10`,
      { headers: { 'Authorization': `Bearer ${token}` }}
    );
    const deals = await dealsRes.json();

    // Fetch Employees from Zoho People
    const employeesRes = await fetch(
      `${API_URL}/n8n/zoho/people/employees?limit=50`,
      { headers: { 'Authorization': `Bearer ${token}` }}
    );
    const employees = await employeesRes.json();

    // Fetch Salesforce Opportunities
    const opportunitiesRes = await fetch(
      `${API_URL}/n8n/salesforce/crm/opportunities?limit=20`,
      { headers: { 'Authorization': `Bearer ${token}` }}
    );
    const opportunities = await opportunitiesRes.json();

    return {
      leads: leads.data.data,
      contacts: contacts.data.data,
      deals: deals.data.data,
      employees: employees.data.data,
      opportunities: opportunities.data.data
    };
  } catch (error) {
    console.error('Dashboard data fetch failed:', error);
    throw error;
  }
}

// Use it
getDashboardData().then(data => {
  console.log('CRM Leads:', data.leads.length);
  console.log('Contacts:', data.contacts.length);
  console.log('Deals:', data.deals.length);
  console.log('Employees:', data.employees.length);
  console.log('SF Opportunities:', data.opportunities.length);
});

Testing with Postman

Collection Structure

Centralized Reporting API
├─ Auth
│  ├─ Login
│  └─ Register
├─ OAuth
│  └─ Callback (Zoho)
│  └─ Callback (Salesforce)
└─ n8n Integration
   ├─ Get Supported Providers
   ├─ Zoho CRM
   │  ├─ Get Leads
   │  ├─ Get Contacts
   │  ├─ Get Accounts
   │  └─ Get Deals
   ├─ Zoho Books
   │  ├─ Get Invoices
   │  └─ Get Customers
   ├─ Zoho People
   │  └─ Get Employees
   └─ Salesforce CRM
      ├─ Get Leads
      ├─ Get Accounts
      └─ Get Opportunities

Postman Request Example

GET Zoho CRM Leads

URL: http://localhost:3000/api/v1/n8n/zoho/crm/leads
Method: GET
Headers:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Params:
  limit: 100
  page: 1

Expected Response:

{
  "status": "success",
  "message": "Zoho crm leads data fetched successfully",
  "data": {
    "success": true,
    "data": [
      {
        "id": "4876876000001234567",
        "First_Name": "John",
        "Last_Name": "Doe",
        "Email": "john@example.com",
        "Company": "Acme Corp",
        "Lead_Status": "Qualified"
      }
    ],
    "count": 1,
    "metadata": {}
  },
  "timestamp": "2025-10-09T12:00:00.000Z"
}

Environment Setup Checklist

n8n instance running
Workflow imported and activated

Environment variables set:

N8N_WEBHOOK_URL=http://localhost:5678
N8N_WEBHOOK_ID=04e677f5-ec57-4772-bf12-96f2610d4b9c

OAuth credentials configured for providers
Database migration run
Backend server running
User authenticated with provider(s)

Next Steps

Test with a single provider (e.g., Zoho CRM)
Verify data is returned correctly
Add error handling in your frontend
Implement caching if needed
Add more providers as needed
Monitor n8n workflow execution logs

4.9 KiB Raw Permalink Blame History