Centralized_Reporting_Backend/docs/N8N_QUICK_REFERENCE.md

🚀 n8n Integration - Quick Reference Card

📡 API Endpoints

Get Supported Modules

GET /api/v1/n8n/providers

Fetch Any Provider Data

GET /api/v1/n8n/data/{provider}/{service}/{module}

Zoho Shortcuts

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
GET /api/v1/n8n/zoho/books/invoices
GET /api/v1/n8n/zoho/people/employees
GET /api/v1/n8n/zoho/projects/projects

Salesforce Shortcuts

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

🔑 Query Parameters

Parameter	Type	Default	Max	Description
limit	number	200	1000	Records per page
page	number	1	-	Page number (Zoho)
offset	number	0	-	Offset (Salesforce - deprecated)
nextRecordsUrl	string	null	-	Next page URL (Salesforce pagination)

Salesforce Pagination

Salesforce uses nextRecordsUrl for pagination. See docs/SALESFORCE_PAGINATION.md for details.

📋 Response Format

Zoho Response

{
  "status": "success",
  "message": "...",
  "data": {
    "success": true,
    "data": [...],
    "count": 10,
    "metadata": {}
  },
  "timestamp": "2025-10-09T..."
}

Salesforce Response

{
  "status": "success",
  "message": "...",
  "data": {
    "success": true,
    "data": [...],
    "count": 200,
    "metadata": {
      "totalSize": 7530,
      "done": false,
      "nextRecordsUrl": "/services/data/v61.0/query/..."
    }
  },
  "timestamp": "2025-10-09T..."
}

🎯 Supported Modules

Zoho CRM (8)

leads, contacts, accounts, deals, tasks, invoices, purchase_orders, sales_orders

Zoho Books (10)

organizations, contacts, customers, vendors, accounts, invoices, bills, expenses, purchase_orders, sales_orders

Zoho People (11)

employees, departments, timesheets, leaves, attendence, attendence_entries, attendence_report, leave_tracker, leaves_data, goals_data, performance_data

Zoho Projects (8)

portals, projects, tasks, all_tasks, tasklists, all_tasklists, issues, phases

Salesforce CRM (6)

leads, accounts, tasks, opportunities, events, reports

💻 Code Snippets

JavaScript/Fetch

const response = await fetch(
  'http://localhost:3000/api/v1/n8n/zoho/crm/leads?limit=100',
  { headers: { 'Authorization': `Bearer ${token}` }}
);
const data = await response.json();

Axios

const { data } = await axios.get(
  '/api/v1/n8n/zoho/crm/leads',
  { 
    params: { limit: 100 },
    headers: { Authorization: `Bearer ${token}` }
  }
);

cURL

curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads?limit=100" \
  -H "Authorization: Bearer $TOKEN"

🔧 Environment Variables

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

🐛 Common Errors

Error	Cause	Solution
n8n workflow execution failed	n8n offline	Start n8n
Authentication not found	No OAuth token	Authenticate user
Unsupported combination	Invalid module	Check /providers
Timeout	Slow API	Reduce limit

📊 Status Codes

Code	Meaning
200	Success
400	Validation error / Unsupported module
401	Unauthorized (invalid JWT)
404	Route not found
500	Server error

⚡ Performance Tips

1. Use pagination for large datasets
2. Cache responses in Redis
3. Parallel requests with Promise.all()
4. Reduce limit if timeout occurs
5. Monitor n8n workflow logs

🔐 Security Checklist

• JWT token in Authorization header
• Tokens encrypted in database
• Rate limiting enabled
• HTTPS in production
• Input validation active

🎯 Quick Test

# 1. Login
curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'

# 2. Save token from response
TOKEN="eyJhbGc..."

# 3. Test endpoint
curl -X GET "http://localhost:3000/api/v1/n8n/zoho/crm/leads?limit=10" \
  -H "Authorization: Bearer $TOKEN"

📚 Documentation Links

• Full Guide: docs/N8N_INTEGRATION.md
• Examples: docs/N8N_SETUP_EXAMPLE.md
• Summary: docs/N8N_IMPLEMENTATION_SUMMARY.md
• Module Docs: src/integrations/n8n/README.md

🆘 Troubleshooting Steps

1. Check n8n is running: http://localhost:5678
2. Verify workflow is activated
3. Check user has OAuth tokens: Query user_auth_tokens table
4. Test n8n webhook directly with Postman
5. Check backend logs for errors
6. Verify environment variables
7. Check provider API status

✅ Pre-Deployment Checklist

• n8n workflow imported & activated
• Environment variables set
• Database migration run
• OAuth credentials configured
• Test with real user account
• Error handling tested
• Rate limiting verified
• Logs configured
• Documentation reviewed
• Team trained on endpoints

---

Last Updated: October 9, 2025
Version: 1.0.0