--- name: onec-integration-and-exchange description: "Проектирует и отлаживает файловый импорт (CSV, Excel, клиент-банк, распознавание документов), HTTP/Web-сервисы, планы обмена, EnterpriseData (КД 3), CommerceML, маркировку и асинхронные интеграции 1С. Используй при разработке или диагностике обмена данными, идемпотентности и контрактов API." --- # Интеграции, файловый импорт и обмен данными в 1С Используй навык при разработке и разборе обменов между 1С и внешними системами: загрузка табличных/банковских файлов, HTTP и Web-сервисы, планы обмена БСП, правила конвертации EnterpriseData / КД 3, обмен с сайтом (CommerceML), государственные контуры маркировки и внешние сервисы распознавания или ИИ. Для специализированной загрузки произвольных XML-схем по XSD через пакеты XDTO дополнительно сверяйся с навыком `onec-xdto-import`. ## Контракт файлового импорта (CSV, таблицы, выписки, OCR) До написания разбора зафиксируй физический и предметный контракт файла: - **Кодировка, разделитель полей и экранирование кавычек**: запятая внутри значения в кавычках или десятичный разделитель `1,234` не должны разрезать колонку и превращать дробное количество в две ячейки или в тысячу. - **Ведущие нули и длинные числовые идентификаторы**: ИНН, КПП, БИК, расчётные счета, штрихкоды GTIN/EAN, коды маркировки и внешние артикулы читай **только как строку**; преобразование через число обрезает ведущие нули (`044525...` → `44525...`) и искажает разряды длинных кодов свыше 15–16 цифр. - **Стадия предпросмотра и сопоставления** (особенно для клиент-банка и распознанных сканов/OCR): разделяй загрузку распознанного буфера и проведение учётного документа. Потерянные или нераспознанные строки и реквизиты явно помечай для проверки оператором, а не заполняй пустыми значениями или первым попавшимся контрагентом по подстроке наименования. - **Идемпотентность повторной загрузки**: ключ дубля строится по бизнес-идентификатору операции (номер и дата выписки/внешнего документа + счёт/источник), а не по имени файла на диске. ## HTTP-сервисы, Web-сервисы и внешние вызовы API - **Разделяй транспортный и прикладной статус**: HTTP `200 OK` с телом `{"error": ...}` не является успешной бизнес-операцией, а сетевой таймаут чтения ответа **не доказывает**, что удалённая система не приняла запрос. - **Идемпотентность и корреляция**: передавай устойчивый ключ идемпотентности (`Idempotency-Key` / `MessageID` / `УИД` документа или сообщения очереди) и сквозной идентификатор запроса в лог. При повторе после обрыва связи принимающий HTTP-сервис 1С обязан вернуть статус уже обработанной операции по этому ключу, а не создать дубль заказа или оплаты. - **Безопасность границы доверия и TLS**: для исходящих HTTPS-соединений передавай `Новый ЗащищенноеСоединениеOpenSSL` и явный таймаут в `Новый HTTPСоединение(...)`, а токены читай из безопасного хранилища. Внутри входящего HTTP-сервиса проверяй права и допустимость параметров на сервере, не полагаясь на проверки клиентской формы, заголовок отправителя или совпавший `RequestID`. В ответах об ошибках возвращай согласованный машинный код и безопасное описание без текста SQL, серверных путей и токенов авторизации. - **Стандартный интерфейс OData (`standard.odata`)**: учитывай, что для доступа через OData объект должен быть явно включён в состав стандартного интерфейса OData и опубликован на веб-сервере, а имена сущностей и навигационных свойств чувствительны к регистру и виду объекта (`Catalog_...`, `Document_...`, `InformationRegister_..._RecordType`). Для операций записи через внешний шлюз предусматривай режим предварительного просмотра (`dry-run`) до модификации учётных данных. ## Планы обмена, EnterpriseData (КД 3) и частичные обновления - **Регистрация изменений и квитанции номеров сообщений**: наличие объекта в таблице регистрации узла плана обмена (`ПланыОбмена.ЗарегистрированныеИзменения`) означает лишь поставленную метку; фактический состав пакета определяют правила регистрации и конвертации (`МенеджерОбменаЧерезУниверсальныйФормат`), а подтверждение доставки — номера `ОтправленныйНомер` / `ПринятыйНомер` в заголовке сообщения обмена (удаление регистрации выполняется только после подтверждённой квитанции приёмника). - **Семантика пустых и отсутствующих полей при частичном обмене**: различай три случая во входящем сообщении — поле **не передано вовсе** (сохранить текущее значение приёмника, если согласован частичный патч), передано **явное пустое значение** (очистить реквизит) и передано **новое значение**. Аналогично для табличных частей зафиксируй контракт: полная замена всех строк таблицы документом источника или слияние по ключу строки. - При записи по обмену аккуратно используй `ОбменДанными.Загрузка = Истина`: он отключает повторную регистрацию на узел-отправитель и часть интерактивных проверок, но не должен оставлять проведённый документ без обязательных движений в приёмнике, если сами движения не передаются отдельными наборами записей. ## Типовые отраслевые протоколы (CommerceML, маркировка, внешние ИИ-сервисы) - **CommerceML (обмен с интернет-магазином)**: различай выгрузку каталога товаров (`import.xml`), пакетов предложений/цен/остатков (`offers.xml`, с учётом характеристик/SKU против карточки номенклатуры) и двусторонний обмен заказами. При порционной выгрузке изменений не сбрасывай на сайте остатки не попавших в дельту товаров как нулевые. - **Системы прослеживаемости и маркировки (Честный ЗНАК / ГИС МТ, ЕГАИС, ВетИС)**: моделируй явную карту состояний кода маркировки / документа (сформирован → отправлен → принят оператором → введён в оборот / выведен из оборота → отклонён с кодом ошибки). Запрещай повторную отгрузку одного кода маркировки в другой документ до снятия резерва или отмены предыдущей операции. - **Интеграция с внешними сервисами анализа / ИИ и минимизация данных**: фиксируй версию промпта/контракта, хэш входов для кэширования и признак «требует подтверждения пользователя». Выполняй сетевой вызов в фоновом задании вне транзакции БД, предварительно удаляя секреты и псевдонимизируя чувствительные реквизиты (ФИО, ИНН, счета, телефоны), включая их вхождения в представления ссылок и свободный текст комментариев.