Карта рисков интеграции

Зачем нужна карта рисков

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

Карта рисков помогает не начинать сразу с продуктовой логики, если базовый контур еще не проверен.

Как использовать

Перед разработкой пройдитесь по слоям интеграции и отметьте для каждого:

• что уже подтверждено;
• что нужно проверить в тестовом контуре;
• какой риск блокирует разработку;
• кто отвечает за уточнение;
• какой результат будет считаться достаточным для MVP.

Рабочий шаблон

Используйте этот блок как короткую карту для старта интеграции. Его удобно заполнить на встрече аналитика, тимлида и разработчика до того, как команда начнет писать бизнес-логику.

Для каждой строки важно не заполнить все идеально, а честно отметить статус: подтверждено, проверить, решить до разработки, вынести за рамки MVP. Если по строке нет владельца или решения до разработки, это не “мелочь на потом”, а открытый риск.

Как перейти от карты к контракту и приемке

Карта рисков полезна только как первый шаг. После нее нужно решить, какие риски превращаются в договоренности по API, а какие — в проверяемые критерии приемки.

Рабочая связка такая:

1. В карте рисков отметить слой, где есть неизвестность.
2. В границах API зафиксировать договоренность: данные, ответственность, формат, безопасность, ошибки или правила изменения.
3. В критериях приемки описать, как команда проверит эту договоренность на happy path, ошибках, данных, повторах и наблюдаемости.

Например, риск “таймаут может создать дубль операции” не должен остаться общей заметкой. Он должен пройти дальше:

Риск: ответ внешнего сервиса не пришел, но операция могла выполниться.
Договоренность API: повтор разрешен только с idempotency key и проверкой статуса.
Критерий приемки: при таймауте повторный запрос не создает второй результат, а оператор видит correlation id и статус ожидания.

1. Транспорт

Проверить:

• какой протокол используется;
• есть ли требования к TLS, сертификатам или шифрованию;
• как устроен тестовый контур;
• можно ли отправить минимальный запрос;
• какие ограничения есть по IP, VPN, allowlist или сетевому доступу;
• как диагностируются сетевые ошибки.

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

2. Авторизация и доверие

Проверить:

• кто получает доступ к API;
• какие токены, ключи, сертификаты или подписи нужны;
• где хранятся секреты;
• как проходит ротация;
• какие права нужны в тестовом и production-контуре;
• где проходит граница между пользовательской авторизацией и доверием систем.

Риск: команда смешивает бизнес-права пользователя, технические credentials и доверие между системами.

3. Данные и источник истины

Проверить:

• какие данные отправляются;
• кто является источником истины;
• какие поля обязательны;
• какие данные чувствительные;
• какие данные можно логировать;
• что делать при отсутствии или противоречии данных;
• как обезличивать примеры для документации.

Риск: ошибка данных выглядит как ошибка API, хотя проблема в источнике, маппинге или бизнес-правиле.

4. Форматы и контракт

Проверить:

• формат запроса и ответа;
• типы, даты, статусы, идентификаторы;
• обязательность полей;
• правила валидации;
• формат ошибок;
• совместимость изменений;
• ожидания по версиям API.

Риск: контракт кажется понятным на уровне документации, но не проходит проверку на реальных или тестовых данных.

5. Ошибки, повторы и статусы

Проверить:

• какие ошибки технические;
• какие ошибки бизнесовые;
• какие запросы можно повторять;
• что считается дублем;
• нужен ли idempotency key;
• как меняется статус операции;
• когда нужна ручная проверка.

Риск: повторный запрос создает дубль, статус застревает без диагностики, а поддержка не понимает, что произошло.

6. Наблюдаемость и поддержка

Проверить:

• какие события логируются;
• есть ли correlation id;
• какие данные маскируются;
• какие метрики нужны;
• кто видит ошибку;
• как оператор или поддержка понимают состояние операции;
• что делать после инцидента.

Риск: интеграция работает только в happy path, а при сбое команда не может быстро отличить проблему внешней стороны от проблемы своей системы.

Минимальная карта для MVP

Для первой версии достаточно таблицы:

Карта не должна быть большой. Ее задача — показать, где команда уже уверена, а где пока работает с гипотезой.