Покупатели

Методы для работы с Покупателями

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

Каждому покупателю может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.

Покупатель обладает периодом, который обозначает положение покупателя в жизненном цикле (бизнес-процесс). Список периодов может быть изменен в рамках аккаунта, кроме первого и трех конечных системных периодов.

Добавление, обновление и удаление покупателей

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

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

Параметры

Параметр Тип Описание
add array Список добавляемых покупателей
update array Список существующих покупателей, в которых будут заноситься изменения. Все, описанные для add, актуальны также для update
delete array Массив id удаляемых сделок, перечисляются через запятую.
add/name string Название покупателя
add/next_date timestamp Дата и время следующей покупки
add/created_at timestamp Дата и время создания покупателя
add/updated_at timestamp Дата и время изменения покупателя
add/responsible_user_id int id пользователя ответственного за покупателя
add/created_by int id пользователя создавшего покупателя
add/next_price int Ожидаемая сумма
add/periodicity int Периодичность совершаемых покупок
add/tags string Теги, привязываемые к покупателю. Задаются целостной строковой переменной, внутри строки перечисляются через запятую
add/period_id int id периода цифровой воронки покупателя
add/contacts_id array (int) Массив id существующих контактов, которые привяжутся к покупателю
add/company_id int id существующей компании, которая привяжется к покупателю
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/catalog_elements_id string Список элементов каталогов для привязки с указанием количества, сгруппированный по ID каталога
update/id
require
int id покупателя, в которого будут вноситься изменения
update/updated_at
require
timestamp Дата и время изменения
update/unlink array Массив содержащий информацию для открепления покупателя от других элементов сущностей.
update/unlink/contacts_id array Массив id открепляемых контактов
update/unlink/company_id int id открепляемой компании

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

Параметр Описание
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.    add: [
  3.       {
  4.          name: "ООО СпецГорСтрой" ,
  5.          next_date: "1508878800" ,
  6.          created_at: "1508533200" ,
  7.          responsible_user_id: "504141" ,
  8.          created_by: "504141" ,
  9.          next_price: "5000" ,
  10.          periodicity: "7" ,
  11.          tags: "продажи, маркеры" ,
  12.          period_id: "15489654" ,
  13.          contacts_id: [
  14.             "496531"
  15.          ] ,
  16.          company_id: "475621" ,
  17.          catalog_elements_id: {
  18.             99999 : {
  19.                111111 : 10
  20.             }
  21.          } ,
  22.          custom_fields: [
  23.             {
  24.                id: "4400017" ,
  25.                values: [
  26.                   {
  27.                      value: "Очень важный покупатель"
  28.                   }
  29.                ]
  30.             } ,
  31.             {
  32.                id: "4400021" ,
  33.                values: [
  34.                   "3692471" ,
  35.                   "3692472"
  36.                ]
  37.             } ,
  38.             {
  39.                id: "4399655" ,
  40.                values: [
  41.                   {
  42.                      value: "ул. Охотный ряд, 1" ,
  43.                      subtype: "address_line_1"
  44.                   } ,
  45.                   {
  46.                      value: "Москва" ,
  47.                      subtype: "city"
  48.                   } ,
  49.                   {
  50.                      value: "101010" ,
  51.                      subtype: "zip"
  52.                   } ,
  53.                   {
  54.                      value: "RU" ,
  55.                      subtype: "country"
  56.                   }
  57.                ]
  58.             }
  59.          ]
  60.       }
  61.    ]
  62. }

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

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

Пример запроса на изменение нового покупателя.

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

  1. {
  2.    update: [
  3.       {
  4.          id: "466791" ,
  5.          updated_at: "1508619600" ,
  6.          next_date: "1508878800" ,
  7.          next_price: "1508706000" ,
  8.          custom_fields: [
  9.             {
  10.                id: "4400021" ,
  11.                values: [
  12.                   "3692471" ,
  13.                   "3692472" ,
  14.                   "3692473"
  15.                ]
  16.             }
  17.          ]
  18.       }
  19.    ]
  20. }

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

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

Удаление покупателя

Пример запроса на удаление покупателей.

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

  1. {
  2.    delete : [
  3.       "466812" ,
  4.       "466811" ,
  5.       "466891"
  6.    ]
  7. }

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers" ,
  5.          method: "post"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: {
  10.          deleted: [
  11.             {
  12.                id: 466815 ,
  13.                name: "Елизавета"
  14.             } ,
  15.             {
  16.                id: 466816 ,
  17.                name: "Татьяна"
  18.             }
  19.          ]
  20.       }
  21.    }
  22. }

Список покупателей

Метод для получения списка покупателей с возможностью фильтрации и постраничной выборки.

URL метода
GET /api/v2/customers

Параметры GET

Параметр Описание
id Выбрать элемент с заданным ID (Если указан этот параметр, все остальные игнорируются). Можно передавать в виде массива состоящий из нескольких ID)
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Оффсет выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан
filter/main_user// Выбрать элемент по ответственному пользователю (нужно передавать массив с ID пользователей.
filter/date Выбрать элемент по дате создания или редактирования (нужно передавать массив с параметрами type, from, to)
filter/date/type Выбрать элемент по дате создания или редактирования. Тип даты: create или modify.
filter/date/from Дата с которой нужно начинать выборку. В формате ММ/ЧЧ/ГГГГ. Параметр задаётся в связке с параметром filter/date/type.
filter/date/to Дата до которой нужно выбирать. В формате ММ/ЧЧ/ГГГГ. Параметр задаётся в связке с параметром filter/date/type.
filter/next_date Выбрать элемент по дате след. покупки (нужно передавать массив с параметрами from, to)
filter/next_date/from Аналогично filter/date/from
filter/next_date/to Аналогично filter/date/to

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

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

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

Параметр Тип Описание
id int Уникальный идентификатор элемента cущности "Покупатель"
name
require
string Название элемента
responsible_user_id int id пользователя, ответственного за данного покупателя
created_by int id пользователя, создавшего покупателя
created_at timestamp Дата и время создания покупателя
updated_at timestamp Дата и время изменения покупателя
account_id int id аккаунта, на котором создан покупатель
updated_by int id пользователя, изменившего покупателя
is_deleted bool Удален покупатель или нет.
main_contact array Массив содержащий информацию о главном контакте покупателя
main_contact/id int id главного контакта покупателя
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/is_system bool Является ли дополнительное поле системным
contacts array Массив содержащий информацию по контактам прикреплённым к данному покупателю
contacts/id int id прикреплённого к сделке контакта
company array Массив содержащий информацию о компании, которая прикреплена к данному покупателю
company/id int id компании, которая прикреплена к данной сделке
company/name string название компании, которая прикреплена к данной сделке
next_price int Ожидаемая сумма
closest_task_at timestamp Время ближайшей задачи по данному покупателю
period_id timestamp Уникальный идентификатор периода, цифровой воронки покупателей
periodicity int Периодичнось
next_date
require
timestamp Дата следующей покупки
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

Пример GET запроса списка покупателей, созданных от 10.10.2017
https://example.amocrm.ru/api/v2/customers?filter[date][type]=create&filter[date][from]=10.10.2017

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers" ,
  5.          method: "get"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 466791 ,
  12.             name: "Екатерина" ,
  13.             responsible_user_id: 504141 ,
  14.             created_by: 504141 ,
  15.             created_at: 1508500193 ,
  16.             updated_at: 1508659120 ,
  17.             account_id: 13667499 ,
  18.             updated_by: 504141 ,
  19.             is_deleted: false ,
  20.             main_contact: {
  21.                id: 1099181 ,
  22.                _links: {
  23.                   self: {
  24.                      href: "/api/v2/contacts?id=1099181" ,
  25.                      method: "get"
  26.                   }
  27.                }
  28.             } ,
  29.             tags: [
  30.                {
  31.                   id: 61869 ,
  32.                   name: "Продажи"
  33.                } ,
  34.                {
  35.                   id: 61870 ,
  36.                   name: "Маркеры"
  37.                }
  38.             ] ,
  39.             custom_fields: [
  40.                {
  41.                   id: 4400017 ,
  42.                   name: "Замечания" ,
  43.                   values: [
  44.                      {
  45.                         value: "Задерживают оплату"
  46.                      }
  47.                   ] ,
  48.                   is_system: false
  49.                } ,
  50.                {
  51.                   id: 4400021 ,
  52.                   name: "Мультисписок" ,
  53.                   values: [
  54.                      {
  55.                         value: "3" ,
  56.                         enum : "3692471"
  57.                      } ,
  58.                      {
  59.                         value: "4" ,
  60.                         enum : "3692472"
  61.                      } ,
  62.                      {
  63.                         value: "5" ,
  64.                         enum : "3692473"
  65.                      }
  66.                   ] ,
  67.                   is_system: false
  68.                } ,
  69.             ] ,
  70.             contacts: {
  71.                id: [
  72.                   1099181
  73.                ] ,
  74.                _links: {
  75.                   self: {
  76.                      href: "/api/v2/contacts?id=1099181" ,
  77.                      method: "get"
  78.                   }
  79.                }
  80.             } ,
  81.             company: {
  82.                id: 1099180 ,
  83.                name: ООО СпецГорСтрой,
  84.                _links: {
  85.                   self: {
  86.                      href: "/api/v2/companies?id=1099180" ,
  87.                      method: "get"
  88.                   }
  89.                }
  90.             } ,
  91.             next_price: 1508706000 ,
  92.             closest_task_at: 1508705940 ,
  93.             period_id: 112804 ,
  94.             periodicity: 0 ,
  95.             next_date: 1508878800 ,
  96.             _links: {
  97.                self: {
  98.                   href: "/api/v2/customers?id=466791" ,
  99.                   method: "get"
  100.                }
  101.             }
  102.          }
  103.       ]
  104.    }
  105. }

Пример интеграции, работающей с "Покупателем"

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

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

  1. $customers [ 'add' ] = array (
  2.     array (
  3.       'name' => 'Людмила' ,
  4.       'next_date' => '1508792400' ,
  5.       'created_at' => '1508619600' ,
  6.       'responsible_user_id' => 504141 ,
  7.       'created_by' => 504141 ,
  8.       'next_price' => 7000 ,
  9.       'periodicity' => 7 ,
  10.       'tags' => "Продажи,Карандаши" ,
  11.       'period_id' => 153795 ,
  12.       'contacts_id' => array ( 468986 , 468979 ) ,
  13.       'company_id' => 356463 ,
  14.       'custom_fields' => array (
  15.           array (
  16.             'id' => 4400017 ,
  17.             'values' => array (
  18.                 array (
  19.                   'value' => "Важный клиент"
  20.                )
  21.             )
  22.          ) ,
  23.           array (
  24.             'id' => 4400021 ,
  25.             'values' => array (
  26.                "3692469" ,
  27.                "3692470" ,
  28.                "3692471"
  29.             )
  30.          ) ,
  31.       array (
  32.         'id' => 458615 , #Уникальный индентификатор заполняемого дополнительного поля
  33.        'values' => array (
  34.           array (
  35.             'value' => 'Address line 1' ,
  36.             'subtype' => 'address_line_1' ,
  37.           ) ,
  38.           array (
  39.             'value' => 'Address line 2' ,
  40.             'subtype' => 'address_line_2' ,
  41.           ) ,
  42.           array (
  43.             'value' => 'Город' ,
  44.             'subtype' => 'city' ,
  45.           ) ,
  46.           array (
  47.             'value' => 'Регион' ,
  48.             'subtype' => 'state' ,
  49.           ) ,
  50.           array (
  51.             'value' => '203' ,
  52.             'subtype' => 'zip' ,
  53.           ) ,
  54.           array (
  55.             'value' => 'RU' ,
  56.             'subtype' => 'country' ,
  57.           )
  58.         )
  59.       )
  60. )
  61. ) ,
  62.     'name' => 'Антон' ,
  63.     'created_at' => 1298904164 ,
  64.     'next_date' => '1508782500' ,
  65.     'next_price' => 600200 ,
  66.     'responsible_user_id' => 215309 ,
  67.     'custom_fields' => array (
  68.       array (
  69.         #Нестандартное дополнительное поле типа "мультисписок", которое мы создали
  70.        'id' => 426106 ,
  71.         'values' => array (
  72.           1237756 ,
  73.           1237758
  74.         )
  75.       )
  76.     )
  77. )
  78. ) ;
  79. /* Теперь подготовим данные, необходимые для запроса к серверу */
  80. $subdomain = 'test' ; #Наш аккаунт - поддомен
  81. #Формируем ссылку для запроса
  82. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/customers' ;
  83. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  84. работе с этой
  85. библиотекой Вы можете
  86. прочитать в мануале. */
  87. $curl = curl_init ( ) ; #Сохраняем дескриптор сеанса cURL
  88. #Устанавливаем необходимые опции для сеанса cURL
  89. curl_setopt ( $curl ,CURLOPT_RETURNTRANSFER, true ) ;
  90. curl_setopt ( $curl ,CURLOPT_USERAGENT, 'amoCRM-API-client/1.0' ) ;
  91. curl_setopt ( $curl ,CURLOPT_URL, $link ) ;
  92. curl_setopt ( $curl ,CURLOPT_CUSTOMREQUEST, 'POST' ) ;
  93. curl_setopt ( $curl ,CURLOPT_POSTFIELDS, json_encode ( $customers ) ) ;
  94. curl_setopt ( $curl ,CURLOPT_HTTPHEADER, array ( 'Content-Type: application/json' ) ) ;
  95. curl_setopt ( $curl ,CURLOPT_HEADER, false ) ;
  96. curl_setopt ( $curl ,CURLOPT_COOKIEFILE, dirname ( __FILE__ ) . '/cookie.txt' ) ; #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  97. curl_setopt ( $curl ,CURLOPT_COOKIEJAR, dirname ( __FILE__ ) . '/cookie.txt' ) ; #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  98. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYPEER, 0 ) ;
  99. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYHOST, 0 ) ;
  100. $out = curl_exec ( $curl ) ; #Инициируем запрос к API и сохраняем ответ в переменную
  101. $code = curl_getinfo ( $curl ,CURLINFO_HTTP_CODE) ;
  102. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  103. $code = (int) $code ;
  104. $errors = array (
  105.   301 => 'Moved permanently' ,
  106.   400 => 'Bad request' ,
  107.   401 => 'Unauthorized' ,
  108.   403 => 'Forbidden' ,
  109.   404 => 'Not found' ,
  110.   500 => 'Internal server error' ,
  111.   502 => 'Bad gateway' ,
  112.   503 => 'Service unavailable'
  113. ) ;
  114. try
  115. {
  116.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  117.  if ( $code != 200 && $code != 204 )
  118.     throw new Exception( isset ( $errors [ $code ] ) ? $errors [ $code ] : 'Undescribed error' , $code ) ;
  119. }
  120. catch(Exception $E )
  121. {
  122.   die ( 'Ошибка: ' . $E -> getMessage ( ) .PHP_EOL. 'Код ошибки: ' . $E -> getCode ( ) ) ;
  123. }

Транзакции

Транзакция - это сущность которая описывает основные характеристики покупки (дата и сумма). Является дополнением для "покупателя".

Добавление и удаление транзакций

Метод позволяет добавлять и удалять транзакции по одной или пакетно.

Параметры

Параметр Тип Описание
add array Список добавляемых транзакций
add/customer_id int Уникальный идентификатор покупателя
add/date timestamp Дата совершенной покупки
add/price int Сумма совершенной покупки
add/comment string Комментарий к покупке
add/next_date timestamp Ожидаемая дата покупки
add/next_price int Ожидаемая сумма покупки
add/elements array Список элементов каталогов для привязки с указанием количества, сгруппированный по ID каталога
delete array(int) Массив с уникальными идентификаторами транзакций, которые указываются с целью удаления

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

Параметр Тип Описание
items array(int) Массив id созданных сделок
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

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

Пример запроса на добавление транзакции

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

  1. {
  2.    add: [
  3.       {
  4.          customer_id: "466791" ,
  5.          date: "1507582800" ,
  6.          price: "15000" ,
  7.          comment: "Всё прошло успешно" ,
  8.          next_date: "1508878800" ,
  9.          next_price: "20000" ,
  10.          elements: {
  11.           9999 : {
  12.            111111 : 3
  13.           }
  14.          }
  15.       }
  16.    ]
  17. }

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

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

Пример запроса, на удаление транзакций

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

  1. {
  2.    delete : [
  3.       "4589" ,
  4.       "4588" ,
  5.       "4587"
  6.    ]
  7. }

Комментирование транзакций

Метод для добавления и изменения комментария существующей транзакции. При изменении комментария у существующей транзакции, сама транзакция не обновляется.

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

Параметры

Параметр Тип Описание
update array Список добавляемых/изменяемых комментариев
update/transaction_id
require
int Уникальный идентификатор транзакции
update/comment
require
string Текст комментария

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

Параметр Тип Описание
items array Массив добавленных/изменённых комментариев
id int id добавленного/изменённого комментария
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

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

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

  1. {
  2.    update: [
  3.       {
  4.          transaction_id: "5396" ,
  5.          comment: "Составить договор"
  6.       }
  7.    ]
  8. }

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

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

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

  1. $transactions [ 'add' ] = array (
  2.     'price' => 3000 ,
  3.     'date' => 1476813651 ,
  4.     'customer_id' => 33221355 ,
  5.     'comment' => "example"
  6.   ) ,
  7.     'price' => 9500 ,
  8.     'date' => 14762143651 ,
  9.     'customer_id' => 75321111 ,
  10.     'comment' => "example 2"
  11.   )
  12. ) ;
  13. /* Теперь подготовим данные, необходимые для запроса к серверу */
  14. $subdomain = 'test' ; #Наш аккаунт - поддомен
  15. #Формируем ссылку для запроса
  16. $link = 'https://' . $subdomain . '.amocrm.ru/api/v2/transactions' ;
  17. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  18. работе с этой
  19. библиотекой Вы можете
  20. прочитать в мануале. */
  21. $curl = curl_init ( ) ; #Сохраняем дескриптор сеанса cURL
  22. #Устанавливаем необходимые опции для сеанса cURL
  23. curl_setopt ( $curl ,CURLOPT_RETURNTRANSFER, true ) ;
  24. curl_setopt ( $curl ,CURLOPT_USERAGENT, 'amoCRM-API-client/1.0' ) ;
  25. curl_setopt ( $curl ,CURLOPT_URL, $link ) ;
  26. curl_setopt ( $curl ,CURLOPT_CUSTOMREQUEST, 'POST' ) ;
  27. curl_setopt ( $curl ,CURLOPT_POSTFIELDS, json_encode ( $transactions ) ) ;
  28. curl_setopt ( $curl ,CURLOPT_HTTPHEADER, array ( 'Content-Type: application/json' ) ) ;
  29. curl_setopt ( $curl ,CURLOPT_HEADER, false ) ;
  30. curl_setopt ( $curl ,CURLOPT_COOKIEFILE, dirname ( __FILE__ ) . '/cookie.txt' ) ; #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  31. curl_setopt ( $curl ,CURLOPT_COOKIEJAR, dirname ( __FILE__ ) . '/cookie.txt' ) ; #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  32. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYPEER, 0 ) ;
  33. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYHOST, 0 ) ;
  34. $out = curl_exec ( $curl ) ; #Инициируем запрос к API и сохраняем ответ в переменную
  35. $code = curl_getinfo ( $curl ,CURLINFO_HTTP_CODE) ;
  36. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  37. $code = (int) $code ;
  38. $errors = array (
  39.   301 => 'Moved permanently' ,
  40.   400 => 'Bad request' ,
  41.   401 => 'Unauthorized' ,
  42.   403 => 'Forbidden' ,
  43.   404 => 'Not found' ,
  44.   500 => 'Internal server error' ,
  45.   502 => 'Bad gateway' ,
  46.   503 => 'Service unavailable'
  47. ) ;
  48. try
  49. {
  50.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  51.  if ( $code != 200 && $code != 204 )
  52.     throw new Exception( isset ( $errors [ $code ] ) ? $errors [ $code ] : 'Undescribed error' , $code ) ;
  53. }
  54. catch(Exception $E )
  55. {
  56.   die ( 'Ошибка: ' . $E -> getMessage ( ) .PHP_EOL. 'Код ошибки: ' . $E -> getCode ( ) ) ;
  57. }

Список транзакций

Метод для получения списка транзакций с возможностью фильтрации.

URL метода
GET /api/v2/transactions

Параметры GET

Параметр Описание
id Выбрать транзакцию с заданным id
customer_id Выбрать транзакцию, которая привязана к покупателю с заданным id
limit_rows Кол-во выбираемых строк (системное ограничение 500)
limit_offset Оффсет выборки (с какой строки выбирать). Работает, только при условии, что limit_rows тоже указан

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

Параметр Тип Описание
items array Массив выбранных транзакций
items/id int Уникальный идентификатор транзакции
items/created_by int ID пользователя, создавшего транзакцию
items/created_at timestamp Дата и время создания транзакции
items/updated_at timestamp Дата и время изменения транзакции
items/account_id int id аккаунта на котором создана транзакция
items/updated_by int id пользователя изменившего транзакцию
items/is_deleted bool Удалена транзакция или нет
items/comment string Комментарий
items/price int Сумма покупки
items/date timestamp Дата покупки
items/customer array Массив содержащий информацию о покупателе
items/customer/id int id покупателя
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

Пример GET запроса списка покупателей, созданных от 10.10.2017
https://example.amocrm.ru/api/v2/transactions?limit_rows=50&customer_id=46879

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/transactions" ,
  5.          method: "get"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 5400 ,
  12.             created_by: 504141 ,
  13.             created_at: 1508671514 ,
  14.             updated_at: 1508671514 ,
  15.             account_id: 13667499 ,
  16.             updated_by: 504141 ,
  17.             is_deleted: false ,
  18.             comment: "" ,
  19.             price: 55555 ,
  20.             date: 1508360400 ,
  21.             customer: {
  22.                id: 466791 ,
  23.                _links: {
  24.                   self: {
  25.                      href: "/api/v2/customers?id=466791" ,
  26.                      method: "get"
  27.                   }
  28.                }
  29.             } ,
  30.             _links: {
  31.                self: {
  32.                   href: "/api/v2/transactions?id=5400" ,
  33.                   method: "get"
  34.                }
  35.             }
  36.          } ,
  37.          {
  38.             id: 5399 ,
  39.             created_by: 504141 ,
  40.             created_at: 1508665872 ,
  41.             updated_at: 1508665872 ,
  42.             account_id: 13667499 ,
  43.             updated_by: 504141 ,
  44.             is_deleted: false ,
  45.             comment: "" ,
  46.             price: 15000 ,
  47.             date: 1507582800 ,
  48.             customer: {
  49.                id: 466791 ,
  50.                _links: {
  51.                   self: {
  52.                      href: "/api/v2/customers?id=466791" ,
  53.                      method: "get"
  54.                   }
  55.                }
  56.             } ,
  57.             _links: {
  58.                self: {
  59.                   href: "/api/v2/transactions?id=5399" ,
  60.                   method: "get"
  61.                }
  62.             }
  63.          }
  64.       ]
  65.    }
  66. }

Периоды покупателей

Периоды покупателей – это последовательность шагов, которые проходит потенциальный клиент (покупатель) по воронке покупателей перед покупкой. В amoCRM можно создавать свои периоды для отслеживания хода покупателя. Воронка покупателей может содержать 10 периодов "до покупки" (включая "недавно купили", "покупка сегодня" и "не купили"). Настроить периоды может администратор аккаунта на странице Digital Pipeline (Цифровая воронка). Эти методы доступны только администратору аккаунта

Добавление, удаление и обновление периодов покупателей

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

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

Параметры

Параметр Тип Описание
update array Редактирование периодов покупателя
update//period int Количество дней в периоде. ВАЖНО!!! Данный параметр определяет фиксированную длину периода и не совпадает с количеством дней "до покупки". Количество дней до покупки вычисляется путем сложения данного параметра у всех периодов начиная от "дня покупки" справа на лево. Например: чтобы получить "90, 30 и 10 дней до покупки" нужно создать 3 периода равных 10, 20 и 60 дней: 1) 10+20=30 дней до покупки. 2) 30+60=90 дней до покупки.
update//id int Уникальный идентификатор воронки. (Если id не передан, то будет создан новый период).
update//color string Цвет периода
update//sort int Порядковый номер периода при отображении (Периоды выводятся справа на лево начиная от "дня покупки").

Доступные цвета периодов

Код Образец
#fffeb2 color example
#fffd7f color example
#fff000 color example
#ffeab2 color example
#ffdc7f color example
#ffce5a color example
#ffdbdb color example
#ffc8c8 color example
#ff8f92 color example
#d6eaff color example
#c1e0ff color example
#98cbff color example
#ebffb1 color example
#deff81 color example
#87f2c0 color example
#f9deff color example
#f3beff color example
#ccc8f9 color example
#eb93ff color example
#f2f3f4 color example
#e6e8ea color example

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

Параметр Тип Описание
items array Массив созданных/изменённых периодов
items/id int Уникальный идентификатор периода
items//type string Тип периода (before, after). Тип after можно только редактировать.
items//period int Количество дней в периоде
items//color string Цвет периода
items//sort int Порядковый номер периода при отображении
items/after_buy int Количество дней после покупки (период "не купили")
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

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

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

  1. {
  2.    update: [
  3.       {
  4.          period: "5" ,
  5.          id: "15563" ,
  6.          color: "#000000" ,
  7.          sort: "1"
  8.       }
  9.    ]
  10. }

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers_periods" ,
  5.          method: "post"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 112805 ,
  12.             type: "after" ,
  13.             period: 60 ,
  14.             color: "#fd5598" ,
  15.             sort: 0 ,
  16.             after_buy: 60 ,
  17.             _links: {
  18.                self: {
  19.                   href: "/api/v2/customers_periods" ,
  20.                   method: "get"
  21.                }
  22.             }
  23.          }
  24.       ]
  25.    }
  26. }

Пример интеграции работающей с периодами покупателей

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

Список периодов покупателей

Метод для получения списка периодов. Запрос GET отправляется без дополнительных параметров.

URL метода
GET /api/v2/customers_periods

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

Параметр Тип Описание
items array Массив созданных/изменённых периодов
items/id int Уникальный идентификатор периода
items//type string Тип периода (before, after). Тип after можно только редактировать.
items//period int Количество дней в периоде
items//color string Цвет периода
items//sort int Порядковый номер периода при отображении
items/after_buy int Количество дней после покупки (период "не купили")
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/items array Массив содержащий информацию по каждому отдельному элементу

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

Пример GET запроса списка периодов покупателей
https://example.amocrm.ru/api/v2/customers_periods

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

  1. {
  2.    _links: {
  3.       self: {
  4.          href: "/api/v2/customers_periods" ,
  5.          method: "get"
  6.       }
  7.    } ,
  8.    _embedded: {
  9.       items: [
  10.          {
  11.             id: 112815 ,
  12.             type: "before" ,
  13.             period: 5 ,
  14.             color: "#e6e8ea" ,
  15.             sort: 1 ,
  16.             before_buy: 5
  17.          } ,
  18.          {
  19.             id: 112805 ,
  20.             type: "after" ,
  21.             period: 60 ,
  22.             color: "#fd5598" ,
  23.             sort: 0 ,
  24.             after_buy: 60
  25.          }
  26.       ]
  27.    }
  28. }