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