Интеграция 1С: подбор технических аналогов в смете

NOTE

Это действующий production-контракт. Документ предназначен для разработчика 1С, который добавляет подбор аналогов в свою конфигурацию. Используйте его вместе с описанием Public API и импортируемой коллекцией Postman из examples/postman/1c-fb-mcb/.

Компонент 1С не ищет аналоги самостоятельно. Он передаёт Tracium снимок сметы, получает результат по каждой строке и сохраняет выбор пользователя. До запуска оператор при необходимости выбирает вид изделия и технические ограничения из справочников Tracium. Tracium определяет исходный товар, подбирает доступные предложения поставщиков и возвращает технически допустимые аналоги, если автоматическую замену нельзя подтвердить. Исходную позицию нельзя заменить без явного действия пользователя.

Как работает сценарий

flowchart LR
    A["Строка сметы<br/>текст, артикул, количество"] --> B{"Нужно уточнить<br/>вид изделия или параметры?"}
    B -- "да" --> C["Справочники и поиск<br/>категория, критерии, товары"]
    C --> D["Создать задачу<br/>POST /v1/estimates/jobs"]
    B -- "нет" --> D
    D --> E["Сохранить в 1С<br/>job_id и cursor = 0"]
    E --> F["Фоновое задание<br/>GET /jobs/{id}?after=cursor"]
    F --> G["Сохранить изменения<br/>по lines[].id"]
    G --> H{"Задача<br/>завершена?"}
    H -- "нет" --> F
    H -- "да" --> I["Показать результат<br/>и кандидатов для выбора"]

Задача хранится на сервере примерно 24 часа. Форму 1С можно закрыть: для продолжения работы достаточно сохранённых job_id и cursor.

Карта API для компонента 1С

Этап	Метод	Что возвращает и зачем нужен
Проверка доступа	`GET /v1/whoami`	Привязку ключа к клиенту; это первый вызов после настройки.
Выбор вида изделия	`GET /v1/catalog/categories`	UUID категории, который передаётся как `category_id` и `lines[].category`.
Технический контракт	`GET /v1/catalog/categories/{category_id}/analog-criteria`	Действующие для категории оси и правила сравнения, включая наследование.
Справочник характеристик	`GET /v1/catalog/characteristics`	Стабильный `code`, тип и единицу характеристики.
Справочник enum-значений	`GET /v1/catalog/characteristics/{code}/values`	Нормализованное значение для выпадающего списка.
Идентификация позиции поставщика	`POST /v1/products/resolve`	По известной паре поставщик + SKU связывает исходную строку с canonical-товаром. Не подбирает аналог и не проверяет техническую совместимость.
Ручной поиск товара	`POST /v1/products/search`	Canonical-товары, которые одновременно проходят текст, категорию и все переданные требования.
Карточка и предложения	`GET /v1/products/{id}`	Характеристики и read-side срез офферов выбранного товара.
Предложения поставщиков товара	`GET /v1/products/{id}`	Карточка содержит текущий read-model в `supplier_offers[]`; отдельного публичного маршрута `/offers` нет.
Технические аналоги карточки	`GET /v1/canonical/{id}/analogs`	Кандидатов для отдельного экрана «Аналоги»; в обработке сметы они уже приходят в результате задачи.
Асинхронная смета	`POST /v1/estimates/jobs`	Идентификатор фоновой задачи.
Получение результата	`GET /v1/estimates/jobs/{id}?after={cursor}`	Только новые завершённые строки и новый курсор.
Отмена	`POST /v1/estimates/jobs/{id}/cancel`	Останавливает задачу, не удаляя уже полученный частичный результат.

Все методы ниже используют один и тот же заголовок Authorization: Bearer <ключ API>. В OpenAPI-спеке пути записаны без /v1, потому что /v1 уже входит в базовый URL сервера.

1. Настроить доступ

Параметр	Значение
Базовый URL	`https://api.tracium.ru/v1`
Заголовок авторизации	`Authorization: Bearer <ключ API>`
Требуемые области доступа	`products:read` для каталога и `search:read` для сметы
Максимальный размер одной задачи	250 строк

Используйте ключ API клиента. Сессионный JWT, cookie браузерного кабинета и Admin API для этой интеграции не подходят. Храните ключ в защищённом хранилище настроек 1С, а не в общем модуле, выгрузке конфигурации или коллекции Postman.

Перед началом работы проверьте ключ:

export TRACIUM_API_KEY='ключ-получен-отдельно'
 
curl --fail-with-body \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  https://api.tracium.ru/v1/whoami

Пример успешного ответа:

{
  "customer_id": "<uuid-клиента-1C>",
  "env": "production",
  "key_name": "Prod"
}

Ответ 401 означает, что ключ или заголовок передан неверно. Не отлаживайте подбор сметы, пока whoami не вернёт 200 OK.

2. Уточнить технические условия до запуска сметы

Этот шаг нужен, когда пользователь не просто присылает текст строки, а выбирает вид изделия и фиксирует параметры замены. Он выполняется до создания асинхронной задачи и не заменяет распознавание исходной позиции по артикулу или тексту.

2.1. Найти вид изделия

Найдите вид изделия:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/catalog/categories?search=%D0%BC%D0%BE%D0%B4%D1%83%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5%20%D0%B0%D0%B2%D1%82%D0%BE%D0%BC%D0%B0%D1%82%D1%8B&limit=20&offset=0"

Возьмите items[].id выбранного листа как category_id. Не сохраняйте название вместо UUID: название может повторяться в дереве. Поле slug помогает отличить одноимённые листья при отображении, но в запросы всегда передаётся UUID.

Это постраничный справочник. Во всех трёх справочных методах используйте limit от 1 до 200, offset от 0 и поле ответа has_more. Для следующей страницы сохраняйте тот же набор фильтров и увеличивайте offset на фактическое число полученных items, а не на произвольное значение. Это не позволяет молча потерять категории или значения при большом результате.

API намеренно не возвращает total: его вычисление потребовало бы отдельного полного подсчёта в рабочих справочниках. Единственный признак продолжения — has_more; завершите цикл, когда он станет false.

Для категории доступны фильтры search (подстрока в названии или slug), slug (точное значение) и parent_id (точный UUID родителя). Например, после выбора родительского узла можно загрузить его дочерние листья так:

curl -sS -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/catalog/categories?parent_id=$PARENT_CATEGORY_ID&limit=100&offset=0"

{
  "items": [
    {
      "id": "<uuid-категории-модульных-автоматов>",
      "name": "Модульные автоматические выключатели",
      "slug": "modular-circuit-breakers",
      "parent_id": "<uuid-родительской-категории>"
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

2.2. Получить правила технической совместимости

Прочитайте фактически действующий контракт категории:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/catalog/categories/$CATEGORY_ID/analog-criteria"

Ответ содержит только характеристики, которые действительно участвуют в техническом контракте этой категории. У каждой такой строки required_for_eligibility=true; rule задаёт способ сравнения и показывает, унаследовано ли правило. Только analog_contract_available=true означает, что автоматическая замена в этой категории вообще разрешена правилами. Если значение false, 1С может показать поиск товаров, но должна пометить замену как ручное решение.

{
  "category_id": "<uuid-категории>",
  "analog_contract_available": true,
  "criteria": [
    {"code": "rated_current", "name": "Номинальный ток", "data_type": "number", "unit": "A", "role": "identity", "required_for_eligibility": true, "rule": {"kind": "hard_divergence", "inherited": false}},
    {"code": "rated_short_circuit_breaking_capacity_icu_400v", "name": "Отключающая способность при 400 В", "data_type": "number", "unit": "A", "role": "identity", "required_for_eligibility": true, "rule": {"kind": "monotone_ge", "inherited": false}}
  ]
}

2.3. Получить коды и значения характеристик

Для формы выбора используйте справочник, а не введённые вручную коды:

curl -sS -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/catalog/characteristics?search=%D1%82%D0%BE%D0%BA&data_type=number&unit=A&limit=20&offset=0"
curl -sS -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/catalog/characteristics/tripping_characteristic/values?search=C&limit=20&offset=0"

Первый ответ содержит стабильный code, data_type и unit; второй — нормализованные enum-значения. Используйте справочник характеристик для поиска и карточек, а в форме условий по умолчанию показывайте только criteria выбранной категории. Для числа exact означает равенство, at_least — «не меньше», at_most — «не больше», between — диапазон.

В requirements[].code всегда передавайте именно стабильный строковый код из справочника, например rated_current, а не внутренний UUID. API сам связывает код с UUID характеристики и выполняет фильтр по индексированному каноническому значению. Это одинаково работает для ручного поиска и для строки сметы. Клиенту не нужно и не следует преобразовывать code в UUID самостоятельно.

У характеристик search ищет в названии и коде. Для точного выбора доступны code, data_type (number, enum или string) и unit. У значений характеристики доступен текстовый search. Оба метода используют те же limit, offset и has_more, что и поиск категорий. Фильтры применяются до разбивки на страницы: переход на следующую страницу не меняет состав выборки.

{
  "items": [
    {"code": "rated_current", "name": "Номинальный ток", "data_type": "number", "unit": "A"}
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

{
  "items": [
    {"value": "C", "label": "Кривая C"}
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Число передаётся в канонической единице из поля unit, которое вернул справочник характеристики. Например, Icu 6 кА хранится и передаётся как 6000 A; требование «не ниже 10 кА» — это at_least: 10000. Если в карточке товара число задано диапазоном, API возвращает его только тогда, когда весь диапазон удовлетворяет условию. Это исключает замену с недоказанным запасом. Для enum, текста и boolean разрешён только exact.

Оператор	Когда использовать	Поля запроса
`exact`	Точное значение: ток 25 А, 3 полюса, кривая C, AC.	`value`
`at_least`	Кандидат не хуже требуемого: Icu не ниже 10 кА.	`value`
`at_most`	Значение не больше указанного предела.	`value`
`between`	Значение в закрытом диапазоне.	`min` и `max`

2.4. Связать известную позицию поставщика с canonical-товаром

Этот шаг необязателен. Используйте его, если 1С уже хранит поставщика и его SKU для исходной строки. Метод не ищет замену: он только надёжно определяет, какой товар каталога описывает исходная позиция. Это удобнее и точнее, чем распознавать ту же строку по свободному тексту.

curl --fail-with-body -sS -X POST \
  "https://api.tracium.ru/v1/products/resolve" \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "id": "mcb-source-offer-1",
        "supplier": "russvet",
        "supplier_sku": "1608602",
        "qty_requested": 2
      }
    ]
  }'

{
  "items": [
    {
      "id": "mcb-source-offer-1",
      "status": "resolved",
      "canonical_ref": "<uuid-canonical-товара>",
      "candidates": [
        {
          "canonical_ref": "<uuid-canonical-товара>",
          "match_type": "exact_supplier_sku",
          "confidence": 1
        }
      ]
    }
  ]
}

При status=resolved сохраните canonical_ref: по нему можно открыть карточку и отдельный экран технических аналогов. При ambiguous или not_found не выбирайте первый вариант автоматически — передайте исходные текст, категорию и требования в асинхронную смету. Поле characteristics в этом методе является лишь подсказкой распознавания; для фильтрации допустимых аналогов используйте lines[].requirements в задаче сметы.

2.5. Найти товар по строке, категории и характеристикам

Товары для ручного выбора найдите тем же структурированным поиском, которым пользуется список canonical-товаров в админке. query, category_id и requirements независимы: переданные одновременно условия объединяются логическим «И». Поэтому ниже не «похожий» поиск, а выбор автоматов из одной категории с заданными инженерными параметрами:

curl --fail-with-body -sS -X POST \
  "https://api.tracium.ru/v1/products/search" \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "Выключатель автоматический",
    "category_id": "'"$CATEGORY_ID"'",
    "requirements": [
      {"code":"rated_current","operator":"exact","value":25},
      {"code":"total_number_of_poles","operator":"exact","value":3},
      {"code":"tripping_characteristic","operator":"exact","value":"C"},
      {"code":"current_type","operator":"exact","value":"Переменный ток (AC)"},
      {"code":"rated_short_circuit_breaking_capacity_icu_400v","operator":"at_least","value":10000}
    ]
  }'

Каждый товар в ответе проходит все условия. Затем запросите GET /v1/products/{canonical_id}, чтобы показать его характеристики и предложения поставщиков из supplier_offers[]. Структурированный поиск не выбирает предложение и не обещает, что товар является аналогом: он только даёт строго отфильтрованный пул.

{
  "items": [
    {
      "canonical_id": "<uuid-товара>",
      "viewable_id": "TR-XXXXXXX",
      "name": "Автоматический выключатель …",
      "manufacturer_name": "<производитель>",
      "manufacturer_article": "<артикул>",
      "category_id": "<uuid-категории>",
      "category_name": "Модульные автоматические выключатели",
      "offers_count": 3
    }
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

Сохраните canonical_id выбранного пользователем. По нему допустимо открыть карточку GET /v1/products/{canonical_id} и, если нужен отдельный экран технической замены, GET /v1/canonical/{canonical_id}/analogs?limit=5. Карточка содержит текущий read-side срез в supplier_offers[]. Отдельного публичного метода /v1/products/{id}/offers нет.

2.6. Передать условия в асинхронную смету

Передайте те же условия в lines[].requirements асинхронной сметы. Существующее characteristics остаётся подсказкой распознавания исходной строки; requirements — обязательный фильтр для её аналогов. Кандидат без любой требуемой характеристики исключается до цен, остатков и сроков:

lines[].category — UUID canonical v2, полученный из справочника категорий, а не категория поставщика. В смете он ограничивает пул поиска выбранным листом, его потомками и эквивалентными листьями. Правила сравнения при этом не склеиваются: для каждого распознанного товара применяются правила его фактической категории. Ручной POST /products/search намеренно уже: он ищет только в выбранной категории и её потомках; эквивалентность применяется на следующем шаге — при запросе технических аналогов найденного товара.

{
  "id": "line-26",
  "raw_text": "Авт. выкл. NB1-63H 3P 25A 10кА х-ка C, CHINT",
  "qty_requested": 2,
  "uom": "шт",
  "category": "<uuid-категории>",
  "identifiers": {"mpn": "CH179871"},
  "requirements": [
    {"code":"rated_current","operator":"exact","value":25},
    {"code":"total_number_of_poles","operator":"exact","value":3},
    {"code":"tripping_characteristic","operator":"exact","value":"C"},
    {"code":"current_type","operator":"exact","value":"Переменный ток (AC)"},
    {"code":"rated_short_circuit_breaking_capacity_icu_400v","operator":"at_least","value":10000}
  ]
}

Не подменяйте этим блоком исходный товар: для автоматического подбора аналогов строка всё равно должна быть распознана через артикул, supplier SKU или текст. Если входная строка не распознана, результат остаётся needs_review; сервер не выбирает произвольный товар только по спецификации.

3. Сформировать снимок сметы

Снимок — это состав сметы на момент запуска расчёта. Для каждой строки передайте количество и хотя бы один идентификатор товара:

исходное описание в raw_text или name;
артикул производителя в identifiers.mpn или manufacturer_article;
пару identifiers.supplier и supplier_sku;
либо уже известные category и characteristics.

Передавайте полное описание, бренд и артикул, если они есть в смете. Цена, срок поставки и остаток прежнего поставщика не описывают техническую совместимость и во входной JSON не передаются.

Данные в 1С	Поле API	Как заполнять
UUID строки документа	`lines[].id`	Постоянный идентификатор строки. Не используйте номер строки и не меняйте ID во время опроса.
Номер позиции	`lines[].position`	Нужен для отображения и сверки с исходной сметой.
Описание позиции	`lines[].raw_text`	Не сокращайте значимые технические параметры.
Количество и единица измерения	`qty_requested`, `uom`	Например: `2` и `шт`.
Производитель	`brand`	Необязательное поле, но улучшает распознавание.
Артикул производителя	`identifiers.mpn`	Самый надёжный идентификатор, если он известен.

request_id — идентификатор версии снимка на стороне 1С. Например: estimate-<uuid-документа>-v3. Он нужен для журнала, но не делает запрос идемпотентным. Если соединение оборвалось во время POST, задача могла уже быть создана. Не повторяйте такой запрос бесконечно: зафиксируйте неопределённый результат и предложите пользователю явно создать новую версию снимка.

4. Создать асинхронную задачу

Ниже приведены три позиции из запроса поставщику №722. Полный пример для 13 модульных автоматов и исходный JSON для документа из 88 строк находятся в коллекции Postman в репозитории.

{
  "schema_version": "estimate-request.v1",
  "request_id": "estimate-722-mcb-v1",
  "mode": "reference",
  "target_currency": "RUB",
  "strategy": {"goal": "balanced"},
  "lines": [
    {
      "id": "request-722-line-026",
      "position": "26",
      "raw_text": "Авт. выкл. NB1-63H 3P 25A 10кА х-ка C 179871, CHINT",
      "qty_requested": 2,
      "uom": "шт",
      "brand": "CHINT",
      "identifiers": {"mpn": "CH179871"},
      "category": "<uuid-категории-модульных-автоматов>",
      "requirements": [
        {"code":"rated_current","operator":"exact","value":25},
        {"code":"total_number_of_poles","operator":"exact","value":3},
        {"code":"tripping_characteristic","operator":"exact","value":"C"},
        {"code":"current_type","operator":"exact","value":"Переменный ток (AC)"},
        {"code":"rated_short_circuit_breaking_capacity_icu_400v","operator":"at_least","value":10000}
      ]
    },
    {
      "id": "request-722-line-027",
      "position": "27",
      "raw_text": "Авт. выкл. NB1-63H 3P 32A 10кА х-ка C 179873, CHINT",
      "qty_requested": 1,
      "uom": "шт",
      "brand": "CHINT",
      "identifiers": {"mpn": "CH179873"}
    },
    {
      "id": "request-722-line-038",
      "position": "38",
      "raw_text": "KARAT Авт. выкл. ВА47-60M 1P C 6А 6кА IEK",
      "qty_requested": 5,
      "uom": "шт",
      "brand": "IEK",
      "identifiers": {"mpn": "MVA31-1-006-C"}
    }
  ]
}

Отправьте снимок в API:

curl --fail-with-body -sS -X POST \
  https://api.tracium.ru/v1/estimates/jobs \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @mcb-pilot.json

Сервер принимает задачу и возвращает 202 Accepted. Это подтверждает, что задача поставлена в очередь, но ещё не означает, что расчёт завершён.

{
  "job_id": "6fe2ca25-3a63-4dd2-b29b-f3c14f4f7172",
  "status": "queued",
  "progress": {"total": 3, "done": 0, "percent": 0},
  "created_at": "2026-08-12T08:00:00Z",
  "expires_at": "2026-08-13T08:00:00Z"
}

В одной транзакции 1С сохраните job_id, cursor = 0, ссылку на документ, версию снимка и все исходные lines[].id. Интерактивная форма не должна ждать окончания расчёта.

5. Получать результаты в фоне

Первый запрос всегда выполняется с after=0:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/estimates/jobs/$JOB_ID?after=0"

Пример промежуточного ответа (200 OK):

{
  "job_id": "6fe2ca25-3a63-4dd2-b29b-f3c14f4f7172",
  "status": "running",
  "progress": {"total": 3, "done": 1, "percent": 33},
  "summary": {
    "lines_total": 3,
    "resolved": 0,
    "with_proposals": 0,
    "needs_review": 1
  },
  "lines": [
    {
      "id": "request-722-line-026",
      "position": "26",
      "qty_requested": "2",
      "proposal_qty": 2,
      "uom": "шт",
      "status": "needs_review",
      "reason": "low_confidence",
      "alternatives": [],
      "analogs": [
        {
          "canonical_ref": "<uuid-кандидата>",
          "name": "<наименование кандидата>",
          "manufacturer_article": "<артикул>",
          "score": 0.91
        }
      ]
    }
  ],
  "cursor": 1,
  "expires_at": "2026-08-13T08:00:00Z"
}

cursor — это номер последнего изменения, которое 1С уже получила. После каждого ответа фоновое задание должно:

Обновить результат каждой полученной строки по lines[].id. Если строки ещё нет в хранилище результата, создать её.
В той же транзакции сохранить новый cursor.
Обновить в форме progress и summary.
Если задача ещё не завершена, повторить запрос через 1–3 секунды, передав сохранённый after=<cursor>.

Если сеть недоступна, не меняйте cursor: следующий запрос повторит тот же GET, а сохранение по lines[].id не создаст дубликат. Пустой lines[] при after=<последний cursor> означает, что новых результатов пока нет. Уже сохранённые результаты удалять не нужно.

6. Показать результат по строке

Результат API	Что это означает	Что сделать в 1С
`resolved` и `proposal`	Товар распознан, найдено предложение поставщика.	Показать товар, цену, остаток и срок поставки. Применять его можно только по правилам закупки клиента.
`resolved` без `proposal`	Товар распознан, но доступного предложения нет.	Показать «Нет предложения». Не подставлять нулевую цену.
`needs_review` и `analogs[]`	Автоматическая замена не подтверждена, но есть технически допустимые кандидаты.	Показать кандидатов пользователю. Не менять исходную строку автоматически.
`needs_review`, `analogs[]` пуст	Доказанного решения нет.	Оставить позицию на ручной обработке.

Пример строки, для которой найдено предложение:

{
  "id": "request-722-line-038",
  "position": "38",
  "qty_requested": "5",
  "proposal_qty": 5,
  "uom": "шт",
  "status": "resolved",
  "selected": {
    "product_ref": "TR-XXXXXXXX",
    "canonical_ref": "<uuid-товара>",
    "manufacturer_article": "MVA31-1-006-C",
    "confidence": 0.99,
    "match_type": "mpn"
  },
  "proposal": {
    "offer_ref": "<uuid-оффера>",
    "price": {
      "mode": "fixed",
      "amount": {"value": "123.45", "precision": 2, "currency": "RUB"}
    }
  },
  "alternatives": [],
  "characteristics": [
    {"name": "Номинальный ток", "value": "6 A"},
    {"name": "Количество полюсов", "value": "1"}
  ]
}

price.amount.value передаётся десятичной строкой. Для штучной позиции proposal_qty округляется вверх: например, запрос на 314.5 шт даёт proposal_qty = 315. Покажите пользователю оба значения.

Чтобы открыть карточку кандидата, выбранного пользователем, запросите её по canonical_ref:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/products/<canonical_ref>"

7. Подбор с карточки товара

Для обработки сметы не вызывайте API аналогов отдельно для каждой строки: analogs[] уже приходит в результате асинхронной задачи. Этот запрос нужен только для отдельного экрана «Аналоги» у известной карточки товара.

# Сначала получить канонический UUID: это поле id в ответе карточки.
curl --fail-with-body -sS \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/products/TR-S8YV9Q4"
 
# Затем запросить аналоги по UUID, а не по TR-ID.
curl --fail-with-body -sS \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/canonical/<id-из-карточки>/analogs?limit=5"

results[] содержит технически допустимых кандидатов. Если этот массив пуст, сервер может вернуть partial_results[] с описанием нарушений контракта. Это близкие, но не доказанно совместимые товары; не используйте их для автоматического выбора. Маршрута /v1/products/{id}/analogs нет.

{
  "target_canonical_id": "<uuid-исходного-товара>",
  "model": "<версия-ранжирования>",
  "results": [
    {
      "canonical_id": "<uuid-кандидата>",
      "viewable_id": "TR-XXXXXXX",
      "name": "Автоматический выключатель …",
      "manufacturer_article": "<артикул>",
      "score": 0.93,
      "differences": [
        {
          "canonical_key": "rated_short_circuit_breaking_capacity_icu_400v",
          "name": "Отключающая способность при 400 В",
          "anchor_value": "6 kA",
          "candidate_value": "10 kA",
          "kind": "improved",
          "rule_kind": "monotone_ge"
        }
      ]
    }
  ]
}

Отличие kind=improved означает запас в разрешённую контрактом сторону; это не равнозначно ослаблению любой другой оси. Если есть partial_results, покажите violations и differences, но не переносите такой товар в results и не подставляйте его автоматически.

8. Завершить или отменить задачу

Статус задачи	Значение
`completed`	Все строки обработаны без `needs_review`.
`completed_with_gaps`	Расчёт закончен, но есть позиции, по которым нужно решение пользователя. Это не HTTP-ошибка.
`cancelled`	Расчёт остановлен. Получите частичный результат финальным `GET` с текущим `cursor`.
`failed`	Расчёт не завершился. Сохраните поле `error` и предложите пользователю повторный запуск.

Отменить задачу можно повторно: операция идемпотентна.

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $TRACIUM_API_KEY" \
  "https://api.tracium.ru/v1/estimates/jobs/$JOB_ID/cancel"

Для отдельного экранного запроса GET /v1/canonical/{id}/analogs ответ 504 с error.retryable=true означает временную перегрузку зависимого контура. Не меняйте исходный товар и не подставляйте частичный результат: повторите тот же запрос с ограниченной экспоненциальной паузой. Для расчёта сметы предпочтителен асинхронный путь выше: он не удерживает интерфейс 1С в ожидании подбора одной позиции.

Код ответа	Действие 1С
`401`	Проверить ключ, область доступа и заголовок. Не повторять запрос автоматически.
`422`	Исправить входные данные: селектор пуст, `lines[].id` повторяется, количество не больше нуля или неверно указана валюта.
`404` для задачи	`job_id` не принадлежит этому клиенту или срок хранения истёк. Создать новую задачу из сохранённого снимка.
`500`, `502`, `504` при `GET`	Не менять `cursor` и повторить тот же `GET`.

9. Проверить компонент 1С

Импортировать Tracium 1C FB MCB.postman_collection.json и окружение production. Указать tracium_token только в поле Current value.
Выполнить Who am I. Ожидаемый результат: 200 OK и env = production.
Создать пилотную задачу для 13 модульных автоматов и опрашивать её до конечного статуса.
Убедиться, что каждый lines[].id появился в сохранённом результате ровно один раз, progress содержит total, done и percent, а запрос после последнего cursor возвращает lines: [].
Выполнить полный запрос №722 из 88 строк. Проверить количество результатов, cursor, статусы и отсутствие потерь. Не сравнивать с заранее записанными ценами и кандидатами: каталог и коммерческие условия изменяются.
На новой тестовой задаче проверить отмену и сохранение частичного результата.

В репозитории есть готовый каркас кода 1С: examples/1c/README.md, examples/1c/TraciumPublicAPI.bsl и examples/1c/ФормаРасчетаСметы.bsl. Используйте его асинхронные методы: СоздатьЗадачуСметы, ПолучитьСтатусЗадачи, ОстановитьЗадачуСметы.

Tracium

Разделы

Интеграция 1С: подбор технических аналогов в смете

Как работает сценарий

Карта API для компонента 1С

1. Настроить доступ

2. Уточнить технические условия до запуска сметы

2.1. Найти вид изделия

2.2. Получить правила технической совместимости

2.3. Получить коды и значения характеристик

2.4. Связать известную позицию поставщика с canonical-товаром

2.5. Найти товар по строке, категории и характеристикам

2.6. Передать условия в асинхронную смету

3. Сформировать снимок сметы

4. Создать асинхронную задачу

5. Получать результаты в фоне

6. Показать результат по строке

7. Подбор с карточки товара

8. Завершить или отменить задачу

9. Проверить компонент 1С

Вид графа

Оглавление

Обратные ссылки