dylanlawrence/zohocrm

此软件包的最新版本（v2.0.8）没有可用的许可证信息。

Zoho CRM API SDK for PHP

维护者

详细信息

github.com/dylanlawrence/zcrm-php-sdk

主页

源代码

安装: 147

依赖: 0

建议: 0

安全: 0

星标: 2

关注者: 5

分支: 132

v2.0.8 2021-04-29 19:29 UTC

Requires

Requires (Dev)

Unknown License 5c5e2c063648f590114fa1fee3c2f4558a227378

  • Dylan Lawrence <dylan.woop@visualidentitygroup.com>

This package is auto-updated.

Last update: 2024-09-29 05:08:17 UTC

README

突出显示所需更改的分支

#PHP SDK for Zoho CRM

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

注册 Zoho 客户端

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

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

设置

SDK 期望客户端应用程序提供以下信息。PHP SDK 可以通过 composer 安装。

  • 客户端应用程序必须具有 PHP 5.6
  • cUrl 扩展已启用
  • 必须通过 composer 安装到客户端应用程序中。
  • 同一台机器上的 MySQL 正在默认端口 3306 上运行。
    • 数据库名应为 "zohooauth"。
  • 必须有一个名为 "oauthtokens" 的表
    • 列 "useridentifier"(varchar(100))、"accesstoken"(varchar(100))、"refreshtoken"(varchar(100))、"expirytime"(bigint)。

如果设置了 token_persistence_path 配置，则持久性仅在文件中发生，不需要 MySQL 在指定的 token_persistence_path 中创建一个名为 zcrm_oauthtokens.txt 的空文件

安装

Composer

安装 Composer（如果尚未安装）。有关 Composer 安装说明，请参阅 Composer 文档

PHP SDK

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

composer require zohocrm/php-sdk

配置

在您的项目中创建一个配置文件，例如 'zcrm.config.yml'，并提供以下值。

api:
   apiBaseUrl: www.zohoapis.com
   apiVersion: v2
   sandbox: false
   applicationLogFilePath:
   currentUserEmail:
 oauth:
   client_id: 0
   client_secret:
   redirect_uri:
   accounts_url: https://accounts.zoho.com
   token_persistence_path:
   access_type: offline
   persistence_handler_class: ZohoOAuthPersistenceHandler

只需填写上面显示的键。
client_id、client_secret 和 redirect_uri 是您在注册 Zoho 客户端后获得的 OAuth 客户端配置。
token_persistence_path 是存储 OAuth 相关令牌的文件路径。如果设置了此值，则不需要 database 进行持久性。持久性仅通过 file 进行。
access_type 必须设置为 offline，因为 SDK 目前不支持在线 OAuth 客户端。
persistence_handler_class 是 ZohoOAuthPersistenceInterface 的实现

在您的客户端应用程序机器上创建一个名为 ZCRMClientLibrary.log 的文件，并在 configuration.properties 中将创建的文件的绝对路径指定为 applicationLogFilePath 的键。
您可以在 vendor/zohocrm/php-sdk/src/resources 下找到该文件。此文件用于记录 SDK 使用过程中发生的异常。

请只填写以下键

applicationLogFilePath=

要向 sandbox 账户 发送 API 调用，请将 configurations.properties 中以下键的值更改为 true。默认值为 false

sandbox=true

如果您的应用程序只需要单用户身份验证，您必须在配置文件 configurations.properties 中设置用户 EmailId，如下所示

currentUserEmail=user@email.com

为了使用多用户身份验证，您需要将用户 EmailId 设置在 PHP 超全局变量 ‘$_SERVER’ 中，如下所示

$_SERVER[‘user_email_id’]=“user@email.com”

您也可以使用 $_SERVER 变量进行单用户身份验证，但建议您在 configuration.properties 文件中设置电子邮件 ID。

如果您没有在全局变量中设置用户电子邮件，SDK 将期望从 configuration.properties 文件中获取。如果用户电子邮件在这两个地方都没有设置，SDK 将抛出异常。

应用启动

初始化

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

ZCRMRestClient::initialize($config_path);

一旦 SDK 初始化完成，您就可以使用任何 API。

生成自授权授权令牌

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

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

  2. 点击“选项” → “授权的自客户端”，为您希望授权的客户端选择。

  3. 在“作用域”字段中输入一个或多个（以逗号分隔）有效的 Zoho CRM 作用域，您希望授权，并选择过期时间。

  4. 复制授权令牌。

  5. 使用以下 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 请求

复制刷新令牌以备后用

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

生成访问令牌

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

从授权令牌生成访问令牌

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

$config_path = 'path/to/zcrm.config.yml';
ZCRMRestClient::initialize($config_path);
$oAuthClient = ZohoOAuth::getClientInstance(); 
$grantToken = "paste_the_grant_token_here";  
$oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从刷新令牌生成访问令牌

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

$config_path = 'path/to/zcrm.config.yml';
ZCRMRestClient::initialize($config_path);
$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

在您的客户端应用程序的 PHP 文件中添加以下行，您可以在其中使用 SDK。

require 'vendor/autoload.php'

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

类层次结构

所有 Zoho CRM 实体都作为具有适用于该特定实体的属性和函数的类建模。ZCRMRestClient 是 SDK 的基类。ZCRMRestClient 有用于获取各种其他 Zoho CRM 实体实例的函数。

库的类关系和层次结构遵循 Zoho CRM 内部实体层次结构。以下列出了各种 Zoho CRM 实体的类层次结构

  • ZCRMRestClient
    • ZCRMOrganization
      • ZCRMUser
        • ZCRMUserTheme
          • CRM用户自定义信息
        • CRM角色
        • CRM配置文件
          • CRM权限
          • CRM配置文件部分
            • CRM配置文件类别
      • CRM模块
        • CRM布局
          • CRM部分
            • CRM字段
            • CRM选择列表值
            • CRM查找字段
          • CRM线索转换映射
            • CRM线索转换映射字段
        • CRM自定义视图
          • CRM自定义视图类别
          • CRM自定义视图条件
        • CRM相关列表属性
          • CRM模块相关列表
        • CRM记录
        • CRM笔记
        • CRM附件
        • CRM库存行项目
          • CRM税
        • CRM活动参与者
        • CRM价目表定价
        • CRM模块关系
        • CRM连接记录
        • CRM垃圾桶记录

每个实体类都有通过API调用获取其自身属性和获取其直接子实体数据的函数。

例如：Zoho CRM模块（ZCRMModule）对象将具有获取模块属性（如显示名称、模块ID等）的成员函数，并且还将具有获取所有子对象（如ZCRMLayout）的函数。

实例对象

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

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

总结一下

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

访问记录属性

由于记录属性在模块之间是动态的，因此只有如createdTime、createBy、owner等字段作为ZCRMRecord的默认属性提供。所有其他记录属性均作为ZCRMRecord对象中的映射提供。

要访问记录的个别字段值，请使用可用的getter和setter函数。记录属性映射的键是模块字段的API名称。所有模块的字段API名称都在“设置”→“市场”→“API”→“CRM API”→“API名称”下提供。

要获取字段值，请使用$record → getFieldValue($fieldAPIName);
要设置字段值，请使用$record → setFieldValue($fieldAPIName, $newValue);
在设置字段值时，请确保设置的值是您要设置的字段的适当数据类型。

响应处理

APIResponse和BulkAPIResponse是Zoho CRM API响应的包装对象。所有API调用函数都会返回这两个对象之一。

DownloadFile和downloadPhoto返回FileAPIResponse而不是APIResponse。
用于查找单个实体的函数将返回一个APIResponse对象，而用于查找实体列表的函数将返回一个BulkAPIResponse对象。使用getData()函数从响应包装对象中获取实体数据。从APIResponse → getData()将返回单个Zoho CRM实体对象，而`BulkAPIResponse → getData()`将返回Zoho CRM实体对象列表。除了数据之外，这些响应包装对象还具有以下属性

ResponseHeaders - 当前日/窗口剩余的API计数和时间窗口重置所经过的时间。
ResponseInfo - API提供的除实际数据之外的其他信息。
实体响应数组 - 批量API中单个实体的状态。
例如：由于几个记录，插入记录的API可能部分失败。此数组提供了单个记录的创建状态。

异常

所有意外的行为，如错误的API响应、库异常，都由SDK处理，并以单个异常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，请参阅此链接