# 8. Требования к интеграции с 1С и внешним интерфейсам

## 8.1 Общие требования к интеграционному контуру

Интеграционный слой должен обеспечивать обмен данными между личным кабинетом и внешними системами без потери целостности внутренних сущностей и статусов.

Интеграционный контур должен обеспечивать:

- получение данных из 1С
- прием событий от 1С
- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов, если такой обмен согласован сторонами
- сопоставление внутренних идентификаторов и идентификаторов внешних систем
- регистрацию входящих и исходящих операций обмена
- повторную обработку неуспешных сообщений
- хранение истории обновлений по интеграционным операциям

## 8.2 Интеграция с 1С

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

Система должна обеспечивать получение из 1С следующих данных:

- каталог товаров
- характеристики товаров
- складские остатки
- сведения о заказах
- статусы заказов
- изменения состава, стоимости, доставки и иных существенных параметров заказа
- текущая задолженность клиента
- дата актуальности сведений, полученных из 1С

1С рассматривается как первичный источник учетных данных по заказам, складам, статусам, стоимости, доставке и задолженности. Личный кабинет отображает эти сведения и фиксирует дату их актуальности.

## 8.3 События от 1С

Система должна поддерживать прием webhook-событий от 1С в согласованном формате.

Минимальный состав событий:

- создание нового заказа
- изменение информации по заказу
- изменение статуса заказа
- изменение сроков, условий или параметров доставки
- изменение состава заказа
- изменение сведений о задолженности клиента, если такие данные передаются событийно

Для каждого события должны фиксироваться:

- тип события
- внешний идентификатор объекта 1С
- внутренний идентификатор объекта, если сопоставление выполнено
- дата и время события
- источник события
- статус обработки
- текст ошибки при неуспешной обработке

Система должна защищаться от повторной обработки дублей webhook-событий.

## 8.4 Методы получения данных из 1С

Система должна поддерживать получение данных из 1С через согласованные методы.

Минимальный состав методов:

- получение заказов клиента
- получение товарного каталога
- получение характеристик товаров
- получение доступных остатков по складам
- получение статусов и изменений по заказам
- получение текущей задолженности клиента и даты актуальности этих сведений

Точный набор методов, параметры запросов, формат ответов и ограничения по частоте вызовов фиксируются в интеграционной спецификации.

## 8.5 Требования к структурам обмена

Входные и выходные данные интеграционного слоя должны описываться в структурированном виде и позволять однозначно восстанавливать:

- тип объекта обмена
- идентификатор объекта
- дату и время события
- полезную нагрузку объекта
- статус обработки
- источник изменения

Для обмена должны использоваться структурированные payload-форматы, пригодные для сериализации в `JSON`.

Точная структура payload, схема подписи запросов и набор обязательных полей согласуются сторонами до начала этапа интеграции с 1С.

## 8.6 Интеграционные поля и служебные атрибуты

Для сущностей, участвующих в обмене, должны поддерживаться:

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

## 8.7 Журналирование интеграционных операций

Для ключевых операций обмена система должна сохранять:

- тип объекта
- идентификатор объекта
- предыдущее состояние
- новое состояние
- дату и время изменения
- пользователя либо внешний источник, выполнивший изменение
- статус обработки сообщения
- текст ошибки при наличии

## 8.8 Требования к защите интеграционного обмена

Интеграционные запросы должны выполняться с использованием согласованного механизма авторизации или подписи.

Система должна отклонять интеграционные запросы, если:

- отсутствуют обязательные параметры авторизации
- подпись или токен не прошли проверку
- payload не соответствует согласованной структуре
- невозможно определить тип события или объект обработки

Секреты, используемые для интеграции с 1С, должны храниться только в Vault и передаваться сервисам через runtime-конфигурацию.

## 8.9 Критерии приемки интеграции с 1С

Интеграция с 1С считается готовой в согласованном объеме, если:

- каталог и характеристики товаров получаются и отображаются в личном кабинете
- остатки по складам отображаются в карточках товаров
- заказы клиента получаются и отображаются с актуальными статусами
- изменения заказа из 1С отображаются в карточке заказа
- текущая задолженность клиента и дата актуальности данных отображаются в предусмотренных интерфейсах
- webhook-события не обрабатываются повторно при дублях
- ошибки интеграционного обмена фиксируются в журнале
- неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке