Elevel / e.way connector

Статус: current, реализован. Код коннектора находится в backend/internal/core/ingestion/infra/elevel, нормализация — в backend/internal/core/normalization/infra/elevel. Поставщик регистрируется под стабильным ключом elevel и отображается как Elevel / e.way.

Граница интеграции

Коннектор использует REST/JSON API сервиса e.way — 1С:Бизнес-сеть через HTTPS и HTTP Basic auth (login + password). Регулярный контур загружает весь бесплатный каталог, цены и остатки. Платные карточки, описания и характеристики не входят в scheduled capabilities.

Метод	Назначение	Регулярный режим
POST /nomenclature?fieldSet=standard	постраничный бесплатный каталог	catalog + commerce
POST /registrationNomenclatures	регистрация ID перед offline-выгрузкой	commerce
POST /stockOfGoodsOffline	массовые остатки зарегистрированных ID	commerce, system credential
POST /pricesOffline	массовые цены зарегистрированных ID	commerce, system credential
POST /stockOfGoods	актуальные цена и остаток по списку ID	customer proposal / diagnostic
GET /warehouses	справочник складов	diagnostic

Catalog и commerce — независимые durable cursor jobs. Catalog пишет бесплатные goods payload, commerce повторно листает бесплатную номенклатуру, регистрирует ID батчем и присоединяет price/stock строго по supplier SKU, а не по позиции в ответе.

Credentials и цены клиента

Секреты не читаются из .env. Метаданные credentials и AES-зашифрованный секрет {login,password} хранятся в Credentials BC / Postgres.

• System credential используется для полного каталога и регулярных общих снимков цен/остатков. Bootstrap ID фиксирован как 00000000-0000-0000-0000-000000000007.
• Customer credential создаётся из ЛК с scope=customer и owner_ref клиента. В customer proposal он вызывает online endpoint и возвращает актуальные цены/остатки именно для этого договора.
• System credential разрешает catalog_sync, price_refresh, stock_refresh, customer_proposal, diagnostic_probe; customer credential не получает право полного catalog sweep.
• Ошибки и diagnostic formatting не включают login/password; opaque session имеет redacted string representation.

Платный контент

Платный tier представлен отдельным типом paid_max, но закрыт по умолчанию. Scheduled jobs всегда запрашивают free_standard (fieldSet=standard) и не рекламируют characteristics/specs capability.

Запрос paid_max возможен только через отдельный PaidContentAuthorizer. До HTTP-вызова он обязан проверить точный credential, непустой список item IDs, инициатора, причину и неистёкший срок разрешения. При отсутствии authorizer работает deny-by-default. Включать платный путь одной настройкой scheduler или общим feature flag запрещено.

Нормализация

Бесплатная карточка формирует identity из supplier ID, manufacturer article, manufacturer/brand, категории и названия. Мапперы сохраняют raw refs для goods, price и remains, RUB price set, агрегированные и складские остатки, прогноз поставки и изображения, если они присутствуют в бесплатном payload.

Характеристики и описания из платного max не запрашиваются. Обогащение каноника выполняется уже существующими источниками после matching.

Runtime configuration

Source of truth для production — deploy/prod-env-template.env и compose mapping. Секретов в этих файлах нет.

• SUPPLIER_ELEVEL_BASE_URL — только абсолютный HTTPS URL;
• SUPPLIER_ELEVEL_CATALOG_PAGE_SIZE, SUPPLIER_ELEVEL_COMMERCE_PAGE_SIZE — batch sizes;
• SUPPLIER_ELEVEL_CATALOG_MAX_ITEMS=0 — полный каталог;
• SUPPLIER_ELEVEL_COMMERCE_MAX_PAGES_PER_TICK — bounded commerce cursor tick;
• SUPPLIER_ELEVEL_REQUEST_TIMEOUT, SUPPLIER_ELEVEL_DATA_RPS, SUPPLIER_ELEVEL_DATA_BURST — transport budget;
• SUPPLIER_ELEVEL_LIVE_COALESCE_TTL — coalescing customer live lookups.

HTTP разрешён только в изолированной среде APP_ENVIRONMENT=e2e для mock-elevel; production validation его отклоняет.

Проверки

• Unit и mapper tests: go test ./internal/core/ingestion/infra/elevel ./internal/core/normalization/infra/elevel.
• Provider contract: go test -tags=provider_contract ./test/provider-contract -run Elevel.
• Mock E2E: scripts/backend_e2e_compose.sh; imitation service находится в deploy/docker/resources/mock-elevel.
• Production acceptance: ../../../40-operations/runbooks/elevel-ingestion-deploy.md.

Связанные документы

• framework.md — общий connector contract.
• ../../../50-processes/adding-new-supplier.md — Definition of Done.
• ../../../40-operations/runbooks/live-supplier-contour.md — полный downstream contour.