API для паблишеров

From Справочник сервиса Kadam.net
Jump to: navigation, search

API авторизация с помощью Bearer Token

Для авторизации в паблишерском API используется Bearer Token. В запрос добавляется заголовок "Authorization" со значением "Bearer X", где "X" — ваш персональный токен. Получить токен можно у вашего менеджера; в личном кабинете он доступен в разделе "Профиль и настройки" ("Reset Token" — для сброса). Срок действия токена не ограничен.

Базовый URL: 
https://pub.kadam.net/api

Swagger документация: https://pub.kadam.net/api-doc/#/ru
Через API доступны: Сайты (Sources), Блоки (Places), Конструктор отчётов (CustomReports), AdSpyGlass. Финансы, выплаты, кошельки, уведомления и рефералы — только через личный кабинет (session-based).
Терминология:

  • Source (сайт) — areaID, в API обозначается как webmaster_source
  • Place (блок / рекламное место) — blockID, в API обозначается как webmaster_block


Сайты (Sources)

Список сайтов

Для получения списка сайтов с краткой статистикой используется метод POST /sources/sources-table
Данные аналогичны странице https://pub.kadam.net/platforms

Параметры Значение Дополнительные атрибуты
page Номер страницы (от 1) int; опциональный (по умолчанию 1)
perPage Количество элементов на странице int; опциональный (по умолчанию 20)
sort Сортировка. Ключ — столбец, значение — "asc" / "desc" объект; опциональный
filters.dateFrom Начало периода, формат YYYY-MM-DD (по умолчанию сегодня − 7 дней) строка; опциональный
filters.dateTo Конец периода, формат YYYY-MM-DD (по умолчанию сегодня) строка; опциональный
filters.archive 0 — не в архиве, 1 — в архиве int; опциональный (по умолчанию 0)
filters.timezone Часовой пояс, от -12 до 12. Если не передан — берётся таймзона из настроек аккаунта int; опциональный
tableFilters Массив фильтров по столбцам. Каждый элемент: {"column": "...", "childField": "...", "value": "...", "compareType": 0..4, "include": [...], "exclude": [...]}. compareType: 0 — "=", 1 — ">", 2 — "<", 3 — ">=", 4 — "<=". массив объектов; опциональный

Пример запроса:

POST https://pub.kadam.net/api/sources/sources-table
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "page": 1,
    "perPage": 20,
    "sort": {"dateCreated": "desc"},
    "filters": {
        "dateFrom": "2026-03-01",
        "dateTo": "2026-03-31",
        "archive": 0,
    },
        "timezone": 0
    "tableFilters": []
}

Создание сайта

Для создания сайта (первый этап) используется метод PUT /sources

Параметры Значение Дополнительные атрибуты
name Название сайта строка; обязательный
url URL сайта строка; обязательный
state При создании всегда "oninit" строка; обязательный

Пример запроса:

PUT https://pub.kadam.net/api/sources
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "name": "My Site",
    "url": "https://example.com",
    "state": "oninit"
}

Получение информации о сайте

Для получения всех настроек сайта используется метод GET /sources/{id}
Параметр в пути: id — ID сайта (areaID), int. Пример запроса:

GET https://pub.kadam.net/api/sources/12345
Authorization: Bearer YOUR_TOKEN

Обновление сайта

Для добавления данных к сайту на следующих этапах создания используется метод PUT /sources/{id}
Параметр в пути: id — ID сайта, int.
Тело запроса — поля сайта, которые требуется обновить (набор зависит от этапа). Полную схему см. в Swagger: https://pub.kadam.net/api-doc/#/sources/put_sources__id_

Массовые действия над сайтом

Для изменения состояния сайта используются методы:

  • POST /sources/{id}/activate — активировать сайт
  • POST /sources/{id}/deactivate — приостановить сайт
  • POST /sources/archive/{id} — переместить в архив
  • POST /sources/un-archive/{id} — восстановить из архива

Параметр в пути: id — ID сайта, int. Тело запроса не требуется. Пример запроса:

POST https://pub.kadam.net/api/sources/12345/activate
Authorization: Bearer YOUR_TOKEN

Блоки (Places)

Список блоков сайта

Для получения списка блоков на сайте с краткой статистикой используется метод POST /places/places-table/{id}
Параметр в пути: id — ID сайта (areaID), int.
Данные аналогичны странице https://pub.kadam.net/platforms/{id} Тело запроса — такой же объект TableFilters, как в списке сайтов (page, perPage, sort, filters.dateFrom/dateTo/archive/timezone, tableFilters). Пример запроса:

POST https://pub.kadam.net/api/places/places-table/12345
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "page": 1,
    "perPage": 20,
    "filters": {
        "dateFrom": "2026-03-01",
        "dateTo": "2026-03-31",
        "archive": 0,
        "timezone": 0
    },
    "tableFilters": []
}

Список значений для фильтров таблицы блоков

Для получения списка возможных значений для include/exclude в фильтрах таблицы блоков используется метод POST /places/places-table/table-filters

Параметры Значение Дополнительные атрибуты
column Столбец, для которого запрашивается список строка; обязательный
field Поле фильтра в рамках столбца строка; опциональный

Массовые действия над блоком

Для изменения состояния блока используются методы:

  • POST /places/{id}/activate — активировать блок
  • POST /places/{id}/deactivate — приостановить блок
  • DELETE /places/{id} — переместить в архив
  • POST /places/{id}/restore — восстановить из архива

Параметр в пути: id — ID блока (blockID), int. Пример запроса:

POST https://pub.kadam.net/api/places/98765/activate
Authorization: Bearer YOUR_TOKEN

Пользователь (Users)

Информация о пользователе

Для получения обновлённой информации о пользователе (баланс, счётчик непрочитанных уведомлений) используется метод POST /users/check-upd

Параметры Значение Дополнительные атрибуты
notificationsLimit Максимальное количество получаемых непрочитанных уведомлений int; опциональный

Пример запроса:

POST https://pub.kadam.net/api/users/check-upd
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{"notificationsLimit": 10}

Конструктор отчётов (Custom Reports)

Список группировок, метрик и периодов

Для получения списка доступных группировок, метрик и преднастроенных периодов используется метод OPTIONS /custom-reports Пример запроса:

OPTIONS https://pub.kadam.net/api/custom-reports
Authorization: Bearer YOUR_TOKEN

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

Основной метод построения статистики — POST /custom-reports/data

Параметры Значение Дополнительные атрибуты
groups Массив группировок (см. список ниже) массив строк; обязательный
metrics Массив метрик (см. список ниже) массив строк; обязательный
filters.dateFrom / filters.dateTo Период, формат YYYY-MM-DD строка; обязательные (либо filters.period)
filters.period Преднастроенный период вместо dateFrom/dateTo: today, yesterday, 7days, 14days, month, prevMonth строка; опциональный
filters.timezone Часовой пояс, от -12 до 12 int; опциональный
filters.filters Массив фильтров по столбцам: [{"id": "webmaster_source", "type": "list", "include": [areaId1, areaId2]}, ...] массив объектов; опциональный
sort Сортировка: {"ключ_столбца": "asc"|"desc"} объект; опциональный
page / perPage Пагинация int; опциональные
compare Сравнение с другим периодом: {"dateFrom": "YYYY-MM-DD", "dateTo": "YYYY-MM-DD", "mode": "diff"|"percent"|"compare_value", "period": "...", "sort": false}. null — без сравнения объект; опциональный

Группировки (groups):

  • Время: time_hour, time_day, time_week, time_month
  • Трафик: traffic_region (страна/регион), traffic_browser, traffic_platform (ОС), traffic_platformVersion, traffic_device, traffic_deviceType (mobile/desktop/tablet), traffic_subsAge, traffic_pageCategory, traffic_blockFormat, traffic_blockSize
  • Трафик (только полная таблица, данные с задержкой): traffic_domain, traffic_macros (subID), traffic_pid
  • Паблишер: webmaster_source (areaID), webmaster_block (blockID), webmaster_subId

Метрики (metrics):

  • Трафик: traffic_visits (уникальные визиты), traffic_views (показы материалов), traffic_blockViews (показы блоков), traffic_clicks, traffic_viewRate (%), traffic_trafficback, traffic_subscriptions, traffic_unsubscriptions
  • Финансы: finance_moneyIn (доход, валюта аккаунта)
  • Паблишер: webmaster_cpm (CPM по показам материалов), webmaster_cpc, webmaster_blockCTR (%), webmaster_blockCPM (CPM по показам блоков)

Пример запроса — статистика по стране и SubID за вчера:

POST https://pub.kadam.net/api/custom-reports/data
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
    "groups": ["traffic_region", "webmaster_subId"],
    "metrics": ["traffic_views", "traffic_clicks", "finance_moneyIn"],
    "filters": {
        "filters": [
            {"id": "webmaster_source", "type": "list", "include": [12345]}
        ],
        "period": "yesterday",
        "timezone": 0
    },
    "sort": {"traffic_views": "desc"},
    "compare": null
}

Примечание: фильтр по блоку — {"id": "webmaster_block", "type": "list", "include": [blockId]}.
Вместо period можно указать "dateFrom": "2026-03-01", "dateTo": "2026-03-07".
Группировки traffic_domain, traffic_macros, traffic_pid доступны только из полной таблицы и появляются с задержкой.

Значения для фильтров статистики

Для получения списка возможных значений по конкретному фильтру используется метод POST /custom-reports/filter-data

Параметры Значение Дополнительные атрибуты
id Ключ столбца, для которого нужен список элементов (например, webmaster_source) строка; обязательный
searchQuery Строка поиска (для фильтров с filterSync = true) строка; опциональный

AdSpyGlass (ASG)

Список активных блоков

Для получения списка активных блоков, работающих с AdSpyGlass, используется метод GET /partners/asg/blocks

Параметры Значение Дополнительные атрибуты
token API токен (передаётся в query-параметре) строка; обязательный

Пример запроса:

GET https://pub.kadam.net/api/partners/asg/blocks?token=YOUR_TOKEN

Получение данных блока

Для получения данных конкретного рекламного блока используется метод GET /partners/asg/block

Параметры Значение Дополнительные атрибуты
token API токен строка; обязательный
zone_id ID блока int; обязательный

Пример запроса:

GET https://pub.kadam.net/api/partners/asg/block?token=YOUR_TOKEN&zone_id=98765

Общие правила

Общий формат ответа

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

При ошибке success = false, поле msg содержит описание ошибки.

Пагинация

Эндпоинты-списки принимают:

  • page — номер страницы, int (от 1, по умолчанию 1)
  • perPage — количество элементов на странице, int (по умолчанию 20)

Сортировка

Сортировка задаётся объектом {"ключ_столбца": "asc"|"desc"}. Допустимые ключи зависят от метода.

Фильтры таблиц (tableFilters / filters.filters)

В таблицах сайтов и блоков фильтры задаются массивом tableFilters:

  • column — столбец
  • childField — поле для multiselect-фильтра
  • value — искомый текст или число (compareType: 0="=", 1=">", 2="<", 3=">=", 4="<=")
  • include / exclude — массивы значений для включения/исключения

В конструкторе отчётов — массив filters.filters вида {"id": "ключ", "type": "list"|"range"|"value"|"value_like"|"value_combined", "include": [...], "exclude": [...], "range": {"from": "...", "to": "..."}}.

Что доступно по API

Через Bearer Token доступны: Сайты (CRUD, активация/архив), Блоки (активация/архив), Конструктор отчётов (статистика + фильтры), AdSpyGlass. Финансы, выплаты, кошельки, уведомления, рефералы — только через личный кабинет.

Retrieved from "https://wiki.kadam.net/index.php?title=API_для_паблишеров&oldid=8307"