Наверх

API-метод импорта плановых метрик

Содержание

Описание

API-метод дает возможность импортировать плановые метрики в статистику Calltouch:

mceclip0.png

Подробное описание функционала плановых метрик представлено в отдельной статье.

advice_ver2.png Важно: для успешного импорта название пользовательских столбцов и целей не должны пересекаться с названиями метрик Calltouch.

advice_ver2.png Важно: импортированные с помощью метода API плановые метрики обновятся на следующий день в отчете «Все источники — Данные площадок» и в дашбордах. В остальных отчетах (например, «Все источники — Данные Calltouch») импортированные метрики будут отображены сразу после импорта.

API-метод для импорта плановых метрик

POST: https://api.calltouch.ru/report-service/RestAPI/api/plans-import/add

HTTP-заголовки:

  • Access-Token – API-ключ
  • SiteId – ID ЛК Calltouch

Тело запроса в формате JSON:

{
"items": [
{
"dateFrom": "01-04-2021",
"dateTo": "02-04-2021",
"source": "yandex",
"medium": "cpc",
"campaign": "april",
"content": "sale",
"keyword": "распродажа",
"metric":
{
"type": "Лиды",
"name": "Уникальные лиды",
"value": 100
}
},
{
"dateFrom": "01-04-2021",
"dateTo": "20-04-2021",
"source": "google",
"medium": "cpc",
"metric":
{
"type": "Сделки и ROI",
"name": "Выручка",
"value": 23423
}
},
{
"dateFrom": "01-04-2021",
"dateTo": "20-04-2021",
"medium": "cpc",
"metric":
{
"type": "Пользовательские",
"name": "Название столбца",
"value": 22
}
}
]
}

Описание параметров тела запроса:

Параметр Формат Обязательный Описание
items[n].dateFrom string Да

Начало и конец планового периода, дни начала и окончания включены. Формат: dd-mm-yyyy.

Для импорта плановой метрики за один день используется dateFrom=dateTo.

items[n].dateTo
items[n].metric object Да Объект с типом, названием и значением импортируемой плановой метрики.
items[n].metric.type string Да

Тип метрики, для которой импортируется план. Возможные значения:

  • Лиды;
  • Поведение;
  • Сделки и ROI;
  • Электронная торговля;
  • Площадки;
  • Пользовательские;
  • Цели.
items[n].metric.name string Да

Название метрики, для которой импортируется план. 

Возможные значения:

  • Для items[n].metric.type="Лиды":
    • Все лиды;
    • Уникальные лиды;
    • Неудачные лиды;
    • Целевые лиды;
    • Уникально-целевые лиды;
    • Все звонки;
    • Уникальные звонки;
    • Повторные звонки;
    • Целевые звонки;
    • Уникально-целевые звонки;
    • Неудачные звонки;
    • Спам-звонки;
    • Все обратные звонки;
    • Уникальные обратные звонки;
    • Целевые обратные звонки;
    • Уникально-целевые обратные звонки;
    • Неудачные обратные звонки;
    • Спам-обратные звонки;
    • Все заявки;
    • Уникальные заявки;
    • Повторные заявки;
    • Неудачные заявки;
    • Целевые заявки;
    • Уникально-целевые заявки.
  • Для items[n].metric.type="Поведение":
    • Сессии;
    • Отказы.
  • Для items[n].metric.type="Сделки и ROI":
    • Всего сделок;
    • Средний чек;
    • Выручка.
  • Для items[n].metric.type="Электронная торговля":
    • Просмотры товаров;
    • Добавлен в корзину;
    • Выручка по добавленным в корзину;
    • Маржа по добавленным в корзину;
    • Удалён из корзины;
    • Выручка по удалённым из корзины;
    • Маржа по удалённым из корзины;
    • Товаров в корзине;
    • Выручка по корзине;
    • Маржа по корзине;
    • Заказ оформлен;
    • Количество заказанных товаров;
    • Выручка по заказам;
    • Маржа по заказам;
    • Оплата;
    • Количество оплаченных товаров;
    • Выручка по оплатам;
    • Маржа по оплатам.
  • Для items[n].metric.type="Площадки":
    • Бюджет;
    • Показы;
    • Клики;
    • CPC;
  • Для items[n].metric.type="Пользовательские" и items[n].metric.type="Цели" передаются название пользовательских столбцов и целей соответственно.
items[n].metric.value integer Да

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

items[n].source string Обязательно наличие одного из параметров Источник, для которого добавляется план.
items[n].medium Канал, для которого добавляется план.
items[n].campaign Кампания, для которой добавляется план.
items[n].content Объявление, для которого добавляется план.
items[n].keyword Ключевое слово, для которого добавляется план.

В одном запросе можно передать сразу несколько наборов планов для разных комбинаций параметров. Все наборы перечисляются внутри массива items, максимальное количество наборов - 100.

Ответ

Успешный ответ

Если API-запрос прошел валидацию и был успешно отправлен, в ответ вы получите ID лога, по которому отдельным API-запросом можно будет отследить его статус – успешно ли импортировались данные или нет. Пример ответа:

{
"meta": [],
"data": {
"importLogId": 123
}
}

Где 123 – ID лога, по которому можно в отдельном API-запросе узнать статус импорта.

Ошибки

Все ошибки содержат поясняющий текст в ответе с подсказкой что нужно исправить, чтобы запрос завершился успешно.

1. Ошибка авторизации

{
"message": "Access token не найден"
}

2. Ошибка формата тела запроса

{
"meta": [],
"data": {
"type": "apiError",
"apiErrorData": {
"errorCode": 1,
"errorMessage": "Синтаксическая ошибка JSON в запросе или запрос пустой",
"errorDescription": null
},
"validationErrorData": null
}
}

3. Ошибка в содержимом параметров

{
"meta": [],
"data": {
"type": "validationError",
"apiErrorData": null,
"validationErrorData": {
"violations": [
{
"fieldPath": "items[0].source",
"message": "Должно быть заполнено одно или несколько из полей: source, medium, campaign, content, keyword"
},
{
"fieldPath": "items[n].metric.type",
"message": "Значение не должно быть пустым."
},
{
"fieldPath": "items[n].metric.type",
"message": "Значение не совпадает с одним из допустимых."
},
{
"fieldPath": "items",
"message": "Эта коллекция должна содержать 1 элемент или больше."
}
]
}
}
}

4. Ошибка даты в запросе

{
"meta": [],
"data": {
"type": "validationError",
"apiErrorData": null,
"validationErrorData": {
"violations": [
{
"fieldPath": "items[0].dateTo",
"message": "Значение не является правильной датой."
},
{
"fieldPath": "items[n].dateFrom",
"message": "Значение dateFrom должно быть меньше или равно dateTo"
}
]
}
}
}

5. Отсутствие обязательных полей в запросе

{
"meta": [],
"data":
{
"message": "В запросе не указано обязательное поле \"dateTo\""
}
}

6. Неуникальное название пользовательского столбца в запросе

{
"meta": [],
"data": {
"type": "validationError",
"apiErrorData": null,
"validationErrorData": {
"violations": [
{
"fieldPath": "items[0].metric.name",
"message": "Название пользовательского столбца не уникально, импорт невозможен."
}
]
}
}
}

API-метод для получения статуса импорта

Запрос

POST: https://api.calltouch.ru/report-service/RestAPI/api/plans-import/123/status

HTTP-заголовки:

  • Access-Token – API-ключ
  • SiteId – ID ЛК Calltouch

Где 123 – ID лога, который был в ответе на успешный запрос на импорт плановых метрик.

Ответ

В ответе будут ранее отправленные данные в запросе на импорт плановых метрик, поверх которых добавится параметр status, в котором будут актуальные статусы отправленных ранее API-запросов.

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

{
"meta": [],
"data": {
"status": "success",
"items": [
{
"dateFrom": "01-04-2021",
"dateTo": "02-04-2021",
"source": "yandex",
"medium": "cpc",
"campaign": "april",
"content": "sale",
"keyword": "распродажа",
"metric":
{
"type": "Лиды",
"name": "Уникальные лиды",
"value": 100
}
},
{
"dateFrom": "01-04-2021",
"dateTo": "20-04-2021",
"source": "google",
"medium": "cpc",
"metric":
{
"type": "Сделки и ROI",
"name": "Выручка",
"value": 23423
}
},
{
"dateFrom": "01-04-2021",
"dateTo": "20-04-2021",
"medium": "cpc",
"metric":
{
"type": "Пользовательские",
"name": "Название столбца",
"value": 22
}
}
]
}
}

Возможные значения параметра status:

Статус Описание
success Данные были успешно импортированы
in progress... Данные находятся в процессе импорта
error Ошибка импорта данных. Попробуйте отправить API-запрос на импорт повторно, или свяжитесь с вашим аккаунт-менеджером Calltouch либо напишите на почту info@calltouch.net.