zoho-crm-development

name	zoho-crm-development
description	Build and work with Zoho CRM integration features, including module CRUD operations, Eloquent model sync, OAuth authentication, webhooks, and search. Use when this capability is needed.
metadata	{"author":"asciisd"}

Zoho CRM Development

When to use this skill

Use this skill when:

• Creating, reading, updating, or deleting Zoho CRM records
• Setting up Eloquent model sync with Zoho CRM modules
• Configuring OAuth authentication for Zoho CRM
• Handling Zoho CRM webhooks
• Searching or querying Zoho CRM data
• Working with related records across Zoho CRM modules
• Performing bulk operations on Zoho CRM records

Package Structure

Asciisd\Zoho\
├── Facades\Zoho              # Facade for ZohoClient
├── ZohoClient                # Factory for module instances
├── Models\
│   ├── ZohoModel             # Abstract base — all CRUD/search/upsert methods
│   ├── ZohoContact           # Contacts module
│   ├── ZohoAccount           # Accounts module
│   ├── ZohoLead              # Leads module
│   ├── ZohoDeal              # Deals module
│   ├── ZohoTask              # Tasks module
│   ├── ZohoEvent             # Events module
│   ├── ZohoCall              # Calls module
│   ├── ZohoNote              # Notes module
│   ├── ZohoProduct           # Products module
│   ├── ZohoInvoice           # Invoices module
│   ├── ZohoOAuthToken        # Eloquent model for stored tokens
│   └── ZohoSync              # Polymorphic sync tracking model
├── Auth\OAuthManager          # OAuth flow and token lifecycle
├── Storage\TokenStorage       # Token persistence (cache/database)
├── Traits\SyncsWithZoho       # Auto-sync Eloquent models to Zoho
├── Jobs\SyncModelToZoho       # Queued sync job
├── Events\                    # Webhook events
├── Exceptions\                # Typed exceptions
└── Http\Controllers\ZohoWebhookController

Accessing Modules

Always use the Zoho facade to access CRM modules:

use Asciisd\Zoho\Facades\Zoho;

$contacts = Zoho::contacts();
$leads    = Zoho::leads();
$deals    = Zoho::deals();
$accounts = Zoho::accounts();
$tasks    = Zoho::tasks();
$events   = Zoho::events();
$calls    = Zoho::calls();
$notes    = Zoho::notes();
$products = Zoho::products();
$invoices = Zoho::invoices();

You can also use module classes directly:

use Asciisd\Zoho\Models\ZohoContact;

$contact = ZohoContact::find('record_id');

CRUD Operations

Every module model inherits these static methods from ZohoModel:

// Create a record
$result = Zoho::contacts()->create([
    'First_Name' => 'Jane',
    'Last_Name'  => 'Doe',
    'Email'      => '[e-mail]',
    'Phone'      => '[phone]',
]);

// Find a record by ID
$contact = Zoho::contacts()->find('5344xxxxxxxxxxxx');

// Get all records (paginated)
$contacts = Zoho::contacts()->all();
$contacts = Zoho::contacts()->all(['per_page' => 50]);

// Update a record
$result = Zoho::contacts()->update('5344xxxxxxxxxxxx', [
    'Phone' => '+0987654321',
]);

// Delete a record
$deleted = Zoho::contacts()->delete('5344xxxxxxxxxxxx');

// Clone a record (copies all non-system fields)
$clone = Zoho::contacts()->();


 = ::()->();

Module-Specific Behavior

Calls — Call_Duration normalization

ZohoCall overrides create, update, upsert, and updateMultiple to normalize Call_Duration before sending. Zoho's Calls API expects "mm:ss" (minutes:seconds), but the package accepts:

• Bare numbers as minutes — 30 or "30" → "30:00", 90 → "90:00", 125 → "125:00"
• "HH:mm:ss" strings — converted to total minutes:seconds → "01:02:05" becomes "62:05"
• "mm:ss" strings — normalized with zero-padding → "5:30" becomes "05:30"
• null, empty string, or non-numeric input — passed through unchanged

// Logging a 30-minute call against a Lead
Zoho::calls()->create([
    'Subject'       => 'Discovery call',
    'Call_Type'     => 'Outbound',
    'Call_Duration' => 30,                 // sent as "30:00"
    'What_Id'       => $leadId,            // What_Id for Leads, Accounts, Deals
    '$se_module'    => 'Leads',
]);

// Logging a call against a Contact (Who_Id, no $se_module needed)
Zoho::calls()->create([
    'Subject'       => 'Follow-up call',
    'Call_Type'     => 'Outbound',
    'Call_Duration' => 15,                 // sent as "15:00"
    'Who_Id'        => $contactId,         // Who_Id is for Contacts only
]);

Who_Id vs What_Id: Use Who_Id only for Contacts (the person). For Leads, Accounts, Deals, and other modules, use What_Id with $se_module set to the module API name.

Other modules pass payloads through unchanged — only Calls has this transformation.

Search Operations

// Search with Zoho criteria syntax
$results = Zoho::contacts()->search('(Last_Name:equals:Doe)');
$results = Zoho::leads()->search('(Company:starts_with:Acme)');

// Convenience search methods
$results = Zoho::contacts()->searchByEmail('[e-mail]');
$results = Zoho::contacts()->searchByPhone('[phone]');

Search criteria syntax follows Zoho CRM conventions: (Field_Name:operator:value). Supported operators include equals, starts_with, contains, greater_than, less_than, between, etc.

Upsert (Create or Update)

$result = Zoho::contacts()->upsert(
    [
        'Email'     => '[e-mail]',
        'Last_Name' => 'Doe',
        'Phone'     => '[phone]',
    ],
    ['Email'] // duplicate check fields
);

Bulk Operations

// Update multiple records
$results = Zoho::contacts()->updateMultiple([
    ['id' => '111', 'Phone' => '[phone]'],
    ['id' => '222', 'Phone' => '[phone]'],
]);

// Delete multiple records
$results = Zoho::contacts()->deleteMultiple(['111', '222', '333']);

Related Records

// Get deals related to a contact
$deals = Zoho::contacts()->getRelatedRecords('contact_id', 'Deals');

// Get notes related to an account
$notes = Zoho::accounts()->getRelatedRecords('account_id', 'Notes');

Lead Conversion

$result = Zoho::leads()->convert('lead_id', [
    'overwrite' => true,
    'notify_lead_owner' => true,
]);

Field Metadata

// Get all fields for a module
$fields = Zoho::contacts()->getFieldMetadata();

// Clear cached field names
Zoho::contacts()->clearFieldCache();
ZohoModel::clearAllFieldCache();

Eloquent Model Sync

The SyncsWithZoho trait auto-syncs Eloquent models to Zoho CRM via queued jobs on create, update, and delete.

Required implementation

use Asciisd\Zoho\Traits\SyncsWithZoho;

class Customer extends Model
{
    use SyncsWithZoho;

    protected $fillable = ['name', 'email', 'phone', 'company'];

    // Required: specify which Zoho CRM module this model maps to
    public function getZohoModule(): string
    {
        return 'Contacts';
    }

    // Optional: map model attributes to Zoho field API names
    public function getZohoFieldMapping(): array
    {
        return [
            'name'    => 'Last_Name',
            'email'   => 'Email',
            'phone'   => 'Phone',
            'company' => 'Company',
        ];
    }

    // Optional: conditionally sync (defaults to true)
    protected function shouldSyncToZoho(): bool
    {
        return $this->is_active && !empty(->email);
    }

    
     {
         [, , ];
    }
}

Custom module support

For custom Zoho modules (or modules whose API names don't follow the standard naming convention like Contacts -> ZohoContact), the SyncModelToZoho job resolves the ZohoModel class using a 3-step chain:

1. Model method — override getZohoModelClass() on the Eloquent model to return a specific class
2. Config map — add an entry in zoho.modules mapping the module API name to a class
3. Naming convention — falls back to Zoho + singular module name

// Option 1: Override getZohoModelClass() on the Eloquent model
class Property extends Model
{
    use SyncsWithZoho;

    public function getZohoModule(): string { return 'Property_Listings'; }

    public function getZohoModelClass(): ?string
    {
        return \App\Zoho\ZohoPropertyListing::class;
    }

    public function getZohoFieldMapping(): array
    {
        return ['address' => 'Listing_Address', 'price' => 'Asking_Price'];
    }
}

// Option 2: Config map in config/zoho.php (no model changes needed)
'modules' => [
    'Property_Listings' => \App\Zoho\ZohoPropertyListing::class,
],

The custom ZohoModel class extends ZohoModel and sets MODULE_API_NAME:

use Asciisd\Zoho\Models\ZohoModel;

class ZohoPropertyListing extends ZohoModel
{
    protected const MODULE_API_NAME = 'Property_Listings';
}

Multi-model sync

Multiple Eloquent models can sync to the same Zoho module. The polymorphic ZohoSync model (zohoable_type + zohoable_id) keeps each model's sync records independent — different field mappings, separate Zoho record IDs, no collisions.

// Both User and DemoAccount sync to Leads — each gets its own Zoho record
class User extends Model
{
    use SyncsWithZoho;

    public function getZohoModule(): string { return 'Leads'; }

    public function getZohoFieldMapping(): array
    {
        return ['name' => 'Last_Name', 'email' => 'Email'];
    }
}

class DemoAccount extends Model
{
    use SyncsWithZoho;

    public function getZohoModule(): string { return 'Leads'; }

    public function getZohoFieldMapping(): array
    {
        return ['company_name' => 'Company', 'contact_email' => 'Email'];
    }
}

Key details:

• Each model instance creates a separate record in Zoho (1 User + 1 DemoAccount = 2 Leads)
• withoutZohoSync is per-class — User::withoutZohoSync(...) does not affect DemoAccount
• To converge multiple models on one Zoho record, customize SyncModelToZoho to use upsert with a duplicate check field (e.g. Email)

Sync helpers

// Get the Zoho record ID linked to this model
$zohoId = $customer->getZohoRecordId();

// Access the ZohoSync relationship
$sync = $customer->zohoSync;

// Sync immediately (bypasses queue)
$customer->syncToZohoNow('create');

// Disable sync temporarily
Customer::withoutZohoSync(function () {
    Customer::create([...]);  // will NOT trigger Zoho sync
});

Sync tracking

The zoho_syncs table stores polymorphic relationships between Eloquent models and Zoho records. The ZohoSync model provides scopes:

use Asciisd\Zoho\Models\ZohoSync;

ZohoSync::forModule('Contacts')->get();
ZohoSync::withZohoRecordId('5344xxxx')->first();
ZohoSync::synced()->get();
ZohoSync::notSynced()->get();

Webhook Handling

Routes are registered automatically:

• POST /zoho/webhook — receives webhooks
• GET /zoho/webhook — verification endpoint
• GET /zoho/callback — OAuth callback

Listening to events

// In EventServiceProvider or a listener
use Asciisd\Zoho\Events\ZohoWebhookReceived;
use Asciisd\Zoho\Events\ZohoRecordCreated;
use Asciisd\Zoho\Events\ZohoRecordUpdated;
use Asciisd\Zoho\Events\ZohoRecordDeleted;

// Generic webhook event
Event::listen(ZohoWebhookReceived::class, function ($event) {
    $payload = $event->payload;
    $module  = $event->module;
    $type    = $event->event;
    $data    = $event->getData();
});

// Specific CRUD events
Event::listen(ZohoRecordCreated::class, function ($event) {
    $record   = $event->record;
    $module   = $event->module;
    $recordId = $event->getRecordId();
});

Set ZOHO_WEBHOOK_SECRET to enable HMAC-SHA256 signature verification.

OAuth Authentication

Initial setup

php artisan zoho:setup

Managing tokens

php artisan zoho:auth status     # Check auth status
php artisan zoho:auth url        # Get authorization URL
php artisan zoho:auth refresh    # Refresh access token
php artisan zoho:auth revoke     # Revoke token

php artisan zoho:token:refresh   # Refresh with optional --clear-cache

Programmatic access

$oauth = app('zoho.oauth');

$url    = $oauth->getAuthorizationUrl();
$tokens = $oauth->generateAccessToken($grantCode);
$token  = $oauth->getValidAccessToken();
$oauth->refreshAccessToken();
$oauth->revokeToken();
$oauth->isAuthenticated();

Configuration

Publish the config with:

php artisan vendor:publish --tag=zoho-config

Key settings in config/zoho.php:

Key	Env Variable	Default	Purpose
client_id	ZOHO_CLIENT_ID	—	OAuth client ID
client_secret	ZOHO_CLIENT_SECRET	—	OAuth client secret
redirect_uri	ZOHO_REDIRECT_URI	—	OAuth redirect URI
data_center	ZOHO_DATA_CENTER	US	Data center region
environment	ZOHO_ENVIRONMENT	production	production/sandbox/developer
token_storage	ZOHO_TOKEN_STORAGE	both	cache/database/both
modules	—	[]	Module-to-class map for custom modules
sync.enabled	ZOHO_SYNC_ENABLED	true	Enable model sync
sync.queue	ZOHO_SYNC_QUEUE	default	Queue for sync jobs

Error Handling

The package provides typed exceptions:

use Asciisd\Zoho\Exceptions\ZohoApiException;
use Asciisd\Zoho\Exceptions\ZohoAuthException;
use Asciisd\Zoho\Exceptions\ZohoTokenException;

try {
    $contact = Zoho::contacts()->find('invalid_id');
} catch (ZohoApiException $e) {
    // API errors: recordNotFound, invalidModule, requestFailed,
    //             invalidData, rateLimitExceeded, insufficientPermissions
} catch (ZohoAuthException $e) {
    // Auth errors: invalidCredentials, missingConfiguration,
    //              tokenGenerationFailed, tokenRefreshFailed, tokenExpired
} catch (ZohoTokenException $e) {
    // Token errors: missingToken, invalidToken,
    //               storageFailed, retrievalFailed, refreshTokenExpired
}

Testing Commands

php artisan zoho:test Contacts                  # Test all operations
php artisan zoho:test Contacts --operation=read  # Test specific operation
php artisan zoho:test Leads --operation=search

Service Container Bindings

app('zoho');         // ZohoClient instance
app('zoho.oauth');   // OAuthManager instance
app('zoho.storage'); // TokenStorage instance

Testing

Tests use Orchestra Testbench and PHPUnit 10. All Zoho API calls are mocked with Http::fake() — no real HTTP requests are made.

Running tests

vendor/bin/phpunit

Test structure

tests/
├── TestCase.php                       # Base class — loads provider, config, migrations
├── Mocks/
│   ├── TestCustomer.php              # Eloquent model with SyncsWithZoho + field mapping
│   ├── TestCustomerNoMapping.php     # Eloquent model with SyncsWithZoho, no mapping
│   ├── TestCustomModuleCustomer.php  # Eloquent model syncing to a custom Zoho module
│   └── ZohoPropertyListing.php       # ZohoModel for custom module (Property_Listings)
├── database/migrations/              # Test-only migrations (test_customers table)
├── Unit/
│   ├── Auth/OAuthManagerTest.php
│   ├── Storage/TokenStorageTest.php
│   ├── Models/                       # ZohoModelTest, ZohoSyncTest, ZohoOAuthTokenTest
│   ├── Jobs/SyncModelToZohoTest.php
│   ├── Traits/SyncsWithZohoTest.php
│   ├── Exceptions/ExceptionsTest.php
│   ├── Events/EventsTest.php
│   └── ZohoClientTest.php
└── Feature/
    ├── Http/ZohoWebhookControllerTest.php
    ├── Console/                      # Auth, RefreshToken, Setup command tests
    └── ZohoServiceProviderTest.php

Writing tests — key patterns

// 1. Mock Zoho API responses
Http::fake([
    '*/crm/v8/Contacts' => Http::response([
        'data' => [['code' => 'SUCCESS', 'details' => ['id' => '123']]],
    ]),
]);

// 2. Seed tokens before testing API-dependent code
app('zoho.storage')->storeTokens([
    'access_token' => 'test-token',
    'refresh_token' => 'test-refresh',
    'expires_in' => 3600,
]);

// 3. Prevent sync side effects in unrelated tests
$customer = TestCustomer::withoutZohoSync(fn () => TestCustomer::create([
    'name' => 'Test', 'email' => '[e-mail]',
]));

// 4. Assert sync jobs are dispatched
Queue::fake();
TestCustomer::create([...]);
Queue::assertPushed(SyncModelToZoho::class, fn ($job) => $job->operation === 'create');

// 5. Test webhook signature verification
$payload = ([ => ,  => ]);
 = (, , );
->(, [...], [ => ]);

---

Source: asciisd/zoho — distributed by TomeVault.