Avito Statistics API

openapi: 3.2.0
info:
  description: API для агентств Авито Promo
  title: Авито Promo Statistics API
  version: 1.0.0
servers:
- url: https://api.avito.ru/
tags:
- description: 'С помощью API данного раздела вы можете получать статистику по объявлениям и расходам клиентов.


    ### Типы авторизации


    Для использования данного API запрос должен быть авторизован.

    API Авито Promo использует следующие механизмы авторизации:


    -->'
  name: Statistics
  x-displayName: Статистика клиентов
paths:
  /stats/v2/accounts/{user_id}/items:
    post:
      description: Данный метод позволяет получить различные статистические показатели объявлений клиента.
      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: 'Данный метод позволяет получить статистику расходов клиента.


        ### Доступ к данным клиента


        Для того, чтобы получить данные статистики конкретного клиента,

        необходимо указать идентификатор аккаунта клиента в качестве значения параметра URL `user_id`,

        а также значения заголовка `X-AgencyClientId`!


        ### Параметры тела запроса


        - `dateFrom` — дата в формате `YYYY-MM-DD`, с которой требуется получить статистику.

        - `dateTo` — дата в формате `YYYY-MM-DD`, по которую требуется получить статистику (включительно).

        - `grouping` — группировка расходов.

        - `spendingTypes` — массив необходимых категорий расходов.


        Добавьте ограничения `filter`, если нужно отфильтровать данные статистики:


        - `categoryIDs` — по категориям (идентификаторы). См. доступные значения в

        Справочнике идентификаторов категорий;

        - `itemIDs` — по объявлениям (идентификаторы).


        #### Группировка расходов


        - `day` — группировка по дням.

        - `week` — группировка по неделям.

        - `month` — группировка по месяцам.


        #### Категория расходов


        - `promotion` — продвижение объявлений.

        - `presence` — размещение и целевые действия.

        - `commission` — комиссия.

        - `rest` — остальное.


        Чтобы включить в ответ все категории расходов,

        можно в качестве значения входного параметра `spendingTypes` указать `["all"]` — все расходы.


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


        Метод возвращает назад список данных группировок статистики `result.groupings`

        и временную метку получения данных статистики `result.timestamp`.


        #### Данные группировки


        - `date` — дата группировки расходов в формате `YYYY-MM-DD`.

        - `type` — группировка расходов.

        - `spendings` — список данных категории расходов.


        #### Данные категории расходов


        - `slug` — категория расходов.

        - `value` — сумма расходов в рублях.

        - `services` — список данных расходов категории по услугам.


        #### Данные расходов категории


        - `slug` — услуга.

        - `value` — сумма расходов в рублях.


        #### Услуга


        - `bbip` — Продвижение с прогнозом просмотров.

        - `perf_vas` — ×2, ×5, ×10 и другие.

        - `vas_xl` — XL-объявление.

        - `vas_highlight` — Выделение цветом.

        - `sbc_discount` — Рассылка скидок.

        - `vas_sticker` — Значки на XL-объявлении.

        - `vas_package` — Пакеты продвижения.

        - `orders_commission` — Комиссия за заказы.

        - `bookings_commission` — Комиссия за бронирования.

        - `delivery_subsidy` — Cкидка на доставку для покупателей.

        - `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` — Другое.


        ### Примечания


        - Метод имеет ограничение до 100 запросов в минуту.

        - Глубина данных статистики ограничена 510 днями.'
      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:
  parameters:
    userIdPathParameter:
      description: Идентификатор пользователя клиента
      in: path
      name: user_id
      required: true
      schema:
        $ref: '#/components/schemas/id'
    authHeader:
      description: Токен для авторизации
      in: header
      name: Authorization
      required: true
      schema:
        example: Bearer ACCESS_TOKEN
        type: string
    agencyClientIdHeader:
      description: Идентификатор пользователя клиента
      in: header
      name: X-AgencyClientId
      required: true
      schema:
        $ref: '#/components/schemas/id'
  schemas:
    timestamp:
      description: Временная метка
      example: 1598958000
      type: integer
    statsSpendingsGrouping:
      description: Тип группировки расходов
      enum:
      - day
      - week
      - month
      example: month
      type: string
    amountDouble:
      description: Сумма в рублях
      example: 1000
      format: double
      type: number
    defaultErrorResponse:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          description: Ошибка
          properties:
            code:
              description: Код ошибки
              example: 1001
              type: integer
            message:
              $ref: '#/components/schemas/errorMessage'
          required:
          - code
          - message
          type: object
      required:
      - error
      type: object
    ids:
      description: Список идентификаторов
      items:
        $ref: '#/components/schemas/id'
      minItems: 1
      type: array
    statsMetric:
      description: Показатель статистики
      enum:
      - views
      - contacts
      - contactsShowPhone
      - contactsMessenger
      - contactsShowPhoneAndMessenger
      - contactsSbcDiscount
      - viewsToContactsConversion
      - favorites
      - averageViewCost
      - averageContactCost
      - impressions
      - impressionsToViewsConversion
      - clickPackages
      - jobContacts
      - viewsToOrderedItemsConversion
      - orderedItems
      - orderedItemsPrice
      - deliveredItems
      - deliveredItemsPrice
      - bookingPlacedCount
      - bookingPlacedPrice
      - bookingApprovedCount
      - bookingApprovedPrice
      - bookingAcceptedCount
      - bookingAcceptedPrice
      - allSpending
      - spending
      - presenceSpending
      - promoSpending
      - restSpending
      - commission
      - spendingBonus
      - activeItems
      - newActiveItems
      - oldActiveItems
      example: views
      type: string
    limit:
      description: Ограничение количества сущностей в выборке
      example: 100
      maximum: 1000
      minimum: 1
      type: integer
    counter:
      description: Счетчик
      example: 123
      type: integer
    id:
      description: Идентификатор
      example: 123456
      minimum: 1
      type: integer
    statsMetricsGrouping:
      description: Тип группировки показателей
      enum:
      - day
      - week
      - month
      - totals
      example: month
      type: string
    offset:
      description: Смещение, с которого начинается выборка
      example: 10
      minimum: 0
      type: integer
    errorMessage:
      description: Сообщение об ошибке
      example: Ошибка
      type: string
    date:
      description: Дата в формате YYYY-MM-DD
      example: '2025-05-02'
      format: date
      type: string
  responses:
    defaultInternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Ошибка сервера
    defaultForbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Действие запрещено
    defaultBadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Неверный запрос
    defaultTooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Превышено количество запросов
    defaultUnauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Требуется авторизация
  securitySchemes:
    ClientCredentials:
      description: 'Используйте OAuth2 с механизмом `client_credentials` для доступа к возможностям учётной записи агентства. [Подробнее](#tag/Access)

        '
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.avito.ru/token
      type: oauth2