Наверх
Подписаться

Импорт расходов

Содержание

Описание

API-методы дают возможность импортировать рекламный бюджет в отчет по площадкам личного кабинета Calltouch:

Screenshot_2020-06-22_at_15.11.43.png

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

Запрос на добавление расходов

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

При импорте расхода из API обязательно должен быть указан хотя бы один из пяти параметров – source, medium, campaign, content или term. Импортированный расход из параметра price равномерно распределяется на дни в указанном периоде между параметрами dateFrom и dateTo включительно. Если какой-то из параметров source, medium, campaign, content или term не был указан, то указанный расход импортируется для значения <не заполнено>. Если в рамках одного ЛК прилетает сразу несколько запросов на импорт, то все выполняются по очереди. Если среди какого-либо дня в указанном периоде уже есть расход, то он складывается с импортируемым.

Запрос на обновление расходов

https://api.calltouch.ru/report-service/RestAPI/api/costs-import/update

При использование данного API-метода будет обновляться только расход, импортированный через API, XLS или через интерфейс. Чтобы обновить ранее импортированный расход, необходимо передать ровно тот же набор параметров source, medium, campaign, content и keyword – порядок и вложенность друг в друга не важны, важна лишь комбинация. При несовпадение указанного набора при обновление с существующими, запрос на обновление приравнивается к запросу на импорт новых данных, и переданный при обновление расход суммируется с существующими значениями, а вместо неуказанных параметров будет использовано значение <не заполнено>.

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

Параметры в обоих запросах выше одинаковые.

Метод: POST

Формат тела: JSON

Авторизация: через API-токен в параметре Access-Token в HTTP-заголовке запроса

Пример тела запроса:

{
"items": [
{
"dateFrom": "2020-06-01",
"dateTo": "2020-06-30",
"price": "1000.00",
"currency": "rub",
"source": "yandex",
"medium": "cpc",
"campaign": "june",
"content": "sale",
"keyword": "распродажа"
},
{
"dateFrom": "2020-06-01",
"dateTo": "2020-06-30",
"price": "100000",
"currency": "rub",
"source": "google",
"medium": "organic"
}
]
}

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

Параметр Формат Обязательный Описание
dateFrom yyyy-mm-dd Да Импортируемый расход будет равномерно распределен на все дни в указанном периоде включительно. Чтобы импортировать период за один день, можно указать dateFrom = dateTo.
Должно выполняться условие: dateFrom <= dateTo
dateTo
price xx.xx Да Импортируемый расход. Дробная часть до сотых указывается через точку.
currency rub или usd Да Валюта
source Любые
символы, максимум 1000.  
Должен быть
передан хотя бы один из параметров.
Источник
medium Канал
campaign Кампания
content Объявление
keyword Ключевое слово

Тип все параметров – строка (string). В одном запросе можно передать сразу несколько наборов с импортом расходов для разных комбинаций параметров. Все наборы перечисляются внутри массива items, максимальное кол-во наборов 10000. Все параметры перечисляются внутри объекта items.

Ответ

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

Если 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"
}
]
}
}
}

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

Запрос

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

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

Метод: GET

Авторизация: через API-токен в параметре Access-Token в HTTP-заголовке запроса

Ответ

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

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

{
"meta": [],
"data": {
"status": "success",
"items": [
{
"dateFrom": "2020-06-01",
"dateTo": "2020-06-30",
"price": "1000.00",
"currency": "rub",
"source": "yandex",
"medium": "cpc",
"campaign": "june",
"content": "sale",
"keyword": "распродажа"
},
{
"dateFrom": "2020-06-01",
"dateTo": "2020-06-30",
"price": "100000",
"currency": "rub",
"source": "google",
"medium": "organic",
"campaign": null,
"content": null,
"keyword": null
}
]
}
}

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

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

0 Комментарии

Войдите в службу, чтобы оставить комментарий.