Техническое задание на API-интеграцию должно позволять разработчику реализовать обмен, а владельцу процесса — проверить результат. Перечня «передавать клиентов, товары и заказы» недостаточно: неясны источник данных, момент передачи, обязательные поля, правила обновления, реакция на ошибку и критерий завершения операции.
Хорошее ТЗ строится от бизнес-события. Сначала описывают, что произошло и какой результат нужен двум системам, затем фиксируют объекты и поля, идентификаторы, последовательность вызовов, повторы, безопасность, мониторинг и приёмочные сценарии.
Начните с границы и результата интеграции
В одном абзаце зафиксируйте цель без технических украшений. Например: «После подтверждения заказа в интернет-магазине создать заказ в системе исполнения, зарезервировать доступный товар и вернуть на сайт подтверждённый номер и состояние. Изменения отгрузки и отмены передавать обратно».
Рядом перечислите то, что не входит в этап: старые заказы, бухгалтерские документы, массовая очистка справочника или обратное редактирование товара. Явная граница защищает проект от бесконечного расширения.
| Раздел ТЗ | На какой вопрос отвечает | Проверяемый результат |
|---|---|---|
| Цель и границы | Какой процесс связываем | Понятно, что входит в запуск |
| Объекты и владельцы | Где создаются истинные данные | Нет конфликтующего редактирования |
| События и последовательность | Когда и в каком порядке передавать | Процесс воспроизводим |
| Ошибки и повторы | Как система восстанавливается | Нет дублей и тихих потерь |
| Мониторинг | Кто увидит отклонение | Проблема имеет владельца |
| Приёмка | Как доказать готовность | Есть однозначные тесты |
Составьте реестр объектов и мастер-источников
Для клиента, товара, цены, остатка, заказа, оплаты и статуса определите систему-владельца. Если поле можно менять в обеих системах, ТЗ должно содержать правило разрешения конфликта. Фраза «двусторонняя синхронизация» без такого правила создаёт циклические обновления и случайные перезаписи.
Для каждого объекта нужны внутренний и внешний идентификаторы. Email, телефон или название товара нельзя использовать как единственный ключ: они меняются и могут повторяться. Связь идентификаторов хранится явно.
Описывайте поля вместе с правилами
Таблица полей должна содержать не только название и тип. Укажите обязательность, источник, допустимые значения, преобразование, поведение при пустом значении и пример без персональных данных.
| Поле | Правило | Ошибка или особый случай |
|---|---|---|
| external_id | Стабильный уникальный ключ источника | Повтор обновляет тот же объект |
| status | Сопоставляется по утверждённой таблице | Неизвестное значение помещается в очередь разбора |
| amount | Передаётся с валютой и правилом округления | Несовпадение блокирует финансовое подтверждение |
| updated_at | Время изменения с часовым поясом | Старое событие не перезаписывает новое состояние |
| warehouse_id | Ссылка на таблицу соответствий складов | Неизвестный склад требует настройки |
Зафиксируйте события и порядок
Для каждого сценария укажите триггер, предусловия, запрос, ожидаемый ответ и последующие действия. «Заказ изменён» слишком широко: изменение комментария, адреса и состава имеют разные последствия после начала комплектации.
- Источник фиксирует бизнес-событие в собственной транзакции.
- Событие попадает в надёжную очередь обмена.
- Получатель проверяет идентификатор и версию данных.
- Операция выполняется один раз и возвращает однозначный результат.
- Источник отмечает доставку события либо планирует повтор.
- Контрольная сверка обнаруживает редкие пропуски.
Опишите повтор до того, как произойдёт сбой
Сеть может оборваться после выполнения операции, но до получения ответа. Поэтому повтор того же запроса должен быть безопасным. Клиент передаёт idempotency key или устойчивый идентификатор операции, а сервер возвращает прежний результат вместо создания дубля.
Разделите временные и бизнес-ошибки. Таймаут или недоступность сервиса допускают автоматический повтор с интервалом. Неизвестный товар, закрытый склад или запрещённый переход статуса требуют исправления данных или решения оператора. Бесконечно повторять их бессмысленно.
Не оставляйте мониторинг техническому журналу
Логи полезны разработчику, но бизнесу нужна очередь отклонений: объект, операция, причина, число попыток, время следующего повтора и ответственный. Для критических событий задают контрольный срок. Например, подтверждённый заказ не должен оставаться без результата резерва дольше утверждённого интервала.
| Сценарий приёмки | Ожидаемый результат | Что доказывает |
|---|---|---|
| Обычное создание | Объект создан и идентификаторы связаны | Основной маршрут работает |
| Повтор того же запроса | Дубль не создан, возвращён прежний результат | Идемпотентность |
| Недоступность получателя | Событие сохранено и доставлено после восстановления | Устойчивость очереди |
| Некорректное поле | Понятная ошибка и задача ответственному | Управляемость данных |
| События пришли не по порядку | Старое состояние не перезаписало новое | Контроль версий |
| Контрольная сверка | Намеренно пропущенный объект найден | Выявление тихих потерь |
Безопасность и эксплуатация
В ТЗ фиксируют способ авторизации, минимальные права, хранение секретов, шифрование канала, ограничение частоты, маскирование персональных данных в логах и порядок смены ключей. Боевые доступы не включают в документ и не передают вместе с примерами.
Также нужны владельцы систем, контакт при инциденте, допустимое окно недоступности, порядок остановки обмена и обратного запуска. Версия API и политика совместимости защищают от внезапного изменения одной стороны.
Финальная проверка ТЗ
- цель сформулирована как бизнес-результат;
- границы этапа и исключения перечислены;
- для каждого объекта определён мастер-источник;
- идентификаторы и таблицы соответствий описаны;
- события имеют триггеры и предусловия;
- повторы не создают дубли;
- ошибки разделены по способу обработки;
- мониторинг показывает бизнес-объект и ответственного;
- приёмочные тесты включают негативные сценарии;
- правила безопасности и эксплуатации согласованы.
Техническое задание готово, когда по нему можно не только написать код, но и доказать корректность обмена при обычной работе и сбоях. Для интеграций вокруг ядра Business Reactor такой контракт помогает сохранить единую логику заказов, статусов и ответственности между подключаемыми системами.
