// интеграция информационных систем по API

Техническое задание на интеграцию информационных систем: что проверить до публикации закупки

В таких закупках речь идёт о связке двух-трёх систем: учётной системе, CRM, платёжном шлюзе, ведомственном сервисе. Заказчиком обычно выступает госорган или крупная компания, у которой эти системы уже работают по отдельности, а данные между ними до сих пор переносят вручную или файлами. Интеграция по API должна эту ручную работу убрать.

Особенность интеграции в том, что подрядчик не контролирует ни одну из сторон целиком. Одна система принадлежит заказчику, другая — вендору или ведомству, третья — банку или оператору шлюза. Всё, что в ТЗ не зафиксировано про этот стык, потом решается переговорами, а не инженерной работой.

Поэтому исход проекта определяется ещё на этапе ТЗ. В типовом документе системы названы, цель сформулирована, а описание самого обмена сведено к одной-двум строкам. Ниже — места, где такие ТЗ чаще всего дают слабину, и что в них стоит написать.

Что обычно упускают в ТЗ

Системы названы, но описания их API нет, и не указано, кто его предоставит

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

Как написать правильно. Добавьте раздел «Исходные данные для интеграции»: по каждой системе — версия, тип интерфейса, ссылка на актуальную документацию или приложение к ТЗ. Отдельной строкой укажите, кто и в какой срок после подписания договора передаёт доступ к документации, и что считается задержкой по вине заказчика.

Не описано поведение при сбое обмена

Чем оборачивается. Платёж прошёл, а в учёте он не отразился. Запрос ушёл, ответ не пришёл. Если в ТЗ не сказано, что система делает в таких случаях, подрядчик выбирает сам, и на приёмке заказчик обнаруживает, что дубли, потерянные записи или молчаливые отказы его не устраивают. Спорить не по чему: требования не было.

Как написать правильно. Опишите сценарии отказа явно: недоступность второй стороны, таймаут, ответ с ошибкой, повторная отправка одного и того же сообщения. Для каждого — что делает система: повторяет запрос, кладёт в очередь, помечает запись, уведомляет ответственного, и кого именно. Отдельно потребуйте защиту от дублей при повторах.

У второй стороны нет тестовой среды, и это нигде не оговорено

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

Как написать правильно. В ТЗ укажите, для каких систем нужен тестовый контур, кто его предоставляет и в какой срок. Если тестового контура у стороны нет, пропишите альтернативу: эмулятор, согласованный набор тестовых данных, окно проверки на боевой системе с описанием ограничений. Приёмочные испытания привяжите к этому контуру.

Ответственность за данные на стыке систем не распределена

Чем оборачивается. Когда в одной системе сумма или статус один, а в другой — другой, каждая сторона считает ошибкой чужую. Подрядчик говорит, что передал то, что получил. Владелец исходной системы — что она работает штатно. Заказчик остаётся без ответа, кто исправляет данные и кто за них отвечает.

Как написать правильно. Включите раздел о владении данными: для каждого объекта обмена — какая система является источником истины, кто отвечает за качество исходных данных, кто за преобразование при передаче. Пропишите порядок разбора расхождений: кто фиксирует, кто исправляет, в какой срок.

Нет требования к журналу обмена

Чем оборачивается. Спор о том, отправлялось ли сообщение, что в нём было и какой ответ пришёл, невозможно разрешить без записей. Без журнала разбор инцидента превращается в сверку памяти участников, а претензии к подрядчику или к владельцу соседней системы остаются недоказанными.

Как написать правильно. Требуйте журнал обмена отдельным пунктом: что фиксируется (время, направление, идентификатор операции, статус, код ошибки), как долго хранится, кто имеет доступ к просмотру, как защищены персональные и платёжные данные в записях. Укажите, что журнал является основанием при разборе споров.

Приёмка описана общими словами: «интеграция работает»

Чем оборачивается. Без проверяемых критериев акт можно не подписывать неограниченно долго или подписать, не проверив ничего существенного. Обе стороны оказываются в позиции, где любая оценка результата субъективна.

Как написать правильно. Для каждого сценария обмена составьте перечень проверок: входные данные, ожидаемый результат, среда проверки. Включите в приёмку негативные сценарии из раздела о сбоях и проверку журнала. Условие подписания акта сформулируйте через прохождение этих проверок.

Что даёт хорошее ТЗ

Заказчик получает закупку, в которой подрядчики оценивают один и тот же объём работ, а заявки сопоставимы между собой.

Границы ответственности между системами и сторонами заданы заранее, поэтому спорные ситуации решаются по документу, а не по договорённости.

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

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

Сколько стоит и сколько занимает

Техническое задание — от $400, 1–4 недели: цена зависит от сложности системы, архитектуры, стека и интеграций. Разработка на субподряде — по объёму контракта, оценка до подачи заявки.

ТЗ для тендера или субподряд — подробнее →

Заказчиков и закупки не называем: разбираем типовое ТЗ, а не чей-то тендер.

Готовите закупку или уже выиграли тендер?

Обсудить тендер