Avito Transactions API

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


    Выполните перевод средств на счёт клиента и получите идентификатор транзакции.

    Затем с помощью идентификатора проверьте статус транзакции.

    Отслеживайте транзакции, которые ещё не были завершены.


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


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

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


    -->'
  name: Transactions
  x-displayName: Перевод средств клиентам
paths:
  /agency/balance:
    post:
      description: 'Данный метод выполняет перевод средств агентства на счёт клиента (актуально для рекламной модели).

        При пополнении счёта клиента должны совпадать ИНН и КПП для:


        - аккаунта, от имени которого выполняется запрос;

        - аккаунта, на чей счёт нужно перевести средства;

        - платежа, из которого берётся указанная сумма.


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


        - `userId` — идентификатор клиента, на счёт которого переводятся средства.

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


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


        Метод возвращает назад информацию о созданной транзакции:


        - `result.transactionId` — идентификатор транзакции,

        с помощью которого можно получить информацию о транзакции

        (см. метод Получение информации о транзакции).

        - `result.status` — статус транзакции.

        - `result.reason` — причина текущего статуса транзакции.


        В случае успеха статус будет иметь значение `processing` — транзакция в процессе обработки.

        Если же при создании транзакции возникает ошибка, то статус будет иметь значение `error`.

        В таком случае необходимо обратиться в службу поддержки,

        указав в обращении в том числе значение параметра `result.reason`.'
      operationId: agencyBalance
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                amount:
                  description: Сумма в рублях
                  example: 1000
                  minimum: 1
                  type: integer
                userId:
                  $ref: '#/components/schemas/id'
              required:
              - userId
              - amount
              type: object
        description: Тело запроса
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  result:
                    additionalProperties: false
                    description: Результат перевода средств на счёт клиента
                    properties:
                      reason:
                        description: Причина текущего статуса транзакции
                        example: Создан запрос на перевод средств
                        type: string
                      status:
                        description: Статус транзакции
                        enum:
                        - processing
                        - error
                        example: processing
                        type: string
                      transactionId:
                        $ref: '#/components/schemas/transactionId'
                    required:
                    - transactionId
                    - status
                    - reason
                    type: object
                required:
                - result
                type: object
          description: Успешный ответ
        '400':
          $ref: '#/components/responses/badRequestFields'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/unauthorized'
        '429':
          $ref: '#/components/responses/defaultTooManyRequests'
        '500':
          $ref: '#/components/responses/defaultInternalServerError'
      security:
      - ClientCredentials: []
      summary: Перевод средств на счёт клиента
      tags:
      - Transactions
  /agency/transactions:
    get:
      description: 'Данный метод позволяет получить список незавершённых транзакций.


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


        Метод возвращает назад массив незавершённых транзакций `result`.


        #### Транзакция


        В данных транзакции возвращается её идентификатор `transactionId` и статус `status`.

        По идентификатору транзакции с помощью метода

        Получение информации о транзакции можно получить сообщение об ошибке,

        если её статус имеет значение `error`.


        #### Статус транзакции


        - `success` — перевод средств успешно завершён.

        - `processing` — транзакция создана, но её обработка ещё не завершена.

        - `error` — при обработке транзакции произошла ошибка.'
      operationId: agencyTransactions
      parameters:
      - $ref: '#/components/parameters/authHeader'
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  result:
                    description: Информация о незавершённых транзакциях
                    items:
                      additionalProperties: false
                      description: Информация о транзакции
                      properties:
                        status:
                          $ref: '#/components/schemas/transactionStatus'
                        transactionId:
                          $ref: '#/components/schemas/transactionId'
                      required:
                      - transactionId
                      - status
                      type: object
                    type: array
                required:
                - result
                type: object
          description: Успешный ответ
        '400':
          $ref: '#/components/responses/badRequestFields'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/unauthorized'
        '429':
          $ref: '#/components/responses/defaultTooManyRequests'
        '500':
          $ref: '#/components/responses/defaultInternalServerError'
      security:
      - ClientCredentials: []
      summary: Получение списка незавершённых транзакций
      tags:
      - Transactions
  /agency/transactions/{transaction_id}:
    get:
      description: 'Данный метод позволяет получить информацию о транзакции.


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


        - `transactionId` — идентификатор транзакции

        (см. метод Перевод средств на счёт клиента).


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


        Метод возвращает назад идентификатор транзакции `result.transactionId` и её статус `result.status`.

        Если статус имеет значение `error`, то также возвращается сообщение об ошибке `result.message`.


        #### Статус транзакции


        - `success` — перевод средств успешно завершён.

        - `processing` — транзакция создана, но её обработка ещё не завершена.

        - `error` — при обработке транзакции произошла ошибка.


        #### Сообщение об ошибке


        - «transfer not found» — транзакция с заданным `transactionId` не найдена.

        - «Недостаточно средств у рекламного агентства» — транзакцию не удалось выполнить из-за того,

        что все предварительно внесённые средства исчерпаны.

        - любой другой текст — внутренняя ошибка. Следует обратиться в службу поддержки.'
      operationId: agencyTransaction
      parameters:
      - $ref: '#/components/parameters/transactionIdPathParameter'
      - $ref: '#/components/parameters/authHeader'
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  result:
                    additionalProperties: false
                    description: Информация о транзакции
                    properties:
                      message:
                        $ref: '#/components/schemas/errorMessage'
                      status:
                        $ref: '#/components/schemas/transactionStatus'
                      transactionId:
                        $ref: '#/components/schemas/transactionId'
                    required:
                    - transactionId
                    - status
                    type: object
                required:
                - result
                type: object
          description: Успешный ответ
        '400':
          $ref: '#/components/responses/badRequestFields'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '429':
          $ref: '#/components/responses/defaultTooManyRequests'
        '500':
          $ref: '#/components/responses/defaultInternalServerError'
      security:
      - ClientCredentials: []
      summary: Получение информации о транзакции
      tags:
      - Transactions
components:
  schemas:
    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
    errorMessage:
      description: Сообщение об ошибке
      example: Ошибка
      type: string
    errorField:
      description: Наименование поля
      example: userId
      type: string
    transactionId:
      description: Идентификатор транзакции
      example: b52717c26fbc027acc34f165490fd4fdf404f3aa
      minLength: 1
      type: string
    errorFields:
      description: Ошибки валидации
      items:
        additionalProperties: false
        description: Ошибка валидации поля
        properties:
          field:
            $ref: '#/components/schemas/errorField'
          message:
            $ref: '#/components/schemas/errorMessage'
        required:
        - field
        - message
        type: object
      type: array
    errorResponse:
      additionalProperties: false
      properties:
        result:
          $ref: '#/components/schemas/errorResult'
      required:
      - result
      type: object
    errorResult:
      additionalProperties: false
      description: Результат с ошибкой
      properties:
        message:
          $ref: '#/components/schemas/errorMessage'
      required:
      - message
      type: object
    transactionStatus:
      description: Статус транзакции
      enum:
      - processing
      - success
      - error
      example: success
      type: string
    id:
      description: Идентификатор
      example: 123456
      minimum: 1
      type: integer
  responses:
    unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
      description: Требуется авторизация
    defaultInternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Ошибка сервера
    notFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
      description: Не найдено
    defaultTooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Превышено количество запросов
    forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
      description: Действие запрещено
    badRequestFields:
      content:
        application/json:
          schema:
            additionalProperties: false
            properties:
              result:
                $ref: '#/components/schemas/errorFields'
            required:
            - result
            type: object
      description: Неверный запрос
  parameters:
    authHeader:
      description: Токен для авторизации
      in: header
      name: Authorization
      required: true
      schema:
        example: Bearer ACCESS_TOKEN
        type: string
    transactionIdPathParameter:
      description: Идентификатор транзакции
      in: path
      name: transaction_id
      required: true
      schema:
        $ref: '#/components/schemas/transactionId'
  securitySchemes:
    ClientCredentials:
      description: 'Используйте OAuth2 с механизмом `client_credentials` для доступа к возможностям учётной записи агентства. [Подробнее](#tag/Access)

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