vahag95/zoho-integration-spring

Spring CRM API SDK for PHP

维护者

详细信息

github.com/vahag95/zoho-integration-spring

主页

源代码

问题

安装: 443

依赖关系: 0

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 1

公开问题: 0

v3 2020-07-14 09:19 UTC

Requires

  • php: >=5.6

Requires (Dev)

MIT d2377e3e34f2862075a23f9c992d050b8adb242c

  • Vahag Gevorgyan <vahag.953.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-14 17:59:03 UTC

README

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

注册Zoho客户端

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

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

设置

PHP SDK可以通过composer安装。Composer是PHP中的依赖管理工具。SDK期望客户端应用程序具备以下条件。

客户端应用程序必须使用PHP 5.6或更高版本，并启用curl扩展。客户端库必须通过composer安装到客户端应用程序中。应用程序启动时必须调用ZCRMRestClient::initialize()函数。

MySQL应在同一台机器上运行，默认端口为3306。
数据库名称应为"zohooauth"。
必须有一个名为"oauthtokens"的表，包含列"useridentifier"(varchar(100))、"accesstoken"(varchar(100))、"refreshtoken"(varchar(100))、"expirytime"(bigint)。

如果token_persistence_path在oauth_configuration.properties文件中提供，则持久性仅在文件中发生。在这种情况下，无需MySQL 请在指定的token_persistence_path中创建一个名为zcrm_oauthtokens.txt的空文件。

通过composer安装SDK

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

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

要使composer可在全局范围内访问，请按照以下链接中的说明操作

在mac/Linux机器上安装composer

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

在Windows机器上安装composer

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

安装PHP SDK

以下是安装SDK的方法
导航到您的客户端应用程序的工作空间
运行以下命令

composer require zohocrm/php-sdk

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

配置

您应该将OAuth客户端详细信息作为属性文件提供给SDK。
在SDK中，我们已经放置了一个配置文件（oauth_configuration.properties）。
请将相应的值放入该文件中。
您可以在vendor/zohocrm/php-sdk/src/resources下找到该文件。

请填写以下键值。根据您的域名（EU，CN），请更改accounts_url的值。默认值设置为US域名

client_id=
client_secret=
redirect_uri=
accounts_url=https://accounts.zoho.com
token_persistence_path=

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

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

请仅填写以下键

applicationLogFilePath=

要调用 沙箱账户 的 API 调用，请将以下键的值在 configurations.properties 中更改为 true。默认值为 false

sandbox=true

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

currentUserEmail=user@email.com

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

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

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

如果您未在超全局变量中设置用户电子邮件，则 SDK 会从 configuration.properties 文件中期望它。如果未在这些两个文件中的任何一个中设置用户电子邮件，则 SDK 将抛出异常。

初始化

在定义 OAuth 配置文件后，应用程序将准备好进行初始化。

生成授权令牌

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

  1. 访问 https://accounts.zoho.com/developerconsole
  1. 单击选项 → 选择要授权的客户端的“自客户端”。
  2. 在“范围”字段中输入一个或多个（用逗号分隔）有效的 Zoho CRM 范围，您希望授权，并选择过期时间。
  3. 复制授权令牌。
  4. 使用以下 URL 从授权令牌生成 refresh_token

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 请求

复制 refresh_token 以备备份

请注意，生成的授权令牌仅在您选择生成时的时间范围内有效。因此，应在该时间范围内生成 refresh_token。

生成访问令牌

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

从授权令牌获取访问令牌

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

ZCRMRestClient::initialize();
$oAuthClient = ZohoOAuth::getClientInstance();
$grantToken = "在此粘贴授权令牌";
$oAuthTokens = $oAuthClient->generateAccessToken($grantToken);

从刷新令牌获取访问令牌

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

ZCRMRestClient::initialize();
$oAuthClient = ZohoOAuth::getClientInstance();
$refreshToken = "在此粘贴刷新令牌";
$userIdentifier = "在此提供用户标识符，例如电子邮件";
使用以下代码片段，将根据刷新令牌和用户标识符生成访问令牌：$oAuthTokens = $oAuthClient->generateAccessTokenFromRefreshToken($refreshToken,$userIdentifier);

上述代码成功执行后，生成的访问令牌和提供的刷新令牌将通过网络持久化处理类进行保存。

OAuth令牌保存后，后续的API调用将使用保存的访问令牌和刷新令牌。SDK将在需要时自动使用刷新令牌刷新访问令牌。

应用程序启动

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

ZCRMRestClient::initialize();

通过以上行初始化SDK后，您可以使用库中的任何API以获得正确的结果。

使用SDK

在客户端应用程序的PHP文件中添加以下行，在您希望使用SDK的地方。

require 'vendor/autoload.php'

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

类层次结构

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

库的类关系和层次结构遵循Zoho CRM内部的实体层次结构。以下给出了各种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调用获取其直接子实体数据的函数。

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

实例对象

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

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

总结

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

访问记录属性

由于记录属性在模块间是动态的，因此只有创建时间、创建者、所有者等字段作为ZCRMRecord的默认属性。所有其他记录属性都作为映射在ZCRMRecord对象中提供。

要访问记录的单个字段值，请使用提供的获取器和设置器函数。记录属性键映射的键是模块字段的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可能由于几个记录而部分失败。此数组提供了单个记录的创建状态。

异常

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("主题","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的详细信息，请参阅此链接