API отчётов Sber Ads: авторизация, запрос отчёта, список метрик и группировок
API отчётов Sber Ads работает через cookie с JWT-токенами. Сначала POST на `https://ads.sber.ru/gateway/login` выдаёт `access_token` и `refresh_token`, затем GET на `https://ads.sber.ru/gateway/an/api/stats/v1.0/agency` с токенами в Cookie возвращает данные. Обязательны параметры `metrics` и `start_date` (YYYY-MM-DD), `end_date` по умолчанию сегодня. Доступно 9 группировок и 15 показателей.
Цифры
Адреса и методы
| Что делает | Метод и адрес |
|---|---|
| Получение токена | POST `https://ads.sber.ru/gateway/login` |
| Обновление токена | GET `https://ads.sber.ru/gateway/refresh` |
| Данные по agency | GET `https://ads.sber.ru/gateway/an/api/stats/v1.0/agency` |
Параметры запроса отчёта
| Параметр | Тип | Кратность | Что это |
|---|---|---|---|
| dimensions | массив строк | 0..n | группировки, например adv_account_id, dt |
| metrics | массив строк | 1..n | показатели, например clicks, impressions |
| start_date | строка | 1..1 | дата начала включительно, YYYY-MM-DD |
| end_date | строка | 0..1 | дата окончания включительно, YYYY-MM-DD; по умолчанию today |
| where | строка | 0..1 | условия отбора, пример `gender==male` |
Группировки (dimensions)
| id | Тип | Описание |
|---|---|---|
| dt | STRING | Дата в формате YYYY-MM-DD |
| adv_account_id | INTEGER | ID аккаунта |
| adv_account_name | STRING | Название аккаунта |
| campaign | INTEGER | ID кампании |
| campaign_name | STRING | Название кампании |
| ad_group | INTEGER | ID группы объявлений |
| ad_group_name | STRING | Название группы |
| ad | INTEGER | ID объявления |
| ad_name | STRING | Название объявления |
Показатели (metrics)
| id | Тип | Описание |
|---|---|---|
| impressions | INTEGER | количество видимых показов |
| clicks | INTEGER | количество кликов |
| uniq_clicks | INTEGER | клики уникальные |
| uniq_imps | INTEGER | охват (показы уникальные) |
| wins | PERCENT | частота; отношение показов к уникальным показам, % |
| ctr | PERCENT | CTR, отношение кликов к показам, % |
| ssp_cost | CURRENCY | расход |
| ssp_cost_per_mille | CURRENCY | CPM (в справке: стоимость показа) |
| ssp_cost_per_click | CURRENCY | CPC (стоимость клика) |
| legits | INTEGER | вовлечённые сессии |
| CPES | CURRENCY | стоимость вовлечённой сессии |
| cpa | CURRENCY | стоимость конверсии |
| conversions | INTEGER | конверсии |
| sitelink_1_clicks | INTEGER | количество кликов по быстрой ссылке 1 |
| sitelink_2_clicks | INTEGER | в справке то же описание, что у sitelink_1_clicks: «по быстрой ссылке 1» |
Cookie после входа
| Параметр | Значение |
|---|---|
| Cookie | access_token и refresh_token |
| Domain | ads.sber.ru |
| Path | / |
| HttpOnly | true |
| Secure | true |
| Max-Age в примере ответа | 31536000 секунд |
| Expires в примере таблицы | Fri, 19 Dec 2025 12:55:42 GMT |
Коды ошибок
| HTTP | code | Где описан | Причина |
|---|---|---|---|
| 400 | InvalidParameter | авторизация и отчёты | неверный формат параметра: недопустимые символы, превышена длина, неверный тип данных |
| 401 | Unauthorized | отчёты | ошибка авторизации |
| 403 | AccessFunctionalityForbidden | авторизация | у пользователя нет прав на выполнение запроса |
| 403 | Forbidden | отчёты | у пользователя нет прав на выполнение запроса |
| 500 | InternalServerError | авторизация и отчёты | любая другая внутренняя ошибка сервера |
Подробности
Порядок работы
1. Получить токены: POST на `https://ads.sber.ru/gateway/login` с заголовком Content-Type: application/json и телом JSON с полями `username` и `password`. В ответе сервер ставит cookie `access_token` и `refresh_token`. 2. Запросить отчёт: GET на `https://ads.sber.ru/gateway/an/api/stats/v1.0/agency` с параметрами в строке запроса. Оба токена передают в заголовке Cookie: `access_token=…; refresh_token=…`. 3. Когда срок токена истёк, обновить его: GET на `https://ads.sber.ru/gateway/refresh` с заголовками Content-Type и Accept: application/json и Cookie с обоими токенами. Ответ, как и при входе, содержит заголовки set-cookie.
Пример запроса отчёта
В справке показан запрос с группировкой по дате и показателем кликов за два дня: параметры `dimensions=dt`, `metrics=clicks`, `start_date=2024-11-01`, `end_date=2024-11-02`.
Параметр where
Условия пишут в виде `поле==значение`. Несколько значений одного поля разделяют запятой, несколько условий — точкой с запятой. Пример из справки: `gender==male; adv_account_id==1564,1444`.
Типы значений в ответе
И группировки, и показатели возвращаются в теле ответа в исходном виде: числа числами, текст и даты строками. В таблице справки колонка column_type отделяет группировки (DIMENSION) от показателей (METRIC), а колонка date_type (так в справке) даёт тип значения: STRING, INTEGER, PERCENT, CURRENCY.
Формат ошибки
Тело ошибки содержит поля `requestId` (строка uuid, необязательное), `status` (число, HTTP-код), `code` (строка) и `description` (текстовое описание). Для 400 в примере отчётов: код InvalidParameter и описание «Параметр start_date не соответствует формату». Для 403 при входе описание в примере: «invalid grant: 401 Unauthorized: invalid_grant: Invalid user credentials». Для 500: «Произошла внутренняя ошибка сервера. Попробуйте повторить запрос позже.»
Важно знать
- Сценарий «Обновление токена» описан как «отправляющая сторона формирует и отправляет POST запрос», но в графе «Метод» и в примере стоит GET `/refresh`. Два указания расходятся; какой метод верный, справка не уточняет, проверять запросом.
- Параметр `where`: в одном предложении справка сначала называет запятую разделителем нескольких условий, а потом точку с запятой между условиями и запятую внутри одного поля. Пример подтверждает второй вариант.
- В примере `where` стоит `gender==male`, но в таблице группировок поля gender нет. Какие поля допустимы в `where`, справка не говорит.
- Токены передают в cookie, а текст ошибки 401 в примере говорит о некорректном HTTP-заголовке Authorization. Откуда берётся такая причина, справка не поясняет.
- При неверных учётных данных на входе пример показывает код 403 с текстом «Invalid user credentials», а не 401.
- Срок жизни токена отдельно не назван. В примере таблицы cookie срок — 19 декабря 2025 года, в примере ответа Max-Age равен 31536000 секунд (365 дней).
- Для sitelink_2_clicks описание повторяет sitelink_1_clicks («по быстрой ссылке 1»). Для ssp_cost_per_mille название CPM, а описание «стоимость показа»: за тысячу показов или за один, не сказано.
- Не названы: чьи именно логин и пароль подставлять в `username` и `password` (в примере почта), доступен ли метод `/agency` только агентским аккаунтам, валюта и НДС в полях CURRENCY, пример тела успешного ответа, лимиты запросов, максимальный период и размер выгрузки, способ передачи массивов в `dimensions` и `metrics` при нескольких значениях (в примере по одному).