Добавление элементов

Методы элементов списка

Добавление, обновление и удаление элементов списка

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

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

URL метода

POST /api/v2/catalog_elements

Параметры

Параметр	Тип	Описание
add	array	Список добавляемых элементов списка
update	array	Обновление существующих элементов списка Все параметры, которые описанны в add действуют также и в update
delete	array	Массив удаляемых элементов списков
add[0][catalog_id] require	string	ID списка
add[0][name] require	string	Название элемента
add[0][request_id]	int	Уникальный идентификатор записи в клиентской программе, необязательный параметр (информация о request_id нигде не сохраняется)
add[0][custom_fields]	array	Дополнительные поля
add[0][custom_fields][0]	array	Внутри него будет описание каждого доп поля
add[0][custom_fields][0][id]	int	Уникальный идентификатор заполняемого дополнительного поля (см. Информация аккаунта)
add[0][custom_fields][0][values]	array	Внутри будет еще один массив, с описанием value
add[0][custom_fields][0][values]	array	Здесь будут описаны значения доп. поля, и, если нужно, дополнительный тип (для полей типа "мультисписок" просто перечисляем id выбранных значений)
add[0][custom_fields][0][values][0][value]	string	Значение дополнительного поля
add[0][custom_fields][0][values][0][enum]	string	Выбираемый тип дополнительного поля (например телефон домашний, рабочий и т. д.)
add[0][custom_fields][0][values][0][subtype]	string	Тип изменяемого элемента дополнительного поля. Внимание, все не указанные типы будут стёрты
update[0][id] require	int	Уникальный идентификатор элемента списка, который указывается с целью его обновления
update[0][updated_at] require	int	Уникальный идентификатор элемента списка, который указывается с целью его обновления

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

{
   add: [
      {
         catalog_id: "4220" ,
         name: "Карандаш" ,
         custom_fields: [
            {
               id: "4400050" ,
               values: [
                  {
                     value: "100"
                  }
               ]
            } ,
            {
               id: "4400062" ,
               values: [
                  "3692539" ,
                  "3692540"
               ]
            }
         ]
      }
   ]
}

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

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

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

{
   _link: {
      self: {
         href: "/api/v2/catalog_elements" ,
         method: "post"
      }
   } ,
   _embedded: {
      items: [
         {
            id: 41870 ,
            request_id: 0 ,
            _link: {
               self: {
                  href: "/api/v2/catalog_elements?id=41870" ,
                  method: "get"
               }
            }
         }
      ]
   }
}

Добавление элементов

Для создания нового элемента списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида: $catalog_elements[‘add’]

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

[Здесь]() можно посмотреть структуру кастомных полей на примере массива элемента списка.

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

$catalog_elements [ 'add' ] = array (
  array (
      'catalog_id' => 2534 ,
    'name' => 'Black iPhone' ,
  ) ,
  array (
      'catalog_id' => 2534 ,
    'name' => 'Really Black iPhone' ,
  )
) ;
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test' ; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements' ;
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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 ( $catalogs ) ) ;
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 ;

Обновление элементов

Для обновления элемента списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида: $catalog_elements[‘update’]

Наше API также поддерживает одновременное обновление сразу нескольких элементов списков. Для этого мы помещаем в массив $catalog_elements[‘update’] несколько массивов, каждый из которых описывает необходимые данные для обновления соответствующего элемента.

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

$catalog_elements [ 'update' ] = array (
  array (
      'catalog_id' => 2534 ,
    'id' => 35431 ,
    'name' => 'Explosive Galaxy Note 7' ,
  ) ,
  array (
    'catalog_id' => 2534 ,
    'id' => 35431 ,
    'name' => 'MacBook Pro 2016' ,
  )
) ;
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test' ; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements' ;
Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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 ( $catalog_elements ) ) ;
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 ( ) ) ;
}

Удаление элементов

Для удаления элемента списка необходимо описать массив, содержащий информацию о нём и поместить его в массив следующего вида $catalog_elements[‘delete’]

Наше API также поддерживает одновременное удаление сразу нескольких элементов списков. Для этого мы помещаем в массив $catalog_elements[‘delete’] несколько элементов, каждый из которых описывает необходимые данные для удаления соответствующего элемента.

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


$catalog_elements [ 'delete' ] = array (
  35159 ,
  35164
) ;
/* Теперь подготовим данные, необходимые для запроса к серверу */
$subdomain = 'test' ; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements' ;
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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 ( $catalog_elements ) ) ;
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 ( ) ) ;
}

Перечень элементов списка

Метод для получения элементов списка аккаунта.

URL метода

GET /api/v2/catalog_elements

Параметры GET

Параметр	Описание
id	Выбрать элемент с заданным id
catalog_id require	Выбрать данные из определенного списка
term	Поисковый запрос по названию элемента
page	Страница выборки

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

Параметр	Тип	Описание
id	int	Уникальный идентификатор элемента
name	string	Название элемента
created_at	timestamp	Дата создания
updated_at	timestamp	Дата изменения
catalog_id	int	id списка, в котором находится элемент
created_by	id	id пользователя, создавшего сделку
is_deleted	bool	Удалён элемент или нет
custom_fields	array	Массив дополнительных полей элемента списка
custom_fields[0][id]	int	Уникальный идентификатор дополнительного поля
custom_fields[0][name]	string	Название дополнительного поля
custom_fields[0][values]	array	Массив, значений текущего доп поля
custom_fields[0][values][0][value]	string	Значение текущего доп поля
custom_fields[0][values][0][enum]	string	Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
custom_fields[0][is_system]	bool	Является дополнительное поле системным или нет
_links	array	Массив содержащий информацию о запросе
_links[self]	array	Массив содержащий информацию о текущем запросе
_links[self][href]	string	Относительный URL текущего запроса
_links[self][method]	string	Метод текущего запроса
_embedded	array	Массив содержащий информацию прилегающую к запросу
_embedded[items]	array	Массив содержащий информацию по каждому отдельному элементу

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

{
   _links: {
      self: {
         href: "/api/v2/catalog_elements?catalog_id=4220" ,
         method: "get"
      }
   } ,
   _embedded: {
      items: [
         {
            id: 41873 ,
            name: "Маркеры" ,
            created_by: 504141 ,
            created_at: 1509003163 ,
            updated_at: 1509003163 ,
            updated_by: 504141 ,
            is_deleted: false ,
            custom_fields: [
               {
                  id: 4400049 ,
                  name: "Артикул" ,
                  values: [
                     {
                        value: "416"
                     }
                  ] ,
                  is_system: true
               } ,
               {
                  id: 4400050 ,
                  name: "Количество" ,
                  values: [
                     {
                        value: "250"
                     }
                  ] ,
                  is_system: true
               } ,
               {
                  id: 4400051 ,
                  name: "Цена" ,
                  values: [
                     {
                        value: "80"
                     }
                  ] ,
                  is_system: true
               } ,
               {
                  id: 4400062 ,
                  name: "Мультисписок" ,
                  values: [
                     {
                        value: "2" ,
                        enum : "3692540"
                     } ,
                     {
                        value: "3" ,
                        enum : "3692541"
                     }
                  ] ,
                  is_system: false
               }
            ] ,
            catalog_id: 4220 ,
            _links: {
               self: {
                  href: "/api/v2/catalog_elements?id=41873&catalog_id=4220" ,
                  method: "get"
               }
            }
         } ,
         {
            id: 41872 ,
            name: "Карандаши" ,
            created_by: 504141 ,
            created_at: 1509003145 ,
            updated_at: 1509003145 ,
            updated_by: 504141 ,
            is_deleted: false ,
            custom_fields: [
               {
                  id: 4400049 ,
                  name: "Артикул" ,
                  values: [
                     {
                        value: "415"
                     }
                  ] ,
                  is_system: true
               } ,
               {
                  id: 4400050 ,
                  name: "Количество" ,
                  values: [
                     {
                        value: "300"
                     }
                  ] ,
                  is_system: true
               } ,
               {
                  id: 4400051 ,
                  name: "Цена" ,
                  values: [
                     {
                        value: "75"
                     }
                  ] ,
                  is_system: true
               } ,
               {
                  id: 4400062 ,
                  name: "Мультисписок" ,
                  values: [
                     {
                        value: "1" ,
                        enum : "3692539"
                     } ,
                     {
                        value: "2" ,
                        enum : "3692540"
                     }
                  ] ,
                  is_system: false
               }
            ] ,
            catalog_id: 4220 ,
            _links: {
               self: {
                  href: "/api/v2/catalog_elements?id=41872&catalog_id=4220" ,
                  method: "get"
               }
            }
         }
      ]
   }
}

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

/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain = 'test' ; #Наш аккаунт - поддомен
#Формируем ссылку для запроса
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements' ;
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите
документацию).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
необходимо. */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements?catalog_id=2634' ;
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements?catalog_id=2634&term=запрос' ;
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/catalog_elements?catalog_id=2634&id=47856' ;
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой 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 ) ;
/* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$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' ] ;