Фильтрация (alpha)

Фильтрация – удобный и легкий инструмент для взаимодействия с сущностями. При помощи данного метода можно сделать необходимую выборку подходящую по условиям.

Примечание

На данный момент происходит закрытое  alpha тестирование. Доступ участников к тестированию ограничен и выдается по нашему усмотрению.

 

Базовые фильтры

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

URL метода

GET /api/v4/lead

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

Параметр Тип Описание
filter[name] int Название сделки. Можно передать несколько значений в виде массива, например: ?filter[name][]=name1&filter[name][]=name2
filter[price] int Бюджет сделки. Есть возможность фильтрации по диапазону.
filter[statuses] int Статус в воронке продаж. См. шаблон для фильтра по статусу.
filter[pipeline_id] int Идентификатор воронки продаж. Можно передать несколько значений в виде массива, например: ?filter[pipeline_id][]=341&filter[pipeline_id][]=562
filter[created_by] int Кем создана сделка. Можно передать несколько значений в виде массива, например: ?filter[created_by][]=4441&filter[created_by][]=7421
filter[updated_by] int Кем обновлена сделка. Можно передать несколько значений в виде массива, например: ?filter[updated_by][]=4441&filter[updated_by][]=7421
filter[created_at] timestamp Дата и время создания сделки. Есть возможность фильтрации по диапазону.
filter[updated_at] timestamp Дата и время обновления сделки. Есть возможность фильтрации по диапазону.
filter[closed_at] timestamp Дата и время закрытия сделки сделки. Есть возможность фильтрации по диапазону.
filter[responsible_user_id] int Ответственный за сделку
filter[closest_task_at] timestamp|int Ближайшая по времени задача по сделке. Есть возможность фильтрации по диапазону. Если передать значение для параметра closest_task_at=0, будут возвращены сделки без задач.

Фильтрация по статусу осуществляется следующим образом:


/api/v4/leads?filter[statuses][0][pipeline_id]={pipeline_id}&filter[statuses][0][status_id]={status_id}

Где pipeline_id – это идентификатор воронки продаж, status_id – идентификатор этапа в воронке продаж.

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


/api/v4/lead?filter[{field_name}][from]={date_from}&filter[{field_name}][to]={date_to}

Где field_name – это параметр, по которому будет осуществляться фильтрация, date_from – дата, от которой будет производиться поиск по диапазону и date_to – дата, до которой будет производиться поиск по диапазону

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


GET https://example.amocrm.ru/api/v4/lead?filter[updated_at][from]=1575296400&filter[updated_at][to]=1589540009

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?filter%5Bcustom_fields_values%5D%5B294505%5D%5B0%5D=410223&page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?filter%5Bcustom_fields_values%5D%5B294505%5D%5B0%5D=410223&page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 122751,
                "name": "Сделка для примера",
                "price": 0,
                "responsible_user_id": 1513123,
                "group_id": 0,
                "status_id": 143,
                "pipeline_id": 2194576,
                "loss_reason_id": 3801274,
                "source_id": null,
                "created_by": 3987910,
                "updated_by": 3944275,
                "created_at": 1575296550,
                "updated_at": 1589540009,
                "closed_at": 1575301384,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 294485,
                        "field_name": "Дата",
                        "field_code": null,
                        "field_type": "date",
                        "values": [
                            {
                                "value": 1589490000
                            }
                        ]
                    },
                    {
                        "field_id": 294505,
                        "field_name": "radiobutton",
                        "field_code": null,
                        "field_type": "radiobutton",
                        "values": [
                            {
                                "value": "Вариант 3",
                                "enum_id": 410223
                            }
                        ]
                    }
                ],
                "score": null,
                "account_id": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/122751"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Фильтрация по дополнительным полям

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

URL метода

GET /api/v4/lead

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

Параметр Тип Описание
filter[custom_fields_values] array Массив из параметров дополнительного поля, по которым будет производиться выборка
filter[custom_fields_values][field_id] int Ключ field_id является идентификатором дополнительного поля
filter[custom_fields_values][field_id][from] timestamp Дата и время, от которого будет производиться поиск по диапазону
filter[custom_fields_values][field_id][to] timestamp Дата и время, до которого будет производиться поиск по диапазону

Параметр filter является многомерным массивом. В зависимости от типа дополнительного поля он формируется по-разному. Ниже описаны все доступные типы полей и соответствующие параметры для фильтра.

Типы полей: numeric, text, url, textarea, streetaddress, select, multiselect, radiobutton, checkbox

Шаблон для фильтра:


/api/v4/lead?filter[custom_fields_values][{field_id}][]={value}

Описание передаваемых значений:

Значение Тип Описание
field_id int Идентификатор дополнительного поля
value mixed Значение, по которому будет производиться фильтрация. Для полей: numeric, text, url, textarea, streetaddress этим значением является поле value в параметрах дополнительного поля Для полей: select, multiselect, radiobutton этим значением является поле enum_id в параметрах дополнительного поля Для поля checkbox этим значением является либо 0 (false) либо 1 (true)

Также можно искать по нескольким значениям за один запрос, например:


/api/v4/lead?filter[custom_fields_values][{field_id}][]={value}&filter[custom_fields_values][{field_id}][]={value2}

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


GET https://example.amocrm.ru/api/v4/leads?filter[custom_fields_values][294505][]=410223

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?filter%5Bcustom_fields_values%5D%5B294505%5D%5B0%5D=410223&page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?filter%5Bcustom_fields_values%5D%5B294505%5D%5B0%5D=410223&page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 122751,
                "name": "Сделка для примера",
                "price": 0,
                "responsible_user_id": 123123,
                "group_id": 0,
                "status_id": 143,
                "pipeline_id": 2194576,
                "loss_reason_id": 3801274,
                "source_id": null,
                "created_by": 3987910,
                "updated_by": 3944275,
                "created_at": 1575296550,
                "updated_at": 1589540009,
                "closed_at": 1575301384,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 294485,
                        "field_name": "Дата",
                        "field_code": null,
                        "field_type": "date",
                        "values": [
                            {
                                "value": 1589490000
                            }
                        ]
                    },
                    {
                        "field_id": 294505,
                        "field_name": "radiobutton",
                        "field_code": null,
                        "field_type": "radiobutton",
                        "values": [
                            {
                                "value": "Вариант 3",
                                "enum_id": 410223
                            }
                        ]
                    }
                ],
                "score": null,
                "account_id": 1231233,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/122751"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Типы полей: date, birthday, date_time

Шаблон для фильтра:


/api/v4/lead?filter[custom_fields_values][{field_id}][from]={date_from}&filter[custom_fields_values][{field_id}][to]={date_to}

Описание передаваемых значений:

Значение Тип Описание
field_id int Идентификатор дополнительного поля
date_from timestamp|string Дата и время, от которого будет производится поиск по диапазону
date_from timestamp|string Дата и время, до которого будет производится поиск по диапазону

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


GET https://example.amocrm.ru/api/v4/leads?filter[custom_fields_values][294485][from]=14.05.2020&filter[custom_fields_values][294485][to]=16.05.2020

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads?filter%5Bcustom_fields_values%5D%5B294485%5D%5Bfrom%5D=14.05.2020&filter%5Bcustom_fields_values%5D%5B294485%5D%5Bto%5D=16.05.2020&page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads?filter%5Bcustom_fields_values%5D%5B294485%5D%5Bfrom%5D=14.05.2020&filter%5Bcustom_fields_values%5D%5B294485%5D%5Bto%5D=16.05.2020&page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "leads": [
            {
                "id": 122751,
                "name": "Сделка для примера",
                "price": 0,
                "responsible_user_id": 123123,
                "group_id": 0,
                "status_id": 143,
                "pipeline_id": 2194576,
                "loss_reason_id": 3801274,
                "source_id": null,
                "created_by": 3987910,
                "updated_by": 3944275,
                "created_at": 1575296550,
                "updated_at": 1589540009,
                "closed_at": 1575301384,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 294485,
                        "field_name": "Дата",
                        "field_code": null,
                        "field_type": "date",
                        "values": [
                            {
                                "value": 1589490000
                            }
                        ]
                    },
                    {
                        "field_id": 294513,
                        "field_name": "День рождения",
                        "field_code": null,
                        "field_type": "birthday",
                        "values": [
                            {
                                "value": 1589058000
                            }
                        ]
                    }
                ],
                "score": null,
                "account_id": 12312312,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/122751"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Поиск

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

Примечание

В ближайшее время будет объявлен устаревшим .

Результаты поиска при использовании параметра query, могут быть устаревшими, при возникновении этой ситуации повторите запрос через несколько минут.

В будущем поисковое API будет отделено от API  с фильтрацией.

Так что бы вы всегда могли получать актуальную информацию по сделкам, фильтруя по полям.
И отдельное API с расширенными возможностями поиска и фильтрации, но с возможными задержками при добавлении новой информации

 
URL метода

GET /api/v4/lead

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

Параметр Тип Описание
query string Строка по которой будет производится поиск сделок

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


GET https://example.amocrm.ru/api/v4/leads?query=внедрение

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

КОДЫ ОШИБОК API