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": "email1@mail.com",
"company": "company1",
"birth_date": "1980-01-01",
"fields":
{
"segment": "1"
}
},
{
"id": "222",
"name": "Ваcилий",
"phone": "79999999999,89999999999,87777777777",
"email": "email2@mail.com",
"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": "test@roistat.test",
"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": "test@roistat.test",
"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]}'
Тело запроса:
Строка запроса:
| Параметр | Тип | Описание | Обязательный |
|---|---|---|---|
| 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": "test@domain.com",
"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 | Статус запроса |