README

AmoCRM API 的简单包装。

功能

获取账户信息
获取对象列表
创建新对象
处理自定义字段
处理钩子

目前可查询以下对象

联系人 https://developers.amocrm.ru/rest_api/#contact
公司 https://developers.amocrm.ru/rest_api/#company
交易 https://developers.amocrm.ru/rest_api/#lead
任务 https://developers.amocrm.ru/rest_api/#tasks
事件 https://developers.amocrm.ru/rest_api/#event

要求

PHP >= 5.4
服务器上的 libcurl

安装

将以下内容添加到您的项目 composer.json 中的 "require" 块

"nabarabane/amocrm": "~1.1"

或在控制台输入

composer require nabarabane/amocrm:"~1.1"

准备工作及配置

在包根目录下创建 "config" 文件夹，并将两个文件放入其中

config@{您的 AmoCRM 域名}.php
{您的 AmoCRM 域名}@{请求用户邮箱}.key 文件夹必须可写，以便保存工作所需的 cookies。

配置文件用于存储您将用于工作的 AmoCRM 自定义字段编号，并应返回一个关联数组，例如

return [
	'ResponsibleUserId' => 330242, //ID ответственного менеджера
	'LeadStatusId' => 8156376, // ID первого статуса сделки
	'ContactFieldPhone' => 1426544, // ID поля номера телефона
	'ContactFieldEmail' => 1426546, // ID поля емейла
	'LeadFieldCustom' => 1740351, // ID кастомного поля сделки
	'LeadFieldCustomValue1' => 4055517, // ID первого значения кастомного поля сделки
	'LeadFieldCustomValue2' => 4055519 // ID второго значения кастомного поля сделки
];

您可以通过以下方式获取账户的字段编号

use AmoCRM\Handler;
use AmoCRM\Request;

require('autoload.php');

$api = new Handler('domain', 'user@example.com');
print_r($api->request(new Request(Request::INFO))->result);

页面将显示账户的所有信息。
选择所需的字段编号（用户编号、交易自定义字段编号等），并将其保存到配置文件中，使用您理解的名字。

密钥文件应包含所选用户的 API 密钥。

使用

获取数据

use \AmoCRM\Handler;
use \AmoCRM\Request;

require('autoload.php');

/* Создание экземпляра API, где "domain" - имя вашего домена в AmoCRM, а
"user@example.com" - email пользователя, от чьего имени будут совершаться запросы */
$api = new Handler('domain', 'user@example.com');

/* Создание экземляра запроса */

/* Вторым параметром можно передать дополнительные параметры поиска (смотрите в документации)
В этом примере мы ищем пользователя с номером телефона +7 916 111-11-11
Чтобы получить полный список, укажите пустой массив []
Третьим параметром указывается метод в формате [название объекта, метод] */
$request_get = new Request(Request::GET, ['query' => '79161111111'], ['contacts', 'list']);

/* Выполнение запроса */
$result = $api->request($request_get)->result;

/* Результат запроса сохраняется в свойстве "result" объекта \AmoCRM\Handler()
Содержит в себе объект, полученный от AmoCRM, какой конкретно - сверяйтесь с документацией для каждого метода
Ошибка запроса выбросит исключение */
$api->result == false, если ответ пустой (то есть контакты с таким телефоном не найдены) */

If-Modified-Since

您还可以传递额外的 "IF-MODIFIED-SINCE" 参数，该参数指定期格为 D, d M Y H:i:s 的日期。传递此参数时，将返回自该日期之后更改的实体。

$request_get = new Request(Request::GET, ['query' => '79161111111'], ['contacts', 'list']);
$request_get->setIfModifiedSince((new DateTime('2016-03-14'))->format(DateTime::RFC1123));
$result = $api->request($request_get)->result;

创建新对象

示例代码，涵盖库的所有功能

use \AmoCRM\Handler;
use \AmoCRM\Request;
use \AmoCRM\Lead;
use \AmoCRM\Contact;
use \AmoCRM\Note;
use \AmoCRM\Task;

require('autoload.php');

/* Предположим, пользователь ввел какие-то данные в форму на сайте */
$name = 'Пользователь';
$phone = '79161111111';
$email = 'user@user.com';
$message = 'Здравствуйте';

/* Оборачиваем в try{} catch(){}, чтобы отлавливать исключения */
try {
	$api = new Handler('domain', 'user@example.com');


	/* Создаем сделку,
	$api->config содержит в себе массив конфига,
	который вы создавали в начале */
	$lead = new Lead();
	$lead
		/* Название сделки */
		->setName('Заявка') 
		/* Назначаем ответственного менеджера */
		->setResponsibleUserId($api->config['ResponsibleUserId'])
		/* Кастомное поле */
		->setCustomField(
			$api->config['LeadFieldCustom'], // ID поля
			$api->config['LeadFieldCustomValue1'] // ID значения поля
		)
		/* Теги. Строка - если один тег, массив - если несколько */
		->setTags(['тег 1', 'тег 2'])
		/* Статус сделки */
		->setStatusId($api->config['LeadStatusId']);

	/* Отправляем данные в AmoCRM
	В случае успешного добавления в результате
	будет объект новой сделки */
	$api->request(new Request(Request::SET, $lead));

	/* Сохраняем ID новой сделки для использования в дальнейшем */
	$lead = $api->last_insert_id;


	/* Создаем контакт */
	$contact = new Contact();
	$contact
		/* Имя */
		->setName($name)
		/* Назначаем ответственного менеджера */
		->setResponsibleUserId($api->config['ResponsibleUserId'])
		/* Привязка созданной сделки к контакту */
		->setLinkedLeadsId($lead)
		/* Кастомные поля */
		->setCustomField(
			$api->config['ContactFieldPhone'],
			$phone, // Номер телефона
			'MOB' // MOB - это ENUM для этого поля, список доступных значений смотрите в информации об аккаунте
		) 
		->setCustomField(
			$api->config['ContactFieldEmail'],
			$email, // Email
			'WORK' // WORK - это ENUM для этого поля, список доступных значений смотрите в информации об аккаунте
		) 
		/* Теги. Строка - если один тег, массив - если несколько */
		->setTags(['тег контакта 1', 'тег контакта 2']);

	/* Проверяем по емейлу, есть ли пользователь в нашей базе */
	$api->request(new Request(Request::GET, ['query' => $email], ['contacts', 'list']));

	/* Если пользователя нет, вернется false, если есть - объект пользователя */
	$contact_exists = ($api->result) ? $api->result->contacts[0] : false;

	/* Если такой пользователь уже есть - мержим поля */
	if ($contact_exists) {
		$contact
			/* Указываем, что пользователь будет обновлен */
			->setUpdate($contact_exists->id, $contact_exists->last_modified + 1)
			/* Ответственного менеджера оставляем кто был */
			->setResponsibleUserId($contact_exists->responsible_user_id)
			/* Старые привязанные сделки тоже сохраняем */
			->setLinkedLeadsId($contact_exists->linked_leads_id);
	}


	/* Создаем заметку с сообщением из формы */
	$note = new Note();
	$note
		/* Привязка к созданной сделке*/
		->setElementId($lead)
		/* Тип привязки (к сделке или к контакту). Смотрите комментарии в Note.php */
		->setElementType(Note::TYPE_LEAD)
		/* Тип заметки (здесь - обычная текстовая). Смотрите комментарии в Note.php */
		->setNoteType(Note::COMMON)
		/* Текст заметки*/
		->setText($message);



	/* Создаем задачу для менеджера обработать заявку */
	$task = new Task();
	$task
		/* Привязка к созданной сделке */
		->setElementId($lead)
		/* Тип привязки (к сделке или к контакту) Смотрите комментарии в Task.php */
		->setElementType(Task::TYPE_LEAD)
		/* Тип задачи. Смотрите комментарии в Task.php */
		->setTaskType(Task::CALL)
		/* ID ответственного за задачу менеджера */
		->setResponsibleUserId($api->config['ResponsibleUserId'])
		/* Дедлайн задачи */
		->setCompleteTill(time() + 60 * 2)
		/* Текст задачи */
		->setText('Обработать заявку');


	/* Отправляем все в AmoCRM */
	$api->request(new Request(Request::SET, $contact));
	$api->request(new Request(Request::SET, $note));
	$api->request(new Request(Request::SET, $task));
} catch (\Exception $e) {
	echo $e->getMessage();
}

多对象上传

可以同时创建多个同一类型对象，并通过一个请求发送到 amoCRM

use \AmoCRM\Handler;
use \AmoCRM\Request;
use \AmoCRM\Lead;

require('autoload.php');

try {
	$api = new Handler('domain', 'user@example.com');

	/* Первая сделка */
	$lead1 = new Lead();
	$lead1
	    ->setName('Заявка 1') 
		->setResponsibleUserId($api->config['ResponsibleUserId'])
		->setStatusId($api->config['LeadStatusId']);
	
	/* Вторая сделка */
	$lead2 = new Lead();
	$lead2
	    ->setName('Заявка 2') 
		->setResponsibleUserId($api->config['ResponsibleUserId'])
		->setStatusId($api->config['LeadStatusId']);

	/* Отправляем данные в AmoCRM */
	$api->request(new Request(Request::SET, [$lead1, $lead2]));

调试

如果API请求出错，AmoCRM只返回错误编号，而不提供文本说明。
为了包含错误说明，请将处理器构造函数的第三个参数传递为"true"。

$api = new Handler('domain', 'user@example.com', true);

现在您将不仅能看到错误编号，还能看到这个编号的含义，从而简化调试过程。
启用此模式会在读取保存错误说明的文件的磁盘上创建额外的读取请求，因此请勿在生产环境中启用调试。

Webhooks

如何设置账户以使用Webhooks，请参阅这里。
为了成功处理AmoCRM向您的网站发送的请求，您需要在AmoCRM发送请求的文件中创建一个事件监听器，并定义在特定事件发生时将被调用的函数。

支持的事件列表

交易

leads-add 创建交易
leads-update 更新交易
leads-delete 删除交易
leads-status 更改交易状态
leads-responsible 更改交易负责人

联系信息

contacts-add 创建联系信息
contacts-update 更新联系信息
contacts-delete 删除联系信息

公司

companies-add 创建公司
companies-update 更新公司
companies-delete 删除公司

请注意，在更改交易状态或更改交易负责人时，AmoCRM会同时发送有关交易整体变更的信息，即代码对于 leads-status 和 leads-responsible 总是会与 leads-update 一起执行。

use \AmoCRM\Webhook;

require('autoload.php');

$listener = new Webhook();

/* Указываете обработчики событий
Callback-функция, передаваемая вторым параметром,
будет вызвана при наступлении соответстующего события */
$listener->on('leads-add', function($domain, $id, $data, $config) {
	/* Тут делаете, что нужно при этом событии
	
	Сюда передаются следующие параметры:
		$domain - название домена в AmoCRM, с которого пришло событие
		$id - ID сущности
		$data - массив полей сущности
		$config - конфиг этого домена (если вы создавали соответствующий файл, иначе - пустой массив) */
});

/* Если вы хотите назначить одинаковый обработчик нескольким событиям, можно сделать так */
$listener->on(['contacts-add', 'contacts-update'], function($domain, $id, $data, $config) {/* ... */});

/* Запуск слушателя */
$listener->listen();

nabarabane / amocrm

维护者

详细信息

README

功能

要求

安装

准备工作及配置

使用

获取数据

If-Modified-Since

创建新对象

多对象上传

调试

Webhooks

支持的事件列表

交易

联系信息

公司

nabarabane / amocrm

维护者

详细信息

README

功能

要求

安装

准备工作及配置

使用

获取数据

If-Modified-Since

创建新对象

多对象上传

调试

Webhooks

支持的 事件列表

交易

联系信息

公司

支持的事件列表