Zoho Integration¶

NeoCore integrates with Zoho CRM and Zoho Books for Customer 360 and General Ledger sync. Architecture follows the UST Global 3-layer integration pattern.

Access Status

Zoho trial access is pending from Manoj sir. Credentials and org ID will be updated here once provisioned.

Integration Architecture¶

graph TD
    subgraph NeoCore["NeoCore — Microservices"]
        CS["ms-customer\n:8082"]
        GL["ms-generalledger\n:8088"]
        DS["ms-deposit\n:8081"]
        TS["ms-transaction\n:8085"]
    end

    subgraph Gateway["Layer 1 — API Gateway / Event Bus"]
        GW["Spring Cloud Gateway\nKafka Topics"]
    end

    subgraph Adapter["Layer 2 — Zoho Adapter Service"]
        ZA["zoho-adapter\n(planned)"]
    end

    subgraph Zoho["Layer 3 — Zoho Cloud"]
        ZC["Zoho CRM\nCustomer 360"]
        ZB["Zoho Books\nGeneral Ledger"]
    end

    CS -->|customer-created\ncustomer-updated| GW
    GL -->|gl-posting-made| GW
    DS -->|deposit-created\ndeposit-closed| GW
    TS -->|transaction-created| GW

    GW -->|Kafka consumer| ZA
    ZA -->|REST API v2| ZC
    ZA -->|REST API v2| ZB

Layer 1 — Event Bus (Kafka Topics)¶

NeoCore services publish domain events to Kafka. The Zoho adapter subscribes and transforms them.

Kafka Topic	Source Service	Zoho Target	Event
`customer-created`	ms-customer	Zoho CRM	Create Contact / Account
`customer-updated`	ms-customer	Zoho CRM	Update Contact
`customer-deceased`	ms-customer	Zoho CRM	Mark Contact inactive
`deposit-created`	ms-deposit	Zoho CRM	Add Deposit Deal
`deposit-closed`	ms-deposit	Zoho CRM	Close Deal, update value
`gl-posting-made`	ms-generalledger	Zoho Books	Create Journal Entry
`transaction-created`	ms-transaction	Zoho Books	Create Bank Transaction

Layer 2 — Zoho Adapter Service¶

The adapter service (zoho-adapter) is planned. It will:

Consume Kafka topics listed above
Transform NeoCore payloads to Zoho API format
Authenticate via OAuth 2.0 (Zoho Identity Provider)
POST to Zoho REST API v2 with retry and dead-letter handling

Zoho OAuth 2.0 Flow¶

sequenceDiagram
    participant Adapter as zoho-adapter
    participant ZohoAuth as Zoho Identity
    participant ZohoCRM as Zoho CRM / Books

    Adapter->>ZohoAuth: POST /oauth/v2/token (client_credentials)
    ZohoAuth-->>Adapter: access_token (expires 1h)
    Adapter->>ZohoCRM: POST /crm/v2/Contacts (Authorization: Zoho-oauthtoken {token})
    ZohoCRM-->>Adapter: 201 Created / record id
    Note over Adapter: Token cached in Redis, refreshed proactively at 55 min

OAuth Config (environment variables)¶

ZOHO_CLIENT_ID=your-client-id
ZOHO_CLIENT_SECRET=your-client-secret
ZOHO_REFRESH_TOKEN=your-refresh-token
ZOHO_API_DOMAIN=https://www.zohoapis.in
ZOHO_ORG_ID=your-org-id

Layer 3 — Zoho CRM (Customer 360)¶

NeoCore Customer → Zoho CRM Contact¶

NeoCore Field	Zoho CRM Field	Notes
`custId`	`CF_NeoCore_Customer_ID` (custom field)	Unique reference back to NeoCore
`firstName + lastName`	`First_Name + Last_Name`	Split on space
`contact.mobileNumber`	`Mobile`
`contact.email`	`Email`
`address.permanentAddress`	`Mailing_Street + City + State + Zip`
`kyc.idType + idNumber`	`CF_ID_Type + CF_ID_Number`	Custom fields
`dateOfBirth`	`CF_Date_of_Birth`
`status`	`Lead_Status`	ACTIVE → Active, DECEASED → Inactive

Deposit Deal in Zoho CRM¶

When deposit-created is received, a Deal is created under the Contact:

NeoCore Field	Zoho CRM Deal Field
`depositNumber`	`Deal_Name`
`principalAmount`	`Amount`
`depositDate`	`Closing_Date`
`maturityDate`	`CF_Maturity_Date`
`interestRate`	`CF_Interest_Rate`
`productCode`	`CF_Product_Code`
`status`	`Stage` (ACTIVE → Proposal/Price Quote, CLOSED → Closed Won)

Layer 3 — Zoho Books (General Ledger)¶

GL Posting → Zoho Books Journal Entry¶

NeoCore Field	Zoho Books Field
`transactionRef`	`reference_number`
`valueDate`	`date`
`narration`	`notes`
`accountHeadCode` (debit)	`line_items[].account_id` (mapped via code lookup)
`accountHeadCode` (credit)	`line_items[].account_id`
`amount`	`line_items[].debit_or_credit + amount`

GL account head codes are mapped to Zoho Books account IDs via a configuration table in common_db.

Bank Transaction Sync¶

Cash and transfer transactions from ms-transaction are synced as Zoho Books bank transactions:

NeoCore	Zoho Books
`CREDIT` cash transaction	`deposit` bank transaction
`DEBIT` cash transaction	`withdrawal` bank transaction
`TRANSFER`	`transfer` bank transaction

Resources¶

Resource	Description
Zoho CRM REST API v2	`https://www.zoho.com/crm/developer/docs/api/v2/`
Zoho Books API	`https://www.zoho.com/books/api/v3/`
Zoho OAuth 2.0	`https://www.zoho.com/accounts/protocol/oauth.html`
UST Global Integration Spec	Internal document — request from Manoj sir
Zoho Developer Console	`https://api-console.zoho.in/`
NeoCore Kafka Topics	See Microservice Views
GL Account Head Reference	See Data Models

Rollout Plan¶

Phase	Scope	Status
Phase 1	Zoho trial access provisioning	⏳ Pending (from Manoj sir)
Phase 2	Customer 360 sync — `customer-created` topic	🔲 Planned
Phase 3	Deposit Deal sync — `deposit-created`, `deposit-closed`	🔲 Planned
Phase 4	GL Journal Entry sync — `gl-posting-made`	🔲 Planned
Phase 5	Bank Transaction sync — `transaction-created`	🔲 Planned
Phase 6	Bidirectional sync — Zoho → NeoCore webhook	🔲 Planned