Статусы и сегменты покупателей

СТАТУСЫ

Статусы – жизненный цикл (бизнес-процесс) положения покупателя в воронке продаж. Список статусов может быть изменен в рамках аккаунта, кроме первого и трех конечных системных периодов.
В одном аккаунте может быть не больше 30 статусов.

Получение статусов

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

URL метода

GET /api/v4/customers/statuses/{id} – для получения статуса по его идентификатору

GET /api/v4/customers/statuses – для получения списка статусов

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


GET https://example.amocrm.ru/api/v4/customers/statuses/4051135

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


{
    "id": 4051135,
    "name": "Статус покупателя для примера",
    "sort": 2,
    "is_default": false,
    "conditions": [
        [
            {
                "type": "tag",
                "options": {
                    "name": "Теги"
                },
                "logic_operator": "or",
                "conditions": [
                    {
                        "id": 174727,
                        "name": "Условие"
                    }
                ],
                "match": {
                    "value": [
                        174727
                    ],
                    "logic": "or"
                },
                "tmpl": "tag_customers"
            }
        ],
        []
    ],
    "color": "#ccc8f9",
    "type": 0,
    "account_id": 321321,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/statuses/4051135"
        }
    }
}

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

Параметр Тип Описание
id int Идентификатор статуса
name string Название статуса
sort int Порядок сортировки среди прочих статусов.
is_default bool Является ли статус стандартным.
conditions array Массив условий, по которым покупатели попадают в данный статус.
conditions array Массив условий, по которым покупатели попадают в данный статус.
color string Цвет статуса, который будет отображаться в интерфейса Покупателей.
Доступные цвета:
– ‘#99ccff’, ‘#fd5598’
– ‘#ccff66’, ‘#ffdc7f’
– ‘#ccc8f9’, ‘#d5d8db’
type int Тип статуса.
Возможные значения:
0 Обычный статус, созданный пользователем.
1 ( Тип статуса – “Покупка сегодня” )
2 ( Тип статуса – “Не купили” )
3 ( Тип статуса – “Закрытые” )
4 ( Тип статуса – “Недавно купили” )
account_id int Идентификатор аккаунта

Создание статуса

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

URL метода

POST /api/v4/customers/statuses

Для создания статуса необходимо передать массив из JSON, содержащий обязательные параметры: name, color и дополнительные: sort, request_id ( Идентификатор запроса )
Описание каждого из параметров можно найти здесь.

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


POST https://example.amocrm.ru/api/v4/customers/statuses
Content-Type: application/json

[
    {
        "name": "Новый статус",
        "sort": 10,
        "color": "#ccc8f9"
    },
    {
        "name": "Новый статус 2",
        "sort": 20,
        "color": "#ffdc7f"
    }
]

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


{
    "_total_items": 2,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/statuses"
        }
    },
    "_embedded": {
        "statuses": [
            {
                "id": 5483298,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/statuses/5483298"
                    }
                }
            },
            {
                "id": 5483301,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/statuses/5483301"
                    }
                }
            }
        ]
    }
}

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

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

URL метода

PATCH /api/v4/customers/statuses/{id}

Параметры доступные для изменения:
name
color
sort

Описание каждого из параметров можно найти здесь.

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


PATCH https://example.amocrm.ru/api/v4/customers/statuses/4051141
Content-Type: application/json

{
    "name": "Новое название статуса",
    "color": "#ccc8f9"
}

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


{
    "id": 4051141,
    "name": "Новое название статуса",
    "sort": 4,
    "is_default": false,
    "conditions": [
        [],
        []
    ],
    "color": "#ccc8f9",
    "type": 0,
    "account_id": 123123,
    "request_id": "0",
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/statuses/4051141"
        }
    }
}

Удаление статуса

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

URL метода

DELETE /api/v4/customers/statuses/{id}

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


DELETE https://example.amocrm.ru/api/v4/customers/statuses/5483328

При успешном удалении сервер вернет HTTP-ответ 204 (No Content);

СЕГМЕНТЫ

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

Список сегментов

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

URL метода

GET /api/v4/customers/segments

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

Параметр Тип Описание
page int Страница выборки
limit int Кол-во сегментов, возвращаемых за один запрос
offset int Сдвиг выборки (с какой строки выбирать).

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


GET https://example.amocrm.ru/api/v4/customers/segments?limit=50&offset=0

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


{
    "_total_items": 1,
    "_page": 1,
    "_page_count": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/segments?limit=50&offset=0&page=1"
        }
    },
    "_embedded": {
        "segments": [
            {
                "id": 5,
                "created_at": 1589455836,
                "updated_at": 1589455982,
                "account_id": 123123,
                "name": "Сегмент для примера",
                "color": "a2ad59",
                "available_products_price_types": [],
                "customers_count": 0,
                "custom_fields_values": [
                    {
                        "values": [
                            {
                                "value": "Это сегмент создан для примера"
                            }
                        ],
                        "field_id": 245035,
                        "field_name": "Описание сегмента",
                        "field_code": null,
                        "field_type": "text"
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/5"
                    }
                }
            }
        ]
    }
}

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

Параметр Тип Описание
id int Идентификатор сегмента
name string Название сегмента
account_id int Идентификатор аккаунта
color string Цвет сегмента, который будет отображаться в интерфейса Покупателей. Доступные значения:
‘10599d’, ‘2176ff’, ‘006acc’, ’07a0c3′, ‘247ba0’, ‘177e89’, ‘046e8f’, ‘598381’, ‘0c7c59’, ‘495f41′, ’00a44b’, ‘08605f’, ‘bf2600′, ’06d6a0’, ‘e14945′, ’79b473’, ‘ae003f’, ‘a2ad59’, ‘cd0f53’, ‘8e936d’, ‘832161’, ‘2e5339’, ‘bf126f’, ‘6f7c12’, ‘ff5376’, ‘dd1c1a’, ‘bb304e’, ‘631d76’, ‘9d2b32’, ‘4a001f’, ‘b118c8’, ‘6a0f49’, ‘6610f2’, ‘b38a58’, ‘8963ba’, ‘4b3666’, ‘932f6d’, ‘6b2d5c’, ‘6461a0’, ‘4f517d’
available_products_price_types [ ]string Массив идентификаторов доп. полей типа “Цена” из товарного каталога.
Если покупатель находится в сегменте, в котором включена цена, то покупателю становится доступна покупка товара по этой цене.
customers_count int Количество покупателей, которые относятся к данному сегменту
custom_fields_values array Массив содержащий информацию по дополнительным полям, заданным для данного сегмента.
Подробнее о том как создавать дополнительные поля смотрите тут(ссылка).
created_at timestamp Дата и время создания сегмента
updated_at timestamp Дата и время обновления параметров сегмента

Получение сегмента по идентификатору

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

URL метода

GET /api/v4/customers/segments/{id}

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


GET https://example.amocrm.ru/api/v4/customers/segments/5

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


{
    "id": 5,
    "created_at": 1589455836,
    "updated_at": 1589456462,
    "account_id": 123123,
    "name": "Сегмент для примера",
    "color": "2e5339",
    "available_products_price_types": [],
    "customers_count": 0,
    "custom_fields_values": [
        {
            "values": [
                {
                    "value": "Это сегмент создан для примера"
                }
            ],
            "field_id": 245035,
            "field_name": "Описание сегмента",
            "field_code": null,
            "field_type": "text"
        }
    ],
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/segments/5"
        }
    }
}

Описание каждого из параметров смотрите тут.

Создание сегмента

Метод позволяет создать сегмент

URL метода

POST /api/v4/customers/segments

Для создания сегмента необходимо передать JSON, содержащий один обязательный параметр name и дополнительные параметры:
– available_products_price_types
– color
– custom_fields_values

Описание каждого из параметров смотрите тут.

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


POST https://example.amocrm.ru/api/v4/customers/segments
Content-Type: application/json

{
    "name": "Сегмент для примера",
    "color": "ae003f",
    "custom_fields_values": [
        {
            "field_id": 245035,
            "field_name": "Описание сегмента",
            "values": [
                {
                    "value": "Этот сегмент создан для примера"
                }
            ]
        },
        {
            "field_id": 245351,
            "values": [
                {
                    "enum_id": 387477
                }
            ]
        }
    ]
}

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


{
    "id": 17,
    "created_at": 1589462149,
    "updated_at": 1589462149,
    "account_id": 123123,
    "name": "Сегмент для примера",
    "color": "ae003f",
    "available_products_price_types": [],
    "customers_count": 0,
    "custom_fields_values": [
        {
            "values": [
                {
                    "value": "Этот сегмент создан для примера"
                }
            ],
            "field_id": 245035,
            "field_name": "Описание сегмента",
            "field_code": null,
            "field_type": "text"
        },
        {
            "values": [
                {
                    "value": “Значение мультиселекта",
                    "enum_id": 387477
                }
            ],
            "field_id": 245351,
            "field_name": "Мультиселект поле",
            "field_code": null,
            "field_type": "multiselect"
        }
    ],
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/segments/17"
        }
    }
}

Изменение сегмента

Метод позволяет изменять следующие параметры сегмента:
– name
– available_products_price_typesm
– color
– custom_fields_values

Описание каждого из параметров смотрите тут.

URL метода

PATCH /api/v4/customers/segments/{id}

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


PATCH https://example.amocrm.ru/api/v4/customers/segments/17
Content-Type: application/json

{
    "name": "Новое имя для сегмента",
    "color": "ae003f",
    "custom_fields_values": [
        {
            "field_id": 245035,
            "field_name": "Описание сегмента",
            "values": [
                {
                    "value": "Новое описание для сегмента"
                }
            ]
        }
    ]
}

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


{
    "id": 17,
    "created_at": 1589462149,
    "updated_at": 1589463844,
    "account_id": 123123,
    "name": "Новое имя для сегмента",
    "color": "ae003f",
    "available_products_price_types": [],
    "customers_count": 0,
    "custom_fields_values": [
        {
            "values": [
                {
                    "value": "Новое описание для сегмента"
                }
            ],
            "field_id": 245035,
            "field_name": "Описание сегмента",
            "field_code": null,
            "field_type": "text"
        },
    ],
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/segments/17"
        }
    }
}

Удаление сегмента

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

URL метода

DELETE /api/v4/customers/segments/{id:\d+}

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


DELETE https://example.amocrm.ru/api/v4/customers/segments/17

При успешном удалении сегмента в ответ придет пустое тело и HTTP-код:
Response code: 204 (No Content);

Создание дополнительного поля для сегмента

Метод позволяет создавать дополнительные поля для сегмента по одному или пакетно.
Максимальное количество дополнительные полей для сегментов в аккаунте – 50.

URL метода

POST /api/v4/customers/segments/custom_fields

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

Возможные типы (types) дополнительных полей:
– checkbox
– date
– date_time
– multiselect
– numeric
– radiobutton
– select
– streetaddress
– textarea
– text
– url

Список параметров, которые необходимо передать для каждого типа дополнительного поля, описаны здесь.

Пример создания дополнительных полей типа: multiselect и checkbox


POST https://example.amocrm.ru/api/v4/customers/segments/custom_fields
Content-Type: application/json

[
    {
        "name": "Мультиселект поле",
        "type": "multiselect",
        "sort": 510,
        "enums": [
            {
                "value": "Значение 1",
                "sort": 1
            },
            {
                "value": "Значение 2",
                "sort": 2
            }
        ]
    },
    {
        "name": "Чекбокс поле",
        "type": "checkbox"
    }
]

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


{
    "_total_items": 2,
    "_embedded": {
        "custom_fields": [
            {
                "id": 245351,
                "name": "Мультиселект поле",
                "type": "multiselect",
                "account_id": 123123,
                "code": null,
                "sort": 510,
                "is_api_only": false,
                "enums": [
                    {
                        "id": 387419,
                        "value": "Значение 1",
                        "sort": 1
                    },
                    {
                        "id": 387421,
                        "value": "Значение 2",
                        "sort": 2
                    }
                ],
                "request_id": "0",
                "entity_type": "segments",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/custom_fields/245351"
                    }
                }
            },
            {
                "id": 245353,
                "name": "Чекбокс поле",
                "type": "checkbox",
                "account_id": 123123,
                "code": null,
                "sort": 500,
                "is_api_only": false,
                "enums": null,
                "request_id": "1",
                "entity_type": "segments",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/custom_fields/245353"
                    }
                }
            }
        ]
    }
}

Изменение дополнительного поля сегмента

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

– name (Название)
– is_api_only (Возможность изменения только по API)
– group_id (Группу)
– enums (Возможные значения)

Список доступных параметров для каждого типа дополнительного поля, описан здесь.

URL метода

PATCH /api/v4/customers/custom_fields/{id:\d+} – для изменения по идентификатору

PATCH /api/v4/customers/custom_fields – для пакетного изменения

Пример запроса для пакетного изменения


PATCH https://example.amocrm.ru/api/v4/customers/segments/custom_fields
Content-Type: application/json

[
    {
        "id": 245351,
        "enums": [
            {
                "value": "Новое значение 1",
                "sort": 1
            },
            {
                "value": "Новое значение 2",
                "sort": 2
            }
        ]
    },
    {
        "id": 245353,
        "name": "Новое название для поля",
        "type": "checkbox"
    }
]

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


PATCH https://example.amocrm.ru/api/v4/customers/segments/custom_fields/245353
Content-Type: application/json

{
    "name": "Новое название для поля",
    "type": "checkbox"
}

Получение дополнительного поля

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

URL метода

GET /api/v4/customers/custom_fields – для получения списка

GET /api/v4/customers/custom_fields/{id:\d+} – для получения по идентификатору

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


GET https://example.amocrm.ru/api/v4/customers/segments/custom_fields/245351

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


{
    "id": 245351,
    "name": "Мультиселект поле",
    "type": "multiselect",
    "account_id": 123123,
    "code": null,
    "sort": 510,
    "is_api_only": false,
    "enums": [
        {
            "id": 387477,
            "value": "Значение 1",
            "sort": 1
        },
        {
            "id": 387479,
            "value": "Значение 2",
            "sort": 2
        }
    ],
    "entity_type": "segments",
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/segments/custom_fields/245351"
        }
    }
}

Удаление дополнительного поля сегмента

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

URL метода

DELETE /api/v4/customers/custom_fields/{id:\d+}

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


DELETE https://example.amocrm.ru/api/v4/customers/segments/custom_fields/245347

При успешном удалении дополнительного поля в ответ придет пустое тело и HTTP-код:
Response code: 204 (No Content);

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

КОДЫ ОШИБОК API