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

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

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

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

URL метода

POST /api/v2/catalog_elements

Параметры

Параметр Тип Описание
add array Список добавляемых элементов списка
update array Обновление существующих элементов списка
Все параметры, которые описанны в add действуют также и в update
delete array Массив удаляемых элементов списков
add/catalog_id
require
string ID списка
add/name
require
string Название элемента
add/request_id int Уникальный идентификатор записи в клиентской программе, необязательный параметр (информация о request_id нигде не сохраняется)
add/custom_fields array Дополнительные поля
add/custom_fields// array Внутри него будет описание каждого доп поля
add/custom_fields//id int Уникальный идентификатор заполняемого дополнительного поля (см. Информация аккаунта)
add/custom_fields//values array Внутри будет еще один массив, с описанием value
add/custom_fields//values// array Здесь будут описаны значения доп. поля, и, если нужно, дополнительный тип (для полей типа “мультисписок” просто перечисляем id выбранных значений)
add/custom_fields//values//value string Значение дополнительного поля
add/custom_fields//values//enum string Выбираемый тип дополнительного поля (например телефон домашний, рабочий и т. д.)
add/custom_fields//values//subtype string Тип изменяемого элемента дополнительного поля.
Внимание, все не указанные типы будут стёрты
update/id
require
int Уникальный идентификатор элемента списка, который указывается с целью его обновления
update/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//id int Уникальный идентификатор дополнительного поля
custom_fields//name string Название дополнительного поля
custom_fields//values array Массив, значений текущего доп поля
custom_fields//values//value string Значение текущего доп поля
custom_fields//values//enum string Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
custom_fields//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' ] ;