GUIDE: Цифровая инфраструктура и интеграции (D12)¶

Как работать с доменом¶

Если вы добавляете новую интеграцию¶

Создайте процесс D12-PXX.md по шаблону из CLAUDE.md
Опишите: кто инициатор обмена (ОО или ГИС), протокол, формат данных, периодичность
Добавьте нормативное основание — без него процесс не переходит в review
Если есть схемы (XSD, JSON Schema, OpenAPI) — разместите в best-practices/ рядом с процессом
Укажите зависимость в metadata.yml соответствующего содержательного домена

Если вы документируете существующую интеграцию (как ФИС ГИА)¶

Структура документации в best-practices/<название-интеграции>/:

best-practices/fis-egia-api/
├── README.md          ← обзор и ключевые отличия ВО vs СПО
├── CHANGELOG.md       ← версионирование API
├── getting-started/   ← авторизация, асинхронный паттерн, среды
├── scenarios/         ← сценарии от начала до конца кампании
├── reference/         ← карточки endpoint-ов
├── entities/          ← описание сущностей и их полей
├── classifiers/       ← справочные значения
├── schemas/           ← XSD схемы (для ВО)
├── schemas-spo/       ← JSON Schema (для СПО)
└── spo/               ← специфика СПО

Типовые ошибки¶

Путаница домена данных и канала передачи¶

«Данные о зачислении живут в D12» — нет. Данные живут в D05, D12 — только канал и протокол. Если бизнес-логика меняется — правьте D05. Если меняется формат обмена — правьте D12.

Хранение реальных ключей в репозитории¶

Ключи ОГРН/КПП, Session-Key, сертификаты ЭП — никогда не попадают в репозиторий. Только структурные примеры с плейсхолдерами вида "1234567890123".

Привязка к конкретной версии API без пометки¶

Когда ссылаетесь на поведение API — всегда указывайте версию: (v3.5.0). API ФИС ГИА меняется ежегодно под новый приказ о порядке приёма.

Игнорирование breaking changes¶

При обновлении версии API проверяйте CHANGELOG и поле breaking_changes. Примеры критичных изменений в v3.5.0: NeedHostel стал массивом, CostOfStudy разделился на CostOfStudyRf + CostOfStudyForeigner.

Работа с асинхронным паттерном ФИС ГИА¶

Все операции с данными в ФИС ГИА — асинхронные:

POST /api/token/new  →  получаем IdJwt
GET  /api/token/own/get?idJwt=...  →  ждём результат (статус WAIT → DONE/ERROR)

Рекомендуемая стратегия поллинга: 1. Запросить /api/token/delay/get — сервер скажет ориентировочное время 2. Подождать это время × 1.5 3. Поллить с интервалом 5–10 секунд, не чаще 4. Timeout: 10 минут (после — считать операцию зависшей, логировать)

Работа с электронной подписью¶

Алгоритм: ГОСТ 34.10-2012, формат: detached PKCS#7.

Подписываемая строка: Token-Header-Base64 + "." + payload_base64

Операции чтения (GetBy, GetDirect, GetAll, get_by, get_direct, get_all) подписи не требуют — signature_base64 передаётся пустой строкой.

Среды и доступ¶

Тестовая среда отделена от боевой. Адреса уточняются в технической поддержке ФИС. Для получения доступа к тестовой среде нужны: ОГРН, КПП, сертификат ЭП. Подробнее: best-practices/fis-egia-api/getting-started/environments.md