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

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

    '
  title: Иерархия Аккаунтов Access balance API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- description: 'С помощью API данного раздела вы можете получить информацию о балансе средств агентства и всех операций с ним.


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


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

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


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

    '
  name: balance
  x-displayName: Баланс агентства
paths:
  /api/1/agency/finances/balance:
    get:
      description: 'Данный метод позволяет получить текущий баланс средств агентства.


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


        Метод возвращает назад информацию о балансе агентства `result`:


        - `full` — сумма полного баланса средств агентства в копейках.

        - `pending` — сумма баланса средств агентства, находящихся «в обработке», в копейках.

        '
      operationId: agencyFinancesBalance
      parameters:
      - $ref: '#/components/parameters/authHeader'
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  full:
                    $ref: '#/components/schemas/amountKopecks'
                  pending:
                    $ref: '#/components/schemas/amountKopecks'
                required:
                - full
                - pending
                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:
      - balance
  /api/1/agency/finances/transactionsHistory:
    post:
      description: "Данный метод позволяет получить список всех операций с балансом средств агентства.\n\n### Параметры тела запроса\n\n- `dateFrom` — дата в формате RFC3339, с которой требуется получить операции с балансом.\n- `dateTo` — дата в формате RFC3339, по которую требуется получить операции с балансом.\n- `limit` — инструмент пагинации, ограничивает количество операций в ответе (максимум 1000).\n- `offset` — инструмент пагинации, выполняет смещение, с которого начинается выборка операций.\n\n### Успешный ответ\n\nМетод возвращает назад список транзакций `result.items` — операции с балансом средств агентства.\n\n#### Транзакция\n\nТранзакция содержит в себе следующую информацию:\n\n- `transactionId` — идентификатор транзакции.\n- `operationDateTime` — дата и время проведения транзакции.\n- `amount` — сумма транзакции в копейках.\n- `status` — статус транзакции.\n- `clientId` — идентификатор клиента, которому был совершён перевод.\n  Если не указан, значит, транзакция является пополнением баланса агентства.\n\n#### Статус транзакции\n\n- `success` — транзакция успешно завершена.\n- `pending` — транзакция в обработке.\n- `failed` — при обработке транзакции произошла ошибка.\n- `blocked` — попытка провести транзакцию за 2 дня до окончания отчётного периода.\n  Такие транзакции не выполняются.\n"
      operationId: agencyFinancesTransactionsHistory
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                dateFrom:
                  $ref: '#/components/schemas/dateTime'
                dateTo:
                  $ref: '#/components/schemas/dateTime'
                limit:
                  $ref: '#/components/schemas/limit'
                offset:
                  $ref: '#/components/schemas/offset'
              required:
              - dateFrom
              - dateTo
              - limit
              - offset
              type: object
        description: Тело запроса
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    description: Информация об операциях с балансом агентства
                    items:
                      additionalProperties: false
                      description: Информация об операции с балансом агентства
                      properties:
                        amount:
                          $ref: '#/components/schemas/amountKopecks'
                        clientId:
                          $ref: '#/components/schemas/id'
                        operationDateTime:
                          $ref: '#/components/schemas/dateTime'
                        status:
                          description: Статус транзакции
                          enum:
                          - pending
                          - success
                          - blocked
                          - failed
                          example: success
                          type: string
                        transactionId:
                          $ref: '#/components/schemas/transactionId'
                      required:
                      - transactionId
                      - operationDateTime
                      - amount
                      - status
                      type: object
                    type: array
                required:
                - items
                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:
      - balance
components:
  responses:
    defaultTooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Превышено количество запросов
    defaultUnauthorized:
      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: Неверный запрос
    defaultInternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Ошибка сервера
  schemas:
    errorMessage:
      description: Сообщение об ошибке
      example: Ошибка
      type: string
    dateTime:
      description: Дата в формате RFC3339
      example: '2025-05-02T11:00:00+03:00'
      format: date-time
      type: string
    limit:
      description: Ограничение количества сущностей в выборке
      example: 100
      maximum: 1000
      minimum: 1
      type: integer
    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
    transactionId:
      description: Идентификатор транзакции
      example: b52717c26fbc027acc34f165490fd4fdf404f3aa
      minLength: 1
      type: string
    offset:
      description: Смещение, с которого начинается выборка
      example: 10
      minimum: 0
      type: integer
    id:
      description: Идентификатор
      example: 123456
      minimum: 1
      type: integer
    amountKopecks:
      description: Сумма в копейках
      example: 100000
      type: integer
  parameters:
    authHeader:
      description: Токен для авторизации
      in: header
      name: Authorization
      required: true
      schema:
        example: Bearer ACCESS_TOKEN
        type: string
  securitySchemes:
    AuthorizationCode:
      description: Это API использует OAuth 2 с механизмом authorization_code. Используйте его для доступа к данным других пользователей при разработке стороннего приложения. [Подробнее](/api-catalog/auth/documentation#tag/ApplicationAccess)
      flows:
        authorizationCode:
          authorizationUrl: https://avito.ru/oauth
          scopes:
            ah:access: Взаимодействие с иерархией аккаунтов
          tokenUrl: https://api.avito.ru/token
      type: oauth2
    ClientCredentials:
      description: Это API использует OAuth 2 с механизмом client_credentials. Используйте его для доступа к возможностям своей личной учетной записи. [Подробнее](#tag/Access)
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.avito.ru/token
      type: oauth2