К основному содержимому

Миграция со старого API на новый

Автор: Olga

Эта инструкция для рекламодателей, чьи скрипты и интеграции вызывают старый API на api.kadam.net (параметры app_id и secret_key, подпись запросов, методы вида ads.campaigns.get). Здесь описано, как перенести интеграцию на новый API, чем заменить каждый старый метод и что в новом API не поддерживается.

Описание нового API: API Рекламодателей и Swagger.

Важно: 16 ноября 2026 года старый API будет отключён. После этой даты запросы к api.kadam.net перестанут работать.

Алгоритм переезда

API полностью переработано, обратной совместимости нет. Каждый вызов нужно перенести на новый API. В следующих разделах таблица с базовыми отличиями, а спецификация каждого метода (параметры, тела запросов, ответы) есть в документации нового API.

  1. Составьте список вызовов. Найдите в своём коде все обращения к api.kadam.net и выпишите методы (ads.campaigns.get, ads.materials.put и так далее).

  2. Найдите каждый метод в таблицах ниже. У каждого метода один из трёх статусов:

    • Прямая замена — для той же задачи есть эндпоинт нового API.

    • Альтернатива — той же операции нет, но цель достижима другим способом через API.

    • Не поддерживается в новом API — через новый API цель достичь нельзя.

  3. Получите токен. Откройте кабинет рекламодателя, раздел «Профиль и настройки», скопируйте токен. Храните его как пароль. Сбросить токен можно методом POST /api/users/token-reset.

  4. Замените авторизацию. Удалите вызов auth.token, расчёт signature и параметры app_id, client_id. Добавьте в каждый запрос заголовок Authorization: Bearer <токен>.

  5. Замените адреса и форматы методов. Переведите вызовы по таблицам.

  6. Замените идентификаторы из справочников. Типы кампаний, статусы, страны, регионы, браузеры берите из справочников нового API (GET /dictionaries/{type}, GET /campaigns/options). Не переносите числовые константы из старого кода.

  7. Переделайте разбор ответа. Данные теперь лежат в data, а признак ошибки — success: false и текст в msg.

  8. Сверьте результат с кабинетом. Сравните данные, которые вернул новый API, с кабинетом: списки кампаний и материалов, статистику, баланс.

  9. Запустите интеграцию. Уберите из кода остатки вызовов старого API и включите задачи, которые вы останавливали.

Пример авторизации.

Было:

GET https://api.kadam.net/auth.token?app_id=12345&secret_key=SECRET

GET https://api.kadam.net/ads.campaigns.get?app_id=12345&client_id=12345&limit=50&offset=0&signature=<md5 подписи>

Стало:

POST https://partners.kadam.net/api/v1/campaigns
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"page": 1, "perPage": 50, "sort": {"dateCreation": "desc"}}

Базовые отличия нового API от старого

Старый API

Новый API

Адрес

https://api.kadam.net/<метод>

https://partners.kadam.net/api/v1/<путь>

Ключи

app_id и secret_key

Один Bearer-токен

Получение токена

Запрос auth.token(app_id, secret_key), токен живёт 7 дней

Токен берётся в кабинете, раздел «Профиль и настройки», срок действия не ограничен

Авторизация запроса

Параметр signature, подпись считается для каждого запроса

Заголовок Authorization: Bearer <токен>, подписи нет

Формат вызова

Метод в имени ресурса (ads.campaigns.get) и HTTP-метод

REST: путь и HTTP-метод (POST /campaigns)

Клиент

client_id в каждом вызове

Не нужен: токен привязан к вашему аккаунту

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

{"response": {...}}, при пустом результате HTTP 204

{"success": true, "code": 0, "data": {...}}

Ошибка

{"error": {"code": ..., "msg": ...}}

{"success": false, "code": ..., "msg": ...}

Пагинация

limit и offset

page и perPage

Сортировка

Строка в параметре sort

Объект {"поле": "asc" или "desc"}

Даты и часовой пояс

date_from, date_to, timezone в виде +00:00

dateFrom, dateTo в filters, timezone целым числом от -12 до 12

Соответствие методов

В колонке «Новый API» указаны путь и HTTP-метод. Параметры и схемы тел запросов смотрите в Swagger.

Аккаунт и финансы

Старый метод

Статус

Новый API

Замечания

ads.account.get (баланс аккаунта)

Прямая замена

GET /me, GET /finances/balance

GET /me возвращает ID, баланс, валюту, дату регистрации и часовой пояс. Для проверки одного баланса используйте GET /finances/balance.

data.balance.systems.get (платёжные системы)

Прямая замена

GET /finances/payment-systems

Список зависит от вашего аккаунта: валюты, комиссии и минимальные суммы уже посчитаны для вас.

data.balance.report.operations.get, data.balance.report.types.get, data.balance.report.states.get (справочники отчёта по операциям)

Альтернатива

POST /finances/operations

Отдельных справочников нет. Тип операции задаётся в filters.type (1 показы, 2 пополнение, 3 пополнение администратором, 4 списание, 5 списание администратором). Статус операции приходит в каждой строке ответа в поле status.

Кампании

Старый метод

Статус

Новый API

Замечания

ads.campaigns.get (список)

Прямая замена

POST /campaigns

Фильтры в filters: searchQuery, dateFrom, dateTo, timezone, folderId, campaignId, types, statuses, paymentModels, countries, archive. Архивные кампании: filters.archive = 1.

ads.campaigns.get (одна кампания)

Прямая замена

GET /campaigns/{id}

Ответ в том же формате, который принимает PUT /campaigns/{id}/update.

ads.campaigns.put (создание)

Прямая замена

POST /campaigns/create

Тело зависит от типа кампании: Native, Banner, Push, Popunder, In-Page Push. Заранее проверить тело без создания можно методом POST /campaigns/validate.

ads.campaigns.update (изменение)

Прямая замена

PUT /campaigns/{id}/update

Частичного обновления нет: пропущенное поле сбрасывается в значение по умолчанию. Получите кампанию через GET /campaigns/{id}, измените нужное и отправьте объект целиком.

ads.campaigns.delete

Прямая замена

POST /campaigns/archive, DELETE /campaigns

Старый метод переносил кампанию в архив. В новом API архивирование делает POST /campaigns/archive, а DELETE /campaigns удаляет кампании с материалами насовсем и принимает только архивные.

ads.campaigns.status.get (статусы по ID)

Прямая замена

POST /campaigns

Статус каждой кампании приходит в списке. Для одной кампании используйте filters.campaignId или GET /campaigns/{id}.

ads.campaigns.block.update (блокировка и разблокировка)

Альтернатива

POST /campaigns/pause, POST /campaigns/activate

Это пауза и запуск, а не техническая блокировка со старым статусом.

ads.campaigns.bwlist.put (чёрный и белый списки площадок)

Прямая замена

POST /stats/sites/block, POST /stats/sites/unblock, PUT /campaigns/{id}/update

Чёрный список: POST /stats/sites/block добавляет площадки в чёрный список сразу в нескольких кампаниях, POST /stats/sites/unblock убирает. Остальные поля кампании передавать не нужно. Белый список или полная замена списка: поле sites в PUT /campaigns/{id}/update, формат {"mode": ..., "list": [ID площадок]}, отправляется вместе с остальными полями кампании.

ads.campaigns.cpa.mode.get (URL постбэка Kadam)

Не поддерживается в новом API

—

URL постбэка берётся из документации или из интерфейса редактирования кампании.

ads.campaigns.statblock.get, ads.campaigns.statblock2.get

Альтернатива

POST /stats/sites

В старом API эти методы уже отключены. Статистика по площадкам: POST /stats/sites.

ads.campaigns.statblock.put, ads.campaigns.statblock2.put (множитель ставки по площадке)

Альтернатива

PUT /stats/sites/bids

Ставка для площадок: число, x1.5 для множителя, 0 чтобы убрать. Идентификаторы площадок берутся из поля macrosId ответа POST /stats/sites.

ads.campaigns.categories.get, ads.campaigns.categories.desc.get

Прямая замена

GET /dictionaries/categories

ads.campaigns.formats.get

Прямая замена

GET /dictionaries/campaign-types

Типы: 10 Native, 20 Banner, 30 Push, 40 Popunder, 100 In-Page Push.

ads.campaigns.cp.types.get (модели оплаты)

Прямая замена

GET /campaigns/options, поле cpTypes

ads.campaigns.tags.get, ads.tags.get (теги кампаний и материалов с ценой за тег)

Не поддерживается в новом API

—

В новом API нет ни тегов, ни цены за тег.

Ставки кампании меняются отдельными методами: PUT /campaigns/{id}/bid для одной кампании и PUT /campaigns/bids для нескольких.

Материалы

Старый метод

Статус

Новый API

Замечания

ads.materials.get (список)

Прямая замена

POST /materials

Фильтры: searchQuery, dateFrom, dateTo, timezone, campaignId, types, statuses, archive.

ads.materials.get (один материал)

Прямая замена

GET /materials/{id}

ads.materials.put (создание)

Прямая замена

POST /campaigns/{id}/materials

Файл изображения передаётся прямо в запросе (multipart/form-data). Лимиты размера зависят от формата, например 512 КБ для Native и Push, 153,6 КБ для Banner.

ads.materials.update (изменение)

Прямая замена

PUT /campaigns/{id}/materials

ads.materials.delete

Прямая замена

POST /materials/archive, DELETE /materials

Сначала материал нужно отправить в архив, потом его можно удалить.

ads.materials.banner.sizes.get

Прямая замена

GET /materials/options, поле sizes

data.upload.media.update (предварительная загрузка файла)

Альтернатива

POST /campaigns/{id}/materials, POST /materials/bulk/upload

Отдельной загрузки файла нет: файл идёт в запросе на создание материала. Для пачки изображений есть двухшаговая массовая загрузка: POST /materials/bulk/upload, затем POST /materials/bulk, состояние задачи в GET /materials/bulk/{jobId}.

ads.materials.partners.get

Не поддерживается в новом API

—

Для массовых действий над материалами есть методы POST /materials/activate, /materials/pause, /materials/archive, /materials/restore, /materials/copy, /materials/move. Они принимают список в поле adsIds.

Аудитории

Старый метод

Статус

Новый API

Замечания

ads.audience.get

Прямая замена

POST /audiences, GET /audiences/{audiencesId}

ads.audience.put

Прямая замена

POST /audiences/create

Типы аудиторий: audience, audience_code, s2s. Заранее проверить тело можно методом POST /audiences/validate.

ads.audience.update

Прямая замена

PUT /audiences/{id}

ads.audience.delete

Прямая замена

DELETE /audiences/{id}

Статистика

Старый метод

Статус

Новый API

Замечания

ads.stats.campaign.get (статистика кампаний по датам, кампаниям, регионам)

Прямая замена

POST /custom-reports/data

Группировки и метрики выбираются в теле запроса. Список доступных группировок и метрик возвращает запрос OPTIONS /custom-reports. Сохранённые отчёты возвращает POST /custom-reports.

ads.stats.creative.get (статистика материалов)

Прямая замена

POST /custom-reports/data

То же.

ads.stats.campaign.placement.get, ads.stats.campaign.placement.put

Прямая замена

POST /stats/sites, PUT /stats/sites/bids

ads.analytic.areas.get (аналитика по площадкам)

Альтернатива

POST /stats/sites

ads.analytic.campaign.get, ads.analytic.material.get, ads.analytic.materials.get, ads.analytic.materials2.get

Альтернатива

POST /custom-reports/data

В старом API эти методы уже отключены.

ads.analytic.clicks.get (клики)

Альтернатива

POST /custom-reports/data, POST /stats/conversions

Сырых кликов нет. Агрегированные клики есть в отчётах, сырые конверсии отдаёт POST /stats/conversions.

Справочники

Старый метод

Статус

Новый API

Замечания

ads.targeting.browsers.get

Прямая замена

GET /dictionaries/browsers

ads.targeting.platforms.get

Прямая замена

GET /dictionaries/platforms

ads.targeting.devices.get

Прямая замена

GET /dictionaries/devices

ads.targeting.countries.get, data.geo.countries.get

Прямая замена

GET /dictionaries/countries

ads.targeting.regions.get, data.geo.regions.get

Прямая замена

GET /dictionaries/regions

Страна передаётся параметром countryId.

ads.targeting.cities.get

Прямая замена

GET /dictionaries/cities

ads.targeting.ages.get

Прямая замена

GET /campaigns/options, поля ages и subAges

ads.targeting.langs.get

Прямая замена

GET /campaigns/options, поле languages

ads.targeting.cpa.modes.get

Альтернатива

GET /dictionaries/conversion-templates

Старый метод возвращал список режимов CPA. В новом API режим не выбирается отдельно: статусы постбэка задаются полями conversion и postConversion в кампании, а готовые шаблоны статусов берутся из этого справочника.

Все справочники GET /dictionaries/{type} принимают параметры search, page и perPage (до 500).

Не поддерживается в новом API

Для первого метода ниже есть другой способ получить ту же информацию. Остальные относятся к функциональности, которой в Kadam уже давно нет, — переносить их не нужно.

  • ads.campaigns.cpa.mode.get: URL постбэка берётся из документации или из интерфейса редактирования кампании. Если нужно что-то ещё, напишите своему менеджеру или в поддержку.

  • ads.campaigns.tags.get, ads.tags.get — теги кампаний и материалов с ценой за тег, в Kadam этого давно нет.

  • ads.materials.partners.get — в Kadam этого давно нет.

  • ads.offers.* и ads.offers.landings.* — офферы и лендинги как отдельные сущности, в Kadam этого давно нет. Ссылка перехода задаётся в самой кампании или материале.

  • server.time.get, about.methods.get, about.version.get — служебные методы, не связанные с бизнес-функциональностью.

  • ads.clients.* — управление балансом и клиентами агентских аккаунтов, в Kadam этого давно нет.

Что учесть при переносе

  • Обновление кампании только целиком. PUT /campaigns/{id}/update заменяет кампанию полностью. Пропущенное поле вернётся к значению по умолчанию, например пропущенный dayMoneyLimit снимет дневной лимит. Всегда сначала получайте кампанию через GET /campaigns/{id}.

  • Справочники вместо констант. Идентификаторы статусов, типов и стран берите из справочников нового API.

  • Часовой пояс. Параметр timezone в новом API целое число от -12 до 12, а не строка +00:00.

  • Названия полей. Массовые методы принимают списки в полях campaignIds и adsIds, а не в ids.

  • Пустой результат. Старый API отвечал HTTP 204. В новом API для списков ожидайте success: true и пустой набор строк в data, а не отдельный код ответа.

  • Файлы материалов отправляются в самом запросе создания или изменения материала.

Ошибки

Старый код

Смысл

Ближайший случай в новом API

0

Неизвестная ошибка

success: false и описание в msg

1

Метод не найден

Не применимо: используйте пути из этой инструкции. Если объект (кампания, материал) не найден, API отвечает HTTP 404

2, 7, 9

Не указаны параметры, неверные данные, устаревшие макросы

HTTP 422, поля с ошибками перечислены в msg

3, 8

Клиент или ключ не найден, неверный токен

HTTP 401

4, 5

Токен истёк, неверная подпись

Не применимо: токен бессрочный, подписи нет

6

Доступ запрещён

HTTP 403

10

Слишком много запросов

HTTP 429

Соответствие приблизительное: ориентируйтесь на success и msg. Новый API при ошибке возвращает {"success": false, "code": 400, "msg": {"поле": ["описание ошибки"]}}.

Что нового вам даёт новый API

  • Автоправила для управления ставками в CPC-кампаниях (/autorules, /campaigns/{campaignId}/autorules).

  • Прогноз трафика по ставке до запуска кампании или повышения ставки (POST /campaigns/forecast).

  • Проверка кампании или аудитории без создания (POST /campaigns/validate, POST /audiences/validate).

  • Оптимизация ставок по срезам статистики (/stats/extended).

  • Массовые ставки и блокировка площадок, ставки материалов по странам (PUT /stats/sites/bids, POST /stats/sites/block, PUT /materials/bids).

  • Массовая загрузка материалов из изображений и ZIP-архивов (/materials/bulk/upload, /materials/bulk).

  • Копирование кампаний и материалов, папки кампаний с массовыми действиями (POST /campaigns/{id}/copy, /materials/copy, /campaigns/folders).

  • Дневной лимит расходов аккаунта, Easy Start, импорт креативов из RSS, конструктор отчётов (/finances/day-money-limit, PUT /campaigns/{id}/easy-start, PUT /campaigns/{id}/rss, /custom-reports).

Другие статьи по теме
Нашли ответ на свой вопрос?