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
```json
{
  "status": "success",
  "message": "...",
  "data": {
    "success": true,
    "data": [...],
    "count": 10,
    "metadata": {}
  },
  "timestamp": "2025-10-09T..."
}
```

### Salesforce Response
```json
{
  "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
```javascript
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
```javascript
const { data } = await axios.get(
  '/api/v1/n8n/zoho/crm/leads',
  { 
    params: { limit: 100 },
    headers: { Authorization: `Bearer ${token}` }
  }
);
```

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

## 🔧 Environment Variables

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

```bash
# 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