Покупатели

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

Оглавление

Включение покупателей и смена их режима

Метод

PATCH /api/v4/customers/mode

Описание

Метод позволяет включать/выключать функционал покупателей, а также менять режим функционала.

Ограничения

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

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

Content-Type: application/json

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

Обязательные поля – mode и is_enabled

Параметр Тип данных Описание
mode string Режим покупателей (segments – сегментация, periodicity – периодичность)
is_enabled bool Включен ди функционал покупателей

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

{
    "mode": "segments",
    "is_enabled": true
}

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Режим покупателей успешно изменен
402 Тариф не позволяет включать покупателей
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает переданные свойства в случае успеха

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

{
    "mode": "segments",
    "is_enabled": true
}

Список покупателей

Метод

GET /api/v4/customers

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
query string
int		 Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
filter object Фильтр. Подробней про фильтры читайте в отдельной статье

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр Тип данных Описание
id int ID покупателя
name string Название покупателя
next_price int Ожидаемая сумма покупки
next_date int Ожидаемая дата следующей покупки. Данные в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за покупателя
status_id int ID статуса покупателя в аккаунте подробнее здесь
periodicity int Периодичность (данные необходимы для покупателей, при включенном функционале периодичности)
created_by int ID пользователя, создавший покупателя
updated_by int ID пользователя, изменивший покупателя
created_at int Дата создания покупателя, передается в Unix Timestamp
updated_at int Дата изменения покупателя, передается в Unix Timestamp
closest_task_at int Дата ближайшей задачи к выполнению, передается в Unix Timestamp
is_deleted bool Удален ли покупатель
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данного покупателя
ltv int Сумма покупок
purchases_count int Количество
average_check int Средний размер покупки
account_id int ID аккаунта, в котором находится покупатель
_embedded object Данные вложенных сущностей
_embedded[segments] array Сегменты, в котором состоит покупатель
_embedded[segments][0] object Модель сегмента
_embedded[segments][0][id] int ID сегмента
_embedded[tags] array Данные тегов, привязанных к покупателю
_embedded[tags][0] object Модель тега, привязанного к покупателю
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
_embedded[tags][0][color] 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 Требуется GET параметр with. Данные компании, привязанной к покупателю, в данном массиве всегда 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": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers?limit=2&with=contacts&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/customers?limit=2&with=contacts&page=2"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 1,
                "name": "1",
                "next_price": 214,
                "next_date": 1589058000,
                "responsible_user_id": 504141,
                "status_id": 4740028,
                "periodicity": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1582117365,
                "updated_at": 1589651187,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "ltv": 1231454,
                "purchases_count": 11,
                "average_check": 111950,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/1"
                    }
                },
                "_embedded": {
                    "segments": [
                        {
                            "id": 43,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/customers/segments/43"
                                }
                            }
                        },
                        {
                            "id": 45,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/customers/segments/45"
                                }
                            }
                        },
                        {
                            "id": 47,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/customers/segments/47"
                                }
                            }
                        },
                        {
                            "id": 51,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/customers/segments/51"
                                }
                            }
                        }
                    ],
                    "tags": [],
                    "contacts": [
                        {
                            "id": 7143559,
                            "is_main": false,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/contacts/7143559"
                                }
                            }
                        },
                        {
                            "id": 9820781,
                            "is_main": true,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/contacts/9820781"
                                }
                            }
                        }
                    ]
                }
            },
            {
                "id": 134923,
                "name": "12412",
                "next_price": 0,
                "next_date": 1589403600,
                "responsible_user_id": 504141,
                "status_id": 4740028,
                "periodicity": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1590943901,
                "updated_at": 1590943901,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": null,
                "ltv": 0,
                "purchases_count": 0,
                "average_check": 0,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134923"
                    }
                },
                "_embedded": {
                    "segments": [],
                    "tags": [],
                    "contacts": [
                        {
                            "id": 3,
                            "is_main": true,
                            "_links": {
                                "self": {
                                    "href": "https://example.amocrm.ru/api/v4/contacts/3"
                                }
                            }
                        }
                    ]
                }
            }
        ]
    }
}

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

Параметр Описание
catalog_elements Добавляет в ответ связанные со покупателем элементы списков
contacts Добавляет в ответ информацию о связанных с покупателем контактах
companies Добавляет в ответ информацию о связанных с покупателем компаниях

Получение покупателя по ID

Метод

GET /api/v4/customers/{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 Название покупателя
next_price int Ожидаемая сумма покупки
next_date int Ожидаемая дата следующей покупки. Данные в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за покупателя
status_id int ID статуса покупателя в аккаунте подробнее здесь
periodicity int Периодичность (данные необходимы для покупателей, при включенном функционале периодичности)
created_by int ID пользователя, создавший покупателя
updated_by int ID пользователя, изменивший покупателя
created_at int Дата создания покупателя, передается в Unix Timestamp
updated_at int Дата изменения покупателя, передается в Unix Timestamp
closest_task_at int Дата ближайшей задачи к выполнению, передается в Unix Timestamp
is_deleted bool Удален ли покупатель
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данного покупателя
ltv int Сумма покупок
purchases_count int Количество
average_check int Средний размер покупки
account_id int ID аккаунта, в котором находится покупатель
_embedded object Данные вложенных сущностей
_embedded[segments] array Сегменты, в котором состоит покупатель
_embedded[segments][0] object Модель сегмента
_embedded[segments][0][id] int ID сегмента
_embedded[tags] array Данные тегов, привязанных к покупателю
_embedded[tags][0] object Модель тега, привязанного к покупателю
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
_embedded[tags][0][color] 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 Требуется GET параметр with. Данные компании, привязанной к покупателю, в данном массиве всегда 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": 1,
    "name": "покупатель",
    "next_price": 214,
    "next_date": 1589058000,
    "responsible_user_id": 504141,
    "status_id": 4740028,
    "periodicity": 0,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1582117365,
    "updated_at": 1589651187,
    "closest_task_at": null,
    "is_deleted": false,
    "custom_fields_values": null,
    "ltv": 1231454,
    "purchases_count": 11,
    "average_check": 111950,
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/1"
        }
    },
    "_embedded": {
        "segments": [
            {
                "id": 43,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/43"
                    }
                }
            },
            {
                "id": 45,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/45"
                    }
                }
            },
            {
                "id": 47,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/47"
                    }
                }
            },
            {
                "id": 51,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/segments/51"
                    }
                }
            }
        ],
        "tags": []
    }
}

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

Параметр Описание
catalog_elements Добавляет в ответ связанные со покупателем элементы списков
contacts Добавляет в ответ информацию о связанных с покупателем контактах
companies Добавляет в ответ информацию о связанных с покупателем компаниях

Добавление покупателей

Метод

POST /api/v4/customers

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Обязательные поля – name и next_date, если включен режим периодичности

Параметр Тип данных Описание
name string Название покупателя
next_price int Ожидаемая сумма покупки
next_date int Ожидаемая дата следующей покупки. Данные в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за покупателя
status_id int ID статуса покупателя в аккаунте подробнее здесь
periodicity int Периодичность (данные необходимы для покупателей, при включенном функционале периодичности)
created_by int ID пользователя, создавший покупателя
updated_by int ID пользователя, изменивший покупателя
created_at int Дата создания покупателя, передается в Unix Timestamp
updated_at int Дата изменения покупателя, передается в Unix Timestamp
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данного покупателя. Примеры заполнения полей
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 Данные тегов, привязанных к покупателю
_embedded[tags][0] object Модель тега, привязанного к покупателю
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

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

[
    {
        "name": "Покупатель для примера 1",
        "created_by": 0,
        "custom_fields_values": [
            {
                "field_id": 294479,
                "values": [
                    {
                        "value": "Наш первый покупатель"
                    }
                ]
            }
        ],
        "tags_to_add": [
            {
                "id": 107721
            }
        ]
    },
    {
        "name": "Покупатель для примера 2",
        "_embedded": {
            "tags": [
                {
                    "name": "Важный покупатель"
                }
            ],
            "segments": [
                {
                    "id": 81
                }
            ]
        }
    }
]

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

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/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 134957,
                "request_id": "0"
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134957"
                    }
                }
            },
            {
                "id": 134959,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134959"
                    }
                }
            }
        ]
    }
}

Редактирование покупателей

Метод

PATCH /api/v4/customers

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Обязательных полей нет

Параметр Тип данных Описание
name string Название покупателя
next_price int Ожидаемая сумма покупки
next_date int Ожидаемая дата следующей покупки. Данные в Unix Timestamp
responsible_user_id int ID пользователя, ответственного за покупателя
status_id int ID статуса покупателя в аккаунте подробнее здесь
periodicity int Периодичность (данные необходимы для покупателей, при включенном функционале периодичности)
created_by int ID пользователя, создавший покупателя
updated_by int ID пользователя, изменивший покупателя
created_at int Дата создания покупателя, передается в Unix Timestamp
updated_at int Дата изменения покупателя, передается в Unix Timestamp
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данного покупателя. Примеры заполнения полей
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 Данные тегов, привязанных к покупателю
_embedded[tags][0] object Модель тега, привязанного к покупателю
_embedded[tags][0][id] int ID тега
_embedded[tags][0][name] string Название тега
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

[
    {
        "id": 1299433,
        "name": "Новое название покупателя",
        "_embedded": {
            "tags": [
                {
                    "name": "Тег 125"
                }
            ]
        }
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

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

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

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

Список транзакций

Метод

GET /api/v4/customers/transactions

Описание

Метод позволяет получить список транзакций в аккаунте.
Также вы можете получить транзакции конкретного покупателя обратившись к методу /api/v4/customers/{customer_id}/transactions.

Ограничения

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

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter object Фильтр
filter[id] int
array		 Фильтр по ID транзакций

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр Тип данных Описание
id int ID транзакции
comment string Комментарий к покупке
price int Сумма покупки
completed_at int Когда транзакция была проведена. Данные в Unix Timestamp
customer_id int ID покупателя, в котором находится транзакция
created_by int ID пользователя, создавший транзакцию
updated_by int ID пользователя, изменивший транзакцию
created_at int Дата создания транзакции, передается в Unix Timestamp
updated_at int Дата изменения транзакции, передается в Unix Timestamp
is_deleted bool Удалена ли транзакция
account_id int ID аккаунта, в котором находится транзакция
_embedded object Данные вложенных сущностей
_embedded[customer] object Покупатель, в котором находится транзакция
_embedded[customer][id] int ID покупателя
_embedded[catalog_elements] array Данные элементов списков, привязанных к транзакции
_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": 1,
    "_links": {
        "self": {
            "href": "http://example.amocrm.ru/api/v4/customers/transactions?filter%5Bid%5D%5B0%5D=134643&page=1&limit=50"
        },
        "next": {
            "href": "http://example.amocrm.ru/api/v4/customers/transactions?filter%5Bid%5D%5B0%5D=134643&page=2&limit=50"
        }
    },
    "_embedded": {
        "transactions": [
            {
                "id": 134643,
                "price": 123,
                "comment": null,
                "completed_at": 1591005900,
                "customer_id": 1000000158,
                "created_by": 939801,
                "updated_by": 939801,
                "created_at": 1591005900,
                "updated_at": 1591005900,
                "is_deleted": false,
                "account_id": 17079858,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/1000000158/transactions/134643"
                    }
                },
                "_embedded": {
                    "customer": {
                        "id": 1000000158,
                        "_links": {
                            "self": {
                                "href": "https://example.amocrm.ru/api/v4/customers/1000000158"
                            }
                        }
                    },
                    "catalog_elements": [
                        {
                            "id": 1677,
                            "metadata": {
                                "catalog_id": 1079,
                                "quantity": 10
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Получение транзакции по ID

Метод

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

Описание

Метод позволяет получить транзакцию в аккаунте.
Также вы можете получить транзакцию конкретного покупателя обратившись к методу /api/v4/customers/{customer_id}/transactions/{id}.

Ограничения

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр Тип данных Описание
id int ID транзакции
comment string Комментарий к покупке
price int Сумма покупки
completed_at int Когда транзакция была проведена. Данные в Unix Timestamp
customer_id int ID покупателя, в котором находится транзакция
created_by int ID пользователя, создавший транзакцию
updated_by int ID пользователя, изменивший транзакцию
created_at int Дата создания транзакции, передается в Unix Timestamp
updated_at int Дата изменения транзакции, передается в Unix Timestamp
is_deleted bool Удалена ли транзакция
account_id int ID аккаунта, в котором находится транзакция
_embedded object Данные вложенных сущностей
_embedded[customer] object Покупатель, в котором находится транзакция
_embedded[customer][id] int ID покупателя
_embedded[catalog_elements] array Данные элементов списков, привязанных к транзакции
_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": 14755,
    "price": 123124,
    "comment": "Транзакция",
    "completed_at": 1589025179,
    "customer_id": 1,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1589025179,
    "updated_at": 1589025179,
    "is_deleted": false,
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/1/transactions/14755"
        }
    },
    "_embedded": {
        "customer": {
            "id": 1,
            "_links": {
                "self": {
                    "href": "https://example.amocrm.ru/api/v4/customers/1"
                }
            }
        }
    }
}

Добавление транзакций к покупателю

Метод

POST /api/v4/customers/{customer_id}/transactions

Описание

Метод позволяет добавлять транзакции к конкретному покупателю в аккаунт пакетно.

Ограничения

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

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

Content-Type: application/json

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

Обязательное поле – price

Параметр Тип данных Описание
comment string Комментарий к покупке
price int Сумма покупки
completed_at int Когда транзакция была проведена. Данные в Unix Timestamp
next_price int Ожидаемая сумма следующей покупки у покупателя
next_date int Ожидаемая дата следующей покупки у покупателя. Данные в Unix Timestamp
created_by int ID пользователя, создавший транзакцию
_embedded[catalog_elements] array Данные элементов списков, привязанных к транзакции
_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 списка, в котором находится элемент
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

[
   {
      "price":123,
      "created_by":0,
      "comment":"Комментарий",
      "_embedded":{
         "catalog_elements":[
            {
               "id":1677,
               "metadata":{
                  "catalog_id":1079,
                  "quantity":10
               }
            }
         ]
      }
   }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

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

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 134957,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134957"
                    }
                }
            },
            {
                "id": 134959,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/134959"
                    }
                }
            }
        ]
    }
}

Удаление транзакции

Метод

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

Описание

Метод позволяет удалить транзакцию в аккаунте.
Также вы можете получить удалить транзакцию конкретного покупателя обратившись к методу /api/v4/customers/{customer_id}/transactions/{id}.

Ограничения

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

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

Content-Type: application/json

HTTP коды ответа

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

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

Метод не возвращает тело

Списание/начисление бонусных баллов покупателю

Метод

POST /api/v4/customers/{id}/bonus_points

Описание

Метод позволяет списывать/начислять бонусные баллы покупателю по ID. Взаимодействует с системой карт лояльности amoCRM.

Ограничения

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

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

Content-Type: application/json

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

Если покупателю нужно списать баллы обязательное поле redeem, если начислить, то earn. Оба поля передавать запрещено

Параметр Тип данных Описание
redeem int Указывает сколько бонусных баллов нужно списать
earn int Указывает сколько бонусных баллов нужно начислить

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

В данном примере мы начислим покупателю 500 бонусных баллов.

{
    "earn": 500
}

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает обновленное значение бонусных баллов покупателя

Параметр Тип данных Описание
bonus_points int Количество бонусных баллов покупателя после запроса

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

{
    "bonus_points": 534
}