Avito Item API

openapi: 3.0.0
info:
  contact:
    email: supportautoload@avito.ru
  description: 'API для взаимодействия с иерархией аккаунтов в Авито

    **Авито API для бизнеса предоставляется согласно [Условиям использования](https://www.avito.ru/legal/pro_tools/public-api).**

    '
  title: Иерархия Аккаунтов Access Item API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- description: 'Общие методы API для работы с объявлениями на Авито

    Описание API произведено в формате [**Swagger 3.0**](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).

    Вы можете использовать данный файл для ознакомления с методами API, а также для генерации базового

    кода для работы с API на удобном для вас языке программирования с помощью утилиты

    [**Swagger Codegen**](https://swagger.io/swagger-codegen/) или online сервиса [**Swagger Editor**](https://editor.swagger.io/).


    **Авито API для бизнеса предоставляется согласно [Условиям использования](https://www.avito.ru/legal/pro_tools/public-api).**

    По всем вопросам работы с API необходимо обращаться в Службу Поддержки профессиональных инструментов:


    <li>телефон: <b>+7 495 777-10-66</b></li>

    <li>email: <a href="mailto:supportautoload@avito.ru">supportautoload@avito.ru</a></li>


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

    Для использования данного API запрос должен быть авторизован. В данный момент API Авито использует следующие механизмы авторизации.


    <!-- ReDoc-Inject: <security-definitions> -->


    Подробнее о каждом механизме и его назначении можно прочитать в соответствующем разделе.

    '
  name: Item
  x-displayName: Объявления
paths:
  /core/v1/accounts/{userId}/vas/prices:
    parameters:
    - $ref: '#/components/parameters/pathUserId'
    - $ref: '#/components/parameters/authHeader'
    post:
      description: "Возвращает в ответ список объектов со следующей структурой:\n- `itemId` – идентификатор объявления\n- `vas` – список объектов, которые содержат информацию о стоимости дополнительных услуг и пакетов дополнительных услуг для каждого объявления. Структура объекта:\n  - `slug` – идентификатор услуги или пакета услуг:\n    - `highlight` — [услуга продвижения \"Выделить\"](https://support.avito.ru/articles/200026858)\n    - `xl` – [услуга продвижения \"XL-объявление\"](https://support.avito.ru/articles/685)\n    - `stickerpack_x1` – [1 значок на XL-объявлении](https://support.avito.ru/articles/2450) \n    - `stickerpack_x2` – [2 значка на XL-объявлении](https://support.avito.ru/articles/2450)\n    - `stickerpack_x3` – [3 значка на XL-объявлении](https://support.avito.ru/articles/2450)\n\n    - `x2_1` – [пакет \"до 2 раз больше просмотров на 1 день\"](https://support.avito.ru/articles/1398)\n    - `x2_7` – [пакет \"до 2 раз больше просмотров на 7 дней\"](https://support.avito.ru/articles/1398)\n    - `x5_1` – [пакет \"до 5 раз больше просмотров на 1 день\"](https://support.avito.ru/articles/1398)\n    - `x5_7` – [пакет \"до 5 раз больше просмотров на 7 дней\"](https://support.avito.ru/articles/1398)\n    - `x10_1` – [пакет \"до 10 раз больше просмотров на 1 день\"](https://support.avito.ru/articles/1398)\n    - `x10_7` – [пакет \"до 10 раз больше просмотров на 7 дней\"](https://support.avito.ru/articles/1398)\n    - `x15_1` – [пакет \"до 15 раз больше просмотров на 1 день\"](https://support.avito.ru/articles/1398)\n    - `x15_7` – [пакет \"до 15 раз больше просмотров на 7 дней\"](https://support.avito.ru/articles/1398)\n    - `x20_1` – [пакет \"до 20 раз больше просмотров на 1 день\"](https://support.avito.ru/articles/1398)\n    - `x20_7` – [пакет \"до 20 раз больше просмотров на 7 дней\"](https://support.avito.ru/articles/1398)\n\n  - `price` – цена в рублях с учетом скидки\n\n  - `priceOld` – цена в рублях до применения скидки\n\n- `stickers` – список объектов которые содержат доступные для объявления  [значки](https://support.avito.ru/articles/2450)\n  - `id` – идентификатор значка\n  - `title` – название значка\n  - `description` – описание значка\n"
      operationId: vasPrices
      requestBody:
        content:
          application/json:
            example:
              itemIds:
              - 1234567
              - 7654321
            schema:
              $ref: '#/components/schemas/pricesItemIdsRequestBody'
        description: Набор идентификаторов объявлений на сайте
      responses:
        '200':
          content:
            application/json:
              example:
              - itemId: 1234567
                stickers:
                - description: Description 1
                  id: 1
                  title: Sticker 1
                - description: Description 2
                  id: 2
                  title: Sticker 2
                vas:
                - price: 200
                  priceOld: 300
                  slug: x2_7
                - price: 100
                  priceOld: 150
                  slug: xl
                - price: 50
                  priceOld: 70
                  slug: stickerpack_x1
              - itemId: 7654321
                vas: []
              schema:
                oneOf:
                - $ref: '#/components/schemas/VasPricesResp'
                - $ref: '#/components/schemas/badRequestError'
                - $ref: '#/components/schemas/authError'
          description: Успешный ответ
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validatingError'
          description: Информация об ошибке
      security:
      - AuthorizationCode:
        - items:info
      - ClientCredentials: []
      summary: Получение информации о стоимости услуг продвижения и доступных значках
      tags:
      - Item
  /core/v1/accounts/{user_id}/calls/stats/:
    parameters:
    - $ref: '#/components/parameters/pathUserId'
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/applicationJsonHeader'
    post:
      description: 'Получение агрегированной статистики звонков, полученных пользователем

        '
      operationId: postCallsStats
      requestBody:
        content:
          application/json:
            example:
              dateFrom: '2020-04-01'
              dateTo: '2020-04-08'
              itemIds:
              - 1853257996
            schema:
              $ref: '#/components/schemas/CallsStatsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                result:
                  items:
                  - days:
                    - answered: 0
                      calls: 0
                      date: '2020-04-01'
                      new: 0
                      newAnswered: 0
                    employeeId: 0
                    itemId: 1853257996
              schema:
                $ref: '#/components/schemas/CallsStatsResponse'
          description: Успешный ответ
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestError'
          description: Неверный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authError'
          description: Требуется аутентификация
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notFoundError'
          description: Неверный user_id в запросе
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serviceError'
          description: Внутренняя ошибка метода API
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serviceUnavailableError'
          description: Метод API временно недоступен
      security:
      - AuthorizationCode:
        - items:info
      - ClientCredentials: []
      summary: Получение статистики по звонкам
      tags:
      - Item
  /core/v1/accounts/{user_id}/items/{item_id}/:
    parameters:
    - $ref: '#/components/parameters/pathUserId'
    - $ref: '#/components/parameters/pathItemId'
    - $ref: '#/components/parameters/authHeader'
    get:
      description: 'Возвращает данные об объявлении - его статус, список примененных услуг Максимальное количество запросов в минуту - 500

        **Внимание:** для получения статистики объявления должен использоваться метод:

        [получение статистики по списку объявлений](#operation/itemStatsShallow)

        '
      operationId: getItemInfo
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemInfoAvito'
          description: Успешный ответ
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tooManyRequests'
          description: Превышено допустимое количество запросов
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldError'
          description: Информация об ошибке
      security:
      - AuthorizationCode:
        - items:info
      - ClientCredentials: []
      summary: Получение информации по объявлению
      tags:
      - Item
  /core/v1/accounts/{user_id}/items/{item_id}/vas:
    parameters:
    - $ref: '#/components/parameters/pathUserId'
    - $ref: '#/components/parameters/pathItemId'
    - $ref: '#/components/parameters/authHeader'
    put:
      description: '**Внимание:** метод объявлен устаревшим и больше не поддерживается. Вместо него используйте метод `/core/v2/items/{itemId}/vas/`


        Применение дополнительной услуги к объявлению, в ответе возвращает данные о примененной услуге и сумму списания.

        [Более подробная информация по дополнительным услугам](https://support.avito.ru/sections/200009758)


        **Внимание:** получение ошибки при выполнении этой операции не означает, что услуга точно не была куплена.

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

        '
      operationId: putItemVas
      requestBody:
        content:
          application/json:
            example:
              vas_id: highlight
            schema:
              $ref: '#/components/schemas/vasIdRequestBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VasApplyAvito'
          description: Успешный ответ
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validatingError'
          description: Информация об ошибке
      security:
      - AuthorizationCode:
        - items:apply_vas
      - ClientCredentials: []
      summary: Применение дополнительных услуг
      tags:
      - Item
  /core/v1/items:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - description: Количество записей на странице (целое число больше 0 и меньше 100)
      in: query
      name: per_page
      schema:
        default: 25
        example: 50
        format: int32
        type: integer
    - description: Номер страницы (целое число больше 0)
      in: query
      name: page
      schema:
        default: 1
        example: 1
        format: int32
        type: integer
    - description: Статус объявления на сайте (можно указать несколько значений через запятую)
      in: query
      name: status
      schema:
        default: active
        enum:
        - active
        - removed
        - old
        - blocked
        - rejected
        example: active,old
        type: string
    - description: Фильтр больше либо равно по дате обновления/редактирования объявления в формате YYYY-MM-DD
      in: query
      name: updatedAtFrom
      schema:
        example: '2023-12-18'
        type: string
    - description: 'Идентификатор категории объявления</br> см. возможные варианты категорий в [ справочнике ](https://www.avito.st/s/openapi/catalog-categories.xml)

        '
      in: query
      name: category
      schema:
        example: 111
        format: int32
        type: integer
    get:
      description: 'Возвращает список объявлений авторизованного пользователя - статус, категорию и ссылку на сайте.

        **Внимание! В настоящий момент этот метод не работает с объявлениями [сотрудников](https://pro.avito.ru/employees).** Он позволяет получить объявления только для пользователя, который указан владельцем этого объявления. В случае сотрудника это будет главный аккаунт компании, для авторизованного сотрудника вернётся пустой список объявлений.

        Максимальное количество запросов в минуту - 25.

        '
      operationId: getItemsInfo
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsInfoWithCategoryAvito'
          description: Успешный ответ
        '429':
          description: Превышено допустимое количество запросов
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldError'
          description: Информация об ошибке
      security:
      - AuthorizationCode:
        - items:info
      - ClientCredentials: []
      summary: Получение информации по объявлениям
      tags:
      - Item
  /core/v2/accounts/{user_id}/items/{item_id}/vas_packages:
    parameters:
    - $ref: '#/components/parameters/pathUserId'
    - $ref: '#/components/parameters/pathItemId'
    - $ref: '#/components/parameters/authHeader'
    put:
      description: '**Внимание:** метод объявлен устаревшим и больше не поддерживается. Вместо него используйте метод `/core/v2/items/{itemId}/vas/`


        Применение пакета дополнительных услуг к объявлению, в ответе возвращает сумму списания.


        **Внимание:** получение ошибки при выполнении этой операции не означает, что пакет точно не была куплен.

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

        '
      operationId: putItemVasPackageV2
      requestBody:
        content:
          application/json:
            example:
              package_id: x10_7
            schema:
              $ref: '#/components/schemas/packageIdRequestBodyV2'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VasAmountAvito'
          description: Успешный ответ
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validatingError'
          description: Информация об ошибке
      security:
      - AuthorizationCode:
        - items:apply_vas
      - ClientCredentials: []
      summary: Применение пакета дополнительных услуг
      tags:
      - Item
  /core/v2/items/{itemId}/vas/:
    parameters:
    - $ref: '#/components/parameters/pathItemId'
    - $ref: '#/components/parameters/authHeader'
    put:
      description: "С помощью этого метода вы можете применить к опубликованному объявлению одну или несколько услуг продвижения (например, «XL-объявление», «Выделение цветом» и «До 10 раз больше просмотров на 7 дней»). В рамках одного запроса услуга может быть применена только один раз. \n\nЕсли для вашего объявления доступны значки (такие как «Без ДТП», «Срочно», «1 владелец»), при подключении услуги «XL-объявление» вы можете передать их список (не более трёх значков). В этом случае добавьте соответствующую услугу на 1, 2 или 3 значка.\n\n[Подробнее об услугах продвижения](https://support.avito.ru/partitions/131)\n\nЧтобы получить список доступных услуг и значков,  используйте метод `/core/v1/accounts/{userId}/vas/prices`.\n\nЕсли заказ сформирован успешно, в ответ вы получите уникальные идентификаторы операций покупки для каждой из применяемых услуг. Позже эти идентификаторы можно будет использовать, чтобы узнать статус выполнения заказа.\n\nВ случае некорректного запроса метод вернет код ответа 400 и структуру, содержащую поле `code`. Возможные коды ошибок:\n  - **1001** – один или несколько заголовков неправильно передаются;\n  - **1002** – ошибка в URL;\n  - **1003** – неверный идентификатор объявления из запроса;\n  - **1004** – JSON из тела запроса не соответствует схеме или список идентификаторов услуг пустой;\n  - **1005** – объявление, к которому вы хотите применить услуги, неактивно;\n  - **1006** – неправильное количество выбранных значков для объявления.\nУбедитесь, что в списке идентификаторов услуг есть услуга для покупки значков и она совпадает с количеством выбранных значков.\n      - stickerpack_x1 – 1 значок\n      - stickerpack_x2 – 2 значка\n      - stickerpack_x3 – 3 значка\n  - **1007** – некоторые из выбранных услуг не могут быть применены;\n  - **1008** – в объявлении появились обязательные поля, которые нужно заполнить.\nОтредактируйте объявление и попробуйте применить услугу снова.\n  - **1009** – в кошельке не хватает средств для покупки услуг;\n  - **1010** – вы пытались купить больше одной услуги увеличения просмотров;\n  - **1011** – вы пытались купить значки, недоступные для выбранного объявления.\n\nВ случае внутренней ошибки на стороне Авито вернётся код ответа 500 и структура, содержащая поле `code`. Возможные коды ошибок:\n  - **1000** – ошибка на стороне Авито, попробуйте позже или [напишите в поддержку](https://support.avito.ru/request/659?eventData[contextId]=117);\n\n**Важно:** если ответ пришёл без кода ошибки или его значения нет в списке выше — возможно, услуга всё-таки была куплена. Подождите несколько минут: услуга продвижения появится в списке применённых, а если нет — попробуйте оформить её снова.\n"
      operationId: applyVas
      requestBody:
        content:
          application/json:
            schema:
              properties:
                slugs:
                  description: Список идентификаторов услуг
                  example:
                  - x10_1
                  - xl
                  - stickerpack_x2
                  items:
                    type: string
                  type: array
                stickers:
                  description: Список значков
                  example:
                  - 1
                  - 2
                  items:
                    type: integer
                  type: array
              required:
              - slugs
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties:
                  $ref: '#/components/schemas/ApplyVasResp'
                example:
                  stickerpack_x2:
                    operationId: 123456791
                  x10_1:
                    operationId: 123456789
                  xl:
                    operationId: 123456790
                type: object
          description: Успешный ответ
        '500':
          content:
            application/json:
              schema:
                properties:
                  code:
                    enum:
                    - 1000
                    - 1001
                    - 1002
                    - 1003
                    - 1004
                    - 1005
                    - 1006
                    - 1007
                    - 1008
                    - 1009
                    - 1010
                    - 1011
                    type: integer
                required:
                - code
                type: object
          description: Ответ с ошибкой
      security:
      - AuthorizationCode:
        - items:apply_vas
      - ClientCredentials: []
      summary: Применение услуг продвижения
      tags:
      - Item
  /stats/v1/accounts/{user_id}/items:
    parameters:
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/applicationJsonHeader'
    post:
      description: 'Получение счетчиков по переданному списку объявлений пользователя.


        **Внимание:** в запросе может быть передано не более 200 идентификаторов объявлений.


        **Внимание:** глубина такого запроса ограничена 270 днями.


        ### Счетчики

        * ~~views - общее число просмотров объявления;~~ __DEPRECATED (будет удалено в апреле 2021 г.).__ Используйте поле uniqViews.

        * uniqViews - число уникальных пользователей, просмотревших объявление;

        * ~~contacts - число контактов [1];~~ __DEPRECATED (будет удалено в апреле 2021 г.).__ Используйте поле uniqContacts.

        * uniqContacts - число уникальных пользователей, совершивших контакты [1];

        * ~~favorites - число добавлений объявления в "избранное";~~ __DEPRECATED (будет удалено в апреле 2021 г.).__ Используйте поле uniqFavorites.

        * uniqFavorites - число уникальных пользователей, добавивших объявление в "избранное".


        ### Группировка счетчиков

        Счетчики могут быть сгруппированы [2] по:

        * дням;

        * неделям - в поле `date` соответствующей структуры будет первый день недели;

        * месяцам - в поле `date` соответствующей структуры будет первый день месяца.


        #### Период группировки

        Период группировки передается в теле запроса в поле `periodGrouping`. Доступные значения этого поля:

        * "day" (по умолчанию) - без группировки;

        * "week" - суммирование счетчиков за неделю;

        * "month" - суммирование счетчиков за месяц.


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

        * [1]: Под контактом понимаются: запросы телефона продавца, начатый чат с продавцом по конкретному объявлению, отклик на резюме и пр.

        * [2]: Группировка уникальных пользователей происходит только в рамках одного дня.

        '
      operationId: itemStatsShallow
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatisticsShallowRequestBody'
        description: Набор параметров в теле запроса.
      responses:
        '200':
          content:
            application/json:
              example:
                result:
                  items:
                  - itemId: <item_id_1>
                    stats:
                    - date: '2020-06-11'
                      uniqContacts: 1
                      uniqFavorites: 0
                      uniqViews: 10
                    - date: '2020-06-12'
                      uniqContacts: 0
                      uniqFavorites: 2
                      uniqViews: 7
                  - itemId: <item_id_2>
                    stats:
                    - date: '2020-06-11'
                      uniqContacts: 4
                      uniqFavorites: 3
                      uniqViews: 21
                    - date: '2020-06-12'
                      uniqContacts: 1
                      uniqFavorites: 1
                      uniqViews: 18
              schema:
                $ref: '#/components/schemas/StatisticsResponse'
          description: Успешный ответ
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestError'
          description: Неверный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authError'
          description: Требуется аутентификация
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notFoundError'
          description: Неверный user_id в запросе
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serviceError'
          description: Внутренняя ошибка метода API
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serviceUnavailableError'
          description: Метод API временно недоступен
      security:
      - AuthorizationCode:
        - stats:read
      - ClientCredentials: []
      summary: Получение статистики по списку объявлений
      tags:
      - Item
  /stats/v2/accounts/{user_id}/items:
    parameters:
    - $ref: '#/components/parameters/userId'
    - $ref: '#/components/parameters/authHeader'
    - $ref: '#/components/parameters/applicationJsonHeader'
    x-rate-limiter:
      default: 1
    post:
      description: "Получение статистических показателей по профилю.\n### Группировки показателей\nИспользуйте группировки, чтобы получать конкретную статистику.  Например, можете запросить только общие значения показателей, а если нужны подробности, — значения показателей по каждому объявлению или за определённый период. Доступные группировки:\n\n  - **totals** — по общему значению показателя за о�

# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/avito/refs/heads/main/openapi/avito-item-api-openapi.yml