// Zoho CRM scopes
ZohoCRM.modules.ALL           // Read/write all CRM modules
ZohoCRM.modules.leads.ALL     // Leads module specifically
ZohoCRM.settings.ALL          // Workflow rules, fields, layouts

// Zoho Books scopes
ZohoBooks.invoices.ALL        // Full invoice access
ZohoBooks.contacts.CREATE     // Create contacts only
ZohoBooks.salesorders.READ    // Read sales orders only

// Combined scope string for the Self Client form:
ZohoCRM.modules.ALL,ZohoBooks.invoices.ALL,ZohoBooks.contacts.CREATE

curl -X POST "https://accounts.zoho.com/oauth/v2/token" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://www.example.com/callback" \
  -d "code=YOUR_GRANT_CODE"

// Response:
{
  "access_token":  "1000.41d9xxxxxxxxxxxxxxxxxxxxxxxx",
  "refresh_token": "1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",  // STORE THIS
  "token_type":    "Bearer",
  "expires_in":    3600   // 1 hour
}

import requests, time

class ZohoTokenManager:
    def __init__(self, client_id, client_secret, refresh_token):
        self.client_id = client_id
        self.client_secret = client_secret
        self.refresh_token = refresh_token
        self.access_token = None
        self.expires_at = 0

    def get_token(self):
        # Refresh 5 minutes before expiry
        if time.time() < self.expires_at - 300:
            return self.access_token

        r = requests.post("https://accounts.zoho.com/oauth/v2/token", data={
            "grant_type":    "refresh_token",
            "client_id":     self.client_id,
            "client_secret": self.client_secret,
            "refresh_token": self.refresh_token,
        })
        data = r.json()
        self.access_token = data["access_token"]
        self.expires_at = time.time() + data["expires_in"]
        return self.access_token

// POST to: https://www.zohoapis.com/crm/v8/coql
// Header: Authorization: Zoho-oauthtoken {token}
// Header: Content-Type: application/json

{
  "select_query": "SELECT id, Deal_Name, Account_Name, Amount,
    Stage, Closing_Date, Owner.name, Lead_Source
    FROM Deals
    WHERE Stage = 'Proposal Sent'
    AND Closing_Date <= '2026-12-31'
    AND Amount >= 5000
    ORDER BY Closing_Date ASC
    LIMIT 200 OFFSET 0"
}

// Response shape:
{
  "data": [
    {
      "id": "5000000034523",
      "Deal_Name": "Acme Corp — Q4 Implementation",
      "Amount": 24500,
      "Stage": "Proposal Sent",
      "Closing_Date": "2026-11-30"
    }
  ],
  "info": { "count": 47, "more_records": false }
}

// Canada (accounts registered at ca.zoho.com)
BASE_URL = "https://www.zohoapis.ca/books/v3"

// United States
BASE_URL = "https://www.zohoapis.com/books/v3"

// European Union
BASE_URL = "https://www.zohoapis.eu/books/v3"

// ALL requests require organization_id as a query parameter:
GET "https://www.zohoapis.ca/books/v3/invoices?organization_id=YOUR_ORG_ID"
// Omitting organization_id returns a confusing generic error, not a 401

const axios = require('axios');

async function createInvoice(accessToken, orgId, dealData) {
  const payload = {
    customer_id: dealData.zohoContactId,
    reference_number: dealData.crmDealId,  // idempotency key
    date: new Date().toISOString().split('T')[0],
    due_date: dealData.paymentTermsDate,
    currency_code: 'CAD',
    is_inclusive_tax: false,
    line_items: dealData.lineItems.map(item => ({
      item_id: item.zohoItemId,
      quantity: item.qty,
      rate: item.unitPrice,
      tax_id: item.provinceHSTTaxId  // Ontario HST = 13%
    }))
  };

  const response = await axios.post(
    `https://www.zohoapis.ca/books/v3/invoices?organization_id=${orgId}`,
    payload,
    { headers: {
        'Authorization': `Zoho-oauthtoken ${accessToken}`,
        'Content-Type': 'application/json'
    }}
  );

  return response.data.invoice.invoice_id;
}

// Trigger: Deal stage changes to "Closed Won" in Zoho CRM
// ───────────────────────────────────────────────────────

Zoho CRM Notification API
    ↓  (webhook POST to your endpoint)
Your Integration Server
    ↓  Step 1: Validate the event (field_name == "Stage", new_value == "Closed Won")
    ↓  Step 2: GET full deal record from CRM API (line items, contact ID, amount)
    ↓  Step 3: Check if Books contact exists (GET /books/v3/contacts?email=...)
    ↓  Step 4: Create Books contact if not found (POST /books/v3/contacts)
    ↓  Step 5: Create Books invoice with CRM deal ID as reference_number (idempotency)
    ↓  Step 6: Write Books invoice_id back to CRM deal custom field
Zoho Books
    ↓  Invoice created — visible in Books and linked back to the CRM deal
Zoho CRM Deal Record
    →  Custom field "Books Invoice #" now shows the invoice ID + status

import requests

def sync_won_deal_to_invoice(crm_token, books_token, org_id, deal_id):
    # Step 1: Get full deal from CRM
    deal_resp = requests.get(
        f"https://www.zohoapis.ca/crm/v8/Deals/{deal_id}",
        headers={"Authorization": f"Zoho-oauthtoken {crm_token}"}
    )
    deal = deal_resp.json()["data"][0]

    # Step 2: Find or create Books contact by CRM contact email
    contact_email = deal["Contact_Name"]["email"]
    contact_search = requests.get(
        f"https://www.zohoapis.ca/books/v3/contacts",
        params={"organization_id": org_id, "email": contact_email},
        headers={"Authorization": f"Zoho-oauthtoken {books_token}"}
    )
    contacts = contact_search.json().get("contacts", [])
    books_contact_id = contacts[0]["contact_id"] if contacts else create_books_contact(deal)

    # Step 3: Create invoice (deal_id as reference = idempotency key)
    invoice_payload = {
        "customer_id": books_contact_id,
        "reference_number": deal_id,   # CRITICAL: prevents duplicate invoices
        "currency_code": "CAD",
        "line_items": [{
            "description": deal["Deal_Name"],
            "quantity": 1,
            "rate": deal["Amount"],
        }]
    }
    inv_resp = requests.post(
        f"https://www.zohoapis.ca/books/v3/invoices?organization_id={org_id}",
        json=invoice_payload,
        headers={"Authorization": f"Zoho-oauthtoken {books_token}"}
    )
    invoice_id = inv_resp.json()["invoice"]["invoice_id"]

    # Step 4: Write invoice ID back to CRM deal custom field
    requests.put(
        f"https://www.zohoapis.ca/crm/v8/Deals",
        json={"data": [{"id": deal_id, "Books_Invoice_ID": invoice_id}]},
        headers={"Authorization": f"Zoho-oauthtoken {crm_token}"}
    )
    return invoice_id

// POST https://www.zohoapis.com/crm/v8/actions/watch
// Subscribe to Deals module — only fire when Stage field changes

{
  "watch": [{
    "channel_id": "1000000068001",        // Your identifier
    "events": ["Deals.edit"],          // edit = updates only
    "token": "YOUR_VERIFICATION_TOKEN", // Included in every webhook POST
    "notify_url": "https://your-server.ca/webhooks/crm",
    "channel_expiry": "2027-01-01T00:00:00+05:30", // REQUIRED — no permanent subs
    "resource_uri": "https://www.zohoapis.com/crm/v8/Deals",
    "fields": ["Stage"]  // V6+ field-specific filtering
  }]
}

{
  "query_params": {
    "token": "YOUR_VERIFICATION_TOKEN"
  },
  "module": "Deals",
  "ids": ["5000000034523"],
  "operation": "edit",
  "channel_id": "1000000068001",
  "fields_modified": {
    "Stage": {
      "old_value": "Proposal Sent",
      "new_value": "Closed Won"
    }
  }
}

// Run this weekly via cron — renew subscriptions 7 days before expiry
async function renewNotificationSubscription(token, channelId) {
  const newExpiry = new Date();
  newExpiry.setFullYear(newExpiry.getFullYear() + 1);

  await fetch('https://www.zohoapis.ca/crm/v8/actions/watch', {
    method: 'PATCH',
    headers: {
      'Authorization': `Zoho-oauthtoken ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ watch: [{
      channel_id: channelId,
      channel_expiry: newExpiry.toISOString()
    }]})
  });
}