openapi: 3.0.0
info:
contact:
email: supportautoload@avito.ru
description: 'API для взаимодействия с иерархией аккаунтов в Авито
**Авито API для бизнеса предоставляется согласно [Условиям использования](https://www.avito.ru/legal/pro_tools/public-api).**
'
title: Иерархия Аккаунтов Access DeliveryTariffication 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-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
TermsZone:
properties:
deliveryProviderZoneId:
description: Id зоны сроков на стороне службы доставки
example: z42
type: string
maxTerm:
description: Максимальный срок доставки в рабочих днях
example: 2
format: int32
type: integer
minTerm:
description: Минимальный срок доставки в рабочих днях
example: 1
format: int32
type: integer
name:
description: Человекопонятное название зоны (будет использоваться в интерфейсной части)
example: зона z42
type: string
type: object
DeliveryTariffZone-ServiceDeliveryC2CWithStepCost:
description: Описание модели тарификации какой-либо из услуг доставки
properties:
calculationMechanic:
description: 'Механика расчета стоимости, при которой указывается диапазон с начальной стоимостью, шагом и ценой за шаг.
'
enum:
- WEIGHT_INTERVALS
type: string
chargeableParameter:
description: 'При значении `WEIGHT` работает такая логика подсчета цены: cost + ((Вес товара - minWeight) / step с округлением вверх) * costPerStep
'
enum:
- WEIGHT
type: string
serviceName:
description: Услуга доставки
enum:
- DELIVERY
example: DELIVERY
type: string
values:
description: Список диапазонов весов с начальной стоимостью, шагом и ценой за шаг.
items:
properties:
cost:
description: Начальная стоимость доставки отправления в копейках, соответствующая диапазону весов от предыдущего значения maxWeight до текущего.
example: 20000
format: int32
type: integer
costPerStep:
description: Цена одного шага в копейках.
example: 5000
format: int32
type: integer
maxWeight:
description: Верхняя граница веса отправления (включительно) в граммах, до которой услуга доставки отправления не превышающего данный вес будет тарифицироваться.
example: 2000
format: int32
type: integer
minWeight:
description: Нижняя граница веса отправления в граммах, от которой отсчитывается количество шагов, цену которых необходимо добавить к начальной стоимости.
example: 1000
format: int32
type: integer
step:
description: Шаг веса в граммах, за который прибавляется значение `costPerStep` к конечной сумме доставки.
example: 100
format: int32
type: integer
type: object
type: array
required:
- serviceName
- calculationMechanic
- chargeableParameter
- values
title: Доставка C2C с шаговой ценой
type: object
DeliveryProviderAreaNumber:
description: "id области доставки на стороне службы доставки \n(передается при загрузке областей доставки и будет использоваться при создании заказа \nв качестве идентификатора адресного объекта забора/доставки отправления)\n"
example: 7989jgftyf-jkghtd
maxLength: 128
minLength: 1
type: string
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
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
DeliveryDayTimeInterval:
description: Интервал времени внутри одного дня `hh:mm:ss/hh:mm:ss`
example: 09:00:00/12:00:00
type: string
Schedule:
description: "Значения интервала времени в течение дня должны быть в диапазоне от `00:00:00` до `23:59:59`.\nИнтервал работы после полуночи необходимо переносить в следующий день недели.\n\nПравильно:\n - `\"fri\": [\"09:00:00/12:00:00\", \"13:00:00/18:00:00\"]` – расписание в пятницу с 9 до 18 с перерывом с 12 до 13\n - `\"sun\": []` – выходной в воскресенье\n\nНеправильно:\n - `\"mon\": [\"09:00/18:00\"]` – не хватает значения секунд\n - `\"tue\": [\"09:00:00/01:00:00\"]` – интервал заходит на следующий день\n - `\"wen\": [\"09:00:00/00:00:00\"]` – максимальное значение границы должно быть `23:59:59`\n"
properties:
fri:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
mon:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
sat:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
sun:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
thu:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
tue:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
wed:
$ref: '#/components/schemas/DeliveryDayTimeIntervals'
required:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
type: object
cutoffAndSchedule:
properties:
cutoff:
properties:
cutoffTime:
description: время катофа (время локальное - будет использована временая зона area)
example: '15:04:05'
format: hh:mm:ss
type: string
daysAfterCutoff:
description: 'количество дней, которые надо пропустить исходя из расписания, если сроки рассчитываются после времени указанного в cutoffTime.
1 - пропускаем один день.
'
example: 1
type: integer
daysBeforeCutoff:
description: 'количество дней, которые надо пропустить исходя из расписания, если сроки рассчитываются до времени указанного в cutoffTime.
0 - не пропускаются дни.
'
example: 0
type: integer
required:
- cutoffTime
- daysBeforeCutoff
- daysAfterCutoff
type: object
regularSchedule:
$ref: '#/components/schemas/Schedule'
required:
- cutoff
- regularSchedule
type: object
AddTaskReply:
properties:
data:
nullable: true
properties:
taskId:
description: "id задачи, по которому можно узнать результат выполнения операции используя \n[метод получения результата выполнения задачи](#operation/GetTask)\n"
format: int64
type: integer
type: object
error:
nullable: true
properties:
code:
description: код ошибки
example: fail
title: код ошибки
type: string
message:
description: человекопонятное описание ошибки
example: something went wrong
title: описание ошибки
type
# --- 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