Симулятор ЭДО (citeck-edi-sim)

Примечание

Доступно только в Enterprise версии.

citeck-edi-sim — сервис, заменяющий на стенде реальный портал ЭДО. Он поднимает поверхности провайдеров, к которым обращается микросервис ecos-edi, и позволяет вести вторую сторону обмена руками: доставлять документы, подписывать их от имени контрагента, отклонять, запрашивать уточнение и аннулирование.

Применяется там, где боевой или демо-стенд провайдера не подходит: локальная разработка, автотесты, разбор инцидента на воспроизводимых данных, отладка нового сценария до подключения к провайдеру.

Исходный код: https://gitlab.citeck.ru/citeck-projects/citeck-edi-sim

Важно

Симулятор никогда не проверяет электронные подписи. Он их принимает, хранит и умеет создавать настоящие CMS-подписи, но не верифицирует ни одну. Проверка криптографии — не его задача, и полагаться на него в этом нельзя.

Что эмулируется

Один процесс обслуживает четыре провайдерские поверхности и собственный административный API. Каждая поверхность смонтирована на своём префиксе:

Провайдер

Префикс

Формат обмена

Контур.Диадок

/diadoc

protobuf + gzip

СберКорус

/korus

JSON REST

Didox (Узбекистан)

/didox

JSON REST

Контур EDI/SE

/kontur-edi

EDI-XML, JSON REST

Административный API и консоль

/admin/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 к симулятору

Порядок такой же, как для настоящего провайдера (настройка синхронизации), меняются только адреса и учётные данные:

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

  2. Создайте запись в журнале Конечные точки: адрес — прямой, в обход gateway, вида http://<discovery.appName>:<server.port> плюс префикс нужной поверхности, например http://edi-sim:8080/diadoc.

  3. Заведите ящик в журнале Конфигурация ящиков ЭДО и синхронизацию — как описано в настройке 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 возвращает сертификаты всех организаций — для клиента, который не знает, от чьего имени выбирать.