Avito DeliveryTariffication API

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

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

    '
  title: Иерархия Аккаунтов Access Delivery Tariffication API
  version: '1'
servers:
- url: https://api.avito.ru/
tags:
- name: DeliveryTariffication
  x-displayName: Тарификация
  x-subdivName: Тарификация
paths:
  /delivery-sandbox/tariffs/{tariff_id}/areas:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - description: id тарифа, к которому должны быть прикреплены добавляемые области
      in: path
      name: tariff_id
      required: true
      schema:
        format: int32
        type: integer
    post:
      description: 'Метод позволяет загрузить области, в которых возможна услуга курьерской доставки/забора

        В качестве классификатора адресов используются индесы Почты России, то есть в 1 индекс включаются все адреса,

        которые к нему относятся.


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

        | http code |   error code      |       error message                                       |

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

        |    200    | URL_PATH_INVALID  | Tariff id must be int url path                            |

        |    200    | TERMINALS_INVALID | Failed to convert areas: {error description}          |

        |    200    | TERMINALS_INVALID | Failed to get terminals from request: {error description} |

        '
      operationId: AddAreasSandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAreasRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddTariffReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Загрузить области доставки
      tags:
      - DeliveryTariffication
  /delivery-sandbox/tariffs/{tariff_id}/terms:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    - description: id тарифа, к которому должны быть прикреплены добавляемые области
      in: path
      name: tariff_id
      required: true
      schema:
        format: int32
        type: integer
    post:
      description: "Создание задачи на обновление сроков в тарифе. Подробнее про сроки можно почитать в разделе загрузки тарифа https://developers.avito.ru/api-catalog/delivery-sandbox/documentation#operation/AddTariffSandboxV2.  \n\nВажно ! Список новых сроков должен полностью соответствовать по deliveryProviderZoneId и name списку сроков, переданному при создании тарифа.\nТ.е. необходимо перечислить все те же deliveryProviderZoneId и name, но можете поменять сроки (maxTerm и/или minTerm).\nЕсли в какой-то зоне сроки не меняются, то необходимо все равно передать ее в исходном виде (без изменения в maxTerm и minTerm.\nПри загрузке неполного списка обновление сроков упадет с ошибкой (об этом узнать можно будет через [метод получения результата выполнения задачи](#operation/GetTask))\n\n### Описание ошибок\n| http code |   error code                  |       error message                                                   |\n|-----------|-------------------------------|-----------------------------------------------------------------------|\n|    200    | INVALID_ENTITY                | Не удалось декодировать тело запрос, проверьте структуру              |\n|    200    | INVALID_ENTITY                | Передан пустой список                                                 |\n|    200    | INVALID_ENTITY                | Не указан или указан невалидный tariff_id, должно быть передано число |\n|    200    | INVALID_ENTITY                | Передан tariff_id равный 0                                            |\n|    500    | FAILED_TO_UPDATE_TERMS        | Ошибка обработки сроков                                               |\n\nИтоговый результат операции необходимо проверять через:  \n[метод получения результата выполнения задачи](#operation/GetTask)\n"
      operationId: UpdateTerms
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTermsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTermsReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Обновить сроки по тарифу
      tags:
      - DeliveryTariffication
  /delivery-sandbox/tariffsV2:
    parameters:
    - $ref: '#/components/parameters/authHeader'
    post:
      description: "\nНефункциональные требования:\n\nМаксимальный размер тела запроса - 400MB<br/>\nМаксимальное количество направлений - 1 миллион\n\nМетод позволяет службам доставки самостоятельно управлять:\n  1. Доступностью направлений доставки\n  2. Стоимостью доставки по каждому из направлений\n  3. Сроками доставки по каждому из направлений\n\n## Используемые термины:\n\n- **Пункт выдачи заказов (ПВЗ)(Terminal)** - место, в котором в зависимости от списка предоставляемых услуг пользователь может сдать/получить/вернуть посылку\n\n- **Область доставки (Area)** - зона (список индексов Почты России), в которой осуществляется курьерская доставка/забор посылок\n\n- **Хаб/Сортировочный центр (SortingCenter)** - место, где сортируются посылки для дальнейшей отправки в ПВЗ (используется для кросс-доставки)\n\n- **Тэг направления(Tag)** - используется для объединения в группу ПВЗ/Областей доставки/Сортировочных центров\n    является свойством объекта ПВЗ или области доставки.\n\n    Допускается распределять тэги по ПВЗ/Областям доставки/Сортировочным центрам любым образом, при этом наиболее распространенным критерием для тэгирования является географическая близость ПВЗ/Областей доставки/Сортировочных центров друг к другу или принадлежность к одному административному субъекту.\n\n- **Тарифная зона доставки(TariffZone)** - список правил и параметров необходимых для расчета стоимости различных услуг, которые будут оказаны в процессе доставки заказа, в том числе с разделением на C2C и B2C.\n    Сумма стоимостей по всем услугам перечисленным в тарифной зоне равна расчетной стоимости, которую Авито заплатит службе доставки за доставку заказа.\n    Важно отметить, что допускается загрузка только уникальных тарифных зон - то есть, в одном тарифе не может существовать двух тарифных зон с одинаковыми значениями поля *items*\n\n- **Зона сроков доставки(TermsZone)** - список правил и параметров необходимых для расчета сроков доставки.\n    Как минимальный, так и максимальный срок передаются в рабочих днях.\n    Важно отметить, что допускается загрузка только уникальных зон сроков доставки - то есть, в одном тарифе не может существовать двух зон сроков доставки с одинаковыми значениями поля *minTerm* и *maxTerm*\n\n- **Направление доставки(Direction)** - объект определяющий возможность доставки из directionTagFrom (группа ПВЗ / список индексов_Почты_России в случае курьерской доставки), в directionTagTo (группу ПВЗ / список индексов_Почты_России в случае курьерской доставки).\n    При этом направление так же определяет условия, на которых доставка будет осуществляться: тарифную зону и сроки доставки\n\n- **Тарифный план(Tariff)** - список всех возможных направлений доставки, действующий на определенном интервале времени (например, до подписания договора об изменении тарифов)\n\n## Диаграмма связей между используемыми объектами:\n\n<img src=\"https://www.avito.st/s/avito/components/api-description/delivery/images/tariff_diagram_v2.svg\" />\n\n### Инсталляция (первое добавление службой доставки тарифов):\n>1. [Создать тариф](#operation/AddTariffSandboxV2)\n>Для каждого направления в тарифе нужно указать те типы доставки, которые по нему доступны.\n>2. Загрузить [ПВЗ](#operation/AddTerminalsSandbox)/[Области_доставки](#operation/AddAreasSandbox) и свои [сортировочные центры](#operation/AddSortingCenter), если требуется\n--\n\n*Дополнительно для подключения к кросс доставке:*  \n>3. [Скачать чужие сортировочные центры](#operation/GetSortingCenter)  \n>4. Установить чужим сортировочным центрам тэги из своего тарифа, который был загружен на шаге 1  \n>5. [Загрузить чужие сортировочные центры с тэгами из своего тарифа](#operation/AddTagsToSortingCenter)  \n\n#### Схема работы кросс доставочного тарифа\n\n<img src=\"https://avito.st/static/ims/1a890394-cde9-49cf-b2e0-dd5b00dd9a97_new_xdelivery_common_2490x1380.png\" />\n\n### Бесшовное обновление тарифа\n\nПри использовании данного подхода к обновлению тарифа отсутствует момент даунтайма - то есть отсутствия ПВЗ/Областей_доставки службы доставки на карте Авито.\n  1. Необходимо загрузить новый тариф и сообщить номер залитого тарифа вашему менеджеру по логистике в Авито\n    - Для загрузки тарифа используется [метод загрузки тарифа](#operation/AddTariffSandbox)\n    - Для получения результата загрузки тарифа используется [метод получения результата выполнения задачи](#operation/GetTariffTaskSandbox). Необходимо убедиться в отсутствии ошибок загрузки тарифа\n  2. Дождаться пока ваш менеджер подтвердит, что загруженные данные корректны\n  3. Добавить к загруженному выше тарифу ПВЗ/Области доставки/Сортировочные центры\n    - Для загрузки ПВЗ используется [метод загрузки ПВЗ](#operation/AddTerminalsSandbox). Важно учесть, что в URL необходимо указать id загруженного на предыдущем этапе тарифа\n    - Для получения результата загрузки ПВЗ используется [метод получения результата выполнения задачи](#operation/GetTerminalsTaskSandbox). Необходимо убедиться в отсутствии ошибок загрузки ПВЗ\n  4. Сообщить вашему менеджеру по логистике в Авито о том, что ПВЗ к тарифу успешно загружены\n\n### Дополнительная валидация\n\nЕсли существует направление `тег 1` -> `тег 2` S-PUDO2S-PUDO, то **обязательно** должно существовать направление `тег 2` -> `тег 1` S-PUDO2S-PUDO для возможности возврата товара. \nВ таком случае при обработке задачи на загрузку тарифа будет ошибка вида `X directions have no reverse direction. Each tag1->tag2 S-PUDO2S-PUDO must have tag2->tag1 S-PUDO2S-PUDO direction as reverse.` Ошибка будет получена в [методе получения информации о задаче](#operation/GetTask). \n\n\n### Описание ошибок\n| http code |   error code   |       error message                                      |\n|-----------|----------------|----------------------------------------------------------|\n|    200    | INVALID_ENTITY | Failed to convert entities: {error description}          |\n|    200    | INVALID_ENTITY | Failed to get entities from request: {error description} |\n"
      operationId: AddTariffSandboxV2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTariffRequestV2'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddTaskReply'
          description: OK
        '401':
          $ref: '#/components/responses/DeliveryUnauthorized'
        '403':
          $ref: '#/components/responses/DeliveryForbidden'
        '500':
          $ref: '#/components/responses/DeliveryInternalServerError'
      security:
      - ClientCredentials: []
      summary: Загрузить новый тариф v2
      tags:
      - DeliveryTariffication
components:
  schemas:
    DeliveryTariffZone-ServiceInsuranceC2C:
      description: Описание модели тарификации какой-либо из услуг доставки
      properties:
        calculationMechanic:
          description: Механика расчета стоимости
          enum:
          - GAP_TO_PERCENT
          type: string
        chargeableParameter:
          enum:
          - DECLARED_COST
          example: DECLARED_COST
          type: string
        serviceName:
          enum:
          - INSURANCE
          example: INSURANCE
          type: string
        values:
          description: Список значений для рассчета страховки.
          items:
            properties:
              maxDeclaredCost:
                description: Верхняя граница объявленной стоимости отправления (в копейках), до которой (не включительно) услуга страховки отправления не превышающего данную стоимость будет тарифицироваться в соответствии со значением указанным в поле percent
                example: 10000
                format: int32
                type: integer
              percent:
                description: Процент от объявленной стоимости, по которому рассчитывается стоимость страховки отправления в диапазоне от предыдущего maxDeclaredCost до текущего
                example: 1
                format: float
                type: number
            type: object
          type: array
      required:
      - serviceName
      - calculationMechanic
      - chargeableParameter
      - values
      title: Страховка C2C
      type: object
    DeliveryError:
      properties:
        code:
          description: код ошибки
          example: fail
          title: код ошибки
          type: string
        message:
          description: Человекопонятное описание ошибки
          example: something went wrong
          title: описание ошибки
          type: string
      required:
      - code
      - message
      type:
      - object
      - 'null'
    Area:
      properties:
        deliverySchedule:
          allOf:
          - $ref: '#/components/schemas/cutoffAndSchedule'
          - description: описание регулярного расписания по доставке заказов в текущей области
        directionTag:
          $ref: '#/components/schemas/Delivery-directionTag'
        intakeSchedule:
          allOf:
          - $ref: '#/components/schemas/cutoffAndSchedule'
          - description: описание регулярного расписания по доставке заказов в текущей области
        providerAreaNumber:
          $ref: '#/components/schemas/DeliveryProviderAreaNumber'
        restrictions:
          allOf:
          - $ref: '#/components/schemas/Restriction'
          - description: Максимальные ограничения для данной области для услуг доставки/забора заказа
        services:
          description: Доступные в области услуги. Забор (intake), доставка (delivery)
          items:
            enum:
            - intake
            - delivery
            type: string
          type: array
        utcTimezone:
          description: UTC зона области досатвки
          example: 1
          type: string
        zipCodes:
          description: список почтовых индексов входящих в данную зону доставки (область курьерской доставки/забора)
          items:
            $ref: '#/components/schemas/Delivery-zipCode'
          minLength: 1
          type: array
      required:
      - directionTag
      - providerAreaNumber
      - services
      - utcTimezone
      - zipCodes
      - restrictions
      type: object
    Delivery-zipCode:
      example: '324654'
      title: Почтовый индекс. Не может быть пустым. Должен содержать 6 цифр.
      type: string
    DeliveryTariffZone-ServiceDeliveryC2C:
      description: Описание модели тарификации какой-либо из услуг доставки
      discriminator:
        mapping:
          DIMENSIONS: '#/components/schemas/DeliveryTariffZone-ServiceDeliveryC2CByDimension'
          PAID_WEIGHT: '#/components/schemas/DeliveryTariffZone-ServiceDeliveryC2CByPaidWeight'
          WEIGHT: '#/components/schemas/DeliveryTariffZone-ServiceDeliveryC2CByWeight'
        propertyName: chargeableParameter
      properties:
        calculationMechanic:
          description: 'Механика расчета стоимости <br />

            `GAP_TO_COST` - Механизм расчета при которой в зависимости от параметров отправления подбирается минимально возможное значение параметра `chargeableParameter` и соответствующая ему стоимость доставки

            '
          enum:
          - GAP_TO_COST
          type: string
        chargeableParameter:
          description: "Параметр, относительно которого расчитывается стоимость доставки отправления\n<br />\n  `WEIGHT` - Расчет относительно веса отправления<br />\n  `DIMENSIONS` - Расчет относительно габаритов отправления<br />\n  `PAID_WEIGHT` - Расчет относительно платного веса (большего из реального и объемного весов)<br />\n"
          enum:
          - WEIGHT
          - DIMENSIONS
          - PAID_WEIGHT
          example: WEIGHT
          type: string
        serviceName:
          description: Услуга доставки C2C
          enum:
          - DELIVERY
          example: DELIVERY
          type: string
      required:
      - serviceName
      - calculationMechanic
      - chargeableParameter
      title: Доставка C2C
      type: object
    DeliveryTariffZone-ServiceInsuranceB2C:
      description: Описание модели тарификации какой-либо из услуг доставки
      properties:
        calculationMechanic:
          description: Механика расчета стоимости
          enum:
          - GAP_TO_PERCENT
          type: string
        chargeableParameter:
          enum:
          - DECLARED_COST
          example: DECLARED_COST
          type: string
        serviceName:
          enum:
          - INSURANCE_B2C
          example: INSURANCE_B2C
          type: string
        values:
          description: Список значений для рассчета страховки.
          items:
            properties:
              maxDeclaredCost:
                description: Верхняя граница объявленной стоимости отправления (в копейках), до которой (не включительно) услуга страховки отправления не превышающего данную стоимость будет тарифицироваться в соответствии со значением указанным в поле percent
                example: 10000
                format: int32
                type: integer
              percent:
                description: Процент от объявленной стоимости, по которому рассчитывается стоимость страховки отправления в диапазоне от предыдущего maxDeclaredCost до текущего
                example: 1
                format: float
                type: number
            type: object
          type: array
      required:
      - serviceName
      - calculationMechanic
      - chargeableParameter
      - values
      title: Страховка B2C
      type: object
    AddTariffReply:
      properties:
        data:
          properties:
            taskId:
              description: id задачи на добавление тарифа, по которому узнать статус загрузки тарифа
              format: int32
              type: integer
          type:
          - object
          - 'null'
        error:
          $ref: '#/components/schemas/DeliveryError'
      type: object
    Zone:
      properties:
        tariffZoneId:
          description: Идентификатор [тарифной зоны](#tag/AvitoDeliveryTariffZone); ссылается на один из объектов в поле tariffZones
          example: t42
          type: string
        termsZoneId:
          description: Идентификатор [зоны сроков](#tag/AvitoDeliveryTariffZone); ссылается на один из объектов в поле termsZones
          example: z42
          type: string
        type:
          description: "Буквенные обозначения типа являются DEPRECATED, используйте числовые обозначения.<br /><br />\nТип доставки, которую описывают данные условия\n<br />\n  `0` - `S-PUDO2S-PUDO`: Доставка из собственных ПВЗ в собственные ПВЗ. Обратите внимание, что если существует направление `тег 1` -> `тег 2` S-PUDO2S-PUDO, то **обязательно** должно существовать направление `тег 2` -> `тег 1` S-PUDO2S-PUDO для возможности возврата товара<br /><br />\n  `3` - `S-AREA2S-AREA`: Доставка из собственной области доставки в собственную область доставки<br /><br />\n  `4` - `S-PUDO2S-AREA`: Доставка из собственных ПВЗ в собственные области доставки<br /><br />\n  `5` - `S-PUDO-BTW-F-HUB`: Доставка из своего ПВЗ в чужой ХАБ на прямом потоке или из чужого ХАБа в свой ПВЗ на обратном потоке<br />\n                  (тут важно обратить внимание, что только одна зона может быть установлена для одного tagFrom, \n                  что эквивалентно тому, что один свой ПВЗ может быть связан только с одним ХАБом чужой службы доставки)<br /><br />\n  `6` - `S-HUB-BTW-S-PUDO`: Доставка из своего ХАБа в свой ПВЗ на прямом потоке или из своего ПВЗ в свой ХАБ на обратном потоке<br /><br />\n"
          enum:
          - '0'
          - '3'
          - '4'
          - '5'
          - '6'
          - S-PUDO2S-PUDO
          - S-AREA2S-AREA
          - S-PUDO2S-AREA
          - S-PUDO-BTW-F-HUB
          - S-HUB-BTW-S-PUDO
          example: '0'
          type: string
      type: object
    UpdateTermsReply:
      properties:
        data:
          properties:
            taskId:
              format: int32
              type: integer
          required:
          - taskId
          type: object
        error:
          $ref: '#/components/schemas/DeliveryError'
      type: object
    DeliveryTariffZone-ServiceDeliveryB2C:
      description: Описание модели тарификации какой-либо из услуг доставки
      discriminator:
        mapping:
          DIMENSIONS: '#/components/schemas/DeliveryTariffZone-ServiceDeliveryB2CByDimension'
          PAID_WEIGHT: '#/components/schemas/DeliveryTariffZone-ServiceDeliveryB2CByPaidWeight'
          WEIGHT: '#/components/schemas/DeliveryTariffZone-ServiceDeliveryB2CByWeight'
        propertyName: chargeableParameter
      properties:
        calculationMechanic:
          description: 'Механика расчета стоимости <br />

            `GAP_TO_COST` - Механизм расчета при которой в зависимости от параметров отправления подбирается минимально возможное значение параметра `chargeableParameter` и соответствующая ему стоимость доставки

            '
          enum:
          - GAP_TO_COST
          type: string
        chargeableParameter:
          description: "Параметр, относительно которого расчитывается стоимость доставки отправления\n<br />\n  `WEIGHT` - Расчет относительно веса отправления<br />\n  `DIMENSIONS` - Расчет относительно габаритов отправления<br />\n  `PAID_WEIGHT` - Расчет относительно платного веса (большего из реального и объемного весов)<br />\n"
          enum:
          - WEIGHT
          - DIMENSIONS
          - PAID_WEIGHT
          example: WEIGHT
          type: string
        serviceName:
          description: Услуга доставки B2C
          enum:
          - DELIVERY_B2C
          example: DELIVERY_B2C
          type: string
      required:
      - serviceName
      - calculationMechanic
      - chargeableParameter
      title: Доставка B2C
      type: object
    Restriction:
      properties:
        dimensionalFactor:
          description: "Используется при подсчете ограничения по объемному весу в пункте выдачи по формуле: Д * Ш * В / dimensionalFactor = объемный вес. \nЕсли задан maxDimensionalWeight, то dimensionalFactor должен быть обязательно передан.\n"
          example: 1000
          format: int32
          maximum: 100000
          minimum: 1000
          type: integer
        maxDeclaredCost:
          description: "Максимальное ограничения по объявленной стоимости товара, который можно получить/отправить в пункте выдачи. Значение указывается в копейках.  \nЕсли объявленная стоимость товара будет больше этого значения, Авито посчитает невозможным отправку/получение товара через этот пункт\nи не даст покупателю выбрать его как точку доставки/сдачи посылки.\n"
          example: 1000
          format: int32
          maximum: 15000000
          minimum: 1000
          type: integer
        maxDimensionalWeight:
          description: "Максимальное ограничения по объемному весу товара, который можно получить/отправить в пункте выд�

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