openapi: 3.0.0
info:
contact:
email: supportautoload@avito.ru
description: 'API для взаимодействия с иерархией аккаунтов в Авито
**Авито API для бизнеса предоставляется согласно [Условиям использования](https://www.avito.ru/legal/pro_tools/public-api).**
'
title: Иерархия Аккаунтов Access statistics API
version: '1'
servers:
- url: https://api.avito.ru/
tags:
- description: 'С помощью API данного раздела вы можете получать статистику по объявлениям и расходам клиентов.
### Типы авторизации
Для использования данного API запрос должен быть авторизован.
API Авито Promo использует следующие механизмы авторизации:
<!-- ReDoc-Inject: <security-definitions> -->
'
name: statistics
x-displayName: Статистика клиентов
paths:
/stats/v2/accounts/{user_id}/items:
post:
description: "Данный метод позволяет получить различные статистические показатели объявлений клиента.\n\n### Доступ к данным клиента\n\nДля того, чтобы получить данные статистики конкретного клиента,\n необходимо указать идентификатор аккаунта клиента в качестве значения параметра URL `user_id`,\n а также значения заголовка `X-AgencyClientId`! \n\n### Параметры тела запроса\n\n- `dateFrom` — дата в формате `YYYY-MM-DD`, с которой требуется получить статистику.\n- `dateTo` — дата в формате `YYYY-MM-DD`, по которую требуется получить статистику (включительно).\n- `grouping` — группировка показателей.\n- `metrics` — набор необходимых показателей.\n\nДобавьте ограничения `filter`, если нужно отфильтровать данные статистики:\n\n- `categoryIDs` — по категориям (идентификаторы). См. доступные значения в\n [Справочнике идентификаторов категорий](https://www.avito.st/s/openapi/catalog-categories.xml);\n- `employeeIDs` — по сотрудникам (идентификаторы).\n См. метод [Получение списка сотрудников иерархии](#operation/getEmployeesV1).\n\nДобавьте следующие опции, если нужно настроить пагинацию:\n\n- `limit` — ограничивает количество сущностей статистики в ответе (максимум 1000).\n- `offset` — выполняет смещение, с которого начинается выборка данных статистики.\n- `sort` — сортировка данных статистики. Задается массивом настроек: \n `key` — показатель, `order` — порядок сортировки: `asc` — в порядке возрастания, `desc` — убывания.\n\n#### Группировка показателей\n\n- `day` — группировка по дням.\n- `week` — группировка по неделям.\n- `month` — группировка по месяцам.\n- `totals` — группировка по общему значению показателя за определённый период, без детализации.\n\n#### Показатель\n\nОсновные показатели:\n\n- `views` — просмотры. Сколько раз объявление показывалось в результатах поиска и рекомендациях.\n Несколько показов за сутки одному пользователю считаются как один.\n- `contacts` — контакты. Количество пользователей, которые посмотрели ваш номер, \n написали в чат или откликнулись на скидку после рассылки.\n Несколько контактов за сутки от одного пользователя считаются как один.\n- `contactsShowPhone` — посмотрели телефон. Количество пользователей,\n которые посмотрели ваш телефон или нажали «Позвонить».\n Несколько таких действий за сутки от одного пользователя считаются как один.\n- `contactsMessenger` — написали в чат. Количество пользователей, которые написали вам.\n Несколько чатов за сутки от одного пользователя считаются как один.\n- `contactsShowPhoneAndMessenger` — посмотрели телефон и написали в чат.\n Количество пользователей, которые и посмотрели ваш телефон, и написали в чат.\n Несколько таких действий за сутки от одного пользователя считаются как один.\n- `contactsSbcDiscount` — откликнулись на скидку в чате.\n Количество пользователей, которые приняли ваше спецпредложение после рассылки.\n- `viewsToContactsConversion` — конверсия из просмотров в контакты.\n Процент пользователей, которые после перехода в объявление посмотрели ваш телефон или написали в чат.\n- `favorites` — добавили в избранное. Сколько раз объявление добавили в избранное.\n- `averageViewCost` — средняя цена просмотра.\n Расходы на размещение и продвижение объявлений делятся на число просмотров.\n- `averageContactCost` — средняя цена контакта.\n Расходы на размещение и продвижение объявлений делятся на число контактов.\n- `impressions` — показы. Сколько раз объявление показывалось в результатах поиска и рекомендациях.\n Несколько показов за сутки одному пользователю считаются как один.\n- `impressionsToViewsConversion` — конверсия из показов в просмотры. Процент пользователей,\n которые перешли в объявление после того, как оно показалось в результатах поиска и рекомендациях.\n\nЦелевые действия:\n\n- `clickPackages` — целевые просмотры. Просмотры,\n которые оплачены из тарифа и считаются целевыми по правилам Авито.\n- `jobContacts` — отклики на вакансии. Отклики,\n которые оплачены из тарифа и считаются целевыми по правилам Авито.\n\nЗаказы товаров с Авито Доставкой:\n\n- `viewsToOrderedItemsConversion` — конверсия из просмотров в заказанные товары.\n Процент пользователей, которые после перехода в объявление заказали товар.\n- `orderedItems` — заказано товаров. Количество товаров, которые заказали с Авито Доставкой.\n- `orderedItemsPrice` — стоимость заказанных товаров в копейках. Общая стоимость заказов.\n Это сумма, которую вы получите на руки, если клиенты примут заказы.\n- `deliveredItems` — доставлено товаров. Количество товаров, которые заказали с Авито Доставкой и уже приняли.\n- `deliveredItemsPrice` — стоимость доставленных товаров в копейках.\n Общая стоимость заказов, которые покупатели приняли. Это сумма, которую вы получаете на руки.\n\nПосуточная аренда недвижимости:\n\n- `bookingPlacedCount` — получено заявок. Общее количество заявок на бронирование.\n- `bookingPlacedPrice` — стоимость полученных заявок в копейках. Общая стоимость бронирований.\n Это сумма, которую вы получите на руки, если гости заселятся.\n- `bookingApprovedCount` — подтверждено заявок. Количество заявок на бронирование, которые вы подтвердили.\n- `bookingApprovedPrice` — стоимость подтвержденных заявок в копейках.\n Общая стоимость бронирований, которые вы подтвердили.\n Это сумма, которую вы получите на руки, если гости заселятся.\n- `bookingAcceptedCount` — заявки с заселением. Количество бронирований, по которым заселились гости.\n Заселение засчитывается в 15:00 по Москве на следующий день после заезда.\n- `bookingAcceptedPrice` — стоимость заявок с заселением в копейках.\n Общая стоимость бронирований, по которым заселились гости. Это сумма, которую вы получаете на руки.\n\nРасходы:\n\n- `allSpending` — все расходы в копейках. Сколько всего денег и бонусов вы потратили на объявления.\n- `spending` — расходы на объявления в копейках.\n Сколько денег вы потратили на размещение, продвижение, целевые действия и комиссию.\n- `presenceSpending` — расходы на размещение и целевые действия в копейках.\n Сколько денег вы потратили на размещения и целевые действия — просмотры, чаты, звонки и отклики.\n- `promoSpending` — расходы на продвижение в копейках.\n Сколько денег вы потратили на продвижение и на услуги, которые влияют на внешний вид объявления.\n- `restSpending` — остальные расходы в копейках.\n Сколько денег вы потратили на чат-ботов и услуги, которые система не смогла распознать.\n- `commission` — комиссия в копейках. Какую комиссию вы заплатили за заказы с Авито Доставкой,\n которые приняли покупатели, а также за бронирования жилья.\n- `spendingBonus` — списано бонусов на объявления.\n Сколько бонусов вы потратили на размещение, продвижение, целевые действия и комиссию.\n\nКоличество объявлений за период:\n\n- `activeItems` — активные объявления. Объявления, которые прошли проверку и появились в поиске.\n- `newActiveItems` — новые и опубликованные заново объявления.\n Сколько объявлений опубликовано впервые или повторно.\n- `oldActiveItems` — активны с прошлого периода.\n Сколько объявлений остаются опубликованными с предыдущего периода.\n\n### Успешный ответ\n\nМетод возвращает назад список данных группировок статистики `result.groupings`\n и общее количество сущностей `result.dataTotalCount`.\n\n#### Данные группировки\n\n- `id` — идентификатор объявления или временная метка (зависит от типа группировки).\n- `type` — группировка показателей.\n- `metrics` — список данных статистических показателей.\n Представлен массивом объектов: `slug` — показатель, `value` — значение показателя.\n\n### Примечания\n\n- Метод имеет ограничение до 100 запросов в минуту.\n- Глубина данных статистики ограничена 270 днями.\n- Показатель не возвращается, если он не доступен для клиента.\n"
operationId: statsAccountsItems
parameters:
- $ref: '#/components/parameters/userIdPathParameter'
- $ref: '#/components/parameters/authHeader'
- $ref: '#/components/parameters/agencyClientIdHeader'
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
dateFrom:
$ref: '#/components/schemas/date'
dateTo:
$ref: '#/components/schemas/date'
filter:
additionalProperties: false
description: Набор ограничений, по которым будут отфильтрованы данные статистики
properties:
categoryIDs:
$ref: '#/components/schemas/ids'
employeeIDs:
$ref: '#/components/schemas/ids'
type: object
grouping:
$ref: '#/components/schemas/statsMetricsGrouping'
limit:
$ref: '#/components/schemas/limit'
metrics:
description: Набор показателей, которые должны быть в статистике
items:
$ref: '#/components/schemas/statsMetric'
minItems: 1
type: array
offset:
$ref: '#/components/schemas/offset'
sort:
additionalProperties: false
description: Сортировка данных статистики
properties:
key:
$ref: '#/components/schemas/statsMetric'
order:
description: Порядок сортировки
enum:
- asc
- desc
example: asc
type: string
required:
- key
- order
type: object
required:
- dateFrom
- dateTo
- grouping
- metrics
type: object
description: Тело запроса
required: true
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
result:
additionalProperties: false
description: Статистические показатели клиента
properties:
dataTotalCount:
$ref: '#/components/schemas/counter'
groupings:
description: Группировки статистических показателей клиента
items:
additionalProperties: false
description: Группировка статистических показателей клиента
properties:
id:
$ref: '#/components/schemas/id'
metrics:
description: Статистические показатели
items:
additionalProperties: false
description: Статистический показатель
properties:
slug:
$ref: '#/components/schemas/statsMetric'
value:
$ref: '#/components/schemas/counter'
required:
- slug
- value
type: object
type: array
type:
$ref: '#/components/schemas/statsMetricsGrouping'
required:
- id
- type
- metrics
type: object
type: array
required:
- dataTotalCount
- groupings
type: object
required:
- result
type: object
description: Успешный ответ
'400':
$ref: '#/components/responses/defaultBadRequest'
'401':
$ref: '#/components/responses/defaultUnauthorized'
'403':
$ref: '#/components/responses/defaultForbidden'
'429':
$ref: '#/components/responses/defaultTooManyRequests'
'500':
$ref: '#/components/responses/defaultInternalServerError'
security:
- ClientCredentials: []
summary: Получение статистических показателей клиента
tags:
- statistics
/stats/v2/accounts/{user_id}/spendings:
post:
description: "Данный метод позволяет получить статистику расходов клиента.\n\n### Доступ к данным клиента\n\nДля того, чтобы получить данные статистики конкретного клиента,\n необходимо указать идентификатор аккаунта клиента в качестве значения параметра URL `user_id`,\n а также значения заголовка `X-AgencyClientId`!\n\n### Параметры тела запроса\n\n- `dateFrom` — дата в формате `YYYY-MM-DD`, с которой требуется получить статистику.\n- `dateTo` — дата в формате `YYYY-MM-DD`, по которую требуется получить статистику (включительно).\n- `grouping` — группировка расходов.\n- `spendingTypes` — массив необходимых категорий расходов.\n\n Добавьте ограничения `filter`, если нужно отфильтровать данные статистики:\n\n- `categoryIDs` — по категориям (идентификаторы). См. доступные значения в\n [Справочнике идентификаторов категорий](https://www.avito.st/s/openapi/catalog-categories.xml);\n- `itemIDs` — по объявлениям (идентификаторы).\n\n#### Группировка расходов\n\n- `day` — группировка по дням.\n- `week` — группировка по неделям.\n- `month` — группировка по месяцам.\n\n#### Категория расходов\n\n- `promotion` — продвижение объявлений.\n- `presence` — размещение и целевые действия.\n- `commission` — комиссия.\n- `rest` — остальное.\n\nЧтобы включить в ответ все категории расходов,\n можно в качестве значения входного параметра `spendingTypes` указать `[\"all\"]` — все расходы.\n\n### Успешный ответ\n\nМетод возвращает назад список данных группировок статистики `result.groupings`\n и временную метку получения данных статистики `result.timestamp`.\n\n#### Данные группировки\n\n- `date` — дата группировки расходов в формате `YYYY-MM-DD`.\n- `type` — группировка расходов.\n- `spendings` — список данных категории расходов.\n\n#### Данные категории расходов\n\n- `slug` — категория расходов.\n- `value` — сумма расходов в рублях.\n- `services` — список данных расходов категории по услугам.\n\n#### Данные расходов категории\n\n- `slug` — услуга.\n- `value` — сумма расходов в рублях.\n\n#### Услуга\n\n- `bbip` — Продвижение с прогнозом просмотров.\n- `perf_vas` — ×2, ×5, ×10 и другие.\n- `vas_xl` — XL-объявление.\n- `vas_highlight` — Выделение цветом.\n- `sbc_discount` — Рассылка скидок.\n- `vas_sticker` — Значки на XL-объявлении.\n- `vas_package` — Пакеты продвижения.\n- `orders_commission` — Комиссия за заказы.\n- `bookings_commission` — Комиссия за бронирования.\n- `delivery_subsidy` — Cкидка на доставку для покупателей.\n- `fbs_commission` — Комиссия за услугу «кросс-доставка».\n- `tariff_listing` — Размещения из тарифа.\n- `lf` — Разовые размещения.\n- `tariff_remainder` — Неиспользованные размещения.\n- `cpa_click_package` — Целевые просмотры.\n- `cpa_target_call` — Целевые звонки.\n- `cpa_target_chat` — Целевые чаты.\n- `cpa_job_contact` — Отклики.\n- `service_fee` — Объявления сверх лимита.\n- `cpa_rfp_contact` — Целевые лиды.\n- `cpa_transfer_select` — Лиды Селекта.\n- `profile_promo` — Продвижение профиля.\n- `profile_promo_v2` — Реклама профиля.\n- `tariff_ext` — Подписка на инструменты.\n- `chat_bot` — Чат-боты.\n- `cv` — Пакеты резюме.\n- `other` — Другое.\n\n### Примечания\n\n- Метод имеет ограничение до 100 запросов в минуту.\n- Глубина данных статистики ограничена 510 днями.\n"
operationId: statsAccountsSpendings
parameters:
- $ref: '#/components/parameters/userIdPathParameter'
- $ref: '#/components/parameters/authHeader'
- $ref: '#/components/parameters/agencyClientIdHeader'
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
dateFrom:
$ref: '#/components/schemas/date'
dateTo:
$ref: '#/components/schemas/date'
filter:
additionalProperties: false
description: Набор ограничений, по которым будут отфильтрованы данные статистики
properties:
categoryIDs:
$ref: '#/components/schemas/ids'
itemIDs:
$ref: '#/components/schemas/ids'
type: object
grouping:
$ref: '#/components/schemas/statsSpendingsGrouping'
spendingTypes:
description: Набор категорий расходов клиента
items:
enum:
- all
- promotion
- presence
- commission
- rest
example: all
type: string
type: array
required:
- dateFrom
- dateTo
- grouping
- spendingTypes
type: object
description: Тело запроса
required: true
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
result:
additionalProperties: false
description: Статистика расходов клиента
properties:
groupings:
description: Группировки расходов клиента
items:
additionalProperties: false
description: Группировка расходов клиента
properties:
date:
$ref: '#/components/schemas/date'
spendings:
description: Категории расходов
items:
additionalProperties: false
description: Категория расходов
properties:
services:
description: Расходы по услугам
items:
additionalProperties: false
description: Расход по услугам
properties:
slug:
description: Слаг услуг
enum:
- bbip
- perf_vas
- vas_xl
- vas_highlight
- sbc_discount
- vas_sticker
- vas_package
- orders_commission
- bookings_commission
- delivery_subsidy
- fbs_commission
- tariff_listing
- lf
- tariff_remainder
- cpa_click_package
- cpa_target_call
- cpa_target_chat
- cpa_job_contact
- service_fee
- cpa_rfp_contact
- cpa_transfer_select
- profile_promo
- profile_promo_v2
- tariff_ext
- chat_bot
- cv
- other
example: vas_xl
type: string
value:
$ref: '#/components/schemas/amountDouble'
required:
- slug
- value
type: object
type: array
slug:
description: Слаг категории расходов
enum:
- promotion
- presence
- commission
- rest
example: promotion
type: string
value:
$ref: '#/components/schemas/amountDouble'
required:
- slug
- value
- services
type: object
type: array
type:
$ref: '#/components/schemas/statsSpendingsGrouping'
required:
- date
- type
- spendings
type: object
type: array
timestamp:
$ref: '#/components/schemas/timestamp'
required:
- groupings
- timestamp
type: object
required:
- result
type: object
description: Успешный ответ
'400':
$ref: '#/components/responses/defaultBadRequest'
'401':
$ref: '#/components/responses/defaultUnauthorized'
'403':
$ref: '#/components/responses/defaultForbidden'
'429':
$ref: '#/components/responses/defaultTooManyRequests'
'500':
$ref: '#/components/responses/defaultInternalServerError'
security:
- ClientCredentials: []
summary: Получение статистики расходов клиента
tags:
- statistics
components:
schemas:
errorMessage:
description: Сообщение об ошибке
example: Ошибка
type: string
statsMetric:
description: Показатель статистики
enum:
- views
- contacts
- contactsShowPhone
- contactsMessenger
- contactsShowPhoneAndMessenger
- contactsSbcDiscount
- viewsToContactsConversion
- favorites
- averageViewCost
- averageContactCost
- impressions
- impressionsToViewsConversion
- clickPackages
- jobContacts
- viewsToOrderedItemsConversion
- orderedItems
- orderedItemsPrice
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/avito/refs/heads/main/openapi/avito-statistics-api-openapi.yml