Zoho Integration

🎯 Overview

Zoho CRM integration enables DashClicks users to export their CRM data including contacts, accounts, deals, and notes from Zoho CRM. This integration uses OAuth 2.0 for authentication with automatic token refresh to maintain persistent connections to Zoho's API.

Provider: Zoho Corporation (https://www.zoho.com/crm/)
API Version: v2
Integration Type: REST API with OAuth 2.0

📁 Directory Structure

Documentation Structure:

zoho/
├── 📄 index.md - Integration overview and setup
├── 📄 authentication.md - OAuth 2.0 flow and token management
└── 📄 crm-data.md - CRM data export (contacts, accounts, deals, notes)

Source Code Location:

• Base Path: external/Integrations/Zoho/
• Providers: Providers/auth/, Providers/crmData/
• Controllers: Controller/authController/, Controller/contactController/
• Routes: Routes/authRoutes/, Routes/contactRoutes/
• Model: Model/authModel/

🗄️ MongoDB Collections

📚 Detailed Schema: See Database Collections Documentation

integrations.zoho.key

• Purpose: Store Zoho OAuth tokens and API credentials
• Model: shared/models/zoho-key.js
• Primary Use: Store OAuth access tokens, refresh tokens, and API domain information per user

Document Structure:

{
  "_id": ObjectId,
  "token": {
    "access_token": "1000.xxx...",
    "refresh_token": "1000.xxx...",
    "api_domain": "https://www.zohoapis.in",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "account_id": "12345",
  "owner": "user_Lwh9EzeD8",
  "token_invalidated": false // Set to true when token becomes invalid
}

🔐 Authentication & Configuration

Authentication Method: OAuth 2.0 Authorization Code Flow

Required Environment Variables:

Variable	Description	Required
ACCOUNT_DATA_CENTER	Zoho accounts base URL	✅
ZOHO_CLIENT_ID	OAuth client ID	✅
ZOHO_CLIENT_SECRET	OAuth client secret	✅
ZOHO_REDIRECT_URL	OAuth callback URL	✅
ZOHO_SCOPE_PERMISSIONS	OAuth scopes (ZohoCRM.modules.ALL)	✅
ZOHO_AUTHORIZE_URL	Authorization endpoint	✅
ZOHO_RESPONSE_TYPE	OAuth response type (code)	✅
ZOHO_ACCESS_TOKEN_URL	Token exchange endpoint	✅
ZOHO_GRANT_TYPE	OAuth grant type (authorization_code)	✅
APP_SECRET	JWT secret for state token encryption	✅

Example Configuration (.env):

ACCOUNT_DATA_CENTER=https://accounts.zoho.com/
ZOHO_CLIENT_ID=1000.K74YDUPOSYBG00J5S912EQY5COSY1V
ZOHO_CLIENT_SECRET=e03827dcd291de64b181cdba72e02fbbb48a721a5d
ZOHO_REDIRECT_URL=http://localhost:5000/v1/integrations/zoho/auth/callback
ZOHO_SCOPE_PERMISSIONS=ZohoCRM.modules.ALL
ZOHO_AUTHORIZE_URL=https://accounts.zoho.in/oauth/v2/auth
ZOHO_RESPONSE_TYPE=code
ZOHO_ACCESS_TOKEN_URL=https://accounts.zoho.in/oauth/v2/token
ZOHO_GRANT_TYPE=authorization_code

Credential Storage: OAuth tokens stored in integrations.zoho.key collection with automatic token invalidation detection.

🏗️ Architecture Overview

Key Responsibilities:

• OAuth 2.0 authentication and token management
• CRM data export (contacts, accounts, deals, notes)
• Automatic token refresh on API calls
• Token invalidation detection and cleanup

API Communication Pattern:

• REST API with Bearer token authentication
• Synchronous request/response model
• Automatic token refresh using stored refresh tokens
• Cursor-based pagination for large datasets

Rate Limiting:

• Zoho enforces API rate limits per organization
• Default limits: 100 API calls per minute
• Rate limit information available in response headers

🔗 Features & Capabilities

Core Features

• 📘 Authentication - OAuth 2.0 flow with JWT state management
• 📗 CRM Data Export - Export contacts, accounts, deals, and notes with pagination

🔄 Integration Data Flow

OAuth Authentication Flow:

sequenceDiagram
    participant Client as DashClicks Frontend
    participant DC as Dashboard Gateway
    participant Zoho as Zoho Service
    participant ZohoDB as MongoDB (zoho-key)
    participant ZohoAPI as Zoho CRM API

    Client->>DC: GET /v1/e/zoho/auth?forward_url=...
    DC->>Zoho: Check existing token
    Zoho->>ZohoDB: Find token by account_id & owner

    alt Token exists and valid
        ZohoDB-->>Zoho: Return token
        Zoho-->>Client: Redirect with token ID
    else No token or invalidated
        Zoho->>Zoho: Create JWT state token
        Zoho-->>Client: Redirect to Zoho OAuth
        Client->>ZohoAPI: User authorizes
        ZohoAPI-->>Zoho: Callback with code
        Zoho->>ZohoAPI: Exchange code for tokens
        ZohoAPI-->>Zoho: Access + refresh tokens
        Zoho->>ZohoDB: Save tokens
        Zoho-->>Client: Redirect with token ID
    end

CRM Data Export Flow:

sequenceDiagram
    participant Client as API Consumer
    participant Zoho as Zoho Service
    participant ZohoDB as MongoDB (zoho-key)
    participant ZohoAPI as Zoho CRM API

    Client->>Zoho: GET /v1/e/zoho/export/:type
    Zoho->>ZohoDB: Fetch stored token
    ZohoDB-->>Zoho: Return token with refresh_token
    Zoho->>ZohoAPI: Exchange refresh token
    ZohoAPI-->>Zoho: New access token
    Zoho->>ZohoAPI: GET /crm/v2/{type}
    ZohoAPI-->>Zoho: CRM data + pagination info
    Zoho->>Zoho: Format response
    Zoho-->>Client: Return data with pagination

🔗 API Endpoints

Authentication Endpoints

Endpoint	Method	Description
/v1/e/zoho/auth	GET	Initiate OAuth flow
/v1/e/zoho/auth/callback	GET	OAuth callback handler
/v1/e/zoho/auth	DELETE	Delete stored access token

Data Export Endpoints

Endpoint	Method	Description	Query Parameters
/v1/e/zoho/export/contacts	GET	Export contacts	page, limit
/v1/e/zoho/export/accounts	GET	Export accounts	page, limit
/v1/e/zoho/export/deals	GET	Export deals	page, limit
/v1/e/zoho/export/notes	GET	Export notes	page, limit

🚨 Error Handling

Common Error Scenarios:

1. Invalid Token (INVALID_TOKEN):

   • Automatically sets token_invalidated: true in database
   • Returns error message: TOKEN_INVALIDATED
   • User must re-authenticate via OAuth flow

2. Missing Credentials:

   • Returns 404 when no token found for user
   • Message: "Access Token is not Found"

3. Invalid Export Type:

   • Returns 404 when type parameter is not recognized
   • Valid types: contacts, accounts, deals, notes

4. OAuth Callback Errors:

   • Redirects to forward_url with error status
   • Includes reason parameter with error message

Error Response Format:

{
  "success": false,
  "errno": 400,
  "message": "Error description",
  "additional_info": {} // Provider-specific error details
}

📊 Monitoring & Logging

Token Invalidation Handling:

• Automatic detection of INVALID_TOKEN errors from Zoho API
• Updates all tokens for account with token_invalidated: true
• Logs errors with initiator: external/zoho

Error Logging:

• All database update errors logged with context
• Integration errors include account_id and error details

🔗 Related Documentation

• Provider API Docs: Zoho CRM API Documentation
• OAuth 2.0 Guide: Zoho OAuth Documentation
• Authentication Setup: ./authentication.md
• CRM Data Export: ./crm-data.md

---

⚠️ Important Notes

• 🔐 OAuth Tokens: Access tokens expire after 1 hour; refresh tokens used for automatic renewal
• 🌍 API Domain: Zoho API domain varies by data center (.com, .in, .eu, etc.)
• 🔄 Token Refresh: Every API call automatically refreshes the access token using refresh token
• 📊 Pagination: Zoho uses page-based pagination with configurable per_page limit
• 🚨 Token Invalidation: When tokens are invalidated, users must re-authenticate via OAuth
• 🔒 Scopes: Integration requires ZohoCRM.modules.ALL scope for full CRM access