Симулятор ЭДО (citeck-edi-sim)
Примечание
Доступно только в Enterprise версии.
citeck-edi-sim — сервис, заменяющий на стенде реальный портал ЭДО. Он поднимает поверхности провайдеров, к которым обращается микросервис ecos-edi, и позволяет вести вторую сторону обмена руками: доставлять документы, подписывать их от имени контрагента, отклонять, запрашивать уточнение и аннулирование.
Применяется там, где боевой или демо-стенд провайдера не подходит: локальная разработка, автотесты, разбор инцидента на воспроизводимых данных, отладка нового сценария до подключения к провайдеру.
Исходный код: https://gitlab.citeck.ru/citeck-projects/citeck-edi-sim
Важно
Симулятор никогда не проверяет электронные подписи. Он их принимает, хранит и умеет создавать настоящие CMS-подписи, но не верифицирует ни одну. Проверка криптографии — не его задача, и полагаться на него в этом нельзя.
Что эмулируется
Один процесс обслуживает четыре провайдерские поверхности и собственный административный API. Каждая поверхность смонтирована на своём префиксе:
Провайдер |
Префикс |
Формат обмена |
|---|---|---|
Контур.Диадок |
|
protobuf + gzip |
СберКорус |
|
JSON REST |
Didox (Узбекистан) |
|
JSON REST |
Контур EDI/SE |
|
EDI-XML, JSON REST |
Административный API и консоль |
|
JSON REST |
Административный API управляет организациями, ящиками, контрагентами, документами и сертификатами, а также содержит инспектор запросов: каждый вызов провайдерской поверхности сохраняется с методом, заголовками, разобранным телом (protobuf декодируется в JSON), ответом и временем обработки. Веб-консоль встроена в бинарь и отдаётся с корня.
Запуск и конфигурация
Конфигурация читается из yaml-файла, путь к которому передаётся флагом --config.
Любой параметр переопределяется переменной окружения: имя — это путь ключа в верхнем регистре с подчёркиванием вместо разделителей (server.port → SERVER_PORT,
data.path → DATA_PATH). Учитываются только заданные и непустые переменные.
server:
port: 8080
prefixes:
diadoc: /diadoc
korus: /korus
didox: /didox
konturEdi: /kontur-edi
admin: /admin/api
data:
path: "" # пусто — хранение в памяти; путь — файл БД
cleanup:
maxAge: 168h # удаление документов старше срока; 0 отключает
interval: 1h
log:
level: info # debug | info | warn | error
format: json # json | console
zookeeper:
hosts: [zookeeper-app:2181]
sessionTimeout: 10s
discovery:
host: "" # адрес, по которому до сервиса достучатся соседи
appName: edi-sim # имя, под которым сервис виден в Citeck
auth:
jwtSecret: "" # пусто — API открыт; задан — доступ только ROLE_ADMIN
Хранилище выбирается значением data.path: пустое — данные живут в памяти и теряются при перезапуске (режим для автотестов), путь — данные сохраняются в файл.
Регистрация в Citeck
Симулятор регистрируется в реестре сервисов Citeck через ZooKeeper и после этого доступен через gateway по адресу /gateway/<discovery.appName>/….
Это нужно не только для порядка. Обращение из браузера возможно только тем же источником — через gateway; прямой вызов на порт симулятора будет кросс-доменным, а административный API намеренно не отдаёт CORS-заголовки. Именно так работает отладочный режим электронной подписи. Серверным потребителям (ecos-edi, автотесты) регистрация не требуется — они ходят по прямому адресу.
Адрес ZooKeeper зависит от того, где запущен процесс, — так же, как у остальных приложений платформы:
в сети стенда подходит значение по умолчанию
zookeeper-app:2181;с машины разработчика укажите опубликованный адрес:
ZOOKEEPER_HOSTS=localhost:2181. Это же делает цельmake dev.
Чтобы отключить регистрацию, задайте в файле конфигурации hosts: [].
Регистрация выполняется в фоне и не блокирует запуск: если ZooKeeper недоступен, сервис пишет предупреждение и продолжает работать автономно.
Параметр discovery.host в обычном случае оставляют пустым — тогда сервис объявляет первый не-loopback IP машины. Именно он и нужен, когда gateway работает в контейнере, а
симулятор — на хосте: localhost для контейнера означал бы его самого. Задавайте адрес явно, если автоопределение выбирает не тот интерфейс (VPN, несколько сетевых карт).
Предупреждение
Регистрация открывает административный API людям. Gateway пропускает к зарегистрированному приложению любого пользователя с ролью USER, а этот API умеет выпускать сертификаты, подписывать произвольное содержимое и создавать документы.
На личной машине это безопасно. На общем стенде задайте auth.jwtSecret (переменная AUTH_JWTSECRET) — JWT-секрет стенда в base64. Тогда все маршруты,
кроме /health, потребуют роль ROLE_ADMIN, а межсервисные вызовы с ролью ROLE_SYSTEM продолжат работать. Браузерные сценарии от имени администратора при
этом не ломаются: gateway перевыпускает токен текущего пользователя с его ролями.
При запуске с регистрацией и пустым секретом сервис пишет предупреждение в лог.
Подключение ecos-edi к симулятору
Порядок такой же, как для настоящего провайдера (настройка синхронизации), меняются только адреса и учётные данные:
Создайте запись в журнале Секреты с учётными данными, которые показывает симулятор.
Создайте запись в журнале Конечные точки: адрес — прямой, в обход gateway, вида
http://<discovery.appName>:<server.port>плюс префикс нужной поверхности, напримерhttp://edi-sim:8080/diadoc.Заведите ящик в журнале Конфигурация ящиков ЭДО и синхронизацию — как описано в настройке ecos-edi.
Готовые значения для подстановки не нужно собирать вручную: в консоли симулятора кнопка Подключение показывает по каждой поверхности базовый адрес, схему авторизации, формат обмена и конкретные параметры выбранной организации — идентификатор ящика, ИНН, GLN и ключ разработчика.
Сертификаты и подписание
Симулятор выпускает настоящий ключевой материал: ГОСТ Р 34.10-2012 (256 и 512), RSA-2048/4096, ECDSA P-256. Сертификат выпускается на организацию, субъектом выступает физическое лицо. Срок задаётся при создании — действующий, истёкший или ещё не вступивший в силу; два последних предназначены для негативных проверок.
Сертификат можно скачать: .cer (DER) — для всех алгоритмов, .pfx (PKCS#12, пароль test) и .key (PKCS#8 PEM) — только для RSA и ECDSA.
Примечание
Для ГОСТ доступен только .cer. КриптоПро не импортирует закрытый ключ ГОСТ, созданный вне собственного криптопровайдера, поэтому обратный порядок таков: ключ
создаётся в КриптоПро, а его открытый сертификат загружается в симулятор (POST /admin/api/orgs/{id}/certificates/import). Загруженный таким образом
сертификат подписывать не может — закрытого ключа у симулятора нет.
Подписание выполняется на стороне сервиса, без КриптоПро на машине оператора:
действия
signиsign-senderпринимают необязательныйcertId. С ним документ подписывается настоящей отсоединённой CMS-подписью выбранного сертификата, без него — тестовой подписью, как раньше;POST /admin/api/certificates/{cid}/signподписывает произвольное содержимое, переданное вызывающей стороной, и возвращает отсоединённую CMS. На этом методе построен отладочный режим электронной подписи;GET /admin/api/certificatesвозвращает сертификаты всех организаций — для клиента, который не знает, от чьего имени выбирать.