Avito Order Management 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 Order Management API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- name: Order Management
paths:
  /order-management/1/markings:
    post:
      description: 'Метод для передачи честного знака для товаров в заказе.

        Максимальное количество элементов в одном запросе - 50.

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

        '
      operationId: markings
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setOrderMarkingRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setOrderMarkingResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Передача честного знака
      x-rate-limiter:
        default: 100
      tags:
      - Order Management
  /order-management/1/order/acceptReturnOrder:
    post:
      description: 'Данный метод применяется для подтверждения возврата товара и выбора отделения Почты России, куда будет доставлен возврат.

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

        '
      operationId: acceptReturnOrder
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orderAcceptReturnOrderRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderAcceptReturnOrderResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Выбор отделения отделения Почты России для получения возврата
      x-rate-limiter:
        default: 100
      tags:
      - Order Management
  /order-management/1/order/applyTransition:
    post:
      description: 'Данный метод применяется для изменения статуса заказа, в частности для подтверждения или отмены заказа.

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

        '
      operationId: applyTransition
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orderApplyTransitionRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderApplyTransitionResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Изменение статуса заказа
      x-rate-limiter:
        default: 100
      tags:
      - Order Management
  /order-management/1/order/checkConfirmationCode:
    post:
      description: 'Данный метод используется для подтверждения личности для получения заказа в ПВЗ. Пользователь называет код  из приложения сотруднику СД. Далее через API служба доставки проверяет его валидность.

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

        '
      operationId: checkConfirmationCode
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orderCheckConfirmationCodeRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderCheckConfirmationCodeResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Метод для проверки кода подтверждения заказа.
      x-rate-limiter:
        default: 2000
      tags:
      - Order Management
  /order-management/1/order/cncSetDetails:
    post:
      description: 'Данный метод применяется продавцом для подготовки заказа и передачи адреса, сроков бронирования и сообщения покупателю.

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

        '
      operationId: cncSetDetails
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orderCNCSetDetailsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderCNCSetDetailsResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Метод для подготовки заказа с самовывозом
      x-rate-limiter:
        default: 60
      tags:
      - Order Management
  /order-management/1/order/getCourierDeliveryRange:
    get:
      description: 'Данный метод применяется для получения всех промежутков времени, когда курьер может приехать забрать товар, чтобы отвезти его покупателю.

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

        '
      operationId: getCourierDeliveryRange
      parameters:
      - $ref: '#/components/parameters/authHeader'
      - description: ID заказа
        in: query
        name: orderId
        required: true
        schema:
          minLength: 1
          type: string
      - description: Адрес продавца
        in: query
        name: address
        schema:
          minLength: 1
          nullable: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getDeliveryCourierConfirmationResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Метод получения доступных временных промежутков приезда курьера
      x-rate-limiter:
        default: 100
      tags:
      - Order Management
  /order-management/1/order/setCourierDeliveryRange:
    post:
      description: 'Данный метод применяется после метода получения всех промежутков времени, когда курьер может приехать и забрать товар.  Вызвав этот метод, продавец выбирает определённый временной промежуток приезда курьера.

        Также этот метод можно вызвать, чтобы изменить время приезда курьера, если он ещё не забрал посылку. Максимальное количество запросов в минуту - 200.

        '
      operationId: setCourierDeliveryRange
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setCourierDeliveryRangeRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/setCourierDeliveryRangeResponse'
          description: Успешный выбор времени приезда курьера
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Метод выбора определённого доступного временного промежутка для приезда курьера
      x-rate-limiter:
        default: 100
      tags:
      - Order Management
  /order-management/1/order/setTrackingNumber:
    post:
      description: 'Метод для передачи трек-номера для доставки партнёрами продавца (DBS)

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

        '
      operationId: setOrderTrackingNumber
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orderSetTrackingNumberRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderSetTrackingNumberResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Передача трек-номера
      x-rate-limiter:
        default: 100
      tags:
      - Order Management
  /order-management/1/orders:
    get:
      description: 'Получение информации о заказах по статусу.

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

        '
      operationId: getOrders
      parameters:
      - $ref: '#/components/parameters/authHeader'
      - description: 'Идентификаторы заказов

          '
        in: query
        name: ids
        schema:
          items:
            type: string
          type: array
      - description: 'Статус, по которому нужно получить заказы.


          - on_confirmation - ожидает подтверждения


          - ready_to_ship - ждет отправки


          - in_transit - в пути


          - canceled - отменный заказ


          - delivered - доставлен покупателю


          - on_return - на возврате


          - in_dispute - по заказу открыт спор


          - closed - заказ закрыт

          '
        in: query
        name: statuses
        schema:
          items:
            $ref: '#/components/schemas/status'
          type: array
      - description: Метка времени, с момента которого созданы покупки
        example: 1686735089
        in: query
        name: dateFrom
        schema:
          type: integer
      - description: Номер страницы для пагинации
        example: 1
        in: query
        name: page
        schema:
          type: integer
      - description: Максимальное количество заказов на странице
        example: 10
        in: query
        name: limit
        schema:
          maximum: 20
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ordersInfo'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Получение информации о заказах
      x-rate-limiter:
        default: 500
      tags:
      - Order Management
  /order-management/1/orders/labels:
    post:
      description: "Создаёт задачу на генерацию PDF-этикеток для заказов (до 100 штук).  Возвращает идентификатор задачи для последующей проверки статуса и скачивания результата. \nМаксимальное количество запросов в минуту - 1000. Эта ручка доступна только для ПВЗ заказов.\n"
      operationId: generateLabels
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ordersLabelsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ordersLabelsResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Создать задачу на генерацию этикеток (до 100).
      x-rate-limiter:
        default: 1000
      tags:
      - Order Management
  /order-management/1/orders/labels/extended:
    post:
      description: 'Создаёт задачу на генерацию PDF-этикеток для заказов (до 1000 штук).  Возвращает идентификатор задачи для последующей проверки статуса и скачивания результата.

        Максимальное количество запросов в минуту - 1. Эта ручка доступна только для ПВЗ заказов.

        '
      operationId: generateLabelsExtended
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ordersLabelsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ordersLabelsResponse'
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Создать задачу на генерацию этикеток (до 1000).
      x-rate-limiter:
        default: 1
      tags:
      - Order Management
  /order-management/1/orders/labels/{taskID}/download:
    get:
      description: 'Скачивание сгенерированного PDF-файла с этикетками по идентификатору задачи.  Файл доступен после успешного завершения генерации.

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

        '
      operationId: downloadLabel
      parameters:
      - $ref: '#/components/parameters/authHeader'
      - description: ID задачи на генерацию
        in: path
        name: taskID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/pdf:
              schema:
                format: binary
                type: string
          description: Success
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalError'
      security:
      - ClientCredentials: []
      summary: Скачать сгенерированный PDF-файл (этикетку).
      x-rate-limiter:
        default: 1000
      tags:
      - Order Management
components:
  responses:
    forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Forbidden
    unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Unauthorized
    notFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Not found
    badRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Bad request
    internalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Internal Error
    tooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Too Many Requests
  schemas:
    courierInfo:
      description: Информация об адресе покупателя для курьерской доставки RDBS
      nullable: true
      properties:
        address:
          description: Адрес, на который покупатель оформил доставку
          example: Москва, ул. Каретный ряд, 16, ст. 1, к. 2
          nullable: true
          type: string
        comment:
          description: Комментарий покупателя
          example: Подъезд во дворе дома, домофон не работает
          nullable: true
          type: string
      type: object
    status:
      enum:
      - on_confirmation
      - ready_to_ship
      - in_transit
      - canceled
      - delivered
      - on_return
      - in_dispute
      - closed
      type: string
    ordersInfo:
      description: Ответ для ручки получения информации о заказе
      properties:
        hasMore:
          description: Есть ли еще заказы
          example: true
          type: boolean
        orders:
          description: Массив заказов
          items:
            $ref: '#/components/schemas/order'
          type: array
      required:
      - orders
      - hasMore
      type: object
    delivery:
      description: Информация о доставке
      properties:
        buyerInfo:
          $ref: '#/components/schemas/buyerInfo'
        courierInfo:
          $ref: '#/components/schemas/courierInfo'
        dispatchNumber:
          description: Номер отправления. Отсутствует для RDBS.
          example: '0000042642072'
          type: string
        serviceName:
          description: Название службы доставки.
          example: Boxberry
          type: string
        serviceType:
          description: "Способ доставки \n  - `pvz` - ПВЗ;\n  - `dbs` - Доставка партнёрами продавца (ПВЗ);\n  - `rdbs` - Доставка курьером продавца;\n  - `postamat` - Доставка через постамат;\n"
          enum:
          - pvz
          - dbs
          - rdbs
          type: string
        terminalInfo:
          $ref: '#/components/schemas/terminalInfo'
        trackingNumber:
          description: Номер для отслеживания посылки. Отсутствует для RDBS.
          example: '0000012642072'
          type: string
      type: object
    buyerInfo:
      description: Информация о покупателе. Доступна только для DBS и RDBS после оплаты заказа
      nullable: true
      properties:
        fullName:
          description: ФИО покупателя
          example: Пушкин Александр Сергеевич
          type: string
        phoneNumber:
          description: Номер телефона покупателя
          example: 79876543210
          type: string
      type: object
    orderCheckConfirmationCodeResponse:
      description: Ответ ручки проверки кода подтверждения
      properties:
        data:
          properties:
            status:
              enum:
              - success
              - fail
              - expired
              - attempts
              type: string
          type: object
      type: object
    marking:
      description: Данные маркировки
      properties:
        itemId:
          description: ID товара в Авито
          example: '2799377316'
          type: string
        markings:
          description: Набор маркировок, которые требуется сохранить
          items:
            example: '36376376113637637611363763761123'
            maxLength: 129
            minLength: 29
            type: string
          maxItems: 10
          type: array
        orderId:
          description: ID заказа в Авито
          example: '50000000000000000'
          type: string
      type: object
    setOrderMarkingRequest:
      description: Запрос ручки обновления маркировок
      properties:
        markings:
          description: Массив маркировок, которые требуется передать
          items:
            $ref: '#/components/schemas/marking'
          type: array
      type: object
    orderApplyTransitionResponse:
      description: Ответ перевода заказа в другой статус
      properties:
        success:
          description: Флаг успеха перевода в новый статус
          example: false
          type: boolean
      type: object
    getDeliveryCourierConfirmationResponse:
      properties:
        result:
          description: Данные для отображения виджета подтверждения заказа продавцом
          properties:
            address:
              description: Адрес продавца
              type: string
            addressDetails:
              description: Детали адреса продавца
              type: string
            dateOptions:
              description: Опции с датами
              items:
                description: Опция с датами
                properties:
                  date:
                    description: Дата интервала
                    format: date-time
                    type: string
                  timeIntervals:
                    description: Опции с временными интервалами
                    items:
                      description: Опция с временными интервалами
                      properties:
                        endDate:
                          description: Дата конца
                          format: date-time
                          type: string
                        startDate:
                          description: Дата начала
                          format: date-time
                          type: string
                        title:
                          type: string
                        type:
                          description: Тип интервала
                          type: string
                      type: object
                    type: array
                type: object
              type: array
            endDate:
              description: Конечная дата приезда курьера
              format: date-time
              type: string
            name:
              description: ФИО продавца
              type: string
            phone:
              description: Телефон продавца
              type: string
            startDate:
              description: Начальная дата приезда курьера
              format: date-time
              type: string
          required:
          - dateOptions
          type: object
        status:
          type: string
      required:
      - status
      - result
      type: object
    ordersLabelsRequest:
      description: Запрос на создание генерации этикеток для пользователя по его заказам
      properties:
        orderIDs:
          description: ID заказов в сервисе сделок (marketplace)
          items:
            type: string
          maxItems: 50
          minItems: 1
          type: array
      required:
      - orderIDs
      type: object
    error:
      properties:
        code:
          description: Код ошибки
          example: 500
          type: integer
        message:
          description: Текст ошибки
          example: Error message
          type: string
      required:
      - message
      - code
      type: object
    item:
      properties:
        avitoId:
          description: ID товара в базе Avito
          example: '2799377316'
          type: string
        chatId:
          description: Идентификатор чата
          example: u2i-isUW4p7EZVu4R4Zk6ts2G
          type: string
        count:
          description: Количество товара
          example: 2
          type: integer
        discounts:
          description: Список примененных скидок
          items:
            $ref: '#/components/schemas/discount'
          type: array
        id:
          description: ID товара в базе продавца
          example: '132768483'
          type: string
        location:
          description: Город, в котором размещено объявление
          example: Новосибирск
          type: string
        prices:
          $ref: '#/components/schemas/itemPrices'
        title:
          description: Название товара
          example: Кеды Venice
          type: string
      required:
      - avitoId
      - title
      - prices
      - count
      type: object
    discount:
      properties:
        id:
          description: Идентификатор скидки
          example: myfriendpromo
          type: string
        type:
          description: Тип скидки
          enum:
          - promocode
          type: string
        value:
          description: Размер скидки
          example: 10
          type: number
      type: object
    orderCNCSetDetailsRequest:
      description: Запрос на подготовку заказа и уточнение деталей
      properties:
        address:
          description: Адрес получения товара
          example: Тверская улица, 3, Москва
          type: string
        bookingPeriod:
          description: Сроки бронирования товара
          example: 4
          type: integer
        details:
          description: Комментарий, который получит покупатель
          example: Могу передать товар с 13:00 до 18:00
          type: string
        id:
          description: ID заказа в Авито
          example: '5000000000000000'
          type: string
        marketplaceId:
          description: Номер заказа в Авито в новой системе
          example: '70000000000000000'
          type: string
      required:
      - id
      - marketplaceId
      - bookingPeriod
      type: object
    action:
      properties:
        name:
          description: Название действия
          enum:
          - setMarkings
          - setCNCDetails
          - setTrackNumber
          - fixTrackNumber
          - acceptReturnOrder
          - confirm
          - reject
          - perform
          - receive
          type: string
        required:
          description: Обязательность действия для продвижения заказа.
          type: boolean
      type: object
    terminalInfo:
      description: Информация о ПВЗ выбранном покупателем для доставки DBS
      nullable: true
      properties:
        address:
          description: Адрес ПВЗ
          example: Москва, Настасьинский 8 стр2 6
          nullable: true
          type: string
        code:
          description: Код ПВЗ
          example: MSK14
          nullable: true
          type: string
      t

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