API для работы с клиентами¶
Создать или обновить клиентов¶
POST https://cloud.roistat.com/api/v1/project/clients/import
Данный метод необходим для создания или обновления клиентов.
curl 'https://cloud.roistat.com/api/v1/project/clients/import?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data '[{"id": "111", "name": "Валера"}]'
Тело запроса:
[
{
"id": "111",
"name": "Валера",
"phone": "78888888888",
"email": "[email protected]",
"company": "company1",
"birth_date": "1980-01-01",
"fields":
{
"segment": "1"
}
},
{
"id": "222",
"name": "Ваcилий",
"phone": "79999999999,89999999999,87777777777",
"email": "[email protected]",
"company": "company2",
"birth_date": "1990-01-01",
"fields":
{
"segment": "2"
}
}
]
Строка запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
project | string | Номер проекта | да |
Тело запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
id | string | ID клиента в CRM | да |
name | string | имя клиента | да |
phone | null или string | один или несколько номеров телефона клиента | нет |
null или string | адрес электронной почты клиента | нет | |
company | null или string | название компании клиента | нет |
birth_date | null или string | дата рождения клиента | нет |
fields | object | дополнительные поля и их значения в формате "field_name": "value" | нет |
Параметр | Тип | Описание |
---|---|---|
status | string |
Получить список клиентов из Управления клиентами¶
POST https://cloud.roistat.com/api/v1/project/clients
Данный метод позволяет получить список клиентов из Управления клиентами.
curl 'https://cloud.roistat.com/api/v1/project/clients?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data '{"filters": [["phone","=","79880002233"]]}'
Тело запроса:
{
"clients": [
{
"id": 7,
"first_visit_date": null,
"external_id": "105",
"name": "Имя клиента",
"phone": "79880002233",
"email": "[email protected]",
"first_order_date": null,
"last_order_date": null,
"order_count": 0,
"revenue": 0,
"profit": 0,
"birth_date": null,
"company": "",
"comment": null,
"client_url": "http://example.crm.com/contacts/105",
"first_visit_marker": null,
"first_visit_marker_alias": "",
"first_visit_marker_icon": "https://cloud.roistat.com/img/arrow-right.png",
"first_visit_marker_alias_level_1": ""
},
{
"id": 6,
"first_visit_date": null,
"external_id": "106",
"name": "Иван",
"phone": "79880002233",
"email": "[email protected]",
"first_order_date": null,
"last_order_date": null,
"order_count": 0,
"revenue": 0,
"profit": 0,
"birth_date": null,
"company": "",
"comment": null,
"client_url": "http://example.crm.com/contacts/106",
"first_visit_marker": null,
"first_visit_marker_alias": "",
"first_visit_marker_icon": "https://cloud.roistat.com/img/arrow-right.png",
"first_visit_marker_alias_level_1": ""
}
],
"total": 2,
"status": "success"
}
Строка запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
project | string | Номер проекта | да |
Тело запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
filters | object | нет | |
> and | array[string] | нет | |
limit | integer | нет | |
offset | integer | нет |
Параметр | Тип | Описание |
---|---|---|
clients | array[object] | |
> | object | |
>> id | integer | ID клиента в Roistat |
>> first_visit_date | string или null | дата первого визита |
>> external_id | string | ID клиента в CRM |
>> name | string | имя клиента |
>> phone | string | телефон клиента |
string | емейл клиента | |
>> first_order_date | string или null | дата первого заказа |
>> last_order_date | string или null | дата последнего заказа |
>> order_count | integer | количество заказов |
>> revenue | integer | выручка по заказам |
>> profit | integer | прибыль по заказам |
>> birth_date | string или null | дата дня рождения |
>> company | string | компания клиента |
>> comment | string или null | |
>> client_url | string | URL клиента в CRM |
>> first_visit_marker | string или null | |
>> first_visit_marker_alias | string | |
>> first_visit_marker_icon | string | |
>> first_visit_marker_alias_level_1 | string | |
total | integer | |
status | string |
Получить фид клиента: визиты, события, сделки, звонки, взаимодействие с Ловцом лидов¶
GET https://cloud.roistat.com/api/v1/project/clients/detail/feed
Воспользуйтесь этим методом, чтобы получить фид определенного клиента: информацию по его визитам, сделкам, изменениям статусов сделок, звонкам, сработавшим событиям, взаимодействиям с Ловцом лидов.
{
"feed": [
{
"type": "visit",
"visitId": "41028",
"creationDate": "2021-11-10T14:05:12+0000",
"sourceId": "instagram_stories",
"device": {
"os": "Mac 10.15 ",
"os_icon": "https://cloud.roistat.com/img/os/macosx.png",
"agent": "Chrome 90.0 browser Blink",
"agent_icon": "https://cloud.roistat.com/img/browsers/chrome.png",
"is_mobile": false
},
"sourceTitle": "instagram → stories",
"sourceIcon": "https://cloud.roistat.com/img/instagram.png"
},
{
"type": "order",
"id": "order_41028",
"name": "order_41028",
"status": "0",
"statusType": "progress",
"statusTitle": "Новый",
"revenue": 0,
"formattedRevenue": "0 ₽",
"cost": 0,
"formattedCost": "0 ₽",
"fields": {
"status_name": "Ожидает оплаты",
"Менеджер": "Соколова Мария",
"roistat": 41028
},
"creationDate": "2021-11-10T14:28:59+0000",
"updateDate": null
},
{
"type": "event",
"metaId": "5",
"creationDate": "2021-11-10T14:08:08+0000",
"name": "Переход на страницу корзины"
},
{
"type": "lead_hunter_appearance",
"date": "2021-11-08T16:53:16+0000",
"page": "cozy.kitchen.ru/catalog/accessories"
},
{
"type": "lead_hunter_caught",
"date": "2021-11-08T16:55:16+0000",
"page": "cozy.kitchen.ru/catalog/accessories"
"name": "Мария"
"field": "71234567890"
"status": "1"
},
{
"order_id": "order_41028",
"order_title": "order_41028",
"type": "orderStatusChange",
"status": "1",
"statusType": "progress",
"statusTitle": "В работе",
"date": "2021-11-11T06:28:59+0000"
},
{
"order_id": "order_41028",
"order_title": "order_41028",
"type": "orderStatusChange",
"status": "2",
"statusType": "progress",
"statusTitle": "Ожидает оплаты",
"date": "2021-11-11T07:28:59+0000"
},
{
"order_id": "order_41028",
"order_title": "order_41028",
"type": "orderCostChange",
"cost": 1000,
"formattedCost": "1000 ₽",
"date": "2021-11-11T07:28:59+0000"
},
{
"order_id": "order_41028",
"order_title": "order_41028",
"type": "orderPriceChange",
"price": 1000,
"formattedPrice": "1000 ₽",
"date": "2021-11-11T07:28:59+0000"
}
],
"status": "success"
}
Строка запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
project | string | Номер проекта | да |
client | string | ID клиента (можно получить с помощью /project/clients или посмотреть в списке клиентов) | да |
Тело запроса:
Без параметров.
Параметр | Тип | Описание |
---|---|---|
feed | array[object] | |
> | object | |
>> type | string | visit – если указан этот тип, в массиве передаются данные по визиту |
>> visitId | string | Номер визита |
>> creationDate | string | Дата создания визита в формате 2022-01-01T00:00:00+0300 |
>> sourceId | string | Маркер визита |
>> device | object | Информация об устройстве, с которого совершен визит |
>>> os | string | Операционная система |
>>> os_icon | string | Ссылка на иконку ОС |
>>> agent | string | Браузер |
>>> agent_icon | string | Ссылка на иконку браузера |
>>> is_mobile | boolean | Является ли устройство мобильным: true – да, false – нет |
>> sourceTitle | string | Человекочитаемый маркер визита |
>> sourceIcon | string | Ссылка на иконку источника визита |
> | object | |
>> type | string | order – если указан этот тип, в массиве передаются данные по сделке |
>> id | string | ID сделки |
>> name | string | Название сделки |
>> status | string | ID статуса в системе Roistat (можно узнать с помощью метода /project/integration/order/list](/API/methods/orders/#list)) |
>> statusType | string | Группа, к которой относится статус в системе Roistat: unused – «Не учитываются», progress – «В работе», paid – «Оплаченные», canceled – «Отмененные» |
>> statusTitle | string | Название статуса |
>> revenue | integer | Выручка по сделке |
>> formattedRevenue | string | Выручка по сделке с указанием валюты |
>> cost | integer | Себестоимость сделки |
>> formattedCost | string | Себестоимость сделки с указанием валюты |
>> fields | object | Дополнительные поля сделки и их значения |
>> creationDate | string | Дата создания сделки в формате 2022-01-01T00:00:00+0300 |
>> updateDate | string or null | Дата обновления сделки |
> | object | |
>> type | string | event – если указан этот тип, в массиве передаются данные по событию |
>> metaId | string | ID события в системе Roistat |
>> creationDate | string | Дата срабатывания события в формате 2022-01-01T00:00:00+0300 |
>> name | string | Название события |
> | object | |
>> type | string | lead_hunter_appearance – если указан этот тип, в массиве передаются данные по взаимодействию клиента с Ловцом лидов |
>> date | string | Дата взаимодействия с Ловцом лидов в формате 2022-01-01T00:00:00+0300 |
>> page | string | Страница, на которой произошло взаимодействие с Ловцом лидов |
> | object | |
>> type | string | lead_hunter_caught – если указан этот тип, в массиве передаются данные по пойманным лидам |
>> date | string | Дата создания лида в формате 2022-01-01T00:00:00+0300 |
>> page | string | Страница срабатывания |
>> name | string | Имя лида |
>> field | string | Введенный номер телефона |
>> status | string | Статус пойманного лида: 1 – отправлен, 0 – не отправлен |
> | object | |
>> type | string | orderStatusChange – если указан этот тип, в массиве передается информация об изменении статуса сделки |
>> order_id | string | ID сделки |
>> order_title | string | Название сделки |
>> status | string | ID статуса в системе Roistat (можно узнать с помощью метода /project/integration/order/list](/API/methods/orders/#list)) |
>> statusType | string | Группа, к которой относится статус в системе Roistat: unused – «Не учитываются», progress – «В работе», paid – «Оплаченные», canceled – «Отмененные» |
>> statusTitle | string | Название статуса |
>> date | string | Дата изменения статуса в формате 2022-01-01T00:00:00+0300 |
> | object | |
>> type | string | orderCostChange – если указан этот тип, в массиве передается информация об изменении себестоимости сделки |
>> order_id | string | ID сделки |
>> order_title | string | Название сделки |
>> cost | integer | Измененная себестоимость сделки |
>> formattedCost | string | Измененная себестоимость сделки с указанием валюты |
>> date | string | Дата изменения себестоимости в формате 2022-01-01T00:00:00+0300 |
> | object | |
>> type | string | orderPriceChange – если указан этот тип, в массиве передается информация об изменении цены сделки |
>> order_id | string | ID сделки |
>> order_title | string | Название сделки |
>> price | integer | Измененная цена сделки |
>> formattedPrice | string | Измененная цена сделки с указанием валюты |
>> date | string | Дата изменения цены в формате 2022-01-01T00:00:00+0300 |
> | object | |
>> type | string | call – если указан этот тип, в массиве передается информация о звонках клиента |
>> callee | string | Набранный номер |
>> caller | string | Номер абонента |
>> duration | string | Длительность звонка в секундах |
>> status | string | 1 из 9 статусов звонка: ACTIVE – звонок в процессе; ANSWER – звонок был принят и обработан сотрудником; BUSY – входящий звонок был, но линия была занята; NOANSWER – входящий вызов состоялся, но в течение времени ожидания ответа не был принят сотрудником; CANCEL – входящий вызов состоялся, но был завершен до того, как сотрудник ответил; CONGESTION – вызов не состоялся из-за технических проблем; CHANUNAVAIL – вызываемый номер был недоступен; DONTCALL – входящий вызов был отменен; TORTURE – входящий вызов был перенаправлен на автоответчик. |
>> date | string | Дата звонка в формате 2022-01-01T00:00:00+0300 |
>> file_url | string | Ссылка на запись звонка |
status | string | Статус запроса |
Получить список адресатов Email-рассылок в определенных статусах¶
POST https://cloud.roistat.com/api/v1/project/clients/campaign/contact/list
Данный метод позволяет получить список адресатов рассылок в определенных статусах: Отправлено, Доставлено, Прочитано, Переходы, Отписались, Отметили как спам. Можно указать один или несколько статусов.
curl 'https://cloud.roistat.com/api/v1/project/clients/campaign/contact/list?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data '{"metric_ids": ["sent"], "campaign_ids": [2]}'
Тело запроса:
{
"data": [
{
"contact": "[email protected]",
"metrics": {
"sent": 1
}
},
{
"contact": "[email protected]",
"metrics": {
"sent": 1
}
},
{
"contact": "[email protected]",
"metrics": {
"sent": 1
}
}
],
"count": 3,
"total_count": 3,
"status": "success"
}
Строка запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
project | string | Номер проекта | да |
Тело запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
metric_ids | array[string] | Статусы, для которых нужно выгрузить адресатов: "sent" – Отправлено, "delivered" – Доставлено, "opened" – Прочитано, "click" – Переходы, "unsubscribe" – Отписались, "spam" – Отметили как спам. Можно указать один или несколько статусов. | да |
campaign_ids | array[integer] | Идентификаторы рассылок, для которых нужно выгрузить адресатов. Идентификатор рассылки отображается в списке рассылок в столбце ID. Можно указать один или несколько идентификаторов. | да |
Параметр | Тип | Описание |
---|---|---|
data | array[object] | |
> | object | |
>> contact | string | Email клиента |
>> metrics | object | Объект, содержащий информацию о выбранных статусах |
>>> statusN | integer | Вместо statusN передается статус, указанный в запросе в массиве metric_ids : "sent" , "delivered" , "opened" , "click" , "unsubscribe" или "spam" . Значение параметра – количество писем в данном статусе, отправленных адресату. |
count | integer | Количество результатов запроса в рамках лимита |
total_count | integer | Количество результатов независимо от лимита |
status | string | Статус запроса |
Получить список Email-рассылок и информацию о них¶
POST https://cloud.roistat.com/api/v1/project/clients/campaign/list
Данный метод позволяет получить список Email-рассылок и всю информацию о них.
curl 'https://cloud.roistat.com/api/v1/project/clients/campaign/list?project=12345' \
--request POST \
--header 'Content-type: application/json' \
--header 'Api-key: {KEY}' \
--data '{"filters": [["status_id","=","sent"]]}'
Тело запроса:
{
"data": [
{
"id": 2,
"title": "Скидки",
"status_id": "sent",
"engine_id": "unione",
"status": {
"id": "sent",
"title": "Отправлено",
"description": null
},
"contact_from": "[email protected]",
"name_from": "Test",
"segment_ids": [
6
],
"segments": [
{
"id": 6,
"title": "Гугл-форма | Товары для кухни"
}
],
"client_ids": [],
"timetable": {
"date": "2021-08-17",
"time": "14:00:00",
"timezone": "Europe\/Moscow",
"is_deferred": false
},
"attachments_ids": null,
"attachments": null,
"template": "Test",
"template_id": "1",
"template_metadata": null,
"metrics": {
"sent": 42,
"delivered": 36,
"opened": 28,
"click": 5,
"unsubscribe": 2,
"spam": 2,
"unique_contact_count": 42
},
"price": 9,
"is_enough_money_for_sending": false,
"contact_count": 45,
"recipient_count": 45,
"creation_date": "2022-03-19T20:31:09+0000",
"update_date": "2022-03-19T20:31:09+0000",
"send_date": "2022-04-18T20:31:09+0000",
"service": null,
"send_error_descriptions": []
}
],
"count": 1,
"total_count": 1,
"status": "success"
}
Строка запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
project | string | Номер проекта | да |
Тело запроса:
Параметр | Тип | Описание | Обязательный |
---|---|---|---|
filters | array | Дополнительные фильтры. Указываются в формате "filters": [["<parameter>","=","<value>"]] , где:
| нет |
limit | integer | Максимальное количество результатов в ответе | нет |
offset | integer | Количество результатов в начале, которое нужно пропустить | нет |
Параметр | Тип | Описание |
---|---|---|
data | array[object] | |
> id | string | ID рассылки |
> title | string | Название рассылки |
> status_id | string | Статус рассылки (sent – Отправлено, delivered – Доставлено, opened – Прочитано, click – Переходы, unsubscribe – Отписались, spam – Отметили как спам) |
> engine_id | string | ID сервиса рассылки |
> status | object | Информация о статусе рассылки |
>> id | string | Статус рассылки (sent – Отправлено, delivered – Доставлено, opened – Прочитано, click – Переходы, unsubscribe – Отписались, spam – Отметили как спам) |
>> title | string | Название статуса |
>> description | string | Описание статуса |
> contact_from | string | Email отправителя |
> name_from | string | Имя отправителя |
> segment_ids | array[integer] | ID сегментов для рассылки |
> segments | array[object] | Информация о сегментах для рассылки |
>> id | integer | ID сегмента |
>> id | title | Название сегмента |
> client_ids | array[integer] | ID клиентов |
> timetable | object | Информация о времени отправки |
>> date | string | Дата |
>> time | string | Время |
>> timezone | string | Часовой пояс |
>> is_deferred | boolean | Отложена ли отправка |
> attachments_ids | array[integer] | ID вложений |
> attachments | array | Вложения |
> template | string | Шаблон в формате HTML |
> template_id | integer | ID шаблона |
> template_metadata | array[string] | Метаданные шаблона |
> metrics | object | Показатели рассылки |
>> sent | integer | Отправлено |
>> delivered | integer | Доставлено |
>> opened | integer | Прочитано |
>> click | integer | Переходы |
>> unsubscribe | integer | Отписались |
>> spam | integer | Отметили как спам |
>> unique_contact_count | integer | Уникальные контакты |
> price | integer | Стоимость рассылки |
> is_enough_money_for_sending | boolean | Достаточно ли средств для отправки |
> contact_count | integer | Количество контактов, которым отправляется рассылка |
> recipient_count | integer | Количество получателей |
> creation_date | string | Дата создания рассылки |
> update_date | string | Дата обновления рассылки |
> send_date | string | Дата отправки рассылки |
> service | string | |
> send_error_descriptions | array[string] | Тексты ошибок отправки |
count | integer | Количество результатов |
total_count | integer | Количество результатов независимо от лимита |
status | string | Статус запроса |