Работа с примечаниями

События

События предоставляют возможность добавлять дополнительную структурированную или неструктурированную информацию к элементу сущности. События бывают системные (исходящее смс, отправленное письмо, контакт создан и т.д.), созданные пользователем (примечания, файлы). События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате.

Зачастую события используются виджетами для добавления дополнительной информации к сделке или контакту, когда не очень удобно использовать дополнительные поля. События очень удобно использовать как лог, т.к. они всегда отображаются в хронологическом порядке в ленте и, если ваша информация привязана к дате (хронологии), то желательно использовать именно события.

Добавление и обновление событий

Метод позволяет добавлять новые или обновлять уже существующие события.

URL метода

POST /api/v2/notes

Параметры

Параметр	Тип	Описание
add	array	Список добавляемых событий
update	array	Обновление существующих событий. Все параметры, которые описаны в add действуют также и в update
add/element_id require	int	id элемента, в карточку которого будет добавлено событие
add/element_type require	int	Тип сущности элемента, в карточку которого будет добавлено событие. Доступные типы см. здесь
add/text require	string	Текст события
add/note_type require	int	Тип добавляемого события. Доступные типы см. здесь
add/created_at	timestamp	Дата и время создания события
add/updated_at	timestamp	Дата и время изменения события
add/responsible_user_id	int	id пользователя ответственного за событие. При ограничении прав доступа, только этому пользователю будут доступны внесения изменений в данное событие в карточке сущности.
add/params	int	Массив с передаваемой информацией для определённых типов событий. См. здесь.
update/id require	int	id изменяемого события
update/updated_at require	timestamp	Дата и время изменения события

Типы сущностей

Код	Описание
1	Контакт
2	Сделка
3	Компания
4	Задача. Для задачи доступен только тип события TASK_RESULT
12	Покупатель

Типы событий

Код	Тип	Описание
4	COMMON	Обычное примечание
13	TASK_RESULT	Результат по задаче
25	SYSTEM	Системное сообщение
102	SMS_IN	Входящее смс
103	SMS_OUT	Исходящее смс

Типы событий, для которых обязателен массив params

Тип	Структура	Описание
25	‘params’ => [ ‘text’ => ‘Текст системного сообщения’, ‘service’ => ‘Название сервиса’, ]	Для типа события “системное сообщение”, текст передаётся с помощью массива params, вместо параметра text.
102-103	‘params’ => [ ‘text’ => ‘Текст cмс сообщения’ ]	Для типа события “cмс сообщение”, текст передаётся с помощью массива params, вместо параметра text.
103	‘params’ => [ ‘phone’ => ‘Номер телефона’ ]	Для типа события “Исходящее сообщение” указывается параметр ‘phone’ в массиве с ключом ‘params’ для указания получателя сообщения.

Пример запроса

{
	add: [{
		element_id: "1099238",
		element_type: "1",
		text: "Примечание",
		note_type: "4",
		created_at: "1509570000",
		responsible_user_id: "504141",
		created_by: "504141"
	}],
	update: [{
		id: "3323256",
		updated_at: "1509656400",
		text: "Изменение примечания"
	}]
}

Параметры ответа

Параметр	Описание
id	Уникальный идентификатор новой сущности
request_id	Уникальный идентификатор сущности в клиентской программе, если request_id не передан в запросе, то он генерируется автоматически
_links	Массив, содержащий информацию о запросе
_links/self	Массив, содержащий информацию о текущем запросе
_links/self/href	Относительный URL текущего запроса
_links/self/method	Метод текущего запроса
_embedded	Массив, содержащий информацию прилегающую к запросу
_embedded/items	Массив, содержащий информацию по каждому отдельному элементу

Пример ответа

{
	add: [{
		element_id: "1099238",
		element_type: "1",
		text: "Примечание",
		note_type: "4",
		created_at: "1509570000",
		responsible_user_id: "504141",
		created_by: "504141"
	}],
	update: [{
		id: "3323256",
		updated_at: "1509656400",
		text: "Изменение примечания"
	}]
}

Пример интеграции

$data = array(
    'add' => array(
        0 => array(
            'element_id' => '1099238',
            'element_type' => '1',
            'text' => 'Примечание',
            'note_type' => '4',
            'created_at' => '1509570000',
            'responsible_user_id' => '504141',
            'created_by' => '504141',
        ),
    ),
);
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/notes';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_COOKIEFILE, dirname(__FILE__) . '/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl, CURLOPT_COOKIEJAR, dirname(__FILE__) . '/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int) $code;
$errors = array(
    301 => 'Moved permanently',
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable',
);
try
{
    #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
    if ($code != 200 && $code != 204) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error', $code);
    }

} catch (Exception $E) {
    die('Ошибка: ' . $E->getMessage() . PHP_EOL . 'Код ошибки: ' . $E->getCode());
}

Добавление звонков

Подробнее о том, как добавлять звонки вы можете узнать по этой ссылке.

Список событий

Метод для получения списка примечаний с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице (offset) данным – 500 записей.

URL метода

GET /api/v2/notes

Параметры запроса

Тип	Описание
type require	contact/lead/company/task Получение данных только для указанной сущности
id	Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID.
limit_rows	Кол-во выбираемых строк (системное ограничение 500)
limit_offset	Оффсет выборки (с какой строки выбирать). Работает, только при условии, если limit_rows тоже указан.
element_id	Уникальный идентификатор элемента сущности
note_type	Уникальный идентификатор контакта или сделки. Таблицу типов см. здесь.
if-modified-since	Выбрать события, изменённые от определённой даты. Данные нужно передавать в формате D, d M Y H:i:s через HTTP- заголовок.

Параметры ответа

Параметр	Тип	Описание
id	int	Уникальный идентификатор примечания
created_by	int	id пользователя, создавшего примечание
account_id	int	Уникальный идентификатор аккаунта
group_id	int	id группы, в которой состоит пользователь, имеющий отношение к событию
is_editable	bool	Можно ли изменять данное событие
element_id	int	id элемента, в карточку которого будет добавлено событие
element_type	int	Тип сущности элемента, в карточку которого будет добавлено событие. Доступные типы см. здесь
text	string	Текст события
note_type	int	Тип добавляемого события. Доступные типы см. здесь
created_at	timestamp	Дата и время создания события
updated_at	timestamp	Дата и время изменения события
responsible_user_id	int	id пользователя ответственного за событие. При ограничении прав доступа, только этому пользователю будут доступны внесения изменений в данное событие в карточке сущности.
params	array	Массив, содержащий параметры, обязателен для определённого типа событий. Типы событий см. здесь.
params/text	string	Текст системного примечания
params/service	string	Название сервиса добавившего системное примечание
_links	array	Массив, содержащий информацию о запросе
_links/self	array	Массив, содержащий информацию о текущем запросе
_links/self/href	string	Относительный URL текущего запроса
_links/self/method	string	Метод текущего запроса
_embedded	array	Массив, содержащий информацию прилегающую к запросу
_embedded/items	array	Массив, содержащий информацию по каждому отдельному элементу

Пример ответа

{
	_links: {
		self: {
			href: "/api/v2/notes?type=lead",
			method: "get"
		}
	},
	_embedded: {
		items: [{
				id: 3321308,
				responsible_user_id: 504141,
				created_by: 504141,
				created_at: 1508675473,
				updated_at: 1508675473,
				account_id: 13667499,
				group_id: 0,
				is_editable: false,
				element_id: 1090344,
				element_type: 2,
				attachment: "",
				note_type: 1,
				text: "Добавлен новый объект",
				_links: {
					self: {
						href: "/api/v2/notes?id=3321308&type=lead",
						method: "get"
					}
				}
			},
			{
				id: 3321625,
				responsible_user_id: 504141,
				created_by: 504141,
				created_at: 1509016950,
				updated_at: 1509016950,
				account_id: 13667499,
				group_id: 0,
				is_editable: false,
				element_id: 1090391,
				element_type: 2,
				attachment: "",
				note_type: 1,
				text: "Добавлен новый объект",
				_links: {
					self: {
						href: "/api/v2/notes?id=3321625&type=lead",
						method: "get"
					}
				}
			},
			{
				id: 3322827,
				responsible_user_id: 504141,
				created_by: 504141,
				created_at: 1509447477,
				updated_at: 1509447477,
				account_id: 13667499,
				group_id: 0,
				is_editable: false,
				element_id: 1090571,
				element_type: 2,
				attachment: "",
				note_type: 25,
				params: {
					text: "Какое-то системное примечание",
					service: "some_service",
				},
				_links: {
					self: {
						href: "/api/v2/notes?id=3322827&type=lead",
						method: "get"
					}
				}
			}
		]
	}
}

Пример интеграции

$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/notes?type=contact';
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
документацию).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как
Вам
необходимо. */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/notes?limit_rows=50';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/notes?type=contact&limit_rows=50';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/notes?limit_offset=2';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/notes?type=lead&limit_rows=50&limit_offset=2';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL
#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_COOKIEFILE, dirname(__FILE__) . '/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl, CURLOPT_COOKIEJAR, dirname(__FILE__) . '/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
/* Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M
Y
H:i:s. При
передаче этого заголовка, будут возвращены примечания, изменённые позже этой даты. */
curl_setopt($curl, CURLOPT_HTTPHEADER, array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 08:12:22'));
/* Выполняем запрос к серверу. */
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int) $code;
$errors = array(
    301 => 'Moved permanently',
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable',
);
try
{
    #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
    if ($code != 200 && $code != 204) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error', $code);
    }

} catch (Exception $E) {
    die('Ошибка: ' . $E->getMessage() . PHP_EOL . 'Код ошибки: ' . $E->getCode());
}