Что включить в ТЗ на интеграцию X-tee: операции, тестовые данные и ошибки
Интеграция через X-tee редко срывается из-за того, что разработчик не умеет отправить запрос. Чаще стороны по-разному понимают результат: один считает, что «сервис отвечает», другой ждёт подтверждённого формата ошибок, воспроизводимых тестовых данных и понятных критериев приёмки. ТЗ в такой ситуации — не бюрократия, а способ заранее договориться о границах работ. Ниже — практический разбор того, что включить в ТЗ на интеграцию X-tee: какие операции описать, какие тестовые данные подготовить, как зафиксировать ошибки и повторные запросы. Это не заменяет официальную документацию X-tee: актуальные требования к security server, сертификатам и подключению проверяйте у оператора — в Эстонии ориентиром служит документация Riigi Infosüsteemi Amet (RIA).
Что включить в ТЗ на интеграцию X-tee: границы и участники
X-tee — эстонская инфраструктура обмена данными, построенная на X-Road. Технически обмен идёт через security server, а участники описываются через код организации, подсистему и код сервиса. Для ТЗ из этого следует простой вывод: недостаточно написать «сделать запрос к X-tee». Нужно перечислить участников, их роли и идентификаторы, иначе разработка начнётся с уточнений, которые можно было снять на бумаге.
Первый раздел ТЗ удобно сделать паспортом интеграции. В нём перечисляются стороны, их зоны ответственности и артефакты, по которым будет вестись работа.
- Владелец сервиса и потребитель. Кто публикует сервис, кто его вызывает, кто отвечает за данные на каждой стороне и кто подтверждает изменения.
- Идентификаторы. Код организации, подсистема, код сервиса и версия. Если идентификаторы ещё не согласованы, зафиксируйте, кто их получает, где они хранятся и как передаются в запросе.
- Правовое основание обмена. Если передаются персональные данные, укажите основание и ограничения; формулировки проверьте у DPO или юриста. ТЗ не должно подменять правовую оценку.
- Среды. Production, тестовая среда, если она доступна, стенды разработки. Для каждой среды — свои адреса, сертификаты и правила доступа.
- Артефакты контракта. WSDL или OpenAPI, XSD-схемы, примеры запросов и ответов, описание справочников и перечислений.
- Ответственные и эскалация. Кто со стороны сервиса отвечает на вопросы, кто принимает заявки на доступ, кто подтверждает изменения и в каком канале это происходит.
Отдельно проговорите, что входит в работу, а что нет. Настройка security server может быть зоной оператора или отдельной команды; разработка клиентского приложения — зоной потребителя. Если этот стык не описать, он всплывёт на приёмке в виде вопроса «а это кто должен был сделать?».
Зафиксируйте версионирование. Сервис может существовать в нескольких версиях, и потребителю нужно понимать, какая версия считается основной, как объявляется устаревшая и какой период поддержки стороны готовы обсуждать. Конкретные сроки — предмет договорённости, а не универсальная норма.
Если у вас уже есть опыт описания API-контрактов, используйте ту же логику для X-tee: структура «вход — выход — ошибки — повторы» хорошо переносится на ТЗ. Подробнее о таком контракте можно прочитать в материале «Как описать контракт API: входные данные, ошибки и повтор запросов».
Операции: как описать сервисы и методы
Раздел операций — сердце ТЗ. Здесь недостаточно перечислить названия методов. Для каждой операции нужны назначение, вход, выход, ограничения, ошибки и правила повторного вызова. Если операций много, сгруппируйте их по сценариям: например, «получение справки», «поиск по идентификатору», «передача заявления», «массовая выгрузка».
Сводная таблица помогает увидеть пробелы. Ниже — пример того, как можно структурировать операции в ТЗ. Названия и состав полей условны: замените их на свои.
| Операция | Назначение | Вход | Выход | Ошибки | Повтор |
|---|---|---|---|---|---|
| Получение записи по идентификатору | Вернуть карточку объекта | Идентификатор, контекст запроса | Карточка или признак «не найдено» | Не найдено, нет доступа, неверный формат | Только при транспортной ошибке; «не найдено» не повторять |
| Поиск по параметрам | Найти объекты по фильтрам | Фильтры, пагинация, сортировка | Список и, если поддерживается, общее количество | Неверный фильтр, слишком широкий запрос | Ограниченно, с изменением параметров |
| Передача заявления | Создать объект на стороне сервиса | Тело заявления, идентификатор отправителя | Идентификатор заявления и статус | Ошибка валидации, конфликт, недоступность | Только идемпотентно, с ключом запроса |
| Получение статуса | Показать состояние обработки | Идентификатор заявления | Статус и история переходов | Не найдено, нет доступа | Можно, если статус ещё не финальный |
| Пакетная выгрузка | Передать набор данных за период | Период, формат, размер порции | Файл или задание на выгрузку | Слишком большой объём, таймаут | По идентификатору задания, без дублей |
Для каждой операции опишите не только «счастливый путь», но и поведение на границах. Что считается пустым ответом? Может ли операция вернуть частичный результат? Какие поля обязательны, а какие могут отсутствовать? Что делать, если данных больше, чем помещается в один ответ?
Полезно договориться о служебных полях. В X-tee запросы сопровождаются идентификаторами клиента, сервиса, пользователя и запроса. В ТЗ укажите, какие из них вы используете для трассировки, что попадает в логи и как идентификатор запроса связывает запись на стороне потребителя и сервиса. Точный состав и правила заполнения сверяйте с документацией X-tee: они могут зависеть от версии и типа сервиса.
Синхронные, асинхронные и пакетные сценарии
Синхронный сценарий удобен, когда ответ нужен сразу. В ТЗ для него нужны ожидаемое время ответа, таймаут на стороне клиента и правило, что делать при превышении. Если сервис не успевает, потребитель не должен бесконечно ждать: опишите, уходит ли запрос в повтор, показывается ли пользователю сообщение или сценарий переводится в асинхронный режим.
Асинхронный сценарий требует других деталей: идентификатор задания, способ получения результата, список статусов, правило хранения результата и поведение при отмене. Если статусная модель не описана, потребитель начнёт угадывать, что означает «в обработке» и можно ли запрашивать результат повторно.
Пакетная выгрузка — отдельный жанр. Здесь важны формат файла, кодировка, разделители, размер порции, порядок сортировки и правило, что делать, если данные изменились во время выгрузки. Не смешивайте пакетную выгрузку с обычным поиском в одном методе только потому, что они относятся к одной сущности: у них разные ограничения и разная цена ошибки.
Объёмы, пагинация и ограничения
Ограничения лучше описывать числами, которые стороны подтвердили, а не общими словами «большие объёмы». Если точных лимитов пока нет, зафиксируйте, кто и когда их определяет, и как потребитель узнает о превышении. Для пагинации укажите тип курсора или номер страницы, максимальный размер страницы, стабильность сортировки и поведение при добавлении новых записей.
Отдельно опишите, что происходит при слишком широком запросе. Сервис может вернуть ошибку, потребовать сузить фильтр или ограничить выборку. Любой из вариантов допустим, если он заранее описан и одинаково понимается обеими сторонами.
Тестовые данные: что подготовить и как описать
Тестовые данные — это не «что-нибудь для проверки». От их качества зависит, увидите ли вы ошибки до промышленного запуска. В ТЗ опишите, какие наборы нужны, кто их готовит и по какому признаку считается, что набор подходит.
- Синтетические данные. Основной набор лучше строить на вымышленных данных, которые не относятся к реальным людям. Так проще делиться наборами между командами и не создавать лишних рисков.
- Граничные случаи. Пустые значения, минимальная и максимальная длина, необычные символы, отсутствующие необязательные поля, несколько записей с одинаковыми признаками.
- Эталонные ответы. Для ключевых операций приложите пример ожидаемого ответа. Это помогает проверить формат, а не только факт получения данных.
- Наборы для разных ролей. Пользователь с полным доступом, пользователь с ограниченным доступом, пользователь без доступа. Ошибки авторизации нужно проверять так же, как и успешные вызовы.
- Данные для проверки ошибок. Набор, который гарантированно вызывает ошибку валидации, конфликт и «не найдено». Без него матрица ошибок останется теоретической.
- Версионность. Если сервис поддерживает несколько версий, укажите, какие тестовые наборы относятся к какой версии и что происходит при несовпадении.
Определите, где живут тестовые данные и как они обновляются. Если набор хранится в репозитории, опишите формат и правила изменения. Если данные генерируются, зафиксируйте зерно или алгоритм, чтобы результат был воспроизводим.
Осторожно с персональными данными. Использование реальных данных в тестовой среде может требовать правовой оценки и дополнительных мер защиты. Не записывайте в ТЗ «возьмём боевую выгрузку» как само собой разумеющееся: согласуйте с DPO или юристом, допустимо ли это, нужно ли маскировать данные и как ограничить доступ. Если правового основания нет, используйте синтетические наборы.
Представим ситуацию: команда договорилась проверять поиск на «реальных примерах», но не описала, откуда они берутся. В итоге один разработчик тестирует на пустой базе, другой — на выгрузке, которую нельзя показывать, а приёмка снова упирается в вопрос о данных. Гипотетический сценарий показывает, зачем в ТЗ нужен явный источник тестовых наборов и правило их использования.
Ошибки и повторные запросы: как договориться о поведении
Ошибки — самая частая зона расхождений. Одна сторона считает, что «сервис вернул ошибку», другая ждёт конкретный формат, код и инструкцию. В ТЗ разделите ошибки на категории и для каждой опишите, что видит потребитель и что он делает дальше.
Практичная классификация выглядит так: технические ошибки транспорта, ошибки авторизации и доступа, ошибки валидации, бизнес-ошибки и таймауты. Для SOAP-сервисов ошибка может приходить в виде SOAP Fault, для REST-подобных сценариев — в теле ответа и HTTP-статусе. Точный формат зафиксируйте в ТЗ и сверьте с документацией X-tee и реализацией сервиса: универсального ответа на все случаи нет.
Для каждой ошибки укажите: код или признак, человекочитаемое описание, категорию, можно ли повторять запрос, кто разбирает инцидент и что показывается пользователю. Если ошибка содержит идентификатор запроса, опишите, как его найти в логах. Это экономит время при разборе.
Повторные запросы требуют отдельного правила. Не все ошибки одинаковы: таймаут или временная недоступность могут допускать повтор, а ошибка валидации — нет. Если повторять всё подряд, можно создать дубли. Если не повторять ничего, пользователь увидит ошибку там, где достаточно было подождать.
Опишите политику повторов: сколько попыток допускается, с какой задержкой, есть ли ограничение по общему времени, что происходит после исчерпания попыток. Для операций, создающих объект, нужен ключ идемпотентности или другой механизм защиты от дублей. Если сервис не поддерживает идемпотентность, это нужно прямо написать и предложить альтернативу: например, сначала проверить статус, а затем повторять создание.
Проверка ТЗ на полноту. Возьмите одну операцию и разберите её по шагам: успешный вызов, пустой ответ, ошибка валидации, таймаут, повтор, дубль, отзыв доступа. Если хотя бы на один шаг в ТЗ нет ответа, раздел ошибок ещё не готов.
Логи и трассировка заслуживают отдельного абзаца. Зафиксируйте, какие события пишутся, сколько они хранятся и кто имеет доступ. Не описывайте в ТЗ конкретные сроки хранения, если они не согласованы с политикой организации: лучше указать ответственного и документ, где эти сроки определены.
Если ошибка воспроизводится в коде потребителя, полезно иметь план разбора: версия, логи, шаги воспроизведения. Об этом подробнее — в материале «Как найти причину ошибки на PHP: версия, логи и шаги воспроизведения». Тот же подход применим и к интеграции: без версии, логов и воспроизводимого сценария разбор превращается в переписку.
Приёмка и передача: критерии, тесты и сопровождение
Приёмка начинается не в день сдачи, а в момент, когда в ТЗ появляются проверяемые критерии. Формулировка «интеграция работает» не подходит: она не говорит, что именно проверялось. Замените её на список сценариев, которые должны пройти на согласованных тестовых данных.
В критерии приёмки включите успешные вызовы, граничные случаи, ошибки и повторы. Отдельно проверьте, что потребитель корректно обрабатывает пустой ответ, недоступность сервиса и отказ в доступе. Если в ТЗ есть пакетная выгрузка, добавьте проверку объёма, пагинации и поведения при изменении данных.
- Сценарии приёмки. Список проверок с ожидаемым результатом, а не только с названием операции.
- Матрица ошибок. Какие ошибки воспроизводятся, как они выглядят и что делает потребитель.
- Тестовые данные. Где лежат наборы, кто их обновляет и как подтверждается, что набор актуален.
- Документация. Описание операций, примеры, ограничения и известные особенности.
- Логи и трассировка. Какие идентификаторы позволяют связать запрос и ответ.
- Ответственные. Кто принимает результат, кто фиксирует замечания и кто подтверждает исправления.
- Порядок изменений. Как вносятся правки в контракт, как объявляется новая версия и что происходит со старой.
- Ограничения и риски. Что сознательно не входит в текущую версию и какие зависимости остаются.
Сопровождение лучше описать до запуска. Кто отвечает на инциденты в нерабочее время, если такой режим предполагается? Где публикуются уведомления об изменениях? Как потребитель узнаёт о плановых работах? Даже если ответы пока предварительные, их фиксация снижает вероятность сюрпризов.
В приложении к ТЗ перечислите артефакты: схемы, примеры, тестовые наборы, матрицу ошибок, чек-лист приёмки и контакты ответственных. Приложения не должны дублировать основной текст; их задача — дать разработчику и тестировщику конкретные материалы.
Хорошее ТЗ на интеграцию X-tee отвечает на три вопроса: что именно делает каждая операция, на каких данных это проверяется и как стороны ведут себя, когда что-то идёт не по плану. Если ответы записаны и согласованы, приёмка становится проверкой договорённостей, а не поиском недостающих деталей.
Что обязательно включить в ТЗ на интеграцию X-tee?
Минимальный набор: участники и их идентификаторы, перечень операций с входными и выходными данными, ограничения, тестовые данные, классификация ошибок, правила повторов, критерии приёмки и ответственные. Требования к security server и подключению сверяйте с официальной документацией X-tee, а не выводите из ТЗ.
Нужно ли описывать тестовые данные в ТЗ?
Да, иначе стороны по-разному поймут, что проверять. Опишите источник данных, способ генерации или маскирования, граничные случаи, эталонные ответы и ответственного за обновление наборов. Если используются реальные данные, вопрос требует отдельной правовой оценки.
Как описать ошибки X-tee в ТЗ?
Разделите ошибки на категории: транспорт, авторизация, валидация, бизнес-ошибки, таймауты. Для каждой укажите признак или код, описание, возможность повтора, ответственного и то, что видит пользователь. Точный формат ошибки сверьте с документацией и реализацией сервиса.
Сколько раз повторять запрос при ошибке?
Универсального числа нет: политика зависит от операции и характера ошибки. В ТЗ зафиксируйте допустимое число попыток, задержку, общий лимит времени и поведение после исчерпания попыток. Для создающих операций нужен механизм защиты от дублей.
Можно ли использовать реальные данные в тестовой среде?
Это может требовать правовой оценки и дополнительных мер защиты. Не считайте такой вариант само собой разумеющимся: согласуйте с DPO или юристом, допустимо ли использование, нужно ли маскирование и как ограничивается доступ. Без подтверждённого основания безопаснее синтетический набор.
Кто отвечает за приёмку интеграции?
Ответственного нужно назначить в ТЗ: кто принимает результат, кто фиксирует замечания и кто подтверждает исправления. Обычно участвуют владелец сервиса, представитель потребителя и тестировщик, но конкретный состав зависит от организации и проекта.