Если у вас еще нет amoCRM
Создать прямо сейчасПолностью аналогична сущности “контакт”. Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждая компания может участвовать в одной и более сделке или может быть вообще не связана ни с одной.
E-mail и телефон используются как идентификаторы в связке с другими системами
Каждой компании может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.
Метод позволяет добавлять компании по одной или пакетно, а также обновлять данные по уже существующим компаниям.
POST /api/v2/companies
Параметр | Тип | Описание |
---|---|---|
add | array | Список добавляемых компаний |
update | array | Список существующих компаний, в которые будут заноситься изменения. Все, описанные параметры для add, актуальны также для update |
add/name require |
string | Название компании |
add/created_at | timestamp | Дата и время создания компании |
add/updated_at | timestamp | Дата и время изменения компании |
add/responsible_user_id | int | ID пользователя ответственного за компанию |
add/created_by | int | ID пользователя создавшего компанию |
add/tags | string | Теги, привязываемые к компании. Задаются целостной строковой переменной, внутри строки перечисляются через запятую. |
add/leads_id | string | Сделки, привязываемые к компании. Перечисляются id через запятую. |
add/customers_id | string | Покупатели, привязываемые к компании. Перечисляются id через запятую. |
add/contacts_id | array | Массив контактов, привязываемых к компании. |
add/custom_fields | array | Массив дополнительных полей сущности |
add/custom_fields//id | int | ID дополнительного поля сущности |
add/custom_fields//values | array | Массив значений |
add/custom_fields//values//value | string | Значение дополнительного поля |
add/custom_fields//values//enum | string | Идентификатор раннее предустановленного варианта выбора для списка или мультисписка |
add/custom_fields//values//subtype | string | Тип изменяемого элемента дополнительного поля типа “адрес”. Внимание, все неуказанные типы будут стёрты. |
update/id require |
int | ID компании, в которую будут вноситься изменения |
update/updated_at require |
timestamp | Дата и время изменения |
update/unlink | array | Массив, содержащий информацию для открепления компании от других элементов сущностей. |
update/unlink/contacts_id | array | Массив id открепляемых контактов |
update/unlink/leads_id | array | Массив id открепляемых сделок |
update/unlink/customers_id | array | Массив id открепляемых покупателей |
Приведём пример запроса на добавление новой компании.
{
add: [{
name: "ООО Компания",
responsible_user_id: "504141",
created_by: "504141",
created_at: "1509051600",
tags: "недвижимость,застройка,аренда",
leads_id: [
"45615",
"43510"
],
custom_fields: [{
id: "4396817",
values: [{
value: "5"
}]
},
{
id: "4396818",
values: [{
value: "89999517535",
enum: "WORK"
},
{
value: "89991237895",
enum: "MOB"
}
]
},
{
id: "4396819",
values: [{
value: "company@company.moc",
enum: "WORK"
}]
},
{
id: "4396820",
values: [{
value: "company.moc"
}]
},
{
id: "4400115",
values: [{
value: "ул. Октябрьская, д. 2",
subtype: "address_line_1"
},
{
value: "Москва",
subtype: "city"
},
{
value: "102030",
subtype: "zip"
},
{
value: "RU",
subtype: "country"
}
]
}
]
}]
}
Приведём пример запроса на обновление компании.
{
update: [{
id: "41389",
updated_at: "1508965200",
custom_fields: [{
id: "315289",
values: [{
value: "example.moc",
enum: "WEB"
}]
}]
}]
}
Параметр | Описание |
---|---|
id | Уникальный идентификатор нового элемента сущности |
request_id | Уникальный идентификатор сущности в клиентской программе, если request_id не передан в запросе, то он генерируется автоматически |
_links | Массив, содержащий информацию о запросе |
_links/self | Массив, содержащий информацию о текущем запросе |
_links/self/href | Относительный URL текущего запроса |
_links/self/method | Метод текущего запроса |
_embedded | Массив, содержащий информацию прилегающую к запросу |
_embedded/items | Массив, содержащий информацию по каждому отдельному элементу |
Response Headeres содержит следующие заголовки:
{
_links: {
self: {
href: "/api/v2/companies",
method: "post"
}
},
_embedded: {
items: [{
id: 1099264,
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
}
}]
}
}
Для добавления компании необходимо описать массив, содержащий информацию о компании, и поместить его в массив следующего вида: $companies[‘add’]. Наше API также поддерживает одновременное добавление сразу нескольких компаний. Для этого мы помещаем в массив $companies[‘add’] несколько массивов, каждый из которых описывает необходимые данные для создания соответствующего контакта.
$companies['add'] = array(
array(
'name' => 'ООО Компания',
'responsible_user_id' => 504141,
'created_by' => 504141,
'created_at' => "1509051600",
'tags' => "недвижимость,застройка,аренда",
'leads_id' => array(
"45615",
"43510",
),
'custom_fields' => array(
array(
'id' => 4396818,
'values' => array(
array(
'value' => "89993456872",
'enum' => "WORK",
),
array(
'value' => "89998495162",
'enum' => "MOB",
),
),
),
array(
'id' => 4396819,
'values' => array(
array(
'value' => "company@company.moc",
'enum' => "WORK",
),
),
),
array(
'id' => 4400115,
'values' => array(
array(
'value' => "ул. Октябрьская, д. 2",
'subtype' => "address_line_1",
),
array(
'value' => "Москва",
'subtype' => "city",
),
array(
'value' => "102030",
'subtype' => "zip",
),
array(
'value' => "RU",
'subtype' => "country",
),
),
),
array(
'id' => 3789654,
'values' => array(
"2615948",
"2648159",
"2653867",
),
),
),
),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($companies));
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());
}
/*
Данные получаем в формате JSON, поэтому, для получения читаемых данных,
нам придётся перевести ответ в формат, понятный PHP
*/
$Response = json_decode($out, true);
$Response = $Response['_embedded']['items'];
$output = 'ID добавленных контактов: ' . PHP_EOL;
foreach ($Response as $v) {
if (is_array($v)) {
$output .= $v['id'] . PHP_EOL;
}
}
return $output;
Метод для получения списка компаний с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице (offset) данным – 500 компаний.
GET /api/v2/companies
Параметр | Описание |
---|---|
limit_rows | Кол-во выбираемых строк (системное ограничение 500) |
limit_offset | Сдвиг выборки (с какой строки выбирать). Работает только при условии, если limit_rows указан |
id | Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID |
query | Поисковый запрос (Осуществляет поиск по заполненным полям сущности) |
responsible_user_id | Дополнительный фильтр поиска, по ответственному пользователю (Можно передавать в виде массива) |
Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y H:i:s. При передаче этого заголовка будут возвращены сделки, изменённые позже этой даты. Заголовок должен быть передан в часовом поясе UTC.
curl_setopt($curl, CURLOPT_HTTPHEADER, array('IF-MODIFIED-SINCE: Mon, 01 Aug 2017 07:07:23 UTC'));
Параметр | Тип | Описание |
---|---|---|
id | int | Уникальный идентификатор компании |
name | string | Название компании |
responsible_user_id | int | id ответственного пользователя |
created_by | int | id пользователя создавшего компанию |
created_at | timestamp | Время и дата создания компании |
updated_at | timestamp | Время и дата изменения компании |
account_id | int | id аккаунта на котором создана компания |
updated_by | int | id пользователя обновившего компанию |
group_id | int | id группы в которой состоит пользователь ответственный за данную компнаию |
contacts | array | Массив, содержащий информацию о контактах, которые прикреплены к данной компании |
contacts/id | int | id контакта, который прикреплён к данной компании |
leads | array | Массив, содержащий информацию о сделках, которые прикреплены к данной компании |
leads/id | int | id сделки, которая прикреплена к данной компании |
closest_task_at | int | Время ближайшей задачи по данной компании |
tags | array | Массив, содержащий информацию по тегам, прикреплённым к данной компании |
tags/id | int | id тега, прикреплённого к данной компании |
tags/name | string | Название тега, прикреплённого к данной компании |
custom_fields | array | Массив, содержащий информацию по дополнительным полям, заданным для данной компании |
custom_fields//id | int | id дополнительного поля |
custom_fields//name | string | Название дополнительного поля |
custom_fields//values | array | Массив, содержащий информацию по дополнительным полям, заданным для данной компании |
custom_fields//values//value | string | Значение дополнительного поля |
custom_fields//values//enum | string | Идентификатор раннее предустановленного варианта выбора для списка или мультисписка |
custom_fields//values//subtype | string | Идентификатор значений дополнительного поля “адрес” |
custom_fields//is_system | bool | Является ли дополнительное поле системным |
customers | array | Массив, содержащий информацию о покупателях, которые прикреплены к данной компании |
customers/id | int | id покупателя, прикреплённого к данной компании |
_links | array | Массив, содержащий информацию о запросе |
_links/self | array | Массив, содержащий информацию о текущем запросе |
_links/self/href | string | Относительный URL текущего запроса |
_links/self/method | string | Метод текущего запроса |
_embedded | array | Массив, содержащий информацию прилегающую к запросу |
_embedded/items | array | Массив, содержащий информацию по каждому отдельному элементу |
Response Headeres содержит следующие заголовки:
{
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
},
_embedded: {
items: [{
id: 1099264,
name: "ООО Компания",
responsible_user_id: 504141,
created_by: 504141,
created_at: 1508965200,
updated_at: 1509028320,
account_id: 13667499,
updated_by: 504141,
group_id: 0,
leads: {
id: [
1090408,
1090409,
1090410
],
_links: {
self: {
href: "/api/v2/leads?id=1090408,1090409,1090410",
method: "get"
}
}
},
closest_task_at: 0,
tags: [{
id: 61883,
name: "недвижимость"
},
{
id: 61884,
name: "застройка"
},
{
id: 61885,
name: "аренда"
}
],
custom_fields: [{
id: 4396818,
name: "Телефон",
values: [{
value: "89999517535",
enum: "3685087"
},
{
value: "89991237895",
enum: "3685089"
}
],
is_system: true
},
{
id: 4396819,
name: "Email",
values: [{
value: "company@company.moc",
enum: "3685093"
}],
is_system: true
},
{
id: 4396820,
name: "Web",
values: [{
value: http: //company.moc
}],
is_system: true
}
],
contacts: {
id: [
1099181,
1099268,
1099269
],
_links: {
self: {
href: "/api/v2/contacts?id=1099181,1099268,1099269",
method: "get"
}
}
},
customers: [],
_links: {
self: {
href: "/api/v2/companies?id=1099264",
method: "get"
}
}
}]
}
}
/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies';
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
документацию).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
необходимо. */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies?limit_rows=15';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/companies?limit_rows=15&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);
$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/* Вы также можете передать дополнительный HTTP-заголовок IF-MODIFIED-SINCE, в котором указывается дата в формате D, d M Y
H:i:s. При
передаче этого заголовка будут возвращены контакты, изменённые позже этой даты. */
curl_setopt($curl, CURLOPT_HTTPHEADER, array('IF-MODIFIED-SINCE: Mon, 01 Aug 2013 07:07:23'));
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$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());
}
/*
Данные получаем в формате JSON, поэтому, для получения читаемых данных,
нам придётся перевести ответ в формат, понятный PHP
*/
$Response = json_decode($out, true);
$Response = $Response['_embedded']['items'];