README

此包用于集成新的 Zoho V3 Api CRM

要求

PHP >= 8.0
Laravel >= 8.0

注册 Zoho 客户端

由于 Zoho CRM API 使用 OAuth2 标准进行身份验证，您应该将客户端应用程序注册到 Zoho。要注册应用程序

访问此页面 https://api-console.zoho.com/
点击 添加客户端。
选择 自用客户端。
输入 作用域: aaaserver.profile.READ,ZohoCRM.modules.ALL,ZohoCRM.settings.ALL。
通过提供必要的权限、时间长度（生成的令牌有效的时间长度）和权限描述来创建授权令牌。
您的客户端应用程序现在已经创建并显示出来了。
选择已创建的 OAuth 客户端。

安装

您可以通过 composer require 安装此包

composer require asciisd/zoho-v3

您需要将以下变量添加到您的 .env 文件中。使用之前注册应用程序时获得的凭据。

ZOHO_CLIENT_ID="Code from Client Secrit Section"
ZOHO_CLIENT_SECRET="Code from Client Secrit Section"
ZOHO_REDIRECT_URI=https://APP_URL/zoho/oauth2callback
ZOHO_CURRENT_USER_EMAIL=admin@example.com
ZOHO_TOKEN="Code Generated from last step"

# available datacenters (USDataCenter, EUDataCenter, INDataCenter, CNDataCenter, AUDataCenter)
ZOHO_DATACENTER=USDataCenter
ZOHO_SANDBOX=true

您可以使用以下命令发布配置文件

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

您可以使用以下命令发布和运行迁移

php artisan vendor:publish --tag="zoho-v3-migrations"
php artisan migrate

环境

在某些情况下，您可能希望强制 Zoho 使用 Zoho 的某个环境，因此您可以进入 AppServiceProvider 并使用 Zoho::useEnvironment() 方法

Zoho::useEnvironment(EUDataCenter::DEVELOPER());

这样就会覆盖配置设置。

用法

假设您需要从 Zoho 系统获取所有模块。

use Asciisd\Zoho\ZohoManager;

$response = ZohoManager::make(self::TESTING_MODULE);
$modules  = $response->getAllModules();

模型可以这样使用：

从 v1.1.0 版本开始可用

将 Zohoable 作为扩展类使用，如下所示：

use Asciisd\Zoho\Zohoable;
use Asciisd\Zoho\ZohoManager;

class Invoice extends Zohoable {
    
    // this is your Zoho module API Name
    protected $zoho_module_name = 'Payments';

    public function searchCriteria(){
        // you should return string of criteria that you want to find current record in crm with.
        //EX:
        return ZohoManager::make('Payments')
                            ->where('PaymentID', $this->payment_id)
                            ->andWhere('Order_ID', $this->order_id)
                            ->getCriteria();
    }

    public function zohoMandatoryFields() {
        // you should return array of mandatory fields to create module from this model
        // EX:
        return ['Base_Currency' => $this->currency];
    }
}

现在您可以这样使用发票

$invoice = \App\Invoice::find(1);

// to check if has zoho id stored on local database or not
$invoice->hasZohoId();

// to return the stored zoho id
$invoice->zohoId();

// that will search on zoho with provided criteria to find the record and associated your model with returned id if exist
// if you provided an `id` that will be used instead of searching on Zoho
$invoice->createOrUpdateZohoId($id = null);

// you can also send current model to zoho
// that wil use `zohoMandatoryFields` method to Serialize model to zohoObject
// Also you can pass additional fields as array to this method
$invoice->createAsZohoable($options = []);

注意：要这样使用发票，您必须在数据库中创建与 Laravel 模型相同的 invoices 表。这允许您将数据保存到数据库中，并能够将其链接到 zohos 表，并使用 Zohoable 中的所有功能。如果您不想以这种方式使用 Zohoable 模型，请使用以下 CRUD 功能。

CRUD 可以这样使用：

读取

use Asciisd\Zoho\ZohoManager;

// we can now deal with leads module
$leads = ZohoManager::useModule('Leads');

// OR

$leads = ZohoManager::make('Leads');

// find record by its ID
$lead = $leads->getRecord('3582074000002383003');

更新

$record = new Record();
$record->setId('3582074000002383003');

// Set value as field
$record->addFieldValue(Leads::FirstName(), 'Updated');
$record->addFieldValue(Leads::LastName(), 'Record');

// Set value as key value
$lead->setKeyValue('Phone', '5555555555552');

// Then call update() method
$response = $leads->update($record);

创建

// create the record into zoho crm then get the created instance data
$response = $leads->create([
    'First_Name' => 'Amr',
    'Last_Name' => 'Emad',
    'Email' => 'test@asciisd.com',
    'Phone' => '012345678910',
]);

删除

// delete record by its id
$lead = $leads->delete('3582074000002383003');

搜索

单词

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::useModule('Leads')->searchRecordsByWord('word to be searched');
$first_record = $records[0];

电话

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::useModule('Leads')->searchRecordsByPhone('12345678910');
$first_record = $records[0];

电子邮件

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::make('Leads')->searchRecordsByEmail('nobody@asciisd.com');
$first_record = $records[0];

标准

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::make('Leads')->searchRecordsByCriteria('(City:equals:NY) and (State:equals:Alden)')->get();
$first_record = $records[0];

自定义

use Asciisd\Zoho\ZohoManager;

$records = ZohoManager::make('Leads')
                    ->where('City', 'NY')
                    ->andWhere('State','Alden')
                    ->get();

$first_record = $records[0];

国际版本

如果您使用 zoho.com，则无需更改任何内容。

如果您使用 zoho.eu，请将其添加到 .env

ZOHO_ACCOUNTS_URL=https://accounts.zoho.eu
ZOHO_API_BASE_URL=www.zohoapis.eu

如果您使用 zoho.com.cn，请将其添加到 .env

ZOHO_ACCOUNTS_URL=https://accounts.zoho.com.cn
ZOHO_API_BASE_URL=www.zohoapis.com.cn

支持

联系
asciisd.com
aemad@asciisd.com
+2-010-1144-1444

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全漏洞

请查看我们的安全策略了解如何报告安全漏洞。

致谢

许可证

MIT 许可证 (MIT)。请参阅许可证文件了解更多信息。

1337erik / zoho-laravel-api

维护者

详细信息