Сделки

Одна сделка

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

URL метода

GET /api/v4/leads/{id}

Параметры GET

Параметр Тип Описание
id int Уникальный идентификатор сделки

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

Content-Type:application/hal+json

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


{
    "id": 17657,
    "name": "Тестовая сделка",
    "price": 25000,
    "responsible_user_id": 321123,
    "group_id": 0,
    "status_id": 2030,
    "pipeline_id": 1113,
    "loss_reason_id": null,
    "source_id": null,
    "created_by": 12332,
    "updated_by": 12323,
    "created_at": 1587741226,
    "updated_at": 1588241643,
    "closed_at": null,
    "closest_task_at": null,
    "is_deleted": false,
    "custom_fields_values": [
        {
            "field_id": 1278898021,
            "field_name": "Кастомное поле",
            "field_code": null,
            "field_type": "date",
            "values": [
                {
                    "value": "2020-05-08"
                }
            ]
        }
    ],
    "score": null,
    "account_id": 115135,
    "_links": {
        "self": {
            "href": "https://example.amcrm.ru/api/v4/leads/17657"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 1252595,
                "name": "Тег для примера"
            },
        ],
        "companies": [
            {
                "id": 40401297,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/40401297"
                    }
                }
            }
        ]
    }
}

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

Параметр Тип Описание
id int Уникальный идентификатор сделки
name string Название сделки
price int Бюджет сделки
status_id int ID этапа цифровой воронки, на котором находится данная сделка
pipeline_id int ID цифровой воронки, в которой находится сделка
account_id int ID аккаунта, в котором создана сделка
responsible_user_id int Ответственный сделки
group_id int ID группы в которой состоит пользователь ответственный за данную сделку
loss_reason_id int ID причины отказа
source_id int ID источника сделки
created_by int ID пользователя, создавшего сделку
created_at timestamp Время и дата создания сделки
updated_by int ID пользователя, обновившего параметры сделки
updated_at timestamp Время и дата когда была обновлена сделка
closed_at timestamp Время и дата, когда была завершена данная сделка
closest_task_at timestamp Время ближайшей задачи по данной сделке
is_deleted bool Удалена сделка или нет. Удалённые сделки могут находиться в “удалённых”.
custom_fields_values array Массив, содержащий информацию по дополнительным полям, заданным для данной сделки
_links array Массив содержащий ссылку на текущий запрос
_embedded array Массив вложенных сущностей для сделки, например, мы можем получить все теги и компании связанные со сделкой

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

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

URL метода

GET /api/v4/leads

Возможные GET параметры запроса

Параметр Тип Описание
page int Страница выборки
limit int Кол-во сделок возвращаемых за один запрос (Системное ограничение – 250 сделок)
query mixed Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
with mixed Если в параметре with указать значения (список см. здесь) в ответ придет дополнительная информация по сделке

Значения GET параметра with:

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

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

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

Content-Type:application/hal+json

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


{
    "_page": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=2&offset=50"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=3&offset=100"
        },
        "first": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=1&offset=0"
        },
        "prev": {
            "href": "https://example.amocrm.ru/api/v4/leads?limit=2&page=1&offset=0"
        }
    },
    "_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": []
                }
            }
        ]
    }
}

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

Параметр Тип Описание
_page int Номер текущей страницы
_embedded/leads array Список сделок, попавших в выборку
_links array Список ссылок на предыдущую, следующую, первую и текущую страницы

Создание сделок

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

URL метода

POST /api/v4/leads

Для создания сделок необходимо в теле запроса передать массив с описанием сделки/сделок в формате JSON.

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

Параметр Тип Описание
name string Имя сделки
price int Бюджет сделки
visitor_uid string Уникальный идентификатор посетителя
status_id id ID этапа цифровой воронки, на котором находится данная сделка
pipeline_id id ID цифровой воронки, в которой находится сделка
created_by int ID пользователя, создавшего сделку
updated_by int ID пользователя, обновившего параметры сделки
responsible_user_id int ID пользователя ответственного за сделку
custom_fields_values array Массив, содержащий информацию по дополнительным полям, заданным для данной сделки
_embedded array Массив вложенных сущностей для сделки

Например создадим две сделки:

Первую назовем “Сделка для примера 1”, выставим ей бюджет 20000 руб. и заполним значение дополнительного поля

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


POST http://example.amocrm.ru/api/v4/leads
Content-Type: application/json

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

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

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

Content-Type:application/hal+json


Content-Type: application/hal+json

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

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

Параметр Тип Описание
_links array Список ссылок на предыдущую, следующую, первую и текущую страницы
_embedded/leads array Список сделок, которые были созданы в результате запроса. Каждая сделка содержит уникальный идентификатор и ссылку на получение подробной информации по созданной сделке

Изменение сделок

Метод позволяет изменять следующие значения у сделки:

Параметр Тип Описание
name string Название сделки
price int Бюджет сделки
status_id int ID этапа цифровой воронки, на котором находится данная сделка
pipeline_id int ID цифровой воронки, в которой находится сделка
created_by int ID пользователя, создавшего сделку
created_at timestamp Время и дата создания сделки
updated_by int ID пользователя, обновившего параметры сделки
updated_at timestamp Время и дата обновления сделки
closed_at timestamp Время и дата, когда была завершена данная сделка
responsible_user_id int ID пользователя ответственного за сделку
loss_reason_id int ID причины отказа
custom_fields_values array Массив, содержащий информацию по дополнительным полям, заданным для данной сделки
_embedded array Массив вложенных сущностей для сделки
URL метода

PATCH /api/v4/leads/{id} – Для изменения сделки по ее идентификатору

PATCH /api/v4/leads – Для пакетного изменения сделок

Для изменения сделки по ее идентификатору необходимо передать JSON с параметрами, которые должны быть изменены у сделки

Например:


PATCH https://example.amocrm.ru/api/v4/leads/26058887
Content-Type: application/json

{
   "id": 26058887,
   "name": "Новое название для сделки"
   “price”: 25000
}

Для изменения сделок пакетно необходимо указать массив из json, содержащий в себе обязательное поле id (идентификатор сделки) и дополнительные параметры из списка выше, например:


PATCH https://example.amocrm.ru/api/v4/leads
Content-Type: application/json

[
    {
        "id": 26058887,
        "name": "Новое название для сделки",
        “status_id”: 3132,
        “pipeline_id”: 234
    },
    {
        "id": 26058834,
        "responsible_user_id": 913512,
        “status_id”: 2132
    }
]

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

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

Content-Type:application/hal+json


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 26058887,
                "updated_at": 1588257203,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/26058887"
                    }
                }
            },
            {
                "id": 26058834,
                "updated_at": 1588257243,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/26058834"
                    }
                }
            }
        ]
    }
}

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

Параметр Тип Описание
_links array Список ссылок на предыдущую, следующую, первую и текущую страницы
_embedded/leads array Список сделок, которые были успешно изменены
_embedded/leads/id int ID сделки
_embedded/leads/updated_at timestamp Время и дата обновления сделки

Связи сделки

Метод позволяет получать связанные сущности сделки. Возможные связи: контакты, компании, элементы списков.

URL метода

GET /api/v4/leads/{id}/links

Параметры GET

Параметр Тип Описание
id int Уникальный идентификатор сделки

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

Content-Type:application/hal+json

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


{
    "_total_items": 3,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/14158851/links
        }
    },
    "_embedded": {
        "links": [
            {
                "to_entity_id": 10,
                "to_entity_type": "catalog_elements",
                "metadata": {
                    "quantity": 1,
                    "catalog_id": 1026
                }
            },
            {
                "to_entity_id": 40401297,
                "to_entity_type": "companies",
                "metadata": null
            },
            {
                "to_entity_id": 40401299,
                "to_entity_type": "contacts",
                "metadata": null
            }
        ]
    }
}

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

Параметр Тип Описание
_total_items int Количество связанных сущностей
_links array Массив, содержащий ссылку на текущий запрос
_embedded/links array Список связанных сущностей
_embedded/links/to_entity_id int ID сущности, с которой установлена связь
_embedded/links/to_entity_type string Тип сущности, с которой установлена связь. Возможные значения: ( catalog_elements, companies, contacts )
_embedded/links/metadata array Если связанная сущность является элементом каталога, то в параметре metadata мы получим параметр to_catalog_id ( id каталога, к которому относится элемент каталога )

Создание и удаление связей

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

URL метода

POST /api/v4/leads/{id}/{link|unlink}

Параметры GET

Параметр Тип Описание
id int Уникальный идентификатор сделки
action string Один из следующий методов: link (установка связей), unlink (удаление связей)

Параметры POST

В теле запроса для создания связи между сделкой и одной из сущности (контакт, компания, элемент списка) необходимо передать массив со следующими параметрами:

Параметр Тип Описание
to_entity_id int ID сущности, с которой будет установлена связь
to_entity_type string Тип сущности, с которой будет установлена связь. Возможные значения: catalog_elements, companies, contacts

Пример создания связей:

В примере ниже мы свяжем элемент каталога и контакт со сделкой.


POST https://example.amocrm.ru/api/v4/leads/14158851/link
Content-Type: application/json

[
    {
        "to_entity_id": 10,
        "to_entity_type": "catalog_elements",
        "metadata": {
            "quantity": 1,
            "to_catalog_id": 1026
        }
    },
    {
        "to_entity_id": 457282,
        "to_entity_type": "contacts",
        "metadata": null
    }
]

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

В случае, если запрос прошел успешно. В ответе мы получим массив из созданных связей.


{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/14158851/links"
        }
    },
    "_embedded": {
        "links": [
            {
                "entity_id": 14158851,
                "entity_type": "leads",
                "to_entity_id": 10,
                "to_entity_type": "catalog_elements",
                "metadata": {
                    "quantity": 1,
                    "to_catalog_id": 1026
                }
            },
            {
                "entity_id": 14158851,
                "entity_type": "leads",
                "to_entity_id": 457282,
                "to_entity_type": "contacts",
                "metadata": null
            }
        ]
    }
}

Пример удаления связей:

В данном примере мы удаляем ранее созданные связи сделки с контактом и элементом каталога.


POST https://example.amocrm.ru/api/v4/leads/14158851/unlink
Content-Type: application/json

[
    {
        "to_entity_id": 10,
        "to_entity_type": "catalog_elements",
        "metadata": {
            "quantity": 1,
            "to_catalog_id": 1026
        }
    },
    {
        "to_entity_id": 457282,
        "to_entity_type": "contacts",
        "metadata": null
    }
]

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

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

Response code: 204 (No Content)

Смотрите также

КОДЫ ОШИБОК API