Avito ParcelProcessing 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 ParcelProcessing API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- name: ParcelProcessing
  x-displayName: Процессинг посылок
  x-subdivName: Процессинг посылок
paths:
  /createParcel:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Метод реализуется на стороне службы доставки.


        Описание механики работы и дополнительные требования см. [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/sozdanie_posylki).

        '
      operationId: createParcel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateParcelRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateParcelResponse'
          description: Посылка создана / случилась ошибка.
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      summary: Создание посылки
      tags:
      - ParcelProcessing
  /delivery-sandbox/cancelParcel:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Метод должен быть имплементирован на стороне службы доставки.


        Описание механики работы и дополнительные требования см. [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/otmena_posylki).

        '
      operationId: cancelParcel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cancelParcelRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancelParcelReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      summary: Отмена посылки
      tags:
      - ParcelProcessing
  /delivery-sandbox/order/checkConfirmationCode:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Метод для проверки службой доставки кода подтверждения, который пользователь показал на пункте выдачи заказа.<br />


        ### Статус проверки кода

        | status      |       Значение                                |

        |-------------|-----------------------------------------------|

        |   success   | Код верный.                                   |

        |   fail      | Код неверный.                                 |

        |   expired   | Код подтверждения устарел.                    |

        |   attempts  | Превышено максимальное количество попыток.    |

        '
      operationId: checkConfirmationCode
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckConfirmationCodeRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckConfirmationCodeReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Проверка кода подтверждения
      tags:
      - ParcelProcessing
  /delivery-sandbox/order/properties:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Метод используется для отправки в Avito параметров, относящихся к доставке посылки. <br />

        В случае повторной передачи параметров, данные будут перезаписаны. <br />

        Важно передавать актуальные данные. Например, если конечная стоимость доставки заказа изменилась, нужно отправить ее заново. <br />


        ### Описание ошибок

        | http code |   error code         |       error message                               |

        |-----------|----------------------|---------------------------------------------------|

        |    200    |   ORDER_ID_INVALID   | Could not found order by id and provider name     |

        |    200    |   ORDER_ID_INVALID   | Incorrect order id                                |

        |    200    |   PROPERTIES_INVALID | Failed to get properties from request             |

        |    200    |   PROPERTIES_INVALID | Empty body                                        |

        |    200    |   PROPERTIES_INVALID | Dimensions array must have 3 element              |

        |    200    |   PROPERTIES_INVALID | Dimension must be greater than 0                  |

        |    200    |   PROPERTIES_INVALID | Weight must be greater than 0                     |

        |    200    |   PROPERTIES_INVALID | Delivery cost must be positive integer number     |

        |    200    |   PROPERTIES_INVALID | Forbidden terminal change in current order status |

        |    200    |   PROPERTIES_INVALID | Both terminals cannot be changed                  |

        '
      operationId: setOrderProperties
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliverySetOrderPropertiesRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliverySetOrderPropertiesReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Добавление / изменение параметров доставки посылки
      tags:
      - ParcelProcessing
  /delivery-sandbox/order/realAddress:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: "### Фактический ПВЗ приема\nФактический ПВЗ приема посылки посылки нужен Avito для работы как с [агентскими](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/agentskie_vozvraty), так и с [клиентскими](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/klientskie_vozvraty) возвратами. \nЕсли получатель посылки откажется от её получения \"на месте\", то Avito понадобится показать ПВЗ возврата\nотправителю, а этим ПВЗ будет фактический ПВЗ приема. Если же посылку нужно будет вернуть отправителю через клиентский \nвозврат, то для создания отдельной возвратной посылки Avito критически важно знать тот же фактический ПВЗ приема.<br/>\n\nПрисылайте адрес в момент приема посылки от отправителя или чуть позже, если нет возможности это делать сразу.<br/>\n\n### Фактический адрес возврата\nПВЗ, из которого забрали возврат.<br/>\n\n### Про повторные запросы\nВ случае повторной передачи новые данные будут записаны.<br/>\n\n### Описание ошибок\n| http code |   error code           |       error message                           |\n|-----------|------------------------|-----------------------------------------------|\n|    200    |   ORDER_ID_INVALID     | Could not found order by id and provider name |\n|    200    |   ORDER_ID_INVALID     | Incorrect order id                            |\n|    200    |   REAL_ADDRESS_INVALID | Failed to get real address from request       |\n|    200    |   REAL_ADDRESS_INVALID | Incorrect terminal type                       |\n|    200    |   REAL_ADDRESS_INVALID | Incorrect terminal number                     |\n"
      operationId: setOrderRealAddress
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliverySetRealAddressRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliverySetOrderPropertiesReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Фактический адрес приёма / возврата посылки
      tags:
      - ParcelProcessing
  /delivery-sandbox/order/tracking:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: '

        Метод для передачи информации по трекингу посылки от службы доставки в Avito.


        Механика работы и прочие важные моменты описаны в [разделе](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/treking).


        Обязательно ознакомьтесь и реализуйте [политику повторов запросов](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/politika_povtorov_v_trekinge).

        '
      operationId: tracking
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryTrackingRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliverySetStatusReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Трекинг
      tags:
      - ParcelProcessing
  /delivery-sandbox/prohibitOrderAcceptance:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Метод должен быть имплементирован на стороне службы доставки.


        Описание механики работы и дополнительные требования см. [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/zapret_priema_posylki).

        '
      operationId: prohibitOrderAcceptance
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/prohibitOrderAcceptanceRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/prohibitOrderAcceptanceReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      summary: Запрет приёма посылки от отправителя
      tags:
      - ParcelProcessing
  /delivery/order/changeParcelResult:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Описание механики изменения посылок [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/izmenenie_svoystv_posylok).


        Метод для передачи результата исполнения заявки, созданной с помощью метода [/changeParcels](#operation/ChangeParcels).


        ### Описание ошибок

        | http code |   error code         |       причина ошибки                                                                                                                                                 |

        |-----------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|

        |    200    | ID_INVALID           | “id” заявки невалидный.                                                                                                                                              |

        |    200    | NOT_FOUND            | заявка с “id” не найдена.                                                                                                                                            |

        |    200    | STATUS_INVALID       | заявка не может быть переведена в статус указанный в запросе.                                                                                                        |

        |    200    | FAILED_REASON_MISSES | отсутствует причина, по которой заявка не может быть исполнена. Данный код ошибки будет возвращен при статусе заявки declined и отсутствующем или пустом поле reason.|

        |    200    | PARCEL_CLOSED        | посылка, связанная с заявкой, уже неактивная (была получена, утеряна или ушла на возвратное движение).                                              |


        ### Порядок повторных попыток


        - ID_INVALID, NOT_FOUND: повторные отправки запросов не помогут, имеет место ошибка валидации номера заявки.

        - STATUS_INVALID: может помочь повтор с другим, корректным, статусом.

        - FAILED_REASON_MISSES: повторная отправка возможна после заполнения поля reason для заявки в статусе declined или отправки запроса со статусом approved.

        - PARCEL_CLOSED: нет смысла отправлять запрос повторно, данный код означает, что изменение свойства для посылки более не актуально так как посылка вручена или изменилось направление движение посылки.

        - HTTP 500: означает недоступность API, необходим повтор.



        ### Возможные причины для отклонения заявки и коды приведены в таблице


        | Тип заявки               |   reason code                   |       Описание                                                             |

        |--------------------------|---------------------------------|----------------------------------------------------------------------------|

        | prohibitParcelAcceptance | already_received                | Посылка уже была принята от продавца и запрет её приёма невозможен.        |

        | prohibitParcelAcceptance | parcel_not_found                | Посылка не найдена.                                                        |

        | prohibitParcelReceive    | already_received                | Посылка уже была вручена покупателю и запрет выдачи невозможен.            |

        | prohibitParcelReceive    | parcel_not_found                | Посылка не найдена.                                                        |

        | extendParcelStorage      | storage_period_already_exceeded | Продление срока хранения для посылки уже выполнялось.                      |

        | extendParcelStorage      | invalid_parcel_status           | Продление срока хранения невозможно в текущем состоянии (статусе посылки). |

        | extendParcelStorage      | parcel_not_found                | Посылка не найдена.                                                        |

        | любой                    | текст в свободной форме         | Причина отклонения, которая отличается от стандартизированных              |


        Для описанных сценариев важно использовать стандартизированные причины для отклонения заявки. Это может влиять на политику ретраев и другие внутренние процессы внутри Avito.

        Список стандартных причин может расширяться в будущем в зависимости от статистики использования и возникающих корнер-кейсов.

        '
      operationId: ChangeParcelResult
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeParcelResultRequest'
        description: Результат обработки заявки
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeParcelResultReply'
          description: Successful
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryError'
          description: Error
      summary: Отправка результата исполнения заявки
      tags:
      - ParcelProcessing
  /sandbox/changeParcels:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: 'Описание механики изменения посылок [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/izmenenie_svoystv_posylok).


        Метод реализуется на стороне службы доставки. Предназначен для обновления различных свойств посылок по инициативе Avito.

        '
      operationId: ChangeParcels
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeParcelsRequest'
        description: Создание заявок для обновления свойств посылок.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeParcelsResponse'
          description: Все заявки внутри транзакции зарегистрированы / случилась ошибка.
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      summary: Обновление свойств посылок
      tags:
      - ParcelProcessing
components:
  schemas:
    CreateParcelClientDeliverySecondPartyLogist:
      description: Информация o магистральном перевозчике. Актуально для кросс-доставки.
      properties:
        provider:
          description: Код службы доставки.
          type: string
      required:
      - provider
    ChangeParcelsResponse:
      properties:
        data:
          $ref: '#/components/schemas/ChangeParcelsData'
        error:
          $ref: '#/components/schemas/ChangeParcelsError'
    CheckConfirmationCodeRequest:
      properties:
        confirmCode:
          type: string
        parcelID:
          type: string
      required:
      - parcelID
      - confirmCode
      type: object
    prohibitOrderAcceptanceRequest:
      properties:
        orderId:
          $ref: '#/components/schemas/Delivery-orderId-string'
      required:
      - orderId
      type: object
    DeliverySetOrderPropertiesRequest:
      properties:
        orderId:
          $ref: '#/components/schemas/Delivery-orderId-string'
        properties:
          $ref: '#/components/schemas/Delivery-params'
      required:
      - orderId
      - properties
      type: object
    CreateParcelClient:
      description: 'Описание отправителя / получателя.

        '
      properties:
        delivery:
          $ref: '#/components/schemas/CreateParcelClientDelivery'
        email:
          description: Электронная почта.
          example: any_email@mail.com
          format: email
          maxLength: 320
          type: string
        inn:
          description: 'ИНН участника доставки (отправителя/получателя). Опциональное.


            Заполнятся только для отправителя/получателя с типом `LEGAL` для определенных сценариев доставки и партнеров.

            '
          example: '7727563778'
          type: string
        name:
          description: 'Наименование клиента.

            '
          example: Иванов Иван Иванович
          maxLength: 255
          type: string
        phones:
          description: 'Список телефонов для связи.


            Формат номеров телефона не регламентирован.

            '
          example:
          - '88005553535'
          - '79999999999'
          - '+79859991234'
          items:
            minLength: 1
            type: string
          type: array
        type:
          description: 'Тип отправителя.

            '
          enum:
          - PRIVATE
          - LEGAL
          - 3PL
          example: PRIVATE
          type: string
      required:
      - type
      - phones
      - email
      - name
      - delivery
    CreateParcelItemDimensions:
      properties:
        accuracy:
          $ref: '#/components/schemas/CreateParcelPropertyAccuracy'
        values:
          description: 'Габариты в сантиметрах.


            В порядке: длина, высота, ширина.

            '
          example:
          - 20
          - 20
          - 20
          items:
            maximum: 200
            minimum: 1
            type: integer
          maxLength: 3
          minLength: 3
          type: array
      required:
      - accuracy
      - values
    Delivery-eventDateTime:
      description: Дата и время события в UTC
      example: '1985-04-12T23:20:50.52Z'
      title: Дата и время в формате rfc3339 в UTC
      type: string
    CreateParcelOptions:
      properties:
        return:
          description: 'Опции возврата.


            Опции определяют политику возвратов. Доступен ли возврат, или что делать в определенных случаях.

            '
          properties:
            receiver:
              $ref: '#/components/schemas/CreateParcelClient'
            refused:
              $ref: '#/components/schemas/CreateParcelOptionsReturnPolicy'
            returned:
              $ref: '#/components/schemas/CreateParcelOptionsReturnPolicy'
            unclaimed:
              $ref: '#/components/schemas/CreateParcelOptionsReturnPolicy'
          type: object
        tags:
          description: "Список специфичных особенностей посылки.\n\nНа определенные значения в тегах можно завязывать логику. \nТе теги, которые вас, как службу доставки, не интересуют, игнорируйте.\nСписок может постоянно пополняться.\n"
          enum:
          - C2C
          - B2C
          - X_DELIVERY
          - X_DELIVERY_FIRST_LEG
          - X_DELIVERY_LAST_LEG
          - RETURN
          type: array
    DeliveryTrackingRequest:
      properties:
        avitoEventType:
          description: Описание статусов см. [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/mehanika_raboty_trekinga).
          example: RECEIVED_AT_TRANSIT_TERMINAL
          title: Событие
          type: string
        avitoStatus:
          description: Описание статусов см. [здесь](https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#info/mehanika_raboty_trekinga).
          enum:
          - CONFIRMED
          - IN_TRANSIT
          - ON_DELIVERY
          - DELIVERED
          - IN_TRANSIT_RETURN
          - ON_DELIVERY_RETURN
          - RETURNED
          - LOST
          - DESTROYED
          example: IN_TRANSIT
          title: Статус
        comment:
          description: Комментарий к статусу.
          example: Не понравился цвет
          title: Комментарий
          type: string
        date:
          $ref: '#/components/schemas/Delivery-eventDateTime'
        location:
          description: Локация в которой произошло событие (населённый пункт в именительном падеже).
          example: Казань
          title: Локация
          type: string
        options:
          description: 'Дополнительные опции к статусу. На данный момент в опциях поддержана передача штрихкода посылки и возвратных номеров.

            Если номера `returnTrackingNumber` и `returnDispatchNumber` совпадают, то нужно присылать в них одинаковые значения.

            '
          properties:
            barcode:
              description: Штрихкод посылки.
              title: Штрихкод посылки
              type: string
            returnBarcode:
              description: Возвратный штрихкод посылки. Будет использоваться в кросс-доставке на возвратном потоке.
              title: Возвратный штрихкод
              type: string
            returnDispatchNumber:
              description: Номер, по которому отправитель может получить возвратную посылку.
              title: Возвратный номер получения посылки
              type: string
            returnTrackingNumber:
              description: Номер, по которому отправитель может отследить возвратную посылку.
              title: Возвратный трек-номер
              type: string
          type: object
        orderId:
          $ref: '#/components/schemas/Delivery-orderId-string'
        providerEventCode:
          description: Код события по версии службы доставки.
          example: 3246м4
          title: Код события по версии службы доставки
          type: string
      required:
      - orderId
      - avitoStatus
      - avitoEventType
      - providerEventCode
      - date
      - location
      type: object
    CreateParcelClientDeliveryTerminal:
      description: 'Актуально, если доставка будет осуществляться из / в пункт выдачи заказов.

        '
      properties:
        accuracy:
          $ref: '#/components/schemas/CreateParcelPropertyAccuracy'
        id:
          description: Идентификатор ПВЗ по версии службы доставки владельца.
          example: '123'
          type: string
        provider:
          description: Идентификатор службы доставки владельца ПВЗ.
          example: exmail
          type: string
      required:
      - provider
      - id
      - accuracy
    Delivery-terms:
      properties:
        cost:
          $ref: '#/components/schemas/Cost'
        directControlDate:
          $ref: '#/components/schemas/Delivery-directControlDate'
        receiverTerminalCode:
          $ref: '#/components/schemas/Delivery-receiverTerminalCode'
        returnControlDate:
          $ref: '#/components/schemas/Delivery-returnControlDate'
        senderReceiveTerminalCode:
          $ref: '#/components/schemas/Delivery-senderReceiveTerminalCode'
        toughWrap:
          $ref: '#/components/schemas/Delivery-toughWrap'
      title: Условия доставки
      type: object
    Delivery-directControlDate:
      description: 'Контрольная дата доставки для прямого потока в UTC. <br />

        Используется для посылок в статусе `IN_TRANSIT`

        '
      example: '1985-04-12T23:20:50.52Z'
      title: Контрольная дата доставки для прямого потока rfc3339 в UTC
      type: string
    CreateParcelPackage:
      properties:
        dimensions:
          $ref: '#/components/schemas/CreateParcelItemDimensions'
        weight:
          $ref: '#/components/schemas/CreateParcelItemWeight'
      required:
      - dimensions
      - weight
    CheckConfirmationCodeReply:
      properties:
        data:
          properties:
            status:
              enum:
              - success
              - fail
              - expired
              - attempts
              type: string
          type: object
      type: object
    Delivery-toughWrap:
      description: 'При передачи признака важно учитывать, что он необязательный. <br />

        Это означает, что не смотря на тип boolea

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