API docs by Redocly

Аналитика и данные (analytics)

Анализ данных по финансовым кампаниям, статистика по продвижению, воронки продаж

Аналитика и данные

Анализ данных по финансовым кампаниям, статистика по продвижению, воронки продаж

Статистика по продвижению

Для доступа к методам используйте токен для категории Продвижение

Статистика кампаний{{ /adv/v2/fullstats }}

Описание метода

Возвращает статистику кампаний. Данные вернутся для кампаний в статусах:

  • 7 — завершено
  • 9 — приостановлена продавцом
  • 11 — пауза по расходу бюджета
В запросе можно передавать либо параметр dates либо параметр interval, но не оба.
Можно отправить запрос только с ID кампании. При этом вернутся данные за последние сутки, но не за весь период существования кампании.
Максимум 1 запрос в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
One of
[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
id
integer

ID кампании

dates
Array of strings <date> [ items <date > ]

Даты, за которые необходимо выдать информацию.

Responses

Request samples

Content type
application/json
Example

Запрос с датами

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

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

[
  • {
    }
]

Статистика автоматической кампании по кластерам фраз{{ /adv/v2/auto/stat-words }}

Описание метода

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

Максимум 4 запроса в секунду на один аккаунт продавца
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

ID кампании

Responses

Response samples

Content type
application/json
{
  • "excluded": [
    ],
  • "clusters": [
    ]
}

Статистика поисковой кампании по ключевым фразам{{ /adv/v1/stat/words }}

Описание метода

Возвращает статистику поисковой кампании по ключевым фразам.

Информация обновляется каждые 30 минут

Максимум 4 запроса в секунду на один аккаунт продавца
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

ID кампании

Responses

Response samples

Content type
application/json
{
  • "words": {
    },
  • "stat": [
    ]
}

Статистика по ключевым фразам для Автоматических кампаний и Аукциона{{ /adv/v0/stats/keywords }}

Описание метода

Возвращает статистику по ключевым фразам за каждый день, когда кампания была активна.
Можно получить данные максимум за 7 дней в одном запросе.
Информация обновляется раз в час.

Максимум 4 запроса в секунду на один аккаунт продавца
Authorizations:
HeaderApiKey
query Parameters
advert_id
required
integer
Example: advert_id=123456789

ID кампании

from
required
string <date>
Example: from=2024-08-10

Начало периода

to
required
string <date>
Example: to=2024-08-12

Конец периода

Responses

Response samples

Content type
application/json
{
  • "keywords": [
    ]
}

Получение истории затрат{{ /adv/v1/upd }}

Описание метода

Возвращает историю затрат

Максимум 1 запрос в секунду на один аккаунт продавца
Authorizations:
HeaderApiKey
query Parameters
from
required
string <date>
Example: from=2023-07-31

Начало интервала

to
required
string <date>
Example: to=2023-08-02

Конец интервала.
(Минимальный интервал 1 день, максимальный 31)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Получение истории пополнений счёта{{ /adv/v1/payments }}

Описание метода

Возвращает историю пополнений счёта

Максимум 1 запрос в секунду на один аккаунт продавца
Authorizations:
HeaderApiKey
query Parameters
from
string <date>
Example: from=2023-07-31

Начало интервала

to
string <date>
Example: to=2023-08-02

Конец интервала.
(Минимальный интервал 1 день, максимальный 31)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Статистика медиакампаний{{ /adv/v1/stats }}

Описание метода

Возвращает статистику медиакампаний

Максимум 10 запросов в секунду на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
One of
[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
id
integer

ID кампании

dates
Array of strings <date> [ items <date > ]

Даты, за которые необходимо выдать информацию.

Responses

Request samples

Content type
application/json
Example

Запрос с датами

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

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

[
  • {
    }
]

Воронка продаж

Для доступа к методам используйте токен для категории Аналитика

Таймзоны

Формат IANA, актуальный список можно посмотреть здесь.

Получение статистики карточек товаров за выбранный период по nmID/предметам/брендам/тегам{{ /api/v2/nm-report/detail }}

Описание метода

Возвращает статистику карточек товаров за выбранный период по nmID/предметам/брендам/тегам. Поля brandNames,objectIDs, tagIDs, nmIDs могут быть пустыми, тогда в ответе возвращаются все карточки продавца. При выборе нескольких полей в ответ приходят данные по карточкам, у которых есть все выбранные поля. Можно получить отчёт максимум за последний год (365 дней).
В данных, где предоставляется информация о предыдущем периоде:

  • В previousPeriod данные за такой же период, что и в selectedPeriod.
  • Если дата начала previousPeriod раньше, чем год назад от текущей даты, она будет приведена к виду: previousPeriod.start = текущая дата - 365 дней.
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
brandNames
Array of strings

Название бренда

objectIDs
Array of integers <int32> [ items <int32 > ]

ID предмета

tagIDs
Array of integers <int32> [ items <int32 > ]

ID тега

nmIDs
Array of integers <int32> [ items <int32 > ]

Артикул WB

timezone
string

Временная зона.
Если не указано, то по умолчанию используется Europe/Moscow.

required
object

Период

object

Параметры сортировки. Если не указано, то по умолчанию используется значение "openCard" и сортировка по убыванию.

Все виды сортировки field:
openCard — по открытию карточки (переход на страницу товара)
addToCart — по добавлениям в корзину
orders — по кол-ву заказов
avgRubPrice — по средней цене в рублях
ordersSumRub — по сумме заказов в рублях
stockMpQty — по кол-ву остатков маркетплейса шт.
stockWbQty — по кол-ву остатков на складе шт.
cancelSumRub — сумме возвратов в рублях
cancelCount — по кол-ву возвратов
buyoutCount — по кол-ву выкупов
buyoutSumRub — по сумме выкупов
page
required
integer <int32>

Страница

Responses

Request samples

Content type
application/json
{
  • "brandNames": [
    ],
  • "objectIDs": [
    ],
  • "tagIDs": [
    ],
  • "nmIDs": [
    ],
  • "timezone": "Europe/Moscow",
  • "period": {
    },
  • "orderBy": {
    },
  • "page": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Получение статистики карточек товаров за период с группировкой по предметам, брендам и тегам{{ /api/v2/nm-report/grouped }}

Описание метода

Возвращает статистику карточек товаров за период с группировкой по предметам, брендам и тегам. Поля brandNames, objectIDs, tagIDs могут быть пустыми, тогда группировка происходит по всем карточкам продавца. Можно получить отчёт максимум за последний год (365 дней). В данных, где предоставляется информация о предыдущем периоде:

  • В previousPeriod данные за такой же период, что и в selectedPeriod.
  • Если дата начала previousPeriod раньше, чем год назад от текущей даты, она будет приведена к виду: previousPeriod.start = текущая дата - 365 дней.
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
objectIDs
Array of integers <int32> [ items <int32 > ]

ID предмета

brandNames
Array of strings

Название бренда

tagIDs
Array of integers <int32> [ items <int32 > ]

ID тега

timezone
string

Временная зона.
Если не указано, то по умолчанию используется Europe/Moscow.

required
object

Период

object

Параметры сортировки. Если не указано, то по умолчанию используется значение "openCard" и сортировка по убыванию.

Все виды сортировки field:
openCard — по открытию карточки (переход на страницу товара)
addToCart — по добавлениям в корзину
orders — по кол-ву заказов
avgRubPrice — по средней цене в рублях
ordersSumRub — по сумме заказов в рублях
stockMpQty — по кол-ву остатков маркетплейса шт.
stockWbQty — по кол-ву остатков на складе шт.
page
required
integer <int32>

Страница

Responses

Request samples

Content type
application/json
{
  • "objectIDs": [
    ],
  • "brandNames": [
    ],
  • "tagIDs": [
    ],
  • "timezone": "Europe/Moscow",
  • "period": {
    },
  • "orderBy": {
    },
  • "page": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Получение статистики карточки товара по дням по выбранным nmID{{ /api/v2/nm-report/detail/history }}

Описание метода

Возвращает статистику карточки товара по дням по выбранным nmID. Можно получить отчёт максимум за последнюю неделю. Чтобы получать отчёты за период до года, подпишитесь на расширенную аналитику Джем

Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
nmIDs
required
Array of integers <int32> [ items <int32 > ]

Артикул WB (максимум 20)

required
object

Период

timezone
string

Временная зона.
Если не указано, то по умолчанию используется Europe/Moscow.

aggregationLevel
string

Тип агрегации. Если не указано, то по умолчанию используется агрегация по дням.
Доступные уровни агрегации day, week

Responses

Request samples

Content type
application/json
{
  • "nmIDs": [
    ],
  • "period": {
    },
  • "timezone": "Europe/Moscow",
  • "aggregationLevel": "day"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Получение статистики карточки товара по дням за период с группировкой по предметам, брендам и тегам{{ /api/v2/nm-report/grouped/history }}

Описание метода

Возвращает статистику карточки товара по дням за период с группировкой по предметам, брендам и тегам. Поля brandNames, objectIDs, tagIDs могут быть пустыми, тогда группировка происходит по всем карточкам продавца. Произведение количества предметов, брендов, тегов в запросе не должно быть больше 16. Можно получить отчёт максимум за последнюю неделю. Чтобы получать отчёты за период до года, подпишитесь на расширенную аналитику Джем

Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
objectIDs
Array of integers <int32> [ items <int32 > ]

ID предмета

brandNames
Array of strings

Название бренда

tagIDs
Array of integers <int32> [ items <int32 > ]

ID тега

required
object

Период

timezone
string

Временная зона.
Если не указано, то по умолчанию используется Europe/Moscow.

aggregationLevel
string

Тип агрегации. Если не указано, то по умолчанию используется агрегация по дням.
Доступные уровни агрегации day, week

Responses

Request samples

Content type
application/json
{
  • "objectIDs": [
    ],
  • "brandNames": [
    ],
  • "tagIDs": [
    ],
  • "period": {
    },
  • "timezone": "Europe/Moscow",
  • "aggregationLevel": "day"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "error": true,
  • "errorText": "",
  • "additionalErrors": [
    ]
}

Воронка продаж (Джем)

Для доступа к методам используйте токен для категории Аналитика

Вы можете использовать эти методы только с подпиской Джем.

Чтобы получить отчёт:

  1. Сгенерируйте отчёт.
  2. Дождитесь, когда отчёт будет готов. Вы можете проверить статус готовности отчёта. Готовый отчёт хранится 48 часов, потом его нельзя будет получить.
    Если вы получили статус FAILED, сгенерируйте отчёт повторно
  3. Получите отчёт.

Можно получить отчёт максимум за год.

Максимальное количество отчётов, генерируемых в сутки — 20

Создать отчёт{{ /api/v2/nm-report/downloads }}

Описание метода

Создает отчёт с расширенной аналитикой.

Вы можете создать отчёт с группировкой:

  • по артикулам WB (nmID);
  • по категориям, брендам и тегам.

В каждом из этих отчётов можно сгруппировать данные по дням, неделям или месяцам

Максимум 3 запроса в минуту на один аккаунт продавца, при этом в сутки можно сгенерировать максимум 20 отчётов (считаются только успешные генерации)
Authorizations:
HeaderApiKey
Request Body schema: application/json
One of
id
required
string <uuid>

ID отчёта в UUID-формате. Генерируется продавцом самостоятельно

reportType
required
string

Тип отчёта — DETAIL_HISTORY_REPORT

userReportName
string

Название отчёта (если не указано, сформируется автоматически)

object

Параметры отчёта

Responses

Request samples

Content type
application/json
Example

По артикулам WB (nmID)

{
  • "id": "06eae887-9d9f-491f-b16a-bb1766fcb8d2",
  • "reportType": "DETAIL_HISTORY_REPORT",
  • "userReportName": "Card report",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "data": "Created"
}

Получить список отчётов{{ /api/v2/nm-report/downloads }}

Описание метода
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
query Parameters
filter[downloadIds]
Array of strings <uuid> [ items <uuid > ]

ID отчёта

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Сгенерировать отчёт повторно{{ /api/v2/nm-report/downloads/retry }}

Описание метода
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
downloadId
string <uuid>

ID отчёта

Responses

Request samples

Content type
application/json
{
  • "downloadId": "06eea887-9d9f-491f-b16a-bb1766fcb8d2"
}

Response samples

Content type
application/json
{
  • "data": "Retry"
}

Получить отчёт{{ /api/v2/nm-report/downloads/file/{downloadId} }}

Описание метода

Получить отчёт с расширенной аналитикой.

Можно получить отчёт, который сгенерирован за последние 48 часов.
Отчет будет загружен внутри архива ZIP в формате CSV

Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
path Parameters
downloadId
required
string <uuid>

ID отчёта

Responses

Response samples

Content type
text/csv
Example
nmID, dt, openCardCount, addToCartCount, ordersCount, ordersSumRub, buyoutsCount, buyoutsSumRub, cancelCount, cancelSumRub, addToCartConversion, cartToOrderConversion, buyoutPercent
70027655,2023-12-21,1,0,0,0,0,0,0,0,0,0,0
...
...
150317666,2023-12-21,2,0,0,0,0,0,0,0,0,0,0

Поисковые запросы

Для доступа к методам используйте токен для категории Аналитика

С помощью этих методов можно получать отчёт по поисковым запросам.

Вы можете использовать эти методы только с подпиской Джем

Основная страница{{ /api/v2/search-report/report }}

Описание метода

Формирует набор данных для основной страницы отчёта с:

  • общей информацией
  • позициями товаров
  • данными по видимости и переходам в карточку
  • данными для таблицы по группам

Для получения дополнительных данных в таблице используйте отдельный запрос для:

  • пагинации по группам
  • получения по товарам в группе

Дополнительные параметры выбора списка товаров в таблице:

  • positionCluster — средняя позиция в поиске
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Текущий период

object (pastPeriod)

Прошлый период для сравнения. Количество дней — меньше или равно currentPeriod

nmIds
Array of integers <int32> [ items <int32 > ]

Список артикулов WB для фильтрации

subjectIds
Array of integers <int32> [ items <int32 > ]

Список ID предметов для фильтрации

brandNames
Array of strings

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

tagIds
Array of integers <int64> [ items <int64 > ]

Список ID тегов для фильтрации

positionCluster
required
string (PositionCluster)
Enum: "all" "firstHundred" "secondHundred" "below"

Товары с какой средней позицией в поиске показывать в отчёте:

  • all — все
  • firstHundred — от 1 до 100
  • secondHundred — от 101 до 200
  • below — от 201 и ниже
required
object (OrderBy)

Параметры сортировки

limit
required
integer <uint32> <= 1000

Количество групп товаров в ответе

offset
required
integer <uint32>

После какого элемента выдавать данные

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "nmIds": [
    ],
  • "subjectIds": [
    ],
  • "brandNames": [
    ],
  • "tagIds": [
    ],
  • "positionCluster": "all",
  • "orderBy": {
    },
  • "limit": 130,
  • "offset": 50
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Пагинация по группам{{ /api/v2/search-report/table/groups }}

Описание метода

Пагинация по группам в отчёте. Возможна только при наличии фильтра по бренду, предмету или тегу.

Дополнительные параметры выбора списка товаров в таблице:

  • positionCluster — средняя позиция в поиске
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Текущий период

object (pastPeriod)

Прошлый период для сравнения. Количество дней — меньше или равно currentPeriod

nmIds
Array of integers <int32> [ items <int32 > ]

Список артикулов WB для фильтрации

subjectIds
Array of integers <int32> [ items <int32 > ]

Список ID предметов для фильтрации

brandNames
Array of strings

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

tagIds
Array of integers <int64> [ items <int64 > ]

Список ID тегов для фильтрации

required
object (OrderBy)

Параметры сортировки

positionCluster
required
string (PositionCluster)
Enum: "all" "firstHundred" "secondHundred" "below"

Товары с какой средней позицией в поиске показывать в отчёте:

  • all — все
  • firstHundred — от 1 до 100
  • secondHundred — от 101 до 200
  • below — от 201 и ниже
limit
required
integer <uint32> <= 1000

Количество групп товаров в ответе

offset
required
integer <uint32>

После какого элемента выдавать данные

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "nmIds": [
    ],
  • "subjectIds": [
    ],
  • "brandNames": [
    ],
  • "tagIds": [
    ],
  • "orderBy": {
    },
  • "positionCluster": "all",
  • "limit": 130,
  • "offset": 50
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Пагинация по товарам в группе{{ /api/v2/search-report/table/details }}

Описание метода

Пагинация по товарам в группе. Возможна независимо от наличия фильтров.

Фильтры для пагинации по товарам в группе или без фильтров:

  • кортеж subjectId,brandName,tagId — фильтр для группы
  • nmIds — фильтр по номенклатуре

Дополнительные параметры выбора списка товаров:

  • positionCluster — средняя позиция в поиске
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Текущий период

object (pastPeriod)

Прошлый период для сравнения. Количество дней — меньше или равно currentPeriod

subjectId
integer <int32>

ID предмета

brandName
string

Название товара

tagId
integer <int64>

ID тега

nmIds
Array of integers <uint64> <= 50 items [ items <uint64 > ]

Список артикулов WB

required
object (OrderBy)

Параметры сортировки

positionCluster
required
string
Enum: "all" "firstHundred" "secondHundred" "below"

Товары с какой средней позицией в поиске показывать в отчёте:

  • all — все
  • firstHundred — от 1 до 100
  • secondHundred — от 101 до 200
  • below — от 201 и ниже
limit
required
integer <uint32> <= 1000

Количество товаров в ответе

offset
required
integer <uint32>

После какого элемента выдавать данные

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "subjectId": 123,
  • "brandName": "Apple",
  • "tagId": 45,
  • "nmIds": [
    ],
  • "orderBy": {
    },
  • "positionCluster": "all",
  • "limit": 150,
  • "offset": 100
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Поисковые запросы по товару{{ /api/v2/search-report/product/search-texts }}

Описание метода

Формирует топ поисковых запросов по товару.

Параметр выбора поисковых запросов:

  • limit — количество запросов, максимум 30
  • topOrderBy — способ выбора топа запросов
Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (Period)

Текущий период

object (pastPeriod)

Прошлый период для сравнения. Количество дней — меньше или равно currentPeriod

nmIds
required
Array of integers <uint64> <= 50 items [ items <uint64 > ]

Список артикулов WB

topOrderBy
required
string
Enum: "openCard" "addToCart" "openToCart" "orders" "cartToOrder"

Сортировка по полю:

  • openCard — перешли в карточку из поиска
  • addToCart — добавили в корзину из поиска
  • openToCart — конверсия в корзину из поиска
  • orders — заказали товаров из поиска
  • cartToOrder — конверсия в заказ из поиска
required
object (OrderBy)

Параметры сортировки

limit
required
integer <uint64> (TextLimit) [ 1 .. 30 ]

Количество поисковых запросов по товару

Responses

Request samples

Content type
application/json
{
  • "currentPeriod": {
    },
  • "pastPeriod": {
    },
  • "nmIds": [
    ],
  • "topOrderBy": "openToCart",
  • "orderBy": {
    },
  • "limit": 20
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Заказы и позиции по поисковым запросам товара{{ /api/v2/search-report/product/orders }}

Описание метода

Формирует данные для таблицы по количеству заказов и позиций по запросам. Данные указываются в рамках периода для определённого товара

Максимум 3 запроса в минуту на один аккаунт продавца
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
object (PeriodOrdersRequest)

Текущий период. Максимум 7 суток

nmId
required
integer <uint64>

Артикул WB

searchTexts
required
Array of strings [ 1 .. 30 ] items

Поисковые запросы

Responses

Request samples

Content type
application/json
{
  • "period": {
    },
  • "nmId": 211131895,
  • "searchTexts": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}