Покупатели

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

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

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

Возможные параметры покупателя

Параметр Тип Описание
id int Уникальный идентификатор покупателя
account_id int Уникальный идентификатор аккаунта
name string Название покупателя
next_price int Ожидаемая сумма
next_date timestamp Дата и время следующей покупки
responsible_user_id int ID пользователя ответственного за покупателя
status_id int ID этапа в котором находится покупатель
periodicity int Периодичность
created_by int ID пользователя, создавшего покупателя
created_at timestamp Дата и время создания покупателя
updated_by int ID пользователя, обновившего покупателя
periodicity int Периодичность
updated_at timestamp Дата и время обновления покупателя
closest_task_at timestamp Время ближайшей задачи по данному покупателю
is_deleted bool Удален покупатель или нет.
custom_fields_values array Массив содержащий информацию по дополнительным полям, заданным для данного покупателя.
Список дополнительных полей доступных для покупателей можно посмотреть тут.
ltv int Сумма покупок
purchases_count int Количество покупок
average_check int Средний чек
_embedded[segments] array Массив, содержащий информацию по сегментам
_embedded[tags] array Массив, содержащий информацию по тегам

Получение покупателя по идентификатору

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

URL метода

GET /api/v4/customers/{id:\d+}

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


GET https://example.amocrm.ru/api/v4/customers/401021

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


Content-Type: application/hal+json

{
    "id": 401021,
    "name": "010",
    "next_price": 4500,
    "next_date": 1589230800,
    "responsible_user_id": 1725157,
    "status_id": 4051144,
    "periodicity": 0,
    "created_by": 1725157,
    "updated_by": 3944275,
    "created_at": 1589193534,
    "updated_at": 1589237344,
    "closest_task_at": 1589193534,
    "is_deleted": false,
    "custom_fields_values": [
        {
            "field_id": 22263,
            "field_name": "Дополнительное поле",
            "field_code": null,
            "field_type": "text",
            "values": [
                {
                    "value": "Поле"
                }
            ]
        }
    ],
    "ltv": 4500,
    "purchases_count": 1,
    "average_check": 4500,
    "account_id": 321123,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/401021"
        }
    },
    "_embedded": {
        "segments": [],
        "tags": [
            {
                "id": 264507,
                "name": "Тег"
            }
        ]
    }
}

Получение списка покупателей

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

URL метода

GET /api/v4/customers

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

Параметр Описание
page Страница выборки
limit Кол-во выбираемых строк (системное ограничение 250 строк)
filter[date] Выбрать элемент по дате создания или редактирования нужно передавать массив с параметрами type(create | update), from, to
Например:
filter[date][type]=create&filter[date][from]=1589193534&filter[date][to]=1589193536
filter[next_date] Выбрать элемент по дате след. покупки (нужно передавать массив с параметрами from, to)
Например:
filter[next_date][from]=1589230800&filter[next_date][to]=1589230841
with Если в параметре with указать значения (catalog_elements, loss_reason_name), в ответ придет информация о покупателе по соответствующему значению.

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

В следующем примере мы получим всех покупателей, которые были созданы за определенный период


GET https://example.amocrm.ru/api/v4/customers?filter[date][type]=create&filter[date][from]=1589193534&filter[date][to]=1589193535

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers?filter[date][type]=create&filter[date][from]=1589193534&filter[date][to]=1589193535&page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/customers?filter[date][type]=create&filter[date][from]=1589193534&filter[date][to]=1589193535&page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 401021,
                "name": "Покупатель для примера",
                "next_price": 4500,
                "next_date": 1589230800,
                "responsible_user_id": 1725157,
                "status_id": 4051144,
                "periodicity": 0,
                "created_by": 1725157,
                "updated_by": 3944275,
                "created_at": 1589193534,
                "updated_at": 1589237344,
                "closest_task_at": null,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 22263,
                        "field_name": "Дополнительное поле",
                        "field_code": null,
                        "field_type": "text",
                        "values": [
                            {
                                "value": "Поле"
                            }
                        ]
                    }
                ],
                "ltv": 4500,
                "purchases_count": 1,
                "average_check": 4500,
                "account_id": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/401021"
                    }
                },
                "_embedded": {
                    "segments": [],
                    "tags": [
                        {
                            "id": 264507,
                            "name": "Тег"
                        }
                    ]
                }
            }
        ]
    }
}

Создание покупателей

Метод позволяет создавать покупателей по одному или пакетно ( системное ограничение – 500 )

URL метода

POST /api/v4/customers

При создании покупателя обязательным параметрами являются:
– name
– next_date
Опционально можно указать также :
– next_price
– responsible_user_id
– periodicity
– created_by
– custom_fields_values
– _embedded[segments]
– _embedded[tags]

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

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


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

[
    {
        "name": "Покупатель для примера",
        "next_date": 1589230800,
        "next_price": 10000,
        "responsible_user_id": 3944275,
        "periodicity": 13,
        "created_by": 3944275,
        "custom_fields_values": [
            {
                "field_id": 22263,
                "field_name": "Дополнительное поле",
                "values": [
                    {
                        "value": "Дополнительное поле"
                    }
                ]
            }
        ],
        "_embedded": {
            "tags": [
                {
                    "id": 185177
                }
            ]
        }
    },
    {
        "name": "Покупатель для примера 2",
        "next_date": 1589230800
    }
]

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


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 401419,
                "name": "Покупатель для примера",
                "next_date": 1589230800,
                "responsible_user_id": 321321,
                "status_id": 4051144,
                "periodicity": 0,
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589275673,
                "updated_at": 1589275673,
                "is_deleted": false,
                "account_id": 123123,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/401419"
                    }
                }
            },
            {
                "id": 401421,
                "name": "Покупатель для примера 2",
                "next_date": 1589230800,
                "responsible_user_id": 321321,
                "status_id": 4051144,
                "periodicity": 0,
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589275673,
                "updated_at": 1589275673,
                "is_deleted": false,
                "account_id": 123123,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/401421"
                    }
                }
            }
        ]
    }
}

Изменение свойств покупателя

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

URL метода

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

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

Свойства покупателя доступные для изменения:
– name
– next_price
– next_date
– responsible_user_id
– periodicity
– created_by
– created_at
– updated_by
– updated_at
– custom_fields_values
– _embedded[segments]
– _embedded[tags]

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

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


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

{
    "name": "Новое имя покупателя",
    "next_price": 10000,
    "next_date": 1589230800
    "responsible_user_id": 3987910,
    "periodicity": 1123,
    "created_by": 3987910,
    "updated_by": 3987910,
    "_embedded": {
        "tags": [
            {
                "id": 2757
            }
        ]
    },
    "custom_fields_values": [
        {
            "field_id": 22263,
            "values": [
                {
                    "value": "Дополнительное поле"
                }
            ]
        }
    ],
}

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


Content-Type: application/hal+json

{
    "id": 401317,
    "name": "New name",
    "next_price": 1,
    "next_date": 1589317198,
    "responsible_user_id": 3987910,
    "status_id": 4051144,
    "periodicity": 1123,
    "created_by": 3987910,
    "updated_by": 3987910,
    "created_at": 1589271887,
    "updated_at": 1589278253,
    "is_deleted": false,
    "account_id": 123123,
    "request_id": "401317",
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/401317"
        }
    },
    "_embedded": {
        "tags": [
            {
                "id": 2757,
                "name": "Новый тег"
            }
        ]
    }
}

При массовом изменении покупателей необходимо передать массив из JSON с обязательным параметром id (идентификатор покупателя).

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


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

[
    {
        "id": 401317,
        "next_date": 1589230800,
        "responsible_user_id": 3987910,
        "name": "Новое имя покупателя"
    },
    {
        "id": 401453,
        "next_date": 1589230800,
        "name": "Новое имя покупателя",
        "_embedded": {
            "tags": [
                {
                    "id": 2757
                }
            ]
        }
    }
]

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


Content-Type: application/hal+json

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers"
        }
    },
    "_embedded": {
        "customers": [
            {
                "id": 401317,
                "name": "Новое имя покупателя",
                "next_price": 1,
                "next_date": 1589230800,
                "responsible_user_id": 321321,
                "status_id": 4051147,
                "periodicity": 1123,
                "created_by": 3987910,
                "updated_by": 3944275,
                "created_at": 1589271887,
                "updated_at": 1589357369,
                "is_deleted": false,
                "account_id": 123123,
                "request_id": "401317",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/401317"
                    }
                }
            },
            {
                "id": 401453,
                "name": "Новое имя покупателя",
                "next_price": 0,
                "next_date": 1589230800,
                "responsible_user_id": 3213211,
                "status_id": 4051147,
                "periodicity": 0,
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589277087,
                "updated_at": 1589357369,
                "is_deleted": false,
                "account_id": 123123,
                "request_id": "401453",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/401453"
                    }
                },
                "_embedded": {
                    "tags": [
                        {
                            "id": 2757,
                            "name": "VIP"
                        }
                    ]
                }
            }
        ]
    }
}

ТРАНЗАКЦИИ

Транзакция – это сущность которая описывает основные характеристики покупки (дата и сумма). Является дополнением для “покупателя”.

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

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

URL метода

GET /api/v4/customers/transactions/{id:\d+}

GET /api/v4/customers/{customer_id:\d+}/transactions/{id:\d+}

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

Параметр Описание
customer_id Идентификатор покупателя
id Идентификатор транзакции

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


GET https://example.amocrm.ru/api/v4/customers/transactions/452380

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


{
    "id": 452380,
    "price": 10000,
    "comment": "Комментарий по совершенной транзакции.",
    "completed_at": 1589634420,
    "customer_id": 403466,
    "created_by": 3944275,
    "updated_by": 3944275,
    "created_at": 1589634433,
    "updated_at": 1589634433,
    "is_deleted": false,
    "account_id": 123123,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/403466/transactions/452380"
        }
    },
    "_embedded": {
        "customer": {
            "id": 403466,
            "_links": {
                "self": {
                    "href": "https://example.amocrm.ru/api/v4/customers/403466"
                }
            }
        }
    }
}

Возможные параметры транзакции

Параметр Тип Описание
id int Идентификатор транзакции
price int Сумма транзакции
comment string Комментарий к транзакции
completed_at timestamp Время совершения транзакции
customer_id int Идентификатор покупателя
created_by int Кем создана транзакция
updated_by int Кем обновлена транзакция
created_at timestamp Дата и время создания транзакции
updated_at timestamp Дата и время обновления транзакции
is_deleted bool Удалена ли транзакция
account_id int Идентификатор транзакции
_embedded[customer] object Объект, который содержит идентификатор и ссылку на сущность покупателя.

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

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

URL метода

GET /api/v4/customers/transactions – для получения списка всех транзакций

GET /api/v4/customers/{customer_id:\d+}/transactions – для поиска по идентификатору покупателю

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

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

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


GET https://example.amocrm.ru/api/v4/customers/403466/transactions

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/customers/403466/transactions?page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/customers/403466/transactions?page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "transactions": [
            {
                "id": 452380,
                "price": 10000,
                "comment": "Комментарий к транзакции",
                "completed_at": 1589634420,
                "customer_id": 403466,
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589634433,
                "updated_at": 1589634433,
                "is_deleted": false,
                "account_id": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/403466/transactions/452380"
                    }
                },
                "_embedded": {
                    "customer": {
                        "id": 403466,
                        "_links": {
                            "self": {
                                "href": "https://example.amocrm.ru/api/v4/customers/403466"
                            }
                        }
                    }
                }
            }
        ]
    }
}

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

Добавление транзакции

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

URL метода

POST /api/v4/customers/{customer_id:\d+}/transactions

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

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

При создании покупок необходимо перечислить их в массиве из JSON-объектов, содержащих обязательный параметр price и дополнительные параметры:
– comment ( Комментарий к транзакции )
– completed_at ( Когда была совершена транзакция )
– next_date ( Дата следующей транзакции )
– _embedded[catalog_elements] ( Список купленных товаров )
– request_id ( Идентификатор запроса )

Для того чтобы привязать товар к транзакции, необходимо в теле запроса передать параметр _embedded[catalog_elements] в следующем формате:


"_embedded": {
    "catalog_elements": [
        {
            "id": {{ catalog_element_id }},
            "metadata": {
                "catalog_id": {{ catalog_id }},
                "quantity": {{ quantity }}
            }
        }
    ]
}

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


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

[
    {
        "price": 777,
        "completed_at": 1589640057,
        "comment": "Комментарий к транзакции",
        "next_date": 1589640621,
        "_embedded": {
            "catalog_elements": [
                {
                    "id": 914863,
                    "metadata": {
                        "catalog_id": 1209,
                        "quantity": 2
                    }
                }
            ]
        }
    },
    {
        "price": 1032,
        "comment": "Еще одна транзакция"
    }
]

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


{
    "_total_items": 2,
    "_embedded": {
        "transactions": [
            {
                "id": 452438,
                "customer_id": 403466,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/403466/transactions/452438"
                    }
                },
                "_embedded": {
                    "customer": {
                        "id": 403466,
                        "_links": {
                            "self": {
                                "href": "https://example.amocrm.ru/api/v4/customers/403466"
                            }
                        }
                    }
                }
            },
            {
                "id": 452440,
                "customer_id": 403466,
                "request_id": "1",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/customers/403466/transactions/452440"
                    }
                },
                "_embedded": {
                    "customer": {
                        "id": 403466,
                        "_links": {
                            "self": {
                                "href": "https://example.amocrm.ru/api/v4/customers/403466"
                            }
                        }
                    }
                }
            }
        ]
    }
}

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

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

URL метода

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

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

Параметр Описание
customer_id Идентификатор покупателя
id Идентификатор транзакции

Пример удаления транзакции


DELETE https://example.amocrm.ru/api/v4/customers/403466/transactions/452438

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

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

КОДЫ ОШИБОК API