Сделки

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

Оглавление

Список сделок

Метод

GET /api/v4/leads

Описание

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

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
query string
int		 Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
filter object Фильтр. Подробней про фильтры читайте в отдельной статье
order object Сортировка результатов списка.
Доступные поля для сортировки: created_at, updated_at, id.
Доступные значения для сортировки: asc, desc.
Пример: /api/v4/leads?order[updated_at]=asc

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован

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

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

Параметр Тип данных Описание
id int ID сделки
name string Название сделки
price int Бюджет сделки
responsible_user_id int ID пользователя, ответственного за сделку
group_id int ID группы, в которой состоит ответственны пользователь за сделку
status_id int ID статуса, в который добавляется сделка, по-умолчанию – первый этап главной воронки
pipeline_id int ID воронки, в которую добавляется сделка
loss_reason_id int ID причины отказа
source_id int Требуется GET параметр with. ID источника сделки
created_by int ID пользователя, создающий сделку
updated_by int ID пользователя, изменяющий сделку
closed_at int Дата закрытия сделки, передается в Unix Timestamp
created_at int Дата создания сделки, передается в Unix Timestamp
updated_at int Дата изменения сделки, передается в Unix Timestamp
closest_task_at int Дата ближайшей задачи к выполнению, передается в Unix Timestamp
is_deleted bool Удалена ли сделка
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данной сделки
score int
null		 Скоринг сделки
account_id int ID аккаунта, в котором находится сделка
labor_cost int Тип поля "стоимость труда" показывает сколько времени было затрачено на работу со сделкой. Время исчисления в секундах
is_price_modified_by_robot bool Требуется GET параметр with. Изменен ли в последний раз бюджет сделки роботом
_embedded object Данные вложенных сущностей
_embedded[loss_reason] object Требуется GET параметр with. Причина отказа сделки
_embedded[loss_reason][id] int ID причины отказа
_embedded[loss_reason][name] string Название причины отказа
_embedded[tags] array Данные тегов, привязанных к сделке
_embedded[tags][0] object Модель тега, привязанного к сделке
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
_embedded[tags][0][color] string|null Цвет тега
_embedded[contacts] array Требуется GET параметр with. Данные контактов, привязанных к сделке
_embedded[contacts][0] object Данные контакта, привязанного к сделке
_embedded[contacts][0][id] int ID контакта, привязанного к сделке
_embedded[contacts][0][is_main] bool Является ли контакт главным для сделки
_embedded[companies] array Данные компании, привязанной к сделке, в данном массиве всегда 1 элемент, так как у сделки может быть только 1 компания
_embedded[companies][0] object Данные компании, привязанного к сделке
_embedded[companies][0][id] int ID контакта, привязанного к сделке
_embedded[catalog_elements] array Требуется GET параметр with. Данные элементов списков, привязанных к сделке
_embedded[catalog_elements][0] object Данные элемента списка, привязанного к сделке
_embedded[catalog_elements][0][id] int ID элемента, привязанного к сделке
_embedded[catalog_elements][0][metadata] object Мета-данные элемента
_embedded[catalog_elements][0][quantity] int
float		 Количество элементов у сделки
_embedded[catalog_elements][0][catalog_id] int ID списка, в котором находится элемент
_embedded[catalog_elements][0][price_id] int ID поля типа Цена, которое будет установлено для привязанного элемента в сущности

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

{
    "_page": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=2"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=3"
        },
        "first": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=1"
        },
        "prev": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=1"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 19619,
                "name": "Сделка для примера",
                "price": 46333,
                "responsible_user_id": 123321,
                "group_id": 625,
                "status_id": 142,
                "pipeline_id": 1300,
                "loss_reason_id": null,
                "source_id": null,
                "created_by": 321123,
                "updated_by": 321123,
                "created_at": 1453279607,
                "updated_at": 1502193501,
                "closed_at": 1483005931,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "score": null,
                "account_id": 5135160,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/19619"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            },
            {
                "id": 14460,
                "name": "Сделка для примера 2",
                "price": 655,
                "responsible_user_id": 123321,
                "group_id": 625,
                "status_id": 142,
                "pipeline_id": 1300,
                "loss_reason_id": null,
                "source_id": null,
                "created_by": 321123,
                "updated_by": 321123,
                "created_at": 1453279607,
                "updated_at": 1502193501,
                "closed_at": 1483005931,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "score": null,
                "account_id": 1351360,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/14460"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Параметры для GET-параметра with

Параметр Описание
catalog_elements Добавляет в ответ связанные со сделками элементы списков
is_price_modified_by_robot Добавляет в ответ свойство, показывающее, изменен ли в последний раз бюджет сделки роботом
loss_reason Добавляет в ответ расширенную информацию по причине отказа
contacts Добавляет в ответ информацию о связанных со сделкой контактах
only_deleted Если передать данный параметр, то в ответе на запрос метода, вернутся удаленные сделки, которые еще находятся в корзине. В ответ вы получите модель сделки, у которой доступны дату изменения, ID пользователя сделавшего последнее изменение, её ID и параметр is_deleted = true.
source_id Добавляет в ответ ID источника

Получение сделки по ID

Метод

GET /api/v4/leads/{id}

Описание

Метод позволяет получить данные конкретной сделки по ID.

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
204 Сделка с указанным ID не существует
401 Пользователь не авторизован

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

Метод возвращает модель сделки, рассмотрим ниже её свойства.

Параметр Тип данных Описание
id int ID сделки
name string Название сделки
price int Бюджет сделки
responsible_user_id int ID пользователя, ответственного за сделку
group_id int ID группы, в которой состоит ответственны пользователь за сделку
status_id int ID статуса, в который добавляется сделка, по-умолчанию – первый этап главной воронки
pipeline_id int ID воронки, в которую добавляется сделка
loss_reason_id int ID причины отказа
source_id int Требуется GET параметр with. ID источника сделки
created_by int ID пользователя, создающий сделку
updated_by int ID пользователя, изменяющий сделку
closed_at int Дата закрытия сделки, передается в Unix Timestamp
created_at int Дата создания сделки, передается в Unix Timestamp
updated_at int Дата изменения сделки, передается в Unix Timestamp
closest_task_at int Дата ближайшей задачи к выполнению, передается в Unix Timestamp
is_deleted bool Удалена ли сделка
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данной сделки
score int
null		 Скоринг сделки
account_id int ID аккаунта, в котором находится сделка
labor_cost int Тип поля "стоимость труда" показывает сколько времени было затрачено на работу со сделкой. Время исчисления в секундах
is_price_modified_by_robot bool Требуется GET параметр with. Изменен ли в последний раз бюджет сделки роботом
_embedded object Данные вложенных сущностей
_embedded[loss_reason] object Требуется GET параметр with. Причина отказа сделки
_embedded[loss_reason][id] int ID причины отказа
_embedded[loss_reason][name] string Название причины отказа
_embedded[tags] array Данные тегов, привязанных к сделке
_embedded[tags][0] object Модель тега, привязанного к сделке
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
_embedded[tags][0][color] string|null Цвет тега
_embedded[contacts] array Требуется GET параметр with. Данные контактов, привязанных к сделке
_embedded[contacts][0] object Данные контакта, привязанного к сделке
_embedded[contacts][0][id] int ID контакта, привязанного к сделке
_embedded[contacts][0][is_main] bool Является ли контакт главным для сделки
_embedded[companies] array Данные компании, привязанной к сделке, в данном массиве всегда 1 элемент, так как у сделки может быть только 1 компания
_embedded[companies][0] object Данные компании, привязанного к сделке
_embedded[companies][0][id] int ID контакта, привязанного к сделке
_embedded[catalog_elements] array Требуется GET параметр with. Данные элементов списков, привязанных к сделке
_embedded[catalog_elements][0] object Данные элемента списка, привязанного к сделке
_embedded[catalog_elements][0][id] int ID элемента, привязанного к сделке
_embedded[catalog_elements][0][metadata] object Мета-данные элемента
_embedded[catalog_elements][0][quantity] int
float		 Количество элементов у сделки
_embedded[catalog_elements][0][catalog_id] int ID списка, в котором находится элемент
_embedded[catalog_elements][0][price_id] int ID поля типа Цена, которое установлено для привязанного элемента в сущности

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

{
    "id": 3912171,
    "name": "Example",
    "price": 12,
    "responsible_user_id": 504141,
    "group_id": 0,
    "status_id": 143,
    "pipeline_id": 3104455,
    "loss_reason_id": 4203748,
    "source_id": null,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1585299171,
    "updated_at": 1590683337,
    "closed_at": 1590683337,
    "closest_task_at": null,
    "is_deleted": false,
    "custom_fields_values": null,
    "score": null,
    "account_id": 28805383,
    "is_price_modified_by_robot": false,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/3912171"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 100667,
                "name": "тест",
                "color": null,
            }
        ],
        "catalog_elements": [
            {
                "id": 525439,
                "metadata": {
                    "quantity": 1,
                    "catalog_id": 4521
                }
            }
        ],
        "loss_reason": [
            {
                "id": 4203748,
                "name": "Пропала потребность",
                "sort": 100000,
                "created_at": 1582117280,
                "updated_at": 1582117280,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/loss_reasons/4203748"
                    }
                }
            }
        ],
        "companies": [
            {
                "id": 10971463,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/10971463"
                    }
                }
            }
        ],
        "contacts": [
            {
                "id": 10971465,
                "is_main": true,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/10971465"
                    }
                }
            }
        ]
    }
}

Параметры для GET-параметра with

Параметр Описание
catalog_elements Добавляет в ответ связанные со сделками элементы списков
is_price_modified_by_robot Добавляет в ответ свойство, показывающее, изменен ли в последний раз бюджет сделки роботом
loss_reason Добавляет в ответ расширенную информацию по причине отказа
contacts Добавляет в ответ информацию о связанных со сделкой контактах
only_deleted Если передать данный параметр, то в ответе на запрос метода, вернутся удаленные сделки, которые еще находятся в корзине. В ответ вы получите модель сделки, у которой доступны дату изменения, ID пользователя сделавшего последнее изменение, её ID и параметр is_deleted = true.
source_id Добавляет в ответ ID источника

Добавление сделок

Метод

POST /api/v4/leads

Описание

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

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют

Параметр Тип данных Описание
name string Название сделки. Поле не является обязательным
price int Бюджет сделки. Поле не является обязательным
status_id int ID статуса, в который добавляется сделка. Поле не является обязательным, по-умолчанию – первый этап главной воронки
pipeline_id int ID воронки, в которую добавляется сделка. Поле не является обязательным
created_by int ID пользователя, создающий сделку. При передаче значения 0, сделка будет считаться созданной роботом. Поле не является обязательным
updated_by int ID пользователя, изменяющий сделку. При передаче значения 0, сделка будет считаться измененной роботом. Поле не является обязательным
closed_at int Дата закрытия сделки, передается в Unix Timestamp. Поле не является обязательным
created_at int Дата создания сделки, передается в Unix Timestamp. Поле не является обязательным
updated_at int Дата изменения сделки, передается в Unix Timestamp. Поле не является обязательным
loss_reason_id int ID причины отказа. Поле не является обязательным
responsible_user_id int ID пользователя, ответственного за сделку. Поле не является обязательным
custom_fields_values array Массив, содержащий информацию по дополнительным полям, заданным для данной сделки. Поле не является обязательным. Примеры заполнения полей
tags_to_add array Массив тегов для добавления.
tags_to_add[0] object Модель тега для добавления.
tags_to_add[0][id] array ID тега для добавления. Важно передать или id или name.
tags_to_add[0][name] array Название тега для добавления. Важно передать или id или name.
_embedded object Данные вложенных сущностей, при создании и редактировании можно передать только теги. Поле не является обязательным
_embedded[tags] array
null		 Данные тегов, добавляемых к сделке
_embedded[tags][0] object Модель тега, добавляемого к сделке. Необходимо указать id или name
_embedded[tags][0][id] int ID тега
_embedded[contacts] array Данные контактов, которые будет прикреплены к сделке
_embedded[contacts][0] object Модель контакта, добавляемого к сделке. Необходимо указать id
_embedded[contacts][0][id] int ID контакта
_embedded[contacts][0][is_main] string Флаг, показывающий, является контакт главным или нет
_embedded[companies] array Данные компании, которая будет прикреплена к сделке
_embedded[companies][0] object Модель компании, добавляемой к сделке. Необходимо указать id
_embedded[companies][0][id] int ID компании
_embedded[source][external_id] int Внешний ID источника. Источник можно добавить с помощью API Исчтоников. Если передан external_id источника и не передан pipeline_id, сделка будет добавлена в воронку, в которой находится источник.
_embedded[source][type] string Тип источника. Для сделок, добавляемых интеграциями, поддерживается только widget

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

В данном примере мы создадим 2 сделки.
Для первой мы зададим название, бюджет, создателя – робота, а также значение текстового поля.
Для второй сделки мы зададим название, бюджет и добавим тег.

[
    {
        "name": "Сделка для примера 1",
        "created_by": 0,
        "price": 20000,
        "custom_fields_values": [
            {
                "field_id": 294471,
                "values": [
                    {
                        "value": "Наш первый клиент"
                    }
                ]
            }
        ],
        "tags_to_add": [
            {
              "name": "Первый тег"
            },
            {
              "id": 217261
            }
        ]
    },
    {
        "name": "Сделка для примера 2",
        "price": 10000,
        "_embedded": {
            "tags": [
                {
                    "id": 2719
                }
            ]
        }
    }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Сделки были успешно созданы
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает коллекцию сделок, которые были созданы.

Параметр Тип данных Описание
id int ID сделки
request_id string Строка переданная при запросе или порядковый указатель, если параметр не передан

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 10185151,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/10185151"
                    }
                }
            },
            {
                "id": 10185153,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/10185153"
                    }
                }
            }
        ]
    }
}

Комплексное добавление сделок с контактом и компанией

Метод

POST /api/v4/leads/complex

Описание

Метод позволяет добавлять сделки c контактом и компанией в аккаунт пакетно. Добавляемые данные могут быть проверены в контроле дублей.

Ограничения

Метод доступен в соответствии с правами пользователя.
Для одной сделки можно указать не более 1 связанного контакта и 1 связанной компании.
Для добавляемых сущностей (сделка, контакт, компания), можно передать не более 40 значений дополнительных полей.
Добавляемые данные участвуют в контроле дублей, если он включен для интеграции, которая добавляет данные.
Метод не производит дедубликацию переданных данных, а только ищет дубли среди уже добавленных данных.
За один запрос можно передать не более 50 сделок.
При создании нового контакта и компании, они будут связаны между собой.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют

Параметр Тип данных Описание
name string Название сделки. Поле не является обязательным
price int Бюджет сделки. Поле не является обязательным
status_id int ID статуса, в который добавляется сделка. Поле не является обязательным, по-умолчанию – первый этап главной воронки
pipeline_id int ID воронки, в которую добавляется сделка. Поле не является обязательным
created_by int ID пользователя, создающий сделку. При передаче значения 0, сделка будет считаться созданной роботом. Поле не является обязательным
updated_by int ID пользователя, изменяющий сделку. При передаче значения 0, сделка будет считаться измененной роботом. Поле не является обязательным
closed_at int Дата закрытия сделки, передается в Unix Timestamp. Поле не является обязательным
created_at int Дата создания сделки, передается в Unix Timestamp. Поле не является обязательным
updated_at int Дата изменения сделки, передается в Unix Timestamp. Поле не является обязательным
loss_reason_id int ID причины отказа. Поле не является обязательным
responsible_user_id int ID пользователя, ответственного за сделку. Поле не является обязательным
custom_fields_values array Массив, содержащий информацию по дополнительным полям, заданным для данной сделки. Поле не является обязательным. Примеры заполнения полей
Можно передать не более 40 полей для одной сделки. Если необходимо передать больше – вы можете выполнить операцию обновления после создания или создать через общий метод, который не производит контроля дублей
tags_to_add array Массив тегов для добавления.
tags_to_add[0] object Модель тега для добавления.
tags_to_add[0][id] array ID тега для добавления. Важно передать или id или name.
tags_to_add[0][name] array Название тега для добавления. Важно передать или id или name.
_embedded object Данные вложенных сущностей, при создании можно передать теги, данные связанного контакта, данные связанной компании, метаданные (если создаем неразобранное). Поле не является обязательным
_embedded[tags] array
null		 Данные тегов, добавляемых к сделке
_embedded[tags][0] object Модель тега, добавляемого к сделке. Необходимо указать id или name
_embedded[tags][0][id] int ID тега
_embedded[contacts] array Данные контакта, который будет прикреплен к сделке
_embedded[contacts][0] object Данные контакта, который будет прикреплен к сделке. Можно передать поле _embedded[contacts][0][id] с ID контакта или полную модель контакта. В моделе должно быть передано не более 40 значений дополнительных полей. Подробней о параметрах контакта читайте в разделе Параметры запроса
_embedded[companies] array Данные компании, которая будет прикреплена к сделке
_embedded[companies][0] object Данные компании, которая будет прикреплена к сделке.Можно передать поле _embedded[companies][0][id] с ID контакта или полную модель компании. В моделе должно быть передано не более 40 значений дополнительных полей. Подробней о параметрах компании читайте в разделе Параметры запроса
_embedded[metadata] array Массив, содержащий метаданные для заявки, создаваемой в неразобранном. Если переданы метаданные, мы считаем, что это неразобранное сделки и переданный статус, отличный от статус Неразобранное будет проигнорирован
Параметры аналогичны тем, что передаются при создании неразобранного, за исключением необходимости передачи дополнительного ключа category.Подробней о параметрах метаданных читайте тут
_embedded[metadata][category] string Категория неразобранного. Допустимые варианты – sip, forms
_embedded[source][external_id] int Внешний ID источника. Источник можно добавить с помощью API Исчтоников. Если передан external_id источника и не передан pipeline_id, сделка будет добавлена в воронку, в которой находится источник.
_embedded[source][type] string Тип источника. Для сделок, добавляемых интеграциями, поддерживается только widget

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

В данном примере мы создадим сделку с контактом и компанией, а также неразобранную сделку категории формы в статусе неразобранное с контактом.

[
   {
      "name": "Название сделки",
      "price": 3422,
      "_embedded":{
         "contacts":[
            {
               "first_name":"Екатерина",
               "created_at":1608905348,
               "responsible_user_id":2004184,
               "updated_by":0,
               "custom_fields_values":[
                  {
                     "field_id":66186,
                     "values":[
                        {
                           "enum_id":193200,
                           "value":"example@example.com"
                        }
                     ]
                  },
                  {
                     "field_id":66192,
                     "values":[
                        {
                           "enum_id":193226,
                           "value":"+79123456789"
                        }
                     ]
                  }
               ]
            }
         ],
         "companies":[
            {
               "name":"ООО Рога и Копыта"
            }
         ]
      },
      "created_at":1608905348,
      "responsible_user_id":2004184,
      "custom_fields_values":[
         {
            "field_id":1286573,
            "values":[
               {
                  "value":"Поле текст"
               }
            ]
         },
         {
            "field_id":1286575,
            "values":[
               {
                  "enum_id":2957741
               },
               {
                  "enum_id":2957743
               }
            ]
         }
      ],
      "status_id":33929752,
      "pipeline_id":3383152,
      "request_id": "qweasd"
   },
   {
      "name": "Название сделки",
      "price": 3422,
      "_embedded":{
         "metadata":{
            "category": "forms",
            "form_id": 123,
            "form_name": "Форма на сайте",
            "form_page": "https://example.com",
            "form_sent_at": 1608905348,
            "ip": "8.8.8.8",
            "referer": "https://example.com/form.html"
         },
         "contacts":[
            {
               "first_name":"Евгений",
               "custom_fields_values":[
                  {
                     "field_code":"EMAIL",
                     "values":[
                        {
                           "enum_code":"WORK",
                           "value":"unsorted_example@example.com"
                        }
                     ]
                  },
                  {
                     "field_code":"PHONE",
                     "values":[
                        {
                           "enum_code":"WORK",
                           "value":"+79129876543"
                        }
                     ]
                  }
               ]
            }
         ]
      },
      "status_id":33929749,
      "pipeline_id":3383152,
      "request_id": "uns_qweasd"
   }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Сделки были успешно созданы
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

Параметр Тип данных Описание
id int ID сделки
contact_id int
null		 ID контакта
company_id int
null		 ID компании
merged bool Флаг, который показывает, найден дубль подходящий под условия поиска дублей и произведено объединение или нет
request_id string[] Массив строк с пользовательскими идентификаторами, которые были переданы с каждой сущностью.
Если дубли не найдены, в массиве всегда будет 1 элемент.
Множественное значение может вернуться в случае, если передано несколько дублей одной и той же сделки. В такой случае вернется результирующая сделка, а в массиве request_id будут идентификаторы переданных сделок, которые являются дублями.

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

[
   {
      "id":15198335,
      "contact_id":19663157,
      "company_id":19663155,
      "request_id":[
         "qweasd"
      ],
      "merged":false
   },
   {
      "id":15198337,
      "contact_id":19663161,
      "company_id":19663159,
      "request_id":[
         "uns_qweasd"
      ],
      "merged":false
   }
]

Редактирование сделок

Метод

PATCH /api/v4/leads

Описание

Метод позволяет редактировать сделки пакетно.
Также вы можете добавить ID сделки в метод для редактирования конкретной сделки (/api/v4/leads/{id}).
При редактировании пакетно передается массив из объектов-сделок, при редактировании одной сделки, передается просто модель сделки.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют

Параметр Тип данных Описание
id int ID сделки
name string Название сделки. Поле не является обязательным
price int Бюджет сделки. Поле не является обязательным
status_id int ID статуса, в который добавляется сделка. Поле не является обязательным, по-умолчанию – первый этап главной воронки
pipeline_id int ID воронки, в которую добавляется сделка. Поле не является обязательным
created_by int ID пользователя, создающий сделку. При передаче значения 0, сделка будет считаться созданной роботом. Поле не является обязательным
updated_by int ID пользователя, изменяющий сделку. При передаче значения 0, сделка будет считаться измененной роботом. Поле не является обязательным
closed_at int Дата закрытия сделки, передается в Unix Timestamp. Поле не является обязательным
created_at int Дата создания сделки, передается в Unix Timestamp. Поле не является обязательным
updated_at int Дата изменения сделки, передается в Unix Timestamp. Поле не является обязательным
loss_reason_id int ID причины отказа. Поле не является обязательным
responsible_user_id int ID пользователя, ответственного за сделку. Поле не является обязательным
custom_fields_values array Массив, содержащий информацию по дополнительным полям, заданным для данной сделки. Поле не является обязательным. Примеры заполнения полей
tags_to_add array Массив тегов для добавления.
tags_to_add[0] object Модель тега для добавления.
tags_to_add[0][id] array ID тега для добавления. Важно передать или id или name.
tags_to_add[0][name] array Название тега для добавления. Важно передать или id или name.
tags_to_delete array Массив тегов для удаления.
tags_to_delete[0] object Модель тега для удаления.
tags_to_delete[0][id] array ID тега для удаления. Важно передать или id или name.
tags_to_delete[0][name] array Название тега для удаления. Важно передать или id или name.
_embedded object Данные вложенных сущностей, при создании и редактировании можно передать только теги. Поле не является обязательным
_embedded[tags] array|null Данные тегов, добавляемых к сделке
_embedded[tags][0] object Модель тега, добавляемого к сделке. Необходимо указать id или name
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега

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

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

[
    {
        "id": 54886,
        "pipeline_id": 47521,
        "status_id": 143,
        "closed_at": 1589297221,
        "loss_reason_id": 7323,
        "updated_by": 0,
        "tags_to_add": [
            {
                "name": "Второй тег"
            }
        ],
        "tags_to_delete": [
            {
                "name": "Первый тег"
            }
        ]
    },
    {
        "id": 54884,
        "price": 50000,
        "pipeline_id": 47521,
        "status_id": 525743,
        "_embedded": {
            "tags": null
        }
    }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Сделки были успешно изменены
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

Параметр Тип данных Описание
id int ID сделки
updated_at int Unix Timestamp изменения сделки

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 54886,
                "updated_at": 1589556420,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/54886"
                    }
                }
            },
            {
                "id": 54884,
                "updated_at": 1589556420,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/54884"
                    }
                }
            }
        ]
    }
}