Centralized_Reporting_Backend/docs/N8N_SETUP_EXAMPLE.md

# n8n Integration - Quick Start Example

## Complete Example Flow

### 1. User Authentication (First Time)

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

```http
# 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:

```http
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

```javascript
// 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:
```json
{
  "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:
  ```env
  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

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