Сделки

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

Оглавление

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

Метод

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 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 аккаунта, в котором находится сделка
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[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 Количество элементов у сделки
_embedded[catalog_elements][0][catalog_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.

Получение сделки по 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 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 аккаунта, в котором находится сделка
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[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 Количество элементов у сделки
_embedded[catalog_elements][0][catalog_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": "тест"
            }
        ],
        "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.

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

Метод

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 Массив, содержащий информацию по дополнительным полям, заданным для данной сделки. Поле не является обязательным. Примеры заполнения полей
_embedded object Данные вложенных сущностей, при создании и редактировании можно передать только теги. Поле не является обязательным
_embedded[tags] array|null Данные тегов, добавляемых к сделке
_embedded[tags][0] object Модель тега, добавляемого к сделке. Необходимо указать id или name
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

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

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

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

        
{
    "_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"
                    }
                }
            }
        ]
    }
}
        
    

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

Метод

PATCH /api/v4/leads

Описание

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

Ограничения

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

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

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 Массив, содержащий информацию по дополнительным полям, заданным для данной сделки. Поле не является обязательным. Примеры заполнения полей
_embedded object Данные вложенных сущностей, при создании и редактировании можно передать только теги. Поле не является обязательным
_embedded[tags] array|null Данные тегов, добавляемых к сделке
_embedded[tags][0] object Модель тега, добавляемого к сделке. Необходимо указать id или name
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

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

        
[
    {
        "id": 54886,
        "pipeline_id": 47521,
        "status_id": 143,
        "date_close": 1589297221,
        "loss_reason_id": 7323,
        "updated_by": 0
    },
    {
        "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 Переданы некорректные данные. Подробности доступны в теле ответа

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

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

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

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