Работа со списком событий

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

Список событий

Метод для получения списка с возможностью фильтрации и постраничной выборки. Ограничение по возвращаемым на одной странице данным – 100 событий. Валидный http-код ответа 200 и 204, если событий по фильтру не найдено.

URL метода

GET /api/v2/events

Параметры GET

Параметр Описание
limit Кол-во выбираемых строк (системное ограничение 100)
page Страница выборки
with В данном параметре указываются значения (список доступных значений), которые
дополнят ответ от API информацией.
filter/id Фильтр по ID событий, передаются через запятую, не больше 100 за запрос. Например,
filter[id]=01drbfj5a8k9zd60bgg907a6w9,01drbfj5a8k9zd60bgg907a6w3.
filter/created_at Фильтр по дате событий, передаются до 2-ух timestamp(int) через запятую. Если передан один параметр, то
список будет отфильтрован от переданного timestamp до текущего времени. Если передано два значения, то
список будет отфильтрован от первого timestamp до второго. Например,
filter[created_at]=1573102261,1573142261.
filter/created_by Фильтр по пользователю, передаются до 10-ти ID пользователей, состоящих в аккаунте, через запятую.
Например, filter[created_by]=956328,504141.
filter/entity Фильтр по типу сущности, передаются через запятую. Возможные параметры – lead, contact, company,
customer, task, catalog_{CATALOG_ID}. Например, filter[entity]=lead,contact,catalog_1075.
filter/entity_id Фильтр по ID сущности, передаются до 10-ти ID через запятую. Для использования данного фильтра
обязательна передача фильтра filter[entity] и не более 1 сущности. Например,
filter[entity]=lead&filter[entity_id]=648533.
filter/type Фильтр по типу событий. Типы перечисляются через запятую, подробней о возможных типах и ограничениях
читайте – тут.
filter/value_after Фильтр по значению до. Подробней о возможных значения и ограничениях читайте – тут.
filter/value_after Фильтр по значению после. Подробней о возможных значения и ограничениях читайте – тут.

Значения для фильтра по типу

Значения для фильтра по типу можно указать в соответствии со списком ниже или запросить через метод
API
.

Возможные значения

Значение Описание
lead_added Новая сделка
lead_deleted Сделка удалена
lead_restored Сделка восстановлена
lead_status_changed Изменение этапа продажи
lead_linked Прикрепление сделки
lead_unlinked Открепление сделки
contact_added Новый контакт
contact_deleted Контакт удален
contact_restored Контакт восстановлен
contact_linked Прикрепление контакта
contact_unlinked Открепление контакта
company_added Новая компания
company_deleted Компания удалена
company_restored Компания восстановлена
company_linked Прикрепление компании
company_unlinked Открепление компании
customer_added Новый покупатель
customer_deleted Покупатель удален
customer_status_changed Изменение этапа покупателя
customer_linked Прикрепление покупателя
customer_unlinked Открепление покупателя
task_added Новая задача
task_deleted Задача удалена
task_completed Завершение задачи
task_type_changed Изменение типа задачи
task_text_changed Изменение текста задачи
task_deadline_changed Изменение даты исполнения задачи
task_result_added Результат по задаче
incoming_call Входящий звонок
outgoing_call Исходящий звонок
incoming_chat_message Входящее сообщение
outgoing_chat_message Исходящее сообщение
incoming_sms Входящее SMS
outgoing_sms Исходящее SMS
entity_tag_added Теги добавлены
entity_tag_deleted Теги убраны
entity_linked Прикрепление
entity_unlinked Открепление
sale_field_changed Изменение поля “Бюджет”
name_field_changed Изменение поля “Название”
ltv_field_changed Сумма покупок
custom_field_value_changed Изменение поля
entity_responsible_changed Ответственный изменен
robot_replied Ответ робота
intent_identified Тема вопроса определена
nps_rate_added Новая оценка NPS
link_followed Переход по ссылке
transaction_added Добавлена покупка
common_note_added Новое примечание
common_note_deleted Примечание удалено
attachment_note_added Добавлен новый файл
targeting_in_note_added Добавление в ретаргетинг
targeting_out_note_added Удаление из ретаргетинга
geo_note_added Новое примечание с гео-меткой
service_note_added Новое системное примечание
site_visit_note_added Заход на сайт
message_to_cashier_note_added LifePay: Сообщение кассиру
entity_merged Выполнено объединение
custom_field_{FIELD_ID}_value_changed Изменение поля c переданным ID. Если вы передаете данный тип, то другие типы не могут быть переданы.

Значения для параметра with

Указывать можно более одного значения, через “,”.

Пример: https://example.amocrm.ru/api/v2/events?with=contact_name,lead_name

Возможные значения

Значение Описание
contact_name Если сущностью события является контакт, то помимо его ID, вы получите и название.
lead_name Если сущностью события является сделка, то помимо её ID, вы получите и название.
company_name Если сущностью события является компания, то помимо её ID, вы получите и название.
catalog_element_name Если сущностью события является элемент каталога, то помимо его ID, вы получите и название.
customer_name Если сущностью обытия является покупатель, то помимо его ID, вы получите и название.
catalog_name Если сущностью обытия является элмент каталога, то помимо ID каталога, к которому он относится, вы
получите и название каталога.

Значения для фильтра по значению до/после

В данный момент для фильтра по значению до/после доступны следующие значения:

  1. leads_statuses – фильтр по статусу сделки, доступен для
    события lead_status_changed
  2. customers_statuses – фильтр по статусу покупателя,
    доступен для события customer_status_changed
  3. responsible_user_id – фильтр по ответственному
    пользователю, доступен для события entity_responsible_changed
  4. custom_field_values – фильтр по enum значению поля,
    доступен для события custom_field_{FIELD_ID}_value_changed, в одном запросе должно передаваться не более 1 типа
    события.
  5. value – фильтр по точному значению, доступен для событий
    nps_rate_added, sale_field_changed, name_field_changed, ltv_field_changed, custom_field_value_changed

Описание фильтра по значению до/после – leads_statuses

Данный фильтр позволяет передать ID статусов и их воронок, чтобы получить только необходимые события смены статуса
сделки.
Запрос должен быть составлен следующим образом:


filter[value_after][leads_statuses][0][pipeline_id]=13513&filter[value_after][leads_statuses][0][status_id]=17079863

В примере мы получим все события смены статуса этапа сделки, где сделка перешла в этап 17079863 воронки 13513.
Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'leads_statuses' => [
                [
                    'pipeline_id' => 13513,
                    'status_id' => 17079863,
                ],
                [
                    'pipeline_id' => 13513,
                    'status_id' => 17079860,
                ],
            ],
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B0%5D%5Bpipeline_id%5D=13513&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B0%5D%5Bstatus_id%5D=17079863&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B1%5D%5Bpipeline_id%5D=13513&filter%5Bvalue_after%5D%5Bleads_statuses%5D%5B1%5D%5Bstatus_id%5D=17079860

Описание фильтра по значению до/после – customers_statuses

Данный фильтр позволяет передать ID статусов, чтобы получить только необходимые события смены статуса покупателя.
Запрос должен быть составлен следующим образом:


filter[value_after][customers_statuses][0][status_id]=135751

В примере мы получим все события смены статуса этапа покупателя, где покупатель перешел в этап 135751.
Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'customers_statuses' => [
                [
                    'status_id' => 135751,
                ],
                [
                    'status_id' => 135754,
                ],
            ],
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bcustomers_statuses%5D%5B0%5D%5Bstatus_id%5D=135751&filter%5Bvalue_after%5D%5Bcustomers_statuses%5D%5B1%5D%5Bstatus_id%5D=135754

Описание фильтра по значению до/после – responsible_user_id

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


filter[value_after][responsible_user_id]=448292

В примере мы получим все события смены ответственного пользователя, где ID пользователя 448292.
Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'responsible_user_id' => '448292,457822',
        ],
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bresponsible_user_id%5D=448292%2C457822

Описание фильтра по значению до/после – custom_field_values

фильтр по enum значению поля, доступен для события custom_field_{FIELD_ID}_value_changed, в одном запросе должно
передаваться не более 1 типа события.

Данный фильтр позволяет передать enum значений поля, чтобы получить только необходимые события изменения значения
поля.
Запрос должен быть составлен следующим образом:


filter[value_after][custom_field_values]=145&filter[type]=custom_field_57832_value_changed

В примере мы получим все события смены значения поля с ID 57832, где ID enum равен 145.
Вы можете передать несколько значений в фильтр. Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'custom_field_values' => '145,157,202',
        ],
        'type' => 'custom_field_57832_value_changed',
    ],
];

$filterUri = http_build_query($filter);

filter%5Bvalue_after%5D%5Bcustom_field_values%5D=145%2C157%2C202&filter%5Btype%5D=custom_field_57832_value_changed

Описание фильтра по значению до/после – value

Данный фильтр позволяет передать значение до/после. Он работает только со следующими типами событий: nps_rate_added,
sale_field_changed, name_field_changed, ltv_field_changed, custom_field_value_changed.
Запрос должен быть составлен следующим образом:


filter[value_after][value]=155&filter[type]=sale_field_changed&filter[entity]=lead

В примере мы получим все события смены изменения бюджета, где бюджет сделок стал равен 155.
Ниже приведен пример по формированию такого фильтра используя язык PHP:



$filter = [
    'filter' => [
        'value_after' => [
            'value' => '155',
        ],
        'type' => 'sale_field_changed',
        'entity' => 'lead',
    ],
];

$filterUri = http_build_query($filter);

//filter%5Bvalue_after%5D%5Bvalue%5D=155&filter%5Btype%5D=sale_field_changed&filter%5Bentity%5D=lead

Описание параметров ответа

Параметр Тип Описание
_links object Объект содержащий информацию о запросе
_links/self object Объект содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_links/next object Объект содержащий информацию о запросе следующей страницы
_links/next/href string Относительный URL запроса следующей страницы
_links/next/method string Метод запроса следующей страницы
_links/prev object Объект содержащий информацию о запросе предыдущей страницы
_links/prev/href string Относительный URL запроса предыдущей страницы
_links/prev/method string Метод запроса предыдущей страницы
_embedded object Объект содержащий информацию прилегающую к запросу
_embedded/events array Массив содержащий информацию по каждому отдельному элементу
_embedded/events/0 object Объект содержащий информацию по отдельному элементу
_embedded/events/0/id string ID события
_embedded/events/0/type string Тип события
_embedded/events/0/entity object Сущность события
_embedded/events/0/entity/type string Тип сущности события
_embedded/events/0/entity/id string|int ID сущности события
_embedded/events/0/entity/name string Название сущности события (возвращается, если передать необходимые with параметры)
_embedded/events/0/created_by int ID пользователя, который произвел событие
_embedded/events/0/created_at int Timestamp даты создания события
_embedded/events/0/value_before array Значение ДО (Возможные структуры данных)
_embedded/events/0/value_after array Значение ПОСЛЕ (Возможные структуры данных)
_embedded/events/0/_links object Объект содержащий ссылки на связанные с событием объекты
_embedded/events/0/_links/self object Объект содержащий ссылку на событие
_embedded/events/0/_links/self/href string Относительный URL запроса события
_embedded/events/0/_links/self/method string Метод запроса
_embedded/events/0/_links/entity object Объект содержащий ссылку на сущности события
_embedded/events/0/_links/entity/href string Относительный URL запроса сущности события
_embedded/events/0/_links/entity/method string Метод запроса

Возможные структуры данных в полях value_after и value_before

Структура данных в полях value_after и value_before зависит от типа события и может принимать разные значения.

  • Значение по умолчанию (lead_deleted, lead_restored, contact_deleted, contact_restored, company_deleted, company_restored, customer_deleted, entity_merged, task_added, task_deleted, task_completed):
    Параметр Тип Описание
    value_after|value_before array Пустой массив
    
    {
        "value_after": [],
        "value_before": []
    }
    

  • task_text_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/task object Объект с данными изменения задачи
    value_after|value_before/0/task/text string Текст задачи
    
    {
        "value_after": [
              {
                "task": {
                  "text": "задача"
                }
              }
            ],
        "value_before": [
              {
                "task": {
                  "text": "задача old"
                }
              }
            ],
    }
    

  • robot_replied и intent_identified:
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/helpbot object Объект с данными интента, который сработал
    value_after/0/helpbot/id int ID интента
    
    {
        "value_after": [
              {
                "helpbot": {
                  "id": 145
                }
              }
            ]
    }
    

  • transaction_added:
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/transaction object Объект с данными транзакции
    value_after/0/transaction/id int ID транзакции
    value_after/0/transaction/_links object Объект содержащий ссылки на транзакцию
    value_after/0/transaction/_links/self object Объект содержащий ссылку на транзакцию
    value_after/0/transaction/_links/self/href string Относительный URL запроса транзакции
    value_after/0/transaction/_links/self/method string Метод запроса
    
    {
        "value_after": [
              {
                "transaction": {
                  "id": 33675,
                  "_links": {
                    "self": {
                      "href": "/api/v2/transactions/?id=33675",
                      "method": "get"
                    }
                  }
                }
              }
            ]
    }
    

  • lead_added, contact_added, company_added, customer_added, common_note_added, common_note_deleted, attachment_note_added, targeting_in_note_added, targeting_out_note_added, geo_note_added, service_note_added, site_visit_note_added, message_to_cashier_note_added, incoming_call, outgoing_call, incoming_sms, outgoing_sms, link_followed, task_result_added:
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/note object Объект с данными примечания
    value_after/0/note/id int ID примечания
    value_after/0/note/_links object Объект содержащий ссылки на примечание
    value_after/0/note/_links/self object Объект содержащий ссылку на примечание
    value_after/0/note/_links/self/href string Относительный URL запроса примечания
    value_after/0/note/_links/self/method string Метод запроса
    
    {
        "value_after": [
              {
                "note": {
                  "id": 7422564,
                  "_links": {
                    "self": {
                      "href": "/api/v2/notes/?id=7422564",
                      "method": "get"
                    }
                  }
                }
              }
            ]
    }
    

  • nps_rate_added:
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/nps object Объект с данными оценки
    value_after/0/nps/rate int Оценка от 0 до 10
    
    {
        "value_after": [
              {
                "nps": {
                  "rate": 7
                }
              }
            ]
    }
    

  • incoming_chat_message и outgoing_chat_message:
    Параметр Тип Описание
    value_after array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after/0 object Объект с данными изменения
    value_after/0/message object Объект с данными сообщения
    value_after/0/message/rate string ID сообщения
    
    {
        "value_after": [
              {
                "message": {
                  "id": "1508b51c-aab0-428e-9322-611d847ae747"
                }
              }
            ]
    }
    

  • entity_tag_added и entity_tag_deleted:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/tag object Объект с данными тега
    value_after|value_before/0/tag/name string Название тега
    
    {
        "value_after": [
              {
                "tag": {
                  "name": "тег1"
                }
              }
            ],
        "value_before": [
              {
                "tag": {
                  "name": "тег2"
                }
              },
              {
                "tag": {
                  "name": "тег2"
                }
              }
            ]
    }
    

  • lead_status_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/lead_status object Объект с данными статуса
    value_after|value_before/0/lead_status/id int ID статуса
    value_after|value_before/0/lead_status/pipeline_id int ID воронки
    
    {
        "value_after": [
              {
                "lead_status": {
                  "id": 5233224,
                  "pipeline_id": 437642,
                }
              }
            ],
        "value_before": [
              {
                "lead_status": {
                  "id": 5233224,
                  "pipeline_id": 437642,
                }
              }
            ]
    }
    

  • customer_status_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/customer_status object Объект с данными статуса
    value_after|value_before/0/customer_status/id int ID статуса
    
    {
        "value_after": [
              {
                "customer_status": {
                  "id": 43832
                }
              }
            ],
        "value_before": [
              {
                "customer_status": {
                  "id": 53791
                }
              }
            ]
    }
    

  • customer_linked, customer_unlinked, company_linked, company_unlinked, contact_linked, contact_unlinked, lead_linked, lead_unlinked, entity_linked, entity_unlinked:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/link|unlink object Объект с данными cобытия
    value_after|value_before/0/link|unlink/entity object Объект с сущностью
    value_after|value_before/0/link|unlink/entity/type string Тип сущности
    value_after|value_before/0/link|unlink/entity/id int ID сущности
    value_after|value_before/0/link|unlink/_links object Объект содержащий ссылки на сущность
    value_after|value_before/0/link|unlink/_links/entity object Объект содержащий ссылку на сущность
    value_after|value_before/0/link|unlink/_links/entity/href string Относительный URL запроса сущности
    value_after|value_before/0/link|unlink/_links/entity/method string Метод запроса
    
    {
        "value_after": [
              {
                "link": {
                  "entity": {
                    "type": "lead",
                    "id": 6232965
                  }
                  "_links": {
                    "self": {
                      "href": "/api/v2/leads/?id=6232965",
                      "method": "get"
                    }
                  }
                }
              }
            ],
        "value_before": []
    }
    

    
    {
        "value_after": [],
        "value_before": [
              {
                "unlink": {
                  "entity": {
                    "type": "lead",
                    "id": 6232965
                  }
                  "_links": {
                    "self": {
                      "href": "/api/v2/leads/?id=6232965",
                      "method": "get"
                    }
                  }
                }
              }
            ]
    }
    

  • entity_responsible_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/responsible_user object Объект с данными пользователя
    value_after|value_before/0/responsible_user/id int ID пользователя
    
    {
        "value_after": [
              {
                "responsible_user": {
                  "id": 504329
                }
              }
            ],
        "value_before": [
              {
                "responsible_user": {
                  "id": 37268
                }
              }
            ]
    }
    

  • task_deadline_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/task_deadline object Объект с данными срока выполнения задачи
    value_after|value_before/0/task_deadline/timestamp int Timestamp срока выполнения задачи
    
    {
        "value_after": [
              {
                "task_deadline": {
                  "timestamp": 1573595900
                }
              }
            ],
        "value_before": [
              {
                "task_deadline": {
                  "timestamp": 1573578700
                }
              }
            ]
    }
    

  • task_type_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения (у данного типа всегда только одно изменение в массиве)
    value_after|value_before/0/task_type object Объект с данными типа задачи
    value_after|value_before/0/task_type/id int ID типа задачи
    
    {
        "value_after": [
              {
                "task_type": {
                  "id": 504329
                }
              }
            ],
        "value_before": [
              {
                "task_type": {
                  "id": 37268
                }
              }
            ]
    }
    

  • custom_field_value_changed:
    Параметр Тип Описание
    value_after|value_before array Массив с изменениями по событию
    value_after|value_before/0 object Объект с данными изменения
    value_after|value_before/0/custom_field_value object Объект с данными изменения поля
    value_after|value_before/0/custom_field_value/field_id int ID измененого поля
    value_after|value_before/0/custom_field_value/field_type int Тип измененного поля
    value_after|value_before/0/custom_field_value/enum_id int|null ID enum значения поля, null, если у поля нет enum значений
    value_after|value_before/0/custom_field_value/text string Текст значения поля
    
    {
      "value_after": [
        {
          "custom_field_value": {
            "field_id": 53728,
            "field_type": 8,
            "enum_id": 2352876,
            "text": "example1@test.com"
          }
        },
        {
          "custom_field_value": {
            "field_id": 53728,
            "field_type": 8,
            "enum_id": 2352876,
            "text": "example@test.com"
          }
        }
      ],
      "value_before": [
        {
          "custom_field_value": {
            "field_id": 53728,
            "field_type": 8,
            "enum_id": 193200,
            "text": "example@test.com"
          }
        }
      ]
    }
    

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

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

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

{
  "_links": {
    "self": {
      "href": "/api/v2/events?limit=10",
      "method": "get"
    },
    "next": {
      "href": "/api/v2/events?limit=10&page=2",
      "method": "get"
    }
  },
  "_embedded": {
    "events": [
      {
        "id": "01dt79jq1bkjdakqetdhc96h4a",
        "type": "task_text_changed",
        "entity": {
          "type": "task",
          "id": 18340873
        },
        "created_by": 939801,
        "created_at": 1574350445,
        "value_after": [],
        "value_before": [
          {
            "task": {
              "text": "задача"
            }
          }
        ],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79jq1bkjdakqetdhc96h4a",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/tasks/?id=18340873",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79jpy3swbgwx6v4gsyvsyh",
        "type": "task_result_added",
        "entity": {
          "type": "task",
          "id": 18340873
        },
        "created_by": 939801,
        "created_at": 1574350445,
        "value_after": [
          {
            "note": {
              "id": 42726273,
              "_links": {
                "self": {
                  "href": "/api/v2/notes/?id=42726273",
                  "method": "get"
                }
              }
            }
          }
        ],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79jpy3swbgwx6v4gsyvsyh",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/tasks/?id=18340873",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79jpdkbh7xnaavg1tgcqcb",
        "type": "task_completed",
        "entity": {
          "type": "task",
          "id": 18340873
        },
        "created_by": 939801,
        "created_at": 1574350444,
        "value_after": [],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79jpdkbh7xnaavg1tgcqcb",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/tasks/?id=18340873",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79hz89htr8xw0ez14r27my",
        "type": "attachment_note_added",
        "entity": {
          "type": "lead",
          "id": 26056365
        },
        "created_by": 939801,
        "created_at": 1574350421,
        "value_after": [
          {
            "note": {
              "id": 42726271,
              "_links": {
                "self": {
                  "href": "/api/v2/notes/?id=42726271",
                  "method": "get"
                }
              }
            }
          }
        ],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79hz89htr8xw0ez14r27my",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/leads/?id=26056365",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79hjzzr19zwdc81j4nbarg",
        "type": "task_added",
        "entity": {
          "type": "task",
          "id": 18340873
        },
        "created_by": 939801,
        "created_at": 1574350408,
        "value_after": [],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79hjzzr19zwdc81j4nbarg",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/tasks/?id=18340873",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79hfqdmf47paj3a1zg8dcp",
        "type": "common_note_added",
        "entity": {
          "type": "lead",
          "id": 26056365
        },
        "created_by": 939801,
        "created_at": 1574350405,
        "value_after": [
          {
            "note": {
              "id": 42726269,
              "_links": {
                "self": {
                  "href": "/api/v2/notes/?id=42726269",
                  "method": "get"
                }
              }
            }
          }
        ],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79hfqdmf47paj3a1zg8dcp",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/leads/?id=26056365",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79hay1sdh95je98j44a55z",
        "type": "custom_field_1278897993_value_changed",
        "entity": {
          "type": "lead",
          "id": 26056365
        },
        "created_by": 939801,
        "created_at": 1574350400,
        "value_after": [
          {
            "custom_field_value": {
              "field_id": 1278897993,
              "field_type": 5,
              "enum_id": 3656843,
              "text": "чёрный"
            }
          },
          {
            "custom_field_value": {
              "field_id": 1278897993,
              "field_type": 5,
              "enum_id": 3656847,
              "text": "красный"
            }
          }
        ],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79hay1sdh95je98j44a55z",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/leads/?id=26056365",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79hay1r3ez5y4heb8eakw4",
        "type": "custom_field_1278898001_value_changed",
        "entity": {
          "type": "lead",
          "id": 26056365
        },
        "created_by": 939801,
        "created_at": 1574350400,
        "value_after": [
          {
            "custom_field_value": {
              "field_id": 1278898001,
              "field_type": 2,
              "enum_id": null,
              "text": "1000"
            }
          }
        ],
        "value_before": [],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79hay1r3ez5y4heb8eakw4",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/leads/?id=26056365",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79haxg8enkqv2r2cargr39",
        "type": "sale_field_changed",
        "entity": {
          "type": "lead",
          "id": 26056365
        },
        "created_by": 939801,
        "created_at": 1574350400,
        "value_after": [
          {
            "sale_field_value": {
              "sale": 100
            }
          }
        ],
        "value_before": [
          {
            "sale_field_value": {
              "sale": 1
            }
          }
        ],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79haxg8enkqv2r2cargr39",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/leads/?id=26056365",
            "method": "get"
          }
        }
      },
      {
        "id": "01dt79haxf32hmk144vvkq6wax",
        "type": "name_field_changed",
        "entity": {
          "type": "lead",
          "id": 26056365
        },
        "created_by": 939801,
        "created_at": 1574350400,
        "value_after": [
          {
            "name_field_value": {
              "name": "Название новое"
            }
          }
        ],
        "value_before": [
          {
            "name_field_value": {
              "name": "Название"
            }
          }
        ],
        "_links": {
          "self": {
            "href": "/api/v2/events/?filter[id]=01dt79haxf32hmk144vvkq6wax",
            "method": "get"
          },
          "entity": {
            "href": "/api/v2/leads/?id=26056365",
            "method": "get"
          }
        }
      }
    ]
  }
}

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


/* Для начала нам необходимо инициализировать данные, необходимые для составления запроса. */
$subdomain = 'test'; #Наш аккаунт - поддомен
/* Формируем ссылку для запроса */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/events';
/* Заметим, что в ссылке можно передавать и другие параметры, которые влияют на выходной результат (смотрите документацию
выше).
Следовательно, мы можем заменить ссылку, приведённую выше на одну из следующих, либо скомбинировать параметры так, как Вам
необходимо. */
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/events?limit=10';
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/events?filter[entity]=lead&filter[entity_id]=123344';
/* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Подробнее о
работе с этой
библиотекой Вы можете прочитать в мануале. */
$curl = curl_init();
/* Устанавливаем необходимые опции для сеанса 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',
    409 => 'Conflict',
    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']['events'];

Возможные ошибки и ограничения

Всего данный метод может вернуть 6 видов ошибок:

Передан пустой фильтр

В случае передачи передачи несуществующего аргумента в фильтры value_after/value_before, вы получите ошибку с http-кодом 400. В ошибке в объекте errors будет передан объект разъясняющий ошибку и несущий в себе информацию, какой ключ не верный в запросе.


{
  "errors": {
    "key": "value_after"
  },
  "status": 400,
  "detail": "Please, check your filter.",
  "title": "Filter can not be empty.",
  "type": "https://www.amocrm.ru/developers/content/platform/events"
}

Передан некорректный фильтр.

В случае передачи передачи невалидного параметра в фильтр, например несуществующий ID пользователя, статус сделки, ID воронки, тип сущности, вы получите ошибку с http-кодом 400. В ошибке в объекте errors будет передан объект разъясняющий ошибку и несущий в себе информацию, какой ключ не верный в запросе, а также какое значение не верное в запросе.


{
  "errors": {
    "key": "created_by",
    "value": 12414,
    "detail": "Invalid user_id given."
  },
  "status": 400,
  "detail": "Please, check your filter.",
  "title": "Invalid params passed to filter.",
  "type": "https://www.amocrm.ru/developers/content/platform/events"
}

Переданный фильтр не содержит обязательного параметра

В данный момент действуют следующие обязательные параметры:

  1. filter[entity_id] – вместе с этим фильтром необходимо передать filter[entity_type].
  2. filter[value_after|value_before][value] – вместе с этим фильтром обязательным параметром необходимо уточнить filter[type].
  3. filter[value_after|value_before][custom_field_values] – вместе с этим фильтром обязательным параметром необходимо передать в filter[type] событие изменения поля, в котором содержится ID поля.

В случае передачи фильтра без обязательного параметра вы получите ошибку с http-кодом 400. В ошибке в объекте errors будет передан объект разъясняющий ошибку и несущий в себе информацию, какой ключ не присутствует в запросе.


{
  "errors": {
    "key": "type"
  },
  "status": 400,
  "detail": "Please, check your filter.",
  "title": "Required param missed. You must specify filter.",
  "type": "https://www.amocrm.ru/developers/content/platform/events"
}

Передан фильтр, установленные лимиты.

В данный момент действуют следующие ограничения:

  1. filter[created_by] – не более 10 ID пользователей в одном запросе.
  2. filter[entity_id] – не более 10 ID сущностей в одном запросе и не более 1 типа сущности.
  3. filter[value_after|value_before][custom_field_values] – не более 1 типа событий с ID поля в одном запросе.
  4. filter[id] – не более 100 ID событий в одном запросе.

В случае передачи фильтра превышающего лимиты вы получите ошибку с http-кодом 400. В ошибке в объекте errors будет передан объект разъясняющий ошибку и несущий в себе информацию, какой ключ превысил лимит, а также действующий лимит.


{
  "errors": {
    "key": "created_by",
    "limit": 10
  },
  "status": 400,
  "detail": "Please, specify your filter.",
  "title": "More params given than allowed.",
  "type": "https://www.amocrm.ru/developers/content/platform/events"
}

Передан фильтр, значения которого не совместимы.

В случае передачи конфликтующего фильтра вы получите ошибку с http-кодом 409. В ошибке в объекте errors будет передан объект разъясняющий ошибку и несущий в себе информацию, какой именно параметр неверен.


{
  "errors": {
    "key": "value_after",
    "param": "type",
    "value": "lead_added",
    "detail": "Only custom_field_value_changed, sale_field_changed, name_field_changed, ltv_field_changed types can be passed with given filter."
  },
  "status": 409,
  "detail": "Please, check your filter.",
  "title": "Given filter conflict with other parameters",
  "type": "https://www.amocrm.ru/developers/content/platform/events"
}

Передано некорректное значение параметра with

В случае передачи недопустимого значения параметра with вы получите ошибку с http-кодом 400. В ошибке в объекте errors будет передан объект разъясняющий ошибку и несущий в себе информацию, какой именно параметр неверен.


{
  "errors": {
    "key": "with",
    "detail": "Invalid with - my_with"
  },
  "status": 400,
  "detail": "Please, check your with parameter.",
  "title": "Invalid with parameter given",
  "type": "https://www.amocrm.ru/developers/content/platform/events"
}

Типы списка событий

Метод для получения типов событий с их переводом.

URL метода

GET /api/v2/events/types/

Параметры GET

Параметр Описание
language_code Код языка, в котором вернутся названия типов событий. Если не передан, то вернется в языке пользователя,
под которым происходит запрос. Возможные параметры – en, es, ru.

Описание параметров ответа

Параметр Тип Описание
_links array Массив содержащий информацию о запросе
_links/self array Массив содержащий информацию о текущем запросе
_links/self/href string Относительный URL текущего запроса
_links/self/method string Метод текущего запроса
_embedded array Массив содержащий информацию прилегающую к запросу
_embedded/types array Массив содержащий информацию по каждому отдельному типу
_embedded/types//key string Тип события
_embedded/types//lang string Локализированное название события
_embedded/types//field_id string ID поля, возвращается только для типов событий по конкретным полям

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

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

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


{
  "_links": {
    "self": {
      "href": "/api/v2/events/types?language_code=ru",
      "method": "get"
    }
  },
  "_embedded": {
    "types": {
      "lead_added": {
        "key": "lead_added",
        "type": 1,
        "lang": "Новая сделка"
      },
      "lead_deleted": {
        "key": "lead_deleted",
        "type": 7,
        "lang": "Сделка удалена"
      },
      "lead_restored": {
        "key": "lead_restored",
        "type": 10,
        "lang": "Сделка восстановлена"
      },
      "lead_status_changed": {
        "key": "lead_status_changed",
        "type": 14,
        "lang": "Изменение этапа продажи"
      },
      "lead_linked": {
        "key": "lead_linked",
        "type": 80,
        "lang": "Прикрепление сделки"
      },
      ...............
      "custom_field_1278897670_value_changed": {
        "key": "custom_field_1278897670_value_changed",
        "type": 24,
        "lang": "Изменение поля \"Телефон\"",
        "field_id": 1278897670
      }
    }
  }
}