如何使用 Zoho CRM v2 API 添加 Zoho CRM 潜在客户

Question

如何使用简单的curl 连接通过Zoho CRM v2 API 添加Zoho CRM 潜在客户？该文档不仅不清楚如何添加潜在客户，而且还不清楚如何获取正确的 oAuth 令牌来创建潜在客户。

Answer 1

文档对这个过程不是很清楚。所以，我会简化这个。最大的障碍是获取刷新令牌的步骤。一旦有了它，您就可以生成无数的访问令牌，用于进行实际的 API 调用。

如何获取刷新令牌

1. 使用管理员级别帐户登录您的 Zoho CRM并在选项卡中打开该帐户。然后，在另一个浏览器选项卡中，登录开发人员 API 控制台：https://api-console.zoho.com/
2. 在开发者 API 控制台中，您需要创建一个服务器端客户端。这些字段应按如下方式填充：客户端名称（您想要的任何逻辑名称）、主页 URL（您要进行 API 调用的域的主页，或者仅对您正在执行的操作使用相同的 URL重定向）、授权重定向 URI（将网页放在您要进行 API 调用的域上，并使其仅发出“zoho 已确认”消息）。（“zoho 已确认”不是必需的，文档中也未提及，但确实可以帮助您更好地理解该流程。）单击“创建”。
3. 创建后，再次单击它，会出现一个名为“客户端密钥”的选项卡。单击它并在记事本中记录您的Client ID和Client Secret。
4. 在线获取 URL 编码器脚本（或使用 PHP 或任何其他工具），并对下一步需要在浏览器中编写和加载的新 URL 的以下参数进行 URL 编码：

scope: ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoCRM.users.ALL,ZohoCRM.org.ALL,aaaserver.profile.ALL,ZohoCRM.settings.functions.all,ZohoCRM.notifications.all,ZohoCRM.coql.read,ZohoCRM.files.create,ZohoCRM.bulk.all
response_type: code
access_type: offline
client_id: {use the Client ID you recorded in step 3}
redirect_uri: {use the Authorized Redirect URI you generated in step 2}

5. 使用这些 URL 编码参数，将它们传递到浏览器中该 URL 的末尾：https://accounts.zoho.com/oauth/v2/auth?因此，您将得到类似以下内容的内容：

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL%2CZohoCRM.settings.ALL%2CZohoCRM.users.ALL%2CZohoCRM.org.ALL%2Caaaserver.profile.ALL%2CZohoCRM.settings.functions.all%2CZohoCRM.notifications.all%2CZohoCRM.coql.read%2CZohoCRM.files.create%2CZohoCRM.bulk.all&client_id=1000.TTT0BSTTTC9TTTRILR3MGXBYAC82LH&response_type=code&access_type=offline&redirect_uri=https%3A%2F%2Fexample.com%3Azohoconfirm

请注意，如果您的重定向 URI（如上面的https://example.com/zohoconfirm）使用 301 或 302 重定向进行另一个重定向，并且不转发这些查询参数，那么您将丢失所需的参数看看什么时候完成。

6. 将其加载到浏览器中后，您将看到“接受”按钮。如果您不这样做，那么您可能错过了步骤 1 中您应该在一个选项卡中登录 CRM，然后打开一个新选项卡来执行其他任务的操作。这会为您打开一个会话，并且在执行第 5 步时它会知道您是谁。

7. 单击接受按钮后，Zoho 的帐户系统会将您重定向到您指定的授权重定向 URI。因此，如果您完全按照这些步骤操作，您应该会看到一些输出，例如“zoho已确认”。但不要关闭该选项卡。查看选项卡的 URL 并将其剪切/粘贴到记事本中。在那里，获取该代码参数。

8. 现在您已经有了该代码参数，您需要创建一个特殊的 Curl POST 请求。您可以通过命令行或使用您最喜欢的编程语言来完成此操作。从 Linux 上的命令行来看，这将类似于以下内容：

curl "https://accounts.zoho.com/oauth/v2/token" \
-X POST \
-d "grant_type=authorization_code&code=1000.aaa1f9aa8582eaaaafeaddfaf0f3b6b.bf7fe646ba899783501c21a9a3240aaa&client_id=1000.AAAA0BSIC7C9AAAARILR3MGXBYAC8AAA&client_secret=aaa9aa9166055932ff8c0279c6253a65cb534daaaa&redirect_uri=https%3A%2F%2Fexample.com%2Fzohoconfirm"

您需要填写的 URL 编码参数是：

grant_type: authorization_code
code: {the code you recorded from step 7}
client_id: {the Client ID you recorded in step 3}
client_secret: {the Client Secret you recorded in step 3}
redirect_uri: {the Authorized Redirect URI you recorded in step 2}

9. 运行该 Curl 命令后，它将返回一些类似于以下内容的 JSON：

{"access_token":"1000.aaaa5579abeea73871b096c941ec1df8.7835dbb43bbf5122f2d5810f0b65aaa","refresh_token":"1000.aaaa2683a1723d1aeb7b58899849aaaa.aaaa4c22481da67e85e598f4b988aaa","api_domain":"https://www.zohoapis.com","token_type":"Bearer","expires_in":3600}

10. 现在，在 JSON 输出中，您可以使用该access_token进行 API 调用来生成潜在客户，但您最好只获取该refresh_token并将其放入配置文件中，以便稍后在编程中使用。根据他们的文档，他们的refresh_token永远有效。您应该将其保存在极其安全的地方。

如何获取您的访问令牌

1. 现在您已经获得了refresh_token，每次需要进行 API 调用时，您都可以使用它来生成新的access_token 。为此，请使用类似于下面的 URL 进行另一个 Curl POST。以使用 Curl 的 Linux 命令行为例，它的外观如下：

curl "https://accounts.zoho.com/oauth/v2/token" \
-X POST \
-d "grant_type=refresh_token&refresh_token=1000.aaaa2683a1723d1aeb7b58899849aaaa.aaaa4c22481da67e85e598f4b988aaa&client_id=1000.AAAA0BSIC7C9AAAARILR3MGXBYAC8AAA&client_secret=aaa9aa9166055932ff8c0279c6253a65cb534daaaa"

以下是如何对参数进行 URL 编码的说明：

grant_type: refresh_token
refresh_token: {use the refresh_token (the one I said that would last forever) from your stored config file from step 10 in the previous steps}
client_id: {use your client_id}
client_secret: {use your client_secret} 

2. 运行上述命令应该会返回一些类似于以下内容的 JSON：

{"access_token":"1000.aaa1c95788b34226c2844a841bfd1d5.6aff70f4adbc3fee9e6b57579e481aaa","api_domain":"https://www.zohoapis.com","token_type":"Bearer","expires_in":3600}

3. 在您最喜欢的编程语言中，您将把收到的access_token存储在临时变量中，以便您可以进行 API 调用来执行添加 Zoho CRM 潜在客户等操作。该访问令牌将持续 3600 秒（1 小时），但实际上没有任何影响，因为您可以生成无限的访问令牌，因为您已将该刷新令牌存储在配置文件中。

如何创建 Zoho CRM 潜在客户

1. 在您最喜欢的编程语言中，您将使用该刷新令牌来创建访问令牌，然后将其用于以下标头以传递您的 API 调用：

Authorization: Zoho-oauthtoken XXXXXX

...其中 XXXXXX 是您从上一组指令收到的 access_token。

2. 以下是 PHP 中的示例，使用 file_get_contents（尽管您可以使用 PHP 的 Curl 执行相同操作）来发出添加 Zoho CRM 潜在客户的请求。您可以采用以下示例并用您最喜欢的编程语言对其进行重新编码。将 $sAccessToken 值更改为您生成的值。

请注意，下面我们还将写入一个名为“Lead Source”的字段，其 API 可访问名称为“Lead_Source”。（如果您最终更改下面的代码以写入联系人或帐户，那么您肯定需要创建一个自定义字段，以指示联系人或帐户的来源。例如，如果您有一个购物网站购物车，那么您可以表明该记录来自完成该交易，而不是来自致电的客户。）

<?php

error_reporting(E_ALL);
ini_set('display_errors','On');
header('Content-Type: text/plain');

$sAccessToken = '1000.aaaa5579abeea73871b096c941ec1df8.7835daaa3bbf5122f2d5810f0b65aaaa'; // change me
$sJSON = json_encode(array(
    'First_Name' => 'Mickey',
    'Last_Name' => 'Mouse',
    'Email' => 'mickey@example.com',
    'Phone' => '444-444-4444',
    'Lead_Source' => 'TEST1'
  ));
  $sJSON = str_replace('{','[{',$sJSON);
  $sJSON = str_replace('}','}]',$sJSON);
  $sJSON = '{"data":' . $sJSON . '}';
echo "SENDING: $sJSON\n";
$sURL = 'https://www.zohoapis.com/crm/v2/Leads';
$sResponse = @ file_get_contents($sURL,false,stream_context_create(array('http'=>array(
  'ignore_errors' => TRUE, // critical if you want to see errors in response instead of empty on error
  'method' => 'POST',
  'header' => array(
    'Content-Type: application/json',
    "Authorization: Zoho-oauthtoken $sAccessToken",
    'cache-control: no-cache'
  ),
  'content' => $sJSON
))));
echo "$sResponse\n";

如果成功，这将生成类似于以下内容的响应：

{"data":[{"code":"SUCCESS","details":{"Modified_Time":"2020-05-21T20:45:24-04:00","Modified_By":{"name":"John Manager","id":"9999889000000279991"},"Created_Time":"2020-05-21T20:45:24-04:00","id":"9999889000000279991","Created_By":{"name":"John Manager","id":"9999889000000279991"}},"message":"record added","status":"success"}]}

...其中 John Manager 是您登录 CRM 时使用的管理员级别用户帐户的名称。

有关 Zoho CRM 插入记录 API 的更多信息，请访问： https: //www.zoho.com/crm/developer/docs/api/insert-records.html

要了解在哪里可以找到 API 可寻址字段名称，请在 CRM 中转至：设置 > 开发人员空间 > API > API 名称 > 潜在客户。从“过滤依据”下拉列表中选择“字段”。

请注意，此 API 不会查找重复项。您可以调整上述内容来执行“upsert”而不是“插入”：https://www.zoho.com/crm/developer/docs/api/upsert-records.html

如果您编辑联系人和客户以使其具有与潜在客户相同的自定义字段，则您可以将该行更改https://www.zohoapis.com/crm/v2/Leads为https://www.zohoapis.com/crm/v2/Contacts或https://www.zohoapis.com/crm/v2/Accounts并向其中写入条目。