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

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

Чем серьёзнее проект, тем это заметнее. Платёжные системы, банки, биллинг оператора, телефония, CRM, карты, госсервисы, склад, курьеры — почти ничего интересного не живёт в вакууме. Настоящий продукт почти всегда стоит на десятке чужих API.

Почему это так дорого

Свой код ты понимаешь целиком. Чужую систему — нет. И именно на этой границе прячется всё самое времязатратное.

• Документация врёт. Не со зла — просто она отстаёт от реальности. Поле, помеченное как обязательное, приходит пустым. Ответ, описанный как JSON, иногда прилетает как строка с ошибкой. Пока не увидел реальный трафик — не знаешь, как оно себя ведёт.
• Форматы и мелочи. Кодировки, часовые пояса, формат дат, деньги (копейки против дробных, округления). Одна неверная копейка в платёжке — и это уже не «мелочь».
• Сеть не идеальна. Запрос ушёл, ответ потерялся — а деньги списались. Значит, нужны таймауты, повторы, идемпотентность, дедупликация, очереди. Половина работы над интеграцией — это обработка того, что пошло не так.
• Две системы — две правды. Твоя база говорит одно, чужая — другое. Появляются сверки, компенсирующие операции, ручные разборы расхождений.
• Доступы и безопасность. Подписи запросов, токены, ротация ключей, «пришлите нам статический IP», белые списки, отдельный канал. Это тоже время.
• Тестовых сред либо нет, либо они не похожи на прод. И ты узнаёшь о поведении системы уже на боевом трафике.

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

Из опыта

Мне довелось делать интеграции с CRM и телеком-системами, USSD- и SMS-сервисами, банками и merchant-инфраструктурой, а в собственной доставке — с телефонией. Задачи разные, но узкое место всегда одно и то же: не «написать свою логику», а надёжно ужиться с чужой системой, которая живёт по своим правилам и иногда молча меняет поведение.

Именно поэтому оценка «сам продукт — неделя» почти всегда оказывается неполной. Продукт — да, неделя. А потом три недели на то, чтобы он корректно разговаривал со всем, к чему подключён.

Что помогает

За годы набралось несколько привычек, которые реально экономят нервы:

• Прячь чужое за адаптером. Отдельный слой, который переводит чужой API в твою модель. Меняется чужая сторона — правишь один слой, а не весь продукт.
• Считай, что всё упадёт. Таймауты, повторы с нарастающей задержкой, идемпотентные ключи, очереди. Не «если», а «когда».
• Логируй реальный обмен. Когда что-то расходится, спор решает не документация, а лог запроса и ответа. Наблюдаемость важнее, чем кажется.
• Документируй фактическое поведение, а не обещанное. Твои заметки по чужому API часто полезнее их официальной документации.
• Закладывай время на интеграции сразу. Не в конце, «на всякий случай», а как основную часть работы.

Главная мысль

Со временем я перестал воспринимать интеграции как «приклеивание» готового продукта к внешнему миру. Чаще всего интеграции и есть продукт — по крайней мере, большая и самая сложная его часть. Пользователь не видит этот слой, но именно от него зависит, работает система на самом деле или только на демо.

Поэтому, планируя проект, я теперь задаю себе неудобный вопрос сразу: не «что мы построим?», а «с чем это должно будет ужиться — и сколько это на самом деле стоит?».