Avito Ads 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 Ads API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- name: Ads
paths:
  /ads/v1/account/{accountID}:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    get:
      description: 'Возвращает реквизиты рекламного аккаунта по его ID: ИНН, КПП, ОГРН, юридический и фактический адреса, контактное лицо и менеджера.

        Токен имеет доступ только к тому аккаунту, в котором был выдан.

        '
      operationId: V1GetAccountByID
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetAccountByIdOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Аккаунт не найден
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Получить аккаунт по ID
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
    post:
      description: 'Создаёт тестовый аккаунт. Метод работает **только в песочнице** (`https://api.avito.ru/ads-sandbox/`); для боевых аккаунтов используйте веб-интерфейс кабинета.

        Ограничения песочницы: время жизни аккаунта — до 00:00 текущего дня; в сутки можно создать не более 1 тестового аккаунта.

        '
      operationId: V1CreateAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1CreateAccountIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1CreateAccountOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '207':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1CreateAccountOut'
          description: Аккаунт создан, но часть sandbox-данных не подготовилась
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      summary: Создать аккаунт в песочнице
      x-cost:
        default: 0
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/add-user:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    post:
      description: 'Добавляет пользователя Авито в рекламный аккаунт с указанной ролью. Доступные роли: `admin` (полный доступ) и `viewer` (только просмотр).

        Пользователь идентифицируется по `userId` (ID профиля на Авито).

        '
      operationId: V1AddUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1AddUserIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Добавить пользователя в аккаунт
      x-cost:
        default: 5
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/advertisers:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    post:
      description: 'Возвращает список рекламодателей аккаунта с пагинацией. Доступные фильтры: список `ids`, список `inns`, список ролей (`roles`).

        Параметры пагинации: `limit` — от 1 до 100 (по умолчанию 20), `page` — от 1.

        '
      operationId: V1GetAdvertisersList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1GetAdvertisersListIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetAdvertisersListOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Аккаунт не найден
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Получить список рекламодателей по фильтрам
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/balance:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    get:
      description: 'Возвращает текущий баланс рекламного аккаунта: денежные средства (`balance`) и бонусы (`bonusBalance`).

        Все суммы — в рублях, целые числа.

        '
      operationId: V1GetAccountBalanceByID
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetAccountBalanceByIdOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Аккаунт не найден
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Получить баланс аккаунта по ID
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/bonus-transfer:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    post:
      description: 'Переводит бонусы между родительским и дочерним аккаунтом-неплательщиком. Логика направления та же, что у `funds-transfer`: `accountID` в path — источник, `accountIdTo` в body — получатель; для перевода с дочернего на родителя нужен токен дочернего аккаунта.

        Сумма `amount` — целое число, не меньше 1 бонуса.

        '
      operationId: V1TransferBonus
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1TransferBonusIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Аккаунт не найден
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Перевод бонусов между аккаунтом родителем и дочерними на одном договоре
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/campaigns:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    post:
      description: 'Возвращает список рекламных кампаний аккаунта с пагинацией. Поддерживает фильтрацию по ID, моделям оплаты (`CPM`/`CPC`), типам кампании (`textImage`/`HTML`/`video`), статусам, менеджерам, рекламодателям, договорам, диапазону дат создания и диапазону периода размещения.

        Параметры пагинации: `limit` — от 1 до 100 (по умолчанию 20), `page` — от 1.

        '
      operationId: V1GetCampaignsList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1GetCampaignsListIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetCampaignsListOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Аккаунт не найден
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      summary: Получить список кампаний по фильтрам
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/campaigns/{campaignID}/creatives/stats:
    parameters:
    - description: ID аккаунта
      in: path
      name: accountID
      required: true
      schema:
        type: integer
    - description: ID кампании
      in: path
      name: campaignID
      required: true
      schema:
        type: integer
    post:
      description: 'Возвращает статистику по конкретным креативам указанной кампании за заданный период. В `creativeIDs` нужно передать минимум один ID креатива.

        **Ограничение:** максимальный период между `dateFrom` и `dateTo` — 100 дней.

        '
      operationId: V1GetCreativesStatistic
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1GetCreativesStatisticIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetCreativesStatisticOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Кампания не найдена
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Получить статистику по креативам кампании
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/campaigns/{campaignID}/groups/stats:
    parameters:
    - description: ID аккаунта
      in: path
      name: accountID
      required: true
      schema:
        type: integer
    - description: ID кампании
      in: path
      name: campaignID
      required: true
      schema:
        type: integer
    post:
      description: 'Возвращает статистику по конкретным группам объявлений внутри указанной кампании за заданный период. В `groupIDs` нужно передать минимум один ID группы.

        **Ограничение:** максимальный период между `dateFrom` и `dateTo` — 100 дней.

        '
      operationId: V1GetGroupsStatistic
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1GetGroupsStatisticIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetGroupsStatisticOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Кампания не найдена
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Получить статистику по группам кампании
      x-cost:
        default: 5
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/campaigns/{campaignID}/stats:
    parameters:
    - description: ID аккаунта
      in: path
      name: accountID
      required: true
      schema:
        type: integer
    - description: ID кампании
      in: path
      name: campaignID
      required: true
      schema:
        type: integer
    post:
      description: 'Возвращает агрегированную статистику по кампании (показы, клики, CTR, расход, CPM/CPC, метрики видеопросмотров) за указанный период с дневной гранулярностью, а также сводку по группам и креативам кампании.

        **Ограничение:** максимальный период между `dateFrom` и `dateTo` — 100 дней.

        '
      operationId: V1GetCampaignStatistic
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1GetCampaignStatisticIn'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetCampaignStatisticOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Кампания не найдена
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      security:
      - ClientCredentials: []
      summary: Получить статистику по кампании
      x-cost:
        default: 10
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/children:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    get:
      description: "Возвращает список дочерних аккаунтов, привязанных к текущему (родительскому) аккаунту, вместе с их договорами. \nУ дочерних аккаунтов на одном договоре с родителем не передается информация о договоре.\nЕсли нужны также балансы дочерних аккаунтов, используйте `GET /ads/v1/account/{accountID}/children-with-balances`.\n"
      operationId: V1GetChildAccountsList
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetChildAccountsListOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некорректный запрос
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Не авторизован
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Доступ запрещен
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Аккаунт не найден
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Слишком много запросов
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Ошибка сервера
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Сервис недоступен
      summary: Получить список дочерних аккаунтов
      x-cost:
        default: 1
        type: integer
      x-rate-limiter:
        default: 500
      tags:
      - Ads
  /ads/v1/account/{accountID}/children-with-balances:
    parameters:
    - in: path
      name: accountID
      required: true
      schema:
        type: integer
    get:
      description: 'Возвращает список дочерних аккаунтов вместе с их балансами (денежные средства, бонусы).

        Удобно для проверки результата переводов через `funds-transfer` / `bonus-transfer`.

        '
      operationId: V1GetChildAccountsWithBalancesList
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1GetChildAccountsWithBalancesListOut'
          description: Ok
          headers:
            Api-Point-Balance:
              description: Остаток API-баллов после выполнения запроса
              schema:
                type: integer
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Некоррект�

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