🤯 Разработчик вернул задачу. Я дописала. Снова вернул. Что не так то?! 🤯

Такое часто бывает в интеграционных задачах.

И часто дело не в том, что разработчик «придирается».
Дело в том, что по этой постановке сложно писать код.

Часть решений приходится принимать разработчику самому, и в итоге он начинает делать работу за аналитика — уточнять у прОдукта, дизайнера, QA и других команд, как система должна себя вести.



👉 5 мест, где аналитики чаще всего теряют детали в интеграционных задачах:


1️⃣ «Обработать ошибки» — это не требование, а отписка

👎 Плохо:
«Обработать ошибки внешней системы».

✅ Хорошо:
▫️ при HTTP 401 — обновить токен и повторить запрос
▫️ при HTTP 404 — показать пользователю, что данные не найдены
▫️ при HTTP 500 или timeout — залогировать ошибку и показать сообщение о временной недоступности, если предусмотрен кэш — вернуть данные из кэша по описанным правилам

Без конкретики разработчик может вывести пользователю одно универсальное «Что-то пошло не так» на любую ошибку.
И будет формально прав.
Потому что в требованиях ничего другого не написано.


2️⃣ Нет маппинга данных

👎 «Система передаёт данные пользователя во внешнюю систему».

Какие данные?
Из какого поля?
В каком формате?
Что делать, если значение пустое?

✅ В требованиях должна быть таблица маппинга:
▫️ поле на UI
▫️ поле в API нашей системы
▫️ поле в API внешней системы
▫️ поле в БД, если используется
▫️ тип данных
▫️ обязательность
▫️ правила валидации
▫️ что делать, если null / пусто / некорректный формат

Без этих требований разработчик угадывает как соотносятся данные между частями нашей и внешней системой.
И делает работу за аналитика.


3️⃣ Нет требований к аутентификации и авторизации

👎 «Авторизация через Bearer Token».

А дальше?

✅ Нужно описать:
▫️ где и как получаем токен
▫️ кто настраивает доступы для dev / stage / prod
▫️ где хранятся client_id, client_secret и другие секреты
▫️ когда токен считается истёкшим
▫️ как обновляется токен
▫️ что делать, если токен истёк посреди фоновой джобы
▫️ что делать, если обновить токен не удалось

Аутентификация во внешней системе — это не одна строка в требованиях.

Это отдельная задача с полноценным набором сценариев, которая требует проработки.


4️⃣ Нет Timeout и Retry

👎 Не описали ситуации:
Внешний сервис лёг.
Или отвечает слишком долго.
Или сеть моргнула на 2 секунды.

Что делает наша система?

Если это не описано, разработчик решит сам.

Обычно потом получается так:
запрос висит 30 секунд → падает с ошибкой → пользователь видит белый экран или «Что-то пошло не так».

✅ В требованиях нужно указать:

▫️ timeout на запрос
▫️ количество повторных попыток
▫️ интервал между попытками
▫️ нужен ли backoff
▫️ что делать после исчерпания попыток
▫️ что показываем пользователю
▫️ что логируем
▫️ нужна ли задача на повторную обработку

Интеграции ломаются не только тогда, когда API вернул ошибку.
Иногда он просто не ответил вовремя.


5️⃣ Нет логики при частичном успехе

Это боль всех массовых интеграций:
каталоги, импорт клиентов, обновление статусов, синхронизация заказов.

Например:
Отправили 10 000 записей.
9 847 обработались успешно.
153 упали с ошибкой.

Это успех или провал?

В требованиях нужен явный ответ:

▫️ что считается успешным результатом
▫️ что делать с упавшими записями
▫️ нужно ли повторять обработку
▫️ сколько раз повторять
▫️ кто увидит ошибку
▫️ где будет отчёт
▫️ можно ли продолжать процесс, если часть данных не обработалась

Без этого массовая синхронизация превращается в хаос.



👉 Если этого нет — задача почти гарантированно вернётся на доработку.

И это не потому, что разработчик вредный, а потому что нет требований к обработке ошибок.


#ИнтеграцииGA

📱 GetAnalyst | 💙 VK | 💬 Max