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

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

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

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

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

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

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

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

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

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

Метод: 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: