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

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

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

 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"
}
]
}
   

Тип все параметров — строка (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"
}
]
}
}
}   

Запрос

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:

Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов. За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.