README

Insightly PHP SDK允许PHP开发者快速将应用程序与Insightly REST API（版本2.1）集成。

注意：此SDK当前仅适用于Insightly API的版本2.1。要使用版本2.2，您需要修改此库，或者您可以使用Swagger（www.swagger.io）来自动生成SDK（它可以为十多种不同的目标语言生成SDK）。

注意：最佳搭配PHP版本7.x或5.6.x。

该库处理底层通信、身份验证和编码，以减少新用户的学习曲线和调试开销。该库提供读取/写入/删除所有主要Insightly对象的能力，包括

联系人
事件
组织
机会
项目

要使用该库，只需将Insightly.php添加到您的PHP包含路径。然后进行请求就像

require_once "vendor/autoload.php";

$insightly = new Ryantxr\Insightly\Client('your-api-key');
$contacts = $insightly->getContacts();

添加潜在客户

$insightly = new Ryantxr\Insightly\Client('your-api-key');

$tags = [
    (object)["TAG_NAME" => 'first_tag'],
    (object)["TAG_NAME" => 'second_tag']
]; // add multiple tags if you want
$arr = [
        'FIRST_NAME' => 'Jimmy', // add the person's first and last name
        'LAST_NAME' => 'Hollow', // 
        'ORGANIZATION_NAME' => 'Put-Organization-Name-Here',
        'PHONE_NUMBER' => '555-555-5555',
        'EMAIL_ADDRESS' => 'Put-Email-Here',
        'TAGS' => $tags,
        'LEAD_SOURCE_ID' => 9999999 // Get the real value for the source you want to use
        ];
$lead = $insightly->addLead((object)$arr);

使用模式

创建/更新操作

这些方法期望一个包含有效数据字段的对象。如果成功，它们将返回一个包含存储在服务器上的对象的字典，或者在创建/更新请求失败时引发异常。您可以通过设置记录ID为0或省略它来指示是否要创建新项目。

要获取示例对象，您可以执行以下操作

$contact = $i->addContact('sample');
$event = $i->addEvent('sample');
$organization = $i->addOrganization('sample');
$project = $i->addProject('sample');

这将返回您的账户中的一个随机项目，因此您可以看到所需字段以及代表性的字段值。

搜索操作

这些方法返回包含匹配项目的字典列表。例如，要请求所有联系人的列表，您可以调用

$contacts = $i->getContacts();

使用ODATA的搜索操作

搜索方法识别top、skip、orderby和filters参数，您可以使用它们来分页、排序和筛选记录集。这些参数通过关联数组传递

// get the first 200 contacts   
$contacts = $i->getContacts(array("top" => 200));

// get the first 200 contacts, in first name descending order
$contacts = $i->getContacts(array("orderby" => 'FIRST_NAME desc', "top" => 200));

// get 200 records, after skipping the first 200 records
$contacts = $i->getContacts(array("top" => 200, "skip" => 200));

// get contacts where FIRST_NAME='Brian'
$contacts = $i->getContacts(array("filters" => array('FIRST_NAME=\'Brian\'')));

重要提示：当使用ODATA过滤器时，请确保在搜索词周围包含转义引号。否则，您将收到400（错误请求）错误。

如果查找失败，这些方法将引发异常，或者在成功时返回（可能为空）的对象列表。

读取操作（单个项目）

这些方法将返回包含请求项目属性的单一对象。

$contact = $i->getContact(123456);

删除操作

这些方法在成功时将返回True，或者在失败时引发异常。例如。

$success = $i->deleteContact(123456)

图像和文件附件管理

用于管理图像和文件附件的API调用尚未在PHP库中实现。但是，您可以直接通过我们的REST API直接访问这些内容

需要注意的问题

此库使集成Insightly变得容易，并通过为您自动处理HTTPS请求，消除了用户问题中最常见的诱因。话虽如此，该服务对拒绝没有所需字段或具有无效字段值（例如无效的USER_ID）的请求非常挑剔。在这种情况下，您最好的办法是查阅API文档并查看所需请求数据。

编写/更新方法还包含一个模拟功能，可以返回您可以将其用作起始点的样本对象。例如，要获取样本任务对象，只需调用

$task = $i->addTask('sample');

这将返回您的Insightly账户中的一个任务，这样您就可以了解使用的字段和值。

如果您正在处理大量记录集，我们强烈建议您使用ODATA函数，如top和skip，来遍历记录集，而不是一次性尝试获取整个记录集。这不仅提高了客户端/服务器通信，还减少了您端的内存需求。

故障排除技巧

API用户在编写/更新操作过程中遇到的主要问题是400错误（错误请求），这是由于缺少必需的字段。如果您不清楚服务器期望什么，一个好的故障排除方法是进行以下操作

使用Web界面，创建相关的对象（联系人、项目、团队等），并添加样本数据和子元素
使用相应的getNNNN()方法通过Web API检索此对象
检查对象的内容和结构

API的读取操作通常相当简单，因此如果您在写入操作中遇到困难，这是一个很好的解决方案，因为您可能只是缺少必需的字段或在使用诸如联系人的链接时使用无效的元素ID。

该库是使用PHP标准库构建的。（无需第三方工具，因此它可以在大多数PHP环境中直接运行）。包装函数返回原生PHP对象（数组和对象），因此可以使用内置函数轻松地与它们一起工作。

API接口由Ryantxr\Insightly\Client类提供。请参阅源代码文档以获取更多信息。

该库由Nathan Davis编写，目前处于测试阶段。

ryantxr / insightly-php

维护者

详细信息