Дополнительные поля

Метод, позволяющий создавать и удалять дополнительные поля по одному или пакетно. Пользователь не сможет изменить их значения из интерфейса, но сможет фильтровать по ним и просматривать. Создание и удаление поля также возможно из интерфейса.

Создание и удаление дополнительных полей

URL метода
POST /api/v2/fields

Параметры

Параметр Тип Описание
add array Список добавляемых полей
delete array Список полей для удаления
add/name
require
string Название поля
add/field_type int Тип поля
add/element_type int Тип сущности
add/origin
require
string Уникальный идентификатор сервиса, по которому будет доступно удаление и изменение поля
add/is_editable bool
add/enums array(string) Массив значений для списка или мультисписка. Значения указываются строковыми переменными, через запятую.
add/request_id int Уникальный идентификатор записи в клиентской программе (необязательный параметр). Информация о request_id нигде не сохраняется.
delete/id
require
int Уникальный идентификатор поля, который указывается с целью его удаления
delete/origin
require
string Уникальный идентификатор сервиса по которому будет доступно удаление и изменение поля

Тип сущности

Параметр Описание
1 Контакт
2 Сделка
3 Компания
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)

Запрос на добавление нового дополнительного поля.

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

  1. {
  2.       add: [
  3.          {
  4.             name: "Выбор цветов",
  5.             field_type: "5",
  6.             element_type: "2",
  7.             origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
  8.             is_editable: "0",
  9.             enums: [
  10.                "чёрный",
  11.                "белый",
  12.                "красный",
  13.                "жёлтый",
  14.                "синий",
  15.                "зелёный"
  16.             ]
  17.          }
  18.       ]
  19.    }

Запрос на удаление дополнительного поля.

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

  1. {
  2.    delete: [
  3.       {
  4.          id: "441506",
  5.          origin: "528d0285c1f9180911159a9dc6f759b3_zendesk_widget"
  6.       }
  7.    ]
  8. }

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

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

Response Headeres содержит следующие заголовки:

  • Content-Type:application/hal+json
  • Runtime-Timestamp:1508320306

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

  1. {
  2.    _link: {
  3.       self: {
  4.          href: "/api/v2/fields",
  5.          method: "post"
  6.       }
  7.    },
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 4400161,
  12.             _link: {
  13.                self: {
  14.                   href: "/api/v2/fields?id=4400161",
  15.                   method: "get"
  16.                }
  17.             }
  18.          }
  19.       ]
  20.    }
  21. }

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

Для добавления дополнительного поля необходимо описать массив, содержащий информацию о дополнительном поле и поместить его в массив следующего вида: $fields['add']. Наше API также поддерживает одновременное добавление сразу нескольких полей. Для этого мы помещаем в массив $fields['add'] несколько массивов, каждый из которых описывает необходимые данные для добавления соответствующего дополнительного поля.

  1. $fields['add'] = array(
  2.    array(
  3.       'name' => "Выбор цветов",
  4.       'field_type'=> 5,
  5.       'element_type' => 2,
  6.       'origin' => "528d0285c1f9180911159a9dc6f759b3_zendesk_widget",
  7.       'is_editable' => 0,
  8.       'enums' => array(
  9.          "чёрный",
  10.          "белый",
  11.          "красный",
  12.          "жёлтый",
  13.          "синий",
  14.          "зелёный"
  15.       )
  16.    )
  17. )
  18. );
  19. /* Теперь подготовим данные, необходимые для запроса к серверу */
  20. $subdomain='test'; #Наш аккаунт - поддомен
  21. #Формируем ссылку для запроса
  22. $link='https://'.$subdomain.'.amocrm.ru/api/v2/fields';
  23. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  24. работе с этой
  25. библиотекой Вы можете прочитать в мануале. */
  26. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  27. #Устанавливаем необходимые опции для сеанса cURL
  28. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  29. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  30. curl_setopt($curl,CURLOPT_URL,$link);
  31. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  32. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($fields));
  33. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  34. curl_setopt($curl,CURLOPT_HEADER,false);
  35. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  36. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  37. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  38. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  39. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  40. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  41. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  42. $code=(int)$code;
  43. $errors=array(
  44.   301=>'Moved permanently',
  45.   400=>'Bad request',
  46.   401=>'Unauthorized',
  47.   403=>'Forbidden',
  48.   404=>'Not found',
  49.   500=>'Internal server error',
  50.   502=>'Bad gateway',
  51.   503=>'Service unavailable'
  52. );
  53. try
  54. {
  55.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  56.  if($code!=200 && $code!=204)
  57.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  58. }
  59. catch(Exception $E)
  60. {
  61.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  62. }
  63. /*
  64.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  65.  нам придётся перевести ответ в формат, понятный PHP
  66.  */
  67. $Response=json_decode($out,true);
  68. $Response=$Response[_embedded']['items'];
  69. $output='ID добавленных полей:'.PHP_EOL;
  70. foreach($Response as $v)
  71.  if(is_array($v))
  72.    $output.=$v['id'].PHP_EOL;
  73. return $output;

Значения дополнительных полей

В данном разделе вы узнаете, как правильно заполнить значения дополнительных полей в зависимости от их типа.

  • Перед работой с дополнительными полями вам необходимо узнать id и тип поля методом аккаунт.
  • Обратите внимание на вложенность массивов.
  • В значение "enum" записывается id enum'a, а не его значение.
  • При использовании стандартных полей можно записывать значение данного enum'a, например: 'WORK','SKYPE'.

Параметры

Параметр Тип Описание
id
require
int id дополнительного поля
values
require
array Массив значений дополнительного поля
value
require
int/string Значение поля
enum int/string Значение сущности поля

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

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

  1. $leads['add'] = array(
  2.     array(
  3.         'name'=>'Test_deal',
  4.         //'date_create'=>123456789, //дата создания
  5.         'status_id'=>142,       //Статус сделки
  6.         'sale'=>1000,        //Бюджет
  7.         'responsible_user_id'=>215302,
  8.         'tags' => 'test, fields',  //теги
  9.         "custom_fields"=>[
  10.             [
  11.             "id"=>6223784,     // id поля
  12.             "values"=> [
  13.                 [
  14.                     "value"=>"791112345" //Поле типа текст
  15.                 ]
  16.  
  17.               ]
  18.             ],
  19.             [
  20.             "id"=>644732,           //id поля
  21.             "values"=> [
  22.                 [
  23.                     "value"=>1519210  //Поле типа список, в качестве значения принимает значения параметра enum
  24.                 ]
  25.               ]
  26.             ],
  27.             [
  28.                 "id"=>666558,   //id поля
  29.                 "values"=> [
  30.                     [
  31.                         "value"=>"TEXT" //Поле типа текст
  32.                     ]
  33.                 ]
  34.             ],
  35.             [
  36.                 "id"=>691604,   //id поля
  37.                 "values"=> [
  38.                     [
  39.                         "value"=>1  // Тип поля checkbox, допустимые значения 0 или 1
  40.                     ]
  41.                 ]
  42.             ],
  43.             [
  44.                 "id"=>691606,       //id поля
  45.                 "values"=> [
  46.                     [
  47.                         "value"=>"1999/10/21"   //Поле типа дата, значение поля в виде YYYY/MM/DD
  48.                     ]
  49.                 ]
  50.             ],
  51.             [
  52.                 "id"=>692250,       //id поля
  53.                 "values"=> [1662884,1662886]    //Поле типа мультисписок (может принимать массив значений)
  54.             ],
  55.         ]
  56.     )
  57. );