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

Читать 7

Описание

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


Система баллов API Calltouch

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

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).

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 – порядок и вложенность друг в друга не важны, важна лишь комбинация. При несовпадении указанного набора при обновлении с существующими, запрос на обновление приравнивается к запросу на импорт новых данных, и переданный при обновлении расход суммируется с существующими значениями, а вместо неуказанных параметров будет использовано значение <не заполнено>.

Импортированные с помощью метода 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"
}
]
}

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

Параметр Формат Обязательный Описание
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

Не нашли решение проблемы?
Заполните форму, и мы вам поможем.