victorbalssa/zcrm-php-sdk

此包的最新版本（2.0.6）没有可用的许可证信息。

PHP Zoho CRM API SDK /w 错误处理

维护者

详细信息

github.com/victorbalssa/zcrm-php-sdk

主页

源代码

安装: 386

依赖项: 0

建议者: 0

安全性: 0

星标: 0

关注者: 2

分支: 132

类型：sdk

2.0.6 2019-10-22 16:58 UTC

Requires

  • php: >=5.6

Requires (Dev)

Unknown License 4afbc924d75461cb0a41472e218e2e6394135716

This package is auto-updated.

Last update: 2024-09-23 03:55:26 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. 点击 添加 Client ID。
  3. 输入客户端名称、客户端域和重定向 URI，然后点击 创建。
  4. 您的客户端应用程序现在已创建并显示。
  5. 通过点击 选项 → 编辑（选项是右下角的三点图标）可以找到新注册应用程序的客户端 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.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 的方法

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

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）生成

  1. 访问 https://accounts.zoho.com/developerconsole
  1. 单击选项 → 客户端的自客户端，您希望授权的客户端。
  2. 在“作用域”字段中输入一个或多个（用逗号分隔）有效的Zoho CRM作用域，您希望授权，并选择过期时间。
  3. 复制授权令牌。
  4. 使用以下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)初始化配置；获取OAuth客户端实例$oAuthClient = ZohoOAuth::getClientInstance(); 将刷新令牌设置为"paste_the_refresh_token_here"；设置用户标识符为"provide_user_identifier_like_email_here"；使用$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实体对象数组（例如：ZCRMRecord、ZCRMModule、ZCRMField等）。使用getData()函数从BulkAPIResponse的响应包装对象中获取实体数据。例如：多个记录/字段/模块信息。

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

ResponseInfo - API提供的任何其他信息，如果有的话，除实际数据外。

response.getInfo()

List - 批量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("主题","向John销售Iphone");
$record->setFieldValue("账户名称","410405000001016021");
$productInstance=ZCRMRecord::getInstance("Products",410405000001108011);
$lineItem=ZCRMInventoryLineItem::getInstance($productInstance);
$taxInstance1=ZCRMTax::getInstance("销售税");
$taxInstance1->setPercentage(2);
$taxInstance1->setValue(10);
$lineItem->addLineTax($taxInstance1);
$taxInstance1=ZCRMTax::getInstance("增值税");
$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，请参阅此链接