Node JS

Zoho CRM 的 Node JS SDK

目录

Node SDK 是 Zoho CRM API 的包装器。因此，从您的 Node 应用程序调用 Zoho CRM API 只是函数调用，并提供最合适的响应。

此 SDK 支持单用户认证和多用户认证。

注册 Zoho 客户端

因为 Zoho CRM API 是使用 OAuth2 标准认证的，所以应该向 Zoho 注册您的客户端应用。按照下面步骤注册您的应用：

  1. 访问页面：https://accounts.zoho.com.cn/developerconsole。
  2. 点击“添加客户端 ID”。
  3. 输入客户端名称、客户端域和重定向 URI。
  4. 选择基于 Web 作为客户端类型。
  5. 点击“创建”。
  6. 将立即创建和显示客户端应用。
  7. 可通过点击“选项”→“编辑”来找到新注册应用的客户端 ID 和客户端密钥。
    （“选项”在右侧显示为三个点的图标）。

安装 Node CRM SDK

安装 Node JS SDK，并在本地机器上创建名为“zcrmsdk”的包。

可使用以下代码添加此包：

var ZCRMRestClient = require('zcrmsdk')

安装 SDK

以下介绍如何安装 Node JS SDK

  • 运行以下命令：

    npm install zcrmsdk

安装该 SDK 的另一方法是在具有最新版本（推荐）的 Node 服务器的 package.json 依赖项中添加该 SDK，并在安装 package.json 中提示的所有依赖项的目录中运行 npm install。

升级 SDK

  • 运行以下命令以将 Node JS SDK 升级至最新版本。

    npm install --upgrade zcrmsdk

配置

OAuth 客户端信息将作为配置文件提供给 SDK。在该 SDK 中，您需要配置名为 oauth_configuration.properties 的文件。请在该文件中设置相应值。可将该文件放在使用该 SDK 的 resources 文件夹下。

请填写以下键的值。

根据您的域（EU 或 CN），更改 crm.iamurl 的值。默认值设置为 US 域。

在 oauth_configuration.properties 文件中：

[zoho]
crm.iamurl=
crm.clientid=
crm.clientsecret=
crm.redirecturl=

  • crm.clientid, crm.clientsecret 和 crm.redirecturl 是注册 Zoho 客户端后获取的 OAuth 客户端配置。
  • crm.iamurl 是客户 URL。它可以是 accounts.zoho.com.cn 或 accounts.zoho.eu。如果未指定 crm.iamurl，那么默认情况下该 URL 将为 accounts.zoho.com.cn。

在 configuration.properties 文件中：

[crm]
api.url=
api.user_identifier=
api.tokenmanagement=

  • api.url 是用于调用 API 的 URL。默认情况下，该 URL 为 www.zohoapis.com.cn。
  • 默认情况下，api.user_identifier 将为空。对于单用户认证，可使用相应邮箱地址填写此键，以便使用此用户的认证进行所有调用。
  • api.tokenmanagement 可用于管理和维护令牌。如果未提供 tokenmanagement，那么将遵循 SDK 的默认实现 (mysql)。

configuration.properties 文件中指定的以上键都是可选项。

令牌存储机制

要使用 SDK 提供的默认令牌存储器，应满足以下条件：

Mysql 应在 localhost 中的默认端口中运行。

应该创建名为 zohooauth 的数据库，并且该数据库中应包含具有以下配置的表。名为“oauthtokens”的表，应具有以下列：“useridentifier”(varchar)、“accesstoken”(varchar)、“refreshtoken”(varchar) 和“expirytime”(bigint)。

设置此配置后，SDK 将处理令牌的存储和检索操作。

如果用户要使用自己的机制，那么他们可以通过在api.tokenmanagement 中提供相应模块以在 configuration.properties 中指示该机制。

此模块应包含以下方法：

  1. saveOAuthTokens(token_obj)
  2. updateOAuthTokens(token_obj)
    • 不管响应如何，都将进行下一执行。所以，应由用户负责处理他们的模块。
  3. getOAuthTokens()
    • 此方法的预期响应：包含 expirytime、refreshtoken 和 accesstoken 字段的 JSON 响应。

调用 saveoauthtoken 和 updateOAuthTokens 时应带有 JSON 参数，这些参数包含以下字段：

access_token
refresh_token
expires_in

初始化

每当启动应用时，都将调用以下代码片段以进行初始化。

var ZCRMRestClient = require('zcrmsdk');
ZCRMRestClient.initialize().then(function()
{
//在初始化后做任何需要的事情
})

生成自授权的授权和刷新令牌

对于独立客户端应用，应通过 Zoho 开发者控制台 (https://accounts.zoho.com.cn/developerconsole) 生成自授权的授权令牌。

  1. 请访问 https://accounts.zoho.com.cn/developerconsole
  2. 点击要对其授权的客户端的选项 → 独立客户端。
  3. 在“范围”字段中输入您要授权的一个或多个（各项之间用逗号分隔）有效 Zoho CRM 范围，然后选择到期日期。输入“aaaserver.profile.READ”范围及 Zoho CRM 范围。
  4. 复制授权令牌以进行备份。
  5. 借助创建带有以下 URL 的 POST 请求，通过授权令牌生成刷新令牌

    https://accounts.zoho.com.cn/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code

  6. 复制刷新令牌以进行备份。

请注意，所生成授权令牌仅在您生成它时选择的约定期限内有效。因此，应在该时间范围内生成访问令牌和刷新令牌。

每次重新启动服务器时，必须调用此函数，并且在调用此函数之前，必须对两个简档填充相应值，否则将抛出异常。

zcrm node sdk 中的所有函数返回承诺。

借助方法调用，通过授权令牌获取访问令牌和刷新令牌

ZCRMRestClient.generateAuthTokens(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});

将生成访问令牌和刷新令牌。如果访问令牌到期，那么 SDK 将自动刷新。

如果用户具有刷新令牌并需要生成访问令牌，那么可使用以下函数：

ZCRMRestClient.generateAuthTokenfromRefreshToken(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});

用于获取模块的样本 API 调用：

var input ={};
input.module = "Leads";
var params = {};
params.page = 0;
params.per_page = 5;
input.params = params;
zcrmsdk.API.MODULES.get(input).then(function(response){
    var result = "<html><body><b>Leads</b>";
    var data = response.body;
    data = JSON.parse(data);
    data = data.data;
    for (i in data){
        var record = data[i];
        var name = record.Full_Name;
        result+="<span>"+name+"</span>";
    }
    result+="</body></html>";
   })

层次结构

zcrmsdk

   API
     ORG
       get
     MODULES
       get
       post
       put
       delete
       getAllDeletedRecords
       getRecycleBinRecords
       getPermanentlyDeletedRecords
       search
     SETTINGS
       getFields
       getLayouts
       getCustomViews
       updateCustomViews
       getModules
       getRoles
       getProfiles
       getRelatedLists
     ACTIONS
       convert
     USERS
       get
     ATTACHMENTS
       uploadFile
       deleteFile
       downloadFile
       uploadLink
       uploadPhoto
       downloadPhoto
       deletePhoto
     FUNCTIONS
       executeFunctionsInGet
       executeFunctionsInPost

如此层次结构中所示，zcrmsdk 实体模块有一些变量可用于获取它自己的和其他模块的属性。

例如，要调用 API 以获取模块数据，请求应该为 zcrmsdk.API.MODULES.{operation_type}。操作类型可以是 GET、POST、PUT、DELETE 或 CREATE。

响应处理

所有 API 调用将给出 Zoho API 提供的实际 API 响应，文件下载除外。

对于文件下载，响应将包含额外字段，即 filename。

错误处理：

所有错误将显式抛出，并应在捕获相同内容时进行处理。

还是没有找到您要寻找的内容？

写信给我们：support-crm@zohocorp.com.cn