Покупатели

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

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

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

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

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

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

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 Идентификатор раннее предустановленного варианта выбора для списка или мультисписка
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.          custom_fields: [
  18.             {
  19.                id: "4400017",
  20.                values: [
  21.                   {
  22.                      value: "Очень важный покупатель"
  23.                   }
  24.                ]
  25.             },
  26.             {
  27.                id: "4400021",
  28.                values: [
  29.                   "3692471",
  30.                   "3692472"
  31.                ]
  32.             },
  33.             {
  34.                id: "4399655",
  35.                values: [
  36.                   {
  37.                      value: "ул. Охотный ряд, 1",
  38.                      subtype: "address_line_1"
  39.                   },
  40.                   {
  41.                      value: "Москва",
  42.                      subtype: "city"
  43.                   },
  44.                   {
  45.                      value: "101010",
  46.                      subtype: "zip"
  47.                   },
  48.                   {
  49.                      value: "RU",
  50.                      subtype: "country"
  51.                   }
  52.                ]
  53.             }
  54.          ]
  55.       }
  56.    ]
  57. }

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

  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.   array(
  63.     'name'=>'Антон',
  64.     'created_at'=>1298904164,
  65.     'next_date' => '1508782500',
  66.     'next_price'=>600200,
  67.     'responsible_user_id'=>215309,
  68.     'custom_fields'=>array(
  69.       array(
  70.         #Нестандартное дополнительное поле типа "мультисписок", которое мы создали
  71.        'id'=>426106,
  72.         'values'=>array(
  73.           1237756,
  74.           1237758
  75.         )
  76.       )
  77.     )
  78. )
  79. );
  80. /* Теперь подготовим данные, необходимые для запроса к серверу */
  81. $subdomain='test'; #Наш аккаунт - поддомен
  82. #Формируем ссылку для запроса
  83. $link='https://'.$subdomain.'.amocrm.ru/api/v2/customers';
  84. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
  85. работе с этой
  86. библиотекой Вы можете
  87. прочитать в мануале. */
  88. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  89. #Устанавливаем необходимые опции для сеанса cURL
  90. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  91. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  92. curl_setopt($curl,CURLOPT_URL,$link);
  93. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  94. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($customers));
  95. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  96. curl_setopt($curl,CURLOPT_HEADER,false);
  97. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  98. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  99. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  100. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  101. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  102. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  103. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  104. $code=(int)$code;
  105. $errors=array(
  106.   301=>'Moved permanently',
  107.   400=>'Bad request',
  108.   401=>'Unauthorized',
  109.   403=>'Forbidden',
  110.   404=>'Not found',
  111.   500=>'Internal server error',
  112.   502=>'Bad gateway',
  113.   503=>'Service unavailable'
  114. );
  115. try
  116. {
  117.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  118.  if($code!=200 && $code!=204)
  119.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  120. }
  121. catch(Exception $E)
  122. {
  123.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  124. }

Транзакции

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

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

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

Параметры

Параметр Тип Описание
add array Список добавляемых транзакций
add/customer_id int Уникальный идентификатор покупателя
add/date timestamp Дата совершенной покупки
add/price int Сумма совершенной покупки
add/comment string Комментарий к покупке
add/next_date timestamp Ожидаемая дата покупки
add/next_price int Ожидаемая сумма покупки
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.       }
  11.    ]
  12. }

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

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

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

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

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. }