README

PHP SDK for Zoho CRM APIs 提供了 Zoho CRM API 的封装。因此，从您的客户端应用程序调用 Zoho CRM API 只需一个方法调用即可。它支持单用户和多用户身份验证。

注册 Zoho 客户端

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

访问此页面 https://accounts.zoho.com/developerconsole。
点击 添加客户端 ID。
输入客户端名称、客户端域和重定向 URI，然后点击 创建。
您的客户端应用程序现在已经创建并显示。
通过点击 选项 → 编辑（选项是右上角的三个点图标）可以找到新注册应用程序的客户端 ID 和客户端密钥。

设置

PHP SDK 可以通过 composer 安装。Composer 是 PHP 的依赖管理工具。SDK 期望客户端应用程序满足以下要求。

客户端应用程序必须具有 PHP 5.6 或更高版本，并且启用了 curl 扩展。

必须通过 composer 在客户端应用程序中安装 PHP SDK。

必须在应用程序启动时调用 ZCRMRestClient::initialize($configuration) 函数。

$configuration - 包含键值对形式的配置详细信息。

令牌持久处理（存储和利用 OAuth 令牌）可以通过三种方式完成。文件、数据库和自定义持久化。

通过 composer 安装 SDK

安装 Composer（如果尚未安装）运行以下命令安装 composer

curl -sS https://getcomposer.org/installer | php

要使 composer 可全局访问，请遵循以下链接中的说明

在 mac/ linux 机器上安装 composer

https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx

在 windows 机器上安装 composer

https://getcomposer.org/doc/00-intro.md#installation-windows

安装 PHP SDK

以下是安装 SDK 的方法

导航到您的客户端应用程序的工作区
运行以下命令

composer require zohocrm/php-sdk

因此，PHP SDK 将被安装，并在客户端应用程序的工作区中创建一个名为 'vendor' 的软件包。

配置

要通过 SDK 访问 CRM 服务，客户端应用程序必须首先进行身份验证。这可以通过将键值配置对传递给初始化过程来完成。

必须创建 $configuration 数组。它将包含所需的身份验证凭据。然后必须使用 "ZCRMRestClient::initialize($configuration); " 将配置数组传递。

用户必须将配置值作为 php 数组（键值对）作为参数传递给 ZCRMRestclient::initialize($configuration); 函数。以下是数组中必须存在的键列表。

必填键

client_id client_secret redirect_uri currentUserEmail

可选键

applicationLogFilePath sandbox apiBaseUrl apiVersion access_type accounts_url persistence_handler_class token_persistence_path db_port db_username db_password

client_id、client_secret 和 redirect_uri 是您在注册 Zoho 客户端后获得的 OAuth 客户端配置。

currentUserEmail - 在单用户的情况下，此配置可以使用 "ZCRMRestClient->setCurrentUser()" 设置。

access_type 必须设置为离线，因为目前 PHP SDK 不支持在线 OAuth 客户端。

apiBaseUrl - 调用API时使用的URL。它用于表示用户所在的域名。URL可能是：www.zohoapis.com（默认）www.zohoapis.eu www.zohoapis.com.cn

apiVersion的值为"v2"。

accounts_url - 默认值设置为美国域名。根据您的域名（EU、CN）可以更改此值。accounts.zoho.com accounts.zoho.eu accounts.zoho.com.cn

sandbox - 若要调用沙盒账户的API，请将以下键的值更改为true。默认值为false。

applicationLogFilePath - SDK将日志信息存储在文件中。文件夹的文件路径必须在键中指定，SDK将自动创建文件。默认文件名为ZCRMClientLibrary.log。如果未指定路径，则日志文件将在项目中创建。

persistence_handler_class是实现ZohoOAuthPersistenceInterface的类。

如果未指定可选键，则将自动分配它们的默认值。如果用户不在"com"域名下，则"apiBaseUrl"和"accounts_url"是必填项。

初始化

在定义配置数组后，应用程序将准备好进行初始化。现在用户可以继续生成运行应用程序所需的令牌。

可以通过两种方法生成授权令牌。

基于自客户端重定向的代码生成

我们将在此处使用自客户端选项来演示此过程。

生成自授权授权令牌

对于自客户端应用程序，自授权授权令牌应从Zoho开发者控制台（https://accounts.zoho.com/developerconsole）生成

访问 https://accounts.zoho.com/developerconsole

单击“选项”→“客户端的自客户端”，为要授权的客户端。
在“作用域”字段中输入一个或多个（用逗号分隔）有效的Zoho CRM作用域，您希望授权，并选择过期时间。
复制授权令牌。
使用以下URL从授权令牌生成刷新令牌

https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code 这是一个POST请求

复制刷新令牌以备后用

请注意，生成的授权令牌仅在您生成时指定的规定时间内有效。因此，应在该时间段内生成刷新令牌。

生成访问令牌

访问令牌可以通过授权令牌或刷新令牌生成。以下两种方法中的任何一种都足够。

从授权令牌获取访问令牌

以下代码片段应在您的main类中执行以获取访问令牌。请将复制的授权令牌粘贴到下面的字符串字面量中。这是一个一次性过程。

$configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); ZCRMRestClient::initialize($configuration); $oAuthClient = ZohoOAuth::getClientInstance(); $grantToken = "paste_the_self_authorized_grant_token_here"; $oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从刷新令牌获取访问令牌

以下代码片段应在您的main类中执行以获取访问令牌。请将复制的刷新令牌粘贴到下面的字符串字面量中。这是一个一次性过程。

$configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); ZCRMRestClient::initialize($configuration); $oAuthClient = ZohoOAuth::getClientInstance(); $refreshToken = "paste_the_refresh_token_here"; $userIdentifier = "provide_user_identifier_like_email_here"; $oAuthTokens = $oAuthClient->generateAccessTokenFromRefreshToken($refreshToken,$userIdentifier);

在上面的代码片段成功执行后，生成的访问令牌和提供的刷新令牌将通过我们的持久化处理类进行持久化存储。

一旦OAuth令牌被持久化，后续的API调用将使用持久化的访问和刷新令牌。SDK将在需要时自动使用刷新令牌刷新访问令牌。

应用启动

SDK需要每次启动客户端应用时调用以下代码行。

$configuration =array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id}); ZCRMRestClient::initialize($configuration);

一旦通过上述行初始化了SDK，您就可以使用库中的任何API来获取正确的结果。

使用SDK

在客户端应用的PHP文件中添加以下行，您希望使用SDK的位置。

require 'vendor/autoload.php'

通过此行，您可以访问PHP SDK的所有功能。

类层次结构

所有Zoho CRM实体都作为具有特定实体成员和方法的类进行建模。

ZCRMRestClient是SDK的基类。此类具有获取各种其他Zoho CRM实体实例的方法。

SDK的类关系和层次结构遵循Zoho CRM内部的实体层次结构。

每个类实体都有函数来获取其自身的属性，并通过API调用获取其直接子实体的数据。例如，Zoho CRM模块（ZCRMModule）对象将具有获取模块属性（如显示名称、模块ID等）的成员函数，并且还将具有获取所有子对象（如ZCRMLayout）的函数。

以下列出了各种Zoho CRM实体的类层次结构

ZCRMRestClient
- ZCRMOrganization
  - ZCRMUser
    - ZCRMUserTheme
      - ZCRMUserCustomizeInfo
    - ZCRMRole
    - ZCRMProfile
      - ZCRMPermission
      - ZCRMProfileSection
        
        ZCRMProfileCategory
  - ZCRMModule
    - ZCRMLayout
      - ZCRMSection
        
        ZCRMField
        
        ZCRMPickListValue
        
        ZCRMLookupField
      - ZCRMLeadConvertMapping
        
        ZCRMLeadConvertMappingField
    - ZCRMCustomView
      - ZCRMCustomViewCategory
      - ZCRMCustomViewCriteria
    - ZCRMRelatedListProperties
      - ZCRMModuleRelatedList
    - ZCRMRecord
    - ZCRMNote
    - ZCRMAttachment
    - ZCRMInventoryLineItem
      - ZCRMTax
    - ZCRMEventParticipant
    - ZCRMPriceBookPricing
    - ZCRMModuleRelation
    - ZCRMJunctionRecord
    - ZCRMTrashRecord

实例对象

由于在每个级别都会涉及API调用，因此从顶部完整地遵循类层次结构以获取较低级别实体的数据并不总是有效。为了处理这种情况，每个实体类都有一个getInstance()函数来获取其自己的虚拟对象和获取其子实体虚拟对象的函数。

请注意，getInstance()函数不会填充任何属性，因为它不会触发API调用。这将仅返回一个虚拟对象，该对象仅用于访问类的非静态函数。

总结

ZCRMRestClient::getModule(“Contacts”)将返回实际的Contacts模块，通过API调用填充了Contacts模块的所有属性。
ZCRMRestClient::getModuleInstance(“Contacts”)将返回一个虚拟的ZCRMModule对象，该对象将引用Contacts模块，但没有填充属性，因为这不进行API调用。
因此，要从模块获取记录，不需要从ZCRMRestClient开始。相反，可以使用ZCRMModule::getInstance()获取ZCRMModule实例，然后从创建的实例调用其非静态的getRecords()函数。这将避免触发用于填充ZCRMModule对象的API调用。

访问记录属性

由于记录属性在模块间是动态的，我们只提供了如createdTime、createdBy、owner等公共字段，作为ZCRMRecord的默认成员。所有其他记录属性均以映射的形式存在于ZCRMRecord对象中。要访问记录的各个字段的值，请使用提供的getter和setter方法。这些方法仅支持API名称。

要获取字段值，请使用record.getFieldValue(field_api_name)；

要设置字段值，请使用record.setFieldValue(field_api_name, new_value)；

记录属性映射的键是模块字段的API名称。它们可在您的CRM中找到，

设置 → 开发者空间 → API → CRM API → API名称。

在设置字段值时，请确保设置的值是您要设置的相应字段的类型。

响应处理

寻求单个实体的方法将返回APIResponse对象，而寻求实体列表的方法将返回BulkAPIResponse对象。

APIResponse.getData()将返回单个Zoho CRM实体对象。使用getData()函数从APIResponse的响应包装对象中获取实体数据。（例如：单个记录/字段/模块信息。）

BulkAPIResponse.getData()将返回Zoho CRM实体对象的数组（例如：多个记录/字段/模块信息）。使用getData()函数从BulkAPIResponse的响应包装对象中获取实体数据。

FileAPIResponse将在文件下载API中使用，以从记录或笔记（如record.downloadPhoto()、record.downloadAttachment()等）下载照片或附件。FileAPIResponse有两个定义的方法，即FileAPIResponse.getFileName()，返回下载的文件名，FileAPIResponse.getFileContent()返回文件内容作为String。

ResponseInfo - API提供的任何其他信息，除了实际数据。

response.getInfo()

List<EntityResponse> - 批量API中单个实体的状态。例如：由于一些记录，插入记录API可能部分失败。此字典提供了单个记录的创建状态。它通过以下方式提供：

response.getEntityResponses()

异常

SDK处理所有意外行为，如错误的API响应、库异常，并且仅以单个异常ZCRMException的形式抛出。因此，在客户端应用程序代码中捕获此异常就足够了。

示例

插入记录的示例请求

$zcrmModuleIns = ZCRMModule::getInstance("Invoices");
$bulkAPIResponse=$zcrmModuleIns->createRecords($recordsArray); // $recordsArray - 填充有创建所需数据的ZCRMRecord实例数组。
$entityResponses = $bulkAPIResponse->getEntityResponses();
foreach($entityResponses as $entityResponse)
{
if("success"==$entityResponse->getStatus())
{
echo "状态:".$entityResponse->getStatus();
echo "消息:".$entityResponse->getMessage();
echo "代码:".$entityResponse->getCode();
$createdRecordInstance=$entityResponse->getData();
echo "实体ID:".$createdRecordInstance->getEntityId();
echo "模块API名称:".$createdRecordInstance->getModuleAPIName();
……}

Sample Invoice record instance with filled data
-----------------------------------------------

$record=ZCRMRecord::getInstance("Invoices",null);
$record->setFieldValue("Subject","Iphone sale to John");
$record->setFieldValue("Account_Name","410405000001016021");
$productInstance=ZCRMRecord::getInstance("Products",410405000001108011);
$lineItem=ZCRMInventoryLineItem::getInstance($productInstance);
$taxInstance1=ZCRMTax::getInstance("Sales Tax");
$taxInstance1->setPercentage(2);
$taxInstance1->setValue(10);
$lineItem->addLineTax($taxInstance1);
$taxInstance1=ZCRMTax::getInstance("Vat");
$taxInstance1->setPercentage(12);
$taxInstance1->setValue(60);
$lineItem->addLineTax($taxInstance1);
$lineItem->setQuantity(100);
$lineItem->setDiscount(0.5);
$record->addLineItem($lineItem);

获取记录的示例请求

$zcrmModuleIns = ZCRMModule::getInstance("Contacts");
$bulkAPIResponse=$zcrmModuleIns->getRecords();
$recordsArray = $bulkAPIResponse->getData(); // $recordsArray - ZCRMRecord实例数组

有关更多API，请参阅此链接

yourik / zoho-php-sdk

维护者

详细信息