Если у вас еще нет amoCRM
Создать прямо сейчасМетод, позволяющий создавать и удалять дополнительные поля по одному или пакетно. Пользователь не сможет изменить их значения из интерфейса, но сможет фильтровать по ним и просматривать. Создание и удаление поля также возможно из интерфейса.
POST /api/v2/fields
| Параметр | Тип | Описание |
|---|---|---|
| add | array | Список добавляемых полей |
| delete | array | Список полей для удаления |
| add/name require |
string | Название поля |
| add/type | int | Тип поля |
| add/element_type | int | Тип сущности |
| add/origin require |
string | Уникальный идентификатор сервиса, по которому будет доступно удаление и изменение поля |
| add/is_editable | bool | |
| add/enums | array(string) | Массив значений для списка или мультисписка. Значения указываются строковыми переменными, через запятую. |
| add/request_id | int | Уникальный идентификатор записи в клиентской программе (необязательный параметр). Информация о request_id нигде не сохраняется. |
| add/is_required | bool | Обязательность заполнения поля Данное свойство применимо только для полей списка |
| add/is_deletable | bool | Возможность удалить поле в интерфейсе Данное свойство применимо только для полей списка |
| add/is_visible | bool | Видимость поля в интерфейсе Данное свойство применимо только для полей списка |
| delete/id require |
int | Уникальный идентификатор поля, который указывается с целью его удаления |
| delete/origin require |
string | Уникальный идентификатор сервиса по которому будет доступно удаление и изменение поля |
| Параметр | Описание |
|---|---|
| 1 | Контакт |
| 2 | Сделка |
| 3 | Компания |
| id | Каталог. В качестве параметра необходимо передавать id каталога |
| 12 | Покупатель |
| Параметр | Код | Описание |
|---|---|---|
| 1 | TEXT | Обычное текстовое поле |
| 2 | NUMERIC | Текстовое поле с возможностью передавать только цифры |
| 3 | CHECKBOX | Поле обозначающее только наличие или отсутствие свойства (например: “да”/”нет”) |
| 4 | SELECT | Поле типа список с возможностью выбора одного элемента |
| 5 | MULTISELECT | Поле типа список c возможностью выбора нескольких элементов списка |
| 6 | DATE | Поле типа дата возвращает и принимает значения в формате (Y-m-d H:i:s) |
| 7 | URL | Обычное текстовое поле предназначенное для ввода URL адресов |
| 8 | MULTITEXT | Поле textarea содержащее большое количество текста |
| 9 | TEXTAREA | Поле textarea содержащее большое количество текста |
| 10 | RADIOBUTTON | Поле типа переключатель |
| 11 | STREETADDRESS | Короткое поле адрес |
| 13 | SMART_ADDRESS | Поле адрес (в интерфейсе является набором из нескольких полей) |
| 14 | BIRTHDAY | Поле типа дата поиск по которому осуществляется без учета года, значения в формате (Y-m-d H:i:s) |
| 15 | LEGAL_ENTITY | Поле юридическое лицо (в интерфейсе является набором из нескольких полей) |
| 16 | ITEMS | Поле состав каталога (поле доступно только в пользовательских списках) |
| 17 | ORG_LEGAL_NAME | Поле организации |
Запрос на добавление нового дополнительного поля.
{
add: [{
name: "Выбор цветов",
type: "5",
element_type: "2",
origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
is_editable: "0",
enums: [
"чёрный",
"белый",
"красный",
"жёлтый",
"синий",
"зелёный"
]
}]
}
Запрос на удаление дополнительного поля.
{
delete: [{
id: "441506",
origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget"
}]
}
| Параметр | Описание |
|---|---|
| id | Уникальный идентификатор новой сущности |
| request_id | Уникальный идентификатор сущности в клиентской программе, если request_id не передан в запросе, то он генерируется автоматически |
| _links | Массив, содержащий информацию о запросе |
| _links/self | Массив, содержащий информацию о текущем запросе |
| _links/self/href | Относительный URL текущего запроса |
| _links/self/method | Метод текущего запроса |
| _embedded | Массив, содержащий информацию прилегающую к запросу |
| _embedded/items | Массив, содержащий информацию по каждому отдельному элементу |
Response Headeres содержит следующие заголовки:
{
_link: {
self: {
href: "/api/v2/fields",
method: "post"
}
},
_embedded: {
items: [{
id: 4400161,
_link: {
self: {
href: "/api/v2/fields?id=4400161",
method: "get"
}
}
}]
}
}
Для добавления дополнительного поля необходимо описать массив, содержащий информацию о дополнительном поле и поместить его в массив следующего вида: $fields[‘add’]. Наше API также поддерживает одновременное добавление сразу нескольких полей. Для этого мы помещаем в массив $fields[‘add’] несколько массивов, каждый из которых описывает необходимые данные для добавления соответствующего дополнительного поля.
$fields['add'] = array(
array(
'name' => "Выбор цветов",
'type' => 5,
'element_type' => 2,
'origin' => "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
'is_editable' => 0,
'enums' => array(
"чёрный",
"белый",
"красный",
"жёлтый",
"синий",
"зелёный",
),
),
);
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test'; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/fields';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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($fields));
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;
В данном разделе вы узнаете, как правильно заполнить значения дополнительных полей в зависимости от их типа.
| Параметр | Тип | Описание |
|---|---|---|
| id require |
int | id дополнительного поля |
| values require |
array | Массив значений дополнительного поля |
| value require |
int/string | Значение поля |
| enum | int/string | Значение сущности поля |
Пример добавления значений дополнительных полей, на примере создания нового элемента сущности “Сделка”. Структура части кода запроса, отвечающая за значения дополнительных полей, будет такой же для всех остальных сущностей.
$leads['add'] = array(
array(
'name' => 'Test_deal',
//'date_create'=>123456789, //дата создания
'status_id' => 142, //Статус сделки
'sale' => 1000, //Бюджет
'responsible_user_id' => 215302,
'tags' => 'test, fields', //теги
"custom_fields" => [
[
"id" => 6223784, // id поля
"values" => [
[
"value" => "791112345", //Поле типа текст
],
],
],
[
"id" => 644732, //id поля
"values" => [
[
"value" => 1519210, //Поле типа список, в качестве значения принимает значения параметра enum
],
],
],
[
"id" => 666558, //id поля
"values" => [
[
"value" => "TEXT", //Поле типа текст
],
],
],
[
"id" => 691604, //id поля
"values" => [
[
"value" => 1, // Тип поля checkbox, допустимые значения 0 или 1
],
],
],
[
"id" => 691606, //id поля
"values" => [
[
"value" => "1999/10/21", //Поле типа дата, значение поля в виде YYYY/MM/DD
],
],
],
[
"id" => 692250, //id поля
"values" => [1662884, 1662886], //Поле типа мультисписок (может принимать массив значений)
],
[
"id" => 692257, //id поля
"values" => [ //Поле типа юридическое лицо (может принимать массив значений)
[
"value" => [ //Поле принимает массив значений
"name" => "ООО 'ШОКОЛАДНИЦА'", // Наименование организации. Обязательный параметр для заполнения
"entity_type" => 2, // Тип юр.лица: 1 - ИП, 2 - Юридическое лицо.
"vat_id" => 5009051111, // ИНН
"kpp" => 500901001, // КПП
"address" => "142004, МОСКОВСКАЯ ОБЛ, ДОМОДЕДОВО Г, ЦЕНТРАЛЬНЫЙ МКР, ШКОЛЬНАЯ УЛ, ДОМ 23,
ПОМЕЩЕНИЕ 2", // Адресс
"external_id" => "46b44a52-2a14-458f-92dd-280a3c6af8c8", // Uuid
],
],
],
],
],
),
);
$catalog_element["add"] = [
[
"name" => "00AM-000034",
"catalog_id" => 4966,
"custom_fields" => [
[
"id" => 4411241, // id поля
"values" => [ // Поле типа состав списка (может принимать массив значений)
[
"description" => "Кофе", // Наименование товара
"unit_price" => 1500, // Цена за единицу товара
"unit_type" => "шт", // Единица измерения
"quantity" => 10, // Кол-во товара
"discount" => [ // Скидка
"type" => "amount", // Тип скидки: amount - количественная, percentage - процентная
"value" => 100, // Размер скидки
],
"vat_rate_id" => 3, // ID размера НДС. Список возможных значений можно получить, воспользовавшись методом /api/v2/account?with=custom_fields после создания поля
"external_uid" => '7466efa8-3671-11e8-318c-0050568904f0', // Uuid товара (необязательный параметр)
],
],
],
],
],
];