Документация API КОРВ
Версия 1 · Схема OpenAPI · Swagger UI
Подбор нового состава
POST /api/v1/korv/catalog/select— предварительный подбор типоразмеров и формирование обозначения.GET /api/v1/korv/catalog/sizes— габариты из каталога.GET /api/v1/korv/catalog/glands— коды из каталога и диапазоны диаметров кабелей.GET /api/v1/korv/catalog/components— модели клемм и вводов, размеры, артикулы и ссылки на документы производителей. Параметрbox_executionпозволяет отфильтровать вводы по списку для корпуса.
В запросах к справочникам укажите box_execution=industrial для КОРВ-У или box_execution=ex для КОРВ-В. Для подбора отправьте JSON. Размеры в примере условные.
{
"box_execution": "industrial",
"material": "aisi316l",
"climate": "УХЛ1",
"nominal_voltage_v": 400,
"terminals": [
{"kind": "feed_through", "connection": "screw", "section_mm2": 2.5,
"count": 8, "width_on_rail_mm": 6.2},
{"kind": "pe", "connection": "screw", "section_mm2": 2.5,
"count": 1, "width_on_rail_mm": 6.2}
],
"glands": [
{"side": "B", "code": "PG16M", "count": 4,
"span_along_side_mm": 30, "span_across_depth_mm": 28}
],
"mounting": {
"rail_allowance_mm": 20,
"terminal_zone_l_mm": 110,
"terminal_zone_k_mm": 78,
"gland_side_allowance_mm": 20,
"gland_depth_allowance_mm": 15
}
}
Поля width_on_rail_mm и span_along_side_mm задают монтажную ширину клеммы и шаг одного ввода. span_across_depth_mm — ширина посадочной зоны ввода вдоль K. Зоны клемм по L и K включают проводку, расстояния до стенок и крепёж. Запасы вводятся для каждого ряда целиком, а не на одну деталь. Рейки идут вдоль H. Клеммы с разным rail занимают разные рейки, значение по умолчанию — 1.
Подбор по артикулам
Для клеммы из справочника достаточно {"model_id":"3044131","count":4}. Для ввода укажите также сторону, например {"model_id":"goreltex-knvm2m-20nk-r","side":"B","count":3}. API подставит параметры изделия. Для ввода можно передать большие значения span_along_side_mm и span_across_depth_mm, если нужны дополнительные зазоры. body_envelope_mm берётся с чертежа корпуса ввода. Отверстие, контргайка, доступ для инструмента, проводка и соответствие условиям эксплуатации проверяются отдельно.
Поле max_dimensions ограничивает наружные размеры корпуса по всем трём осям. Для стали с покрытием передайте ral, для нержавеющей стали опустите его. При наличии order_number он добавляется в конец обозначения через подчёркивание.
preliminary_match—candidates[0]имеет наименьший наружный объём. Каждый вариант содержитdesignation.missing_mounting_data— заполните поля изmissing_fields. Массив вариантов пуст.no_catalog_size— подходящего типоразмера нет. Сверьтеrequired_dimensionsи ограничения места установки.
У этих трёх результатов HTTP 200. dimension_checks показывает вклад каждого ограничения в H, L или K. HTTP 422 означает ошибку в параметрах запроса. Подбор возвращает черновое обозначение и не создаёт запись в архиве. Согласуйте внутреннюю компоновку и оформите бланк-заказ до изготовления.
Общая коробка на два двигателя
POST /api/v1/korv/catalog/two-motor/select принимает параметры общего корпуса и две записи branches. У каждой записи свой tag, свои terminals, glands и mounting. Номера DIN-реек задаются внутри ветви. Пример запроса.
layout: "along_h" размещает зоны слева направо, "along_l" — сверху вниз. Задайте запас separation_mm по оси размещения. Размеры зон суммируются по этой оси с учётом запаса. По двум оставшимся осям используются максимумы. При along_h первая ветвь использует A/B/C, вторая A/B/D. При along_l первая использует A/C/D, вторая B/C/D. Вводы на общей стороне учитываются на отдельных участках этой стороны, каждый в своей зоне.
Ответ содержит общий требуемый габарит, расчёт каждой ветви и общие типоразмеры в candidates. Строка обозначения описывает суммарный состав. В бланке состав каждой ветви приведён отдельно. Расчёт предварительный и требует проверки компоновки по чертежу.
Бланк-заказ в Excel и PDF
POST /api/v1/korv/orders/xlsx и POST /api/v1/korv/orders/pdf принимают одинаковый JSON. При успехе ответ содержит файл и заголовок Content-Disposition: attachment. Пример полного запроса для архивной коробки.
- Для архивной коробки передайте
configuration.mode: "archive"иconfiguration.configuration_id. - Для новой коробки передайте
configuration.mode: "catalog", исходный запрос подбора вconfiguration.selectionи выбранныйconfiguration.size_code. Сервер повторно проверяет типоразмер. - Для двух двигателей передайте
configuration.mode: "two_motor", исходный запрос двухветочного подбора вconfiguration.selectionиconfiguration.size_code. Соединения и нумерацию клемм можно приложить готовой схемой. - Реквизиты бланка передайте в
order. Вpositionsу каждой позиции естьquantity, списокtagsи необязательныйline_number. Номер позиции, а при его отсутствии номер бланка, дописывается к обозначению. terminal_blocksзадаёт колодки поимённо. У каждой колодки указываютсяnameи массивpointsсlabel,kindиsection_mm2. Сумма должна совпадать с составом выбранной коробки.
Схема колодок показывает маркировки и сечения. Поля wiring_drawing и mounting_drawing содержат номера и редакции проектных чертежей. Сами файлы включаются в комплект ZIP.
Для неизвестной архивной конфигурации API возвращает HTTP 404. Для противоречивых реквизитов, неверной раскладки колодок или неподходящего типоразмера — HTTP 422. Прикладная причина находится в detail.code и detail.message.
Комплект с чертежами
POST /api/v1/korv/orders/package принимает реквизиты того же заказа и массив drawings. Укажите имя файла filename без пути и его байты в content_base64 без префикса data:. Ответ — ZIP с Excel, PDF и исходными файлами в папке drawings/.
Допускаются PDF, DWG, DXF, PNG и JPEG. До 8 файлов, до 10 МиБ на файл и 20 МиБ в сумме. Повторяющиеся имена нумеруются. При превышении предела запроса или суммарного размера сервер отвечает HTTP 413.
Быстрый подбор от двигателя
POST /api/v1/korv/quick/check возвращает паспортный или оценочный ток, статус журнала заказчика и отдельные результаты в matches с идентификаторами customer и factory. Для двигателя укажите model или power_kw. Поле rated_current_a имеет приоритет. Для оценки тока по мощности на валу нужны voltage_v, phases (1 или 3), efficiency_pct и power_factor.
{
"motor": {"power_kw": 2.2, "voltage_v": 400, "phases": 3,
"efficiency_pct": 88, "power_factor": 0.8},
"box_execution": "industrial",
"customer_journal": "absent",
"factory_cable": {"role": "factory_out", "construction": "unarmored",
"routing": "metal_hose", "outer_diameter_mm": 7, "hose_dn_mm": 15}
}
customer_journal принимает provided, absent или unknown. Поля customer_cable и factory_cable можно опустить до получения данных. Ответ укажет, какие данные о кабеле нужны для подбора. Значения сечения и диаметра задаются по проекту или документации кабеля.
Данные модулей оборудования
Передайте use_kvark_motor: true для точной модели двигателя Уралэлектро АДЭМ из КВАРК-ЭВО, например 63A2. Если rated_current_a отсутствует и запись однозначна, current.status будет catalog, а motor_source покажет источник для исполнения 400 В. При отсутствии записи, конфликте параметров или сбое каталога пояснение приходит в motor_note.
GET /api/v1/korv/quick/equipment/factory-cables перечисляет цепи AeroWall с источником. Передайте factory_profile_id, например aerowall-800-water-control. resolved_factory_cable содержит объединённые данные. Если в источнике нет Ø, укажите factory_cable.outer_diameter_mm по паспорту или замеру конкретного кабеля. Рекомендации по вводу появятся после заполнения монтажных данных.
Кнопка в КВАРК-ЭВО открывает /#quick?equipment=kvark&model=<catalog-id>. Идентификатор кодируется через URLSearchParams. КОРВ загружает сведения о точной позиции через GET /api/v1/korv/quick/equipment/kvark?model=.... Этот запрос возвращает 404 для неизвестной позиции и 503 при недоступности модуля.
Переход из AeroWall передаёт equipment=aerowall, model, series (800 или 1000), heating (no_heat, electric или water) и, если цепь известна, circuit (power или control). Без выбранной цепи КОРВ предлагает подходящие цепи. Для других завес передаётся equipment=curtains и model.
GET /api/v1/korv/quick/equipment/curtains?model=... принимает код заказа завесы и возвращает подтверждённые поля комплектации и их источники. rated_current_a относится к одному двигателю. fan_model обозначает вентилятор в сборе. Пустые поля означают, что для кода нет подтверждённых данных.
motor_count содержит число двигателей, если оно подтверждено. Значение connection_scheme: "ex_individual" означает отдельное подключение каждого двигателя взрывозащищённой завесы. Для неё общая коробка на все двигатели не применяется. При "factory_daisy_chain" кабель заказчика подключается к крайнему вентилятору, а вентиляторы соединены на заводе шлейфом через свои КК. Подбор и проект журнала в этом случае содержат одну внешнюю строку customer.
Для подбора и выгрузки журнала передайте тот же код в curtain_model. Поле motor может быть пустым объектом. При наличии factory в ответе используйте factory.id как factory_profile_id. Ручной паспортный ток и выбранная комплектация сохраняют свои источники в ответе и журнале.
POST /api/v1/korv/quick/journal.xlsx принимает те же данные и необязательные customer_model_id, factory_model_id из кандидатов. Возвращает проект журнала Excel с отметками о недостающих данных, даже если вводы ещё не подобраны.
Подбор по всем двигателям Ex-завесы
Для подтверждённых AeroGuard 700 В/ВК справочник завес возвращает motor_count и ex_motor_line. Заводская схема указывает отдельную линию L1, L2, L3, PE на каждый двигатель. Наружный диаметр, тип кабеля, трассу и присоединительную резьбу берите из проекта и документации точки подключения.
У AeroBlast Ex один двигатель. По схеме подключения указаны U1, V1, W1, PE и трёхфазное питание 400 В, 50 Гц. Параметры кабеля вводятся по проектной документации.
POST /api/v1/korv/quick/ex-motors/check с телом {"curtain_model":"AeroGuard-730W03BK"} создаёт по одной строке на двигатель. Для уточнения отправьте массив motors длиной по комплектации. Каждый элемент содержит tag, объект cable с ролью customer_in и необязательный gland_id из кандидатов этой линии.
POST /api/v1/korv/quick/ex-motors/specification.xlsx принимает тот же запрос и возвращает одну спецификацию Excel. Незаполненные строки помечены для уточнения. Вводы проверяются заново при скачивании. Тип и место установки корпуса определяются проектной схемой.
Кабельный журнал
В новом подборе можно добавить объект cable в каждую группу glands. Для общей коробки это branches[].glands[].cable. Все кабели в группе имеют одинаковый состав. Для разных кабелей задайте отдельные группы вводов.
{
"role": "customer_in",
"tag": "W-01",
"from_point": "Шкаф управления",
"to_point": "Клеммная коробка",
"cable_type": "Марка по проекту",
"construction": "armored",
"routing": "direct",
"cores": 4,
"section_mm2": 2.5,
"outer_diameter_mm": 12,
"inner_diameter_mm": 8
}
role принимает customer_in для кабеля заказчика и factory_out для заводского кабеля. Для записи в журнале достаточно роли. Если выбран model_id, подбор корпуса и выгрузка проверяют указанные параметры кабеля и прокладки по данным модели. Несовместимые значения возвращают HTTP 422.
Автоподбор вводов
POST /api/v1/korv/catalog/glands/select принимает до 100 строк с уникальными id и одним исполнением коробки. Ответ сохраняет порядок строк и возвращает id, role, status, missing_fields, candidates и пояснение.
{
"box_execution": "ex",
"lines": [
{"id": "M1-IN", "cable": {"role": "customer_in", "construction": "armored",
"routing": "direct", "outer_diameter_mm": 18, "inner_diameter_mm": 9}},
{"id": "M1-OUT", "cable": {"role": "factory_out", "construction": "unarmored",
"routing": "metal_hose", "outer_diameter_mm": 7, "hose_dn_mm": 15}}
]
}
construction принимает unarmored, armored или braided, routing — direct, metal_hose или rigid_conduit. Кроме наружного Ø, для брони и оплётки нужен Ø по внутренней оболочке. Для металлорукава нужен hose_dn_mm. Для трубы нужны pipe_thread, например G3/4, и pipe_connection (female или male со стороны трубы на вводе). Если отверстие уже задано, передайте mounting_thread корпуса.
preliminary_match возвращает варианты по возрастанию монтажного габарита. missing_data перечисляет необходимые поля. no_match означает отсутствие модели по заданным параметрам. Для КОВТВЛ требуется armor_thickness_mm, чтобы проверить зажим брони или оплётки. При compound_required: true возвращается manual_review, поскольку требуется сверка прохода жил. Применимость в составе КОРВ согласуется отдельно.
Чтобы применить вариант, передайте его id в поле model_id соответствующей группы glands. Код и минимальные монтажные размеры подставятся из справочника. В вебе кнопки подбора и применения находятся в строке кабельного журнала.
Передайте те же glands при формировании бланка, чтобы журнал вошёл в Excel, PDF и ZIP.
Архивные конфигурации
GET /api/v1/korv/configurations— список архивных конфигураций.GET /api/v1/korv/configurations/{id}— получение одной конфигурации.POST /api/v1/korv/select— поиск по составу. Тип содержимогоapplication/json.
Поиск сравнивает переданные параметры. Одинаковые группы клемм и вводов суммируются. Поля dimensions и ex_marking можно опустить. При передаче габаритов укажите все три размера в миллиметрах.
Тело запроса на подбор
{
"box_execution": "industrial",
"material": "aisi316l",
"climate": "УХЛ1",
"nominal_voltage_v": 400,
"terminals": [
{"kind": "feed_through", "connection": "screw", "section_mm2": 6, "count": 4},
{"kind": "feed_through", "connection": "screw", "section_mm2": 2.5, "count": 3},
{"kind": "pe", "connection": "screw", "section_mm2": 6, "count": 1}
],
"glands": [
{"side": "B", "code": "КНВМ2М20НК", "count": 4}
]
}
Этот запрос возвращает массив с одной записью korv-u-151511-m20x4-r1. Для ссылки из карточки оборудования сохраните id или href и используйте адрес этого сервиса.
Для архивного КОРВ-В передайте "box_execution": "ex". Поле ex_marking сравнивается со строкой в архивном заказе.
Ответы
200— конфигурация по идентификатору или массив конфигураций для списка и подбора.404иdetail.code: "configuration_not_found"— неизвестный идентификатор.404иdetail.code: "no_matching_configuration"— в архиве нет подходящего состава.422— неверный формат запроса. Массивdetailсодержит путь к каждому полю и сообщение.
Статус reference_configuration обозначает запись из архивного заказа. Применимость во взрывоопасной зоне подтверждают действующие документы на изделие.