Импорт расходов
Описание
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. |
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)