138 lines
9.1 KiB
Markdown
138 lines
9.1 KiB
Markdown
# 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-события не обрабатываются повторно при дублях
|
||
- ошибки интеграционного обмена фиксируются в журнале
|
||
- неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке
|