Самая неприятная интеграция в моей практике не падала и не шумела. Запросы проходили, статусы менялись, мониторинг был зеленый. А бизнес в это время терял заказы, получал дубли оплат и звонил клиентам по отмененным заявкам.
Я видел это десятки раз: сам API обычно ни при чем. Проблема начинается в тот момент, когда сайт, CRM, 1С или платежный сервис по-разному понимают, что такое заказ, резерв, оплата и отгрузка. Если не разобрать это до кода, разработка просто ускорит путаницу.
Документация есть, а договоренности нет
Когда мне говорят: «У обеих систем есть API, значит интеграция будет быстрой», я сразу ставлю проект на паузу на пару часов и задаю один вопрос: какая система - источник истины. По заказам, остаткам, ценам, клиентам, статусам. Если ответа нет, через неделю начинаются конфликты данных, а через месяц люди уже сводят все руками.
У нас был оптовый интернет-магазин на Laravel 11, CRM и 1С. Обмен работал, статусы возвращались, явных ошибок почти не было. Но задержка в 10-15 минут ломала процесс: менеджеры брали в работу уже отмененные заказы, склад резервировал то, чего не было в остатках. При потоке 10 000 событий в день даже 1% ошибок - это 100 проблемных записей в сутки.
Можно быстро запустить интеграцию, если документация в порядке? Запустить можно. Гарантировать корректную работу - нет. Документация описывает методы и поля, но не снимает вопрос о смысле статусов и о том, кто меняет данные последним.
Ломается обычно в пяти и тех же местах
На реальных проектах проблемы почти всегда одинаковые. Меняется отрасль, стек, подрядчик, но точки отказа те же:
- разные обязательные поля и форматы данных
- отсутствие
Idempotency-Keyна повторных запросах - слабая обработка
429и5xx - лимиты API под пиковую нагрузку
- двусторонние конфликты, когда две системы обновляют один объект
Один кейс у нас не взлетел сразу. Подключили CRM к платежному сервису напрямую, без очереди и журнала обмена. В пиковый час внешний API начал отдавать 429 Too Many Requests, повторы не настроили, часть оплат не попала в CRM. Финансы закрывали день с расхождением почти на 380 000 ₽. Сначала мы попробовали просто увеличить частоту запросов. Это только ухудшило ситуацию.
Смотрите, вот минимальная таблица, которую я бы согласовал до первой строки кода:
| HTTP-код | Что происходит | Нужен повтор |
|---|---|---|
| 429 | лимит запросов | да |
| 500/502/503 | временный сбой сервиса | да |
| 400 | плохие данные | нет |
| 401/403 | нет доступа | нет |
| 422 | контракт не пройден | нет |
POST /payments
Idempotency-Key: pay-784512-2026-04-18
Content-Type: application/json
Если нет очереди, повторной обработки и нормального лога обмена, временный сбой превращается в тихую рассинхронизацию. Обычно ее находят уже после жалобы клиента.
Карта данных полезнее длинного ТЗ
Перед разработкой я всегда прошу простую таблицу соответствий. Без украшений. Какая сущность куда идет, какие поля обязательны, какие статусы допустимы, кто главный по данным, что делать при конфликте, какая задержка обмена приемлема.
На проекте с 1С и складской системой проблема вскрылась быстро. В одной системе статус «отгружен» означал передачу в доставку, в другой - проведение документов. Данные передавались корректно, но клиентам уходили неверные уведомления.
CTO логистической платформы как-то очень точно сказал: «Самый дорогой баг в интеграции - это когда обе стороны уверены, что статус понятен без уточнений».
До старта мне обычно хватает четырех артефактов:
- таблица полей и правил маппинга
- схема статусов и переходов
- допустимая задержка обмена - где до 30 секунд, где можно 3-5 минут
- правила повтора, отката и ручного восстановления
Если таблицы полей и схемы статусов еще нет, команда пока обсуждает интеграцию, а не управляет ею.
Мгновенный обмен нужен реже, чем кажется
Запрос «сделайте все в real-time» я слышу почти на каждом втором старте. По-честному, это редко оправдано. Чем больше событий летит мгновенно, тем выше цена поддержки и тем больнее любой сбой.
Остатки для витрины маркетплейса или статусы оплаты часто требуют почти мгновенного обмена. Справочники, архивные документы, служебные статусы и часть уведомлений спокойно живут пакетно. На одном B2B-проекте мы перевели обмен на смешанную схему: webhook для критичных событий, RabbitMQ 3.13 для очередей, batch раз в 3 минуты для вторичных данных. За 6 недель число инцидентов упало на 34%.
Когда систем становится больше двух, прямые связки начинают мешать. На 5 системах у вас уже 10 связей, на 6 системах - 15. В таких случаях я обычно выношу интеграцию в отдельный слой на Node.js 20 + NestJS, PostgreSQL 16 и RabbitMQ. Это проще тестировать, логировать и чинить ночью, когда одна из внешних систем легла.
Перед продом проверяют не «работает ли», а «как ломается»
На этом этапе часто экономят зря. Перед запуском нужны тестовая среда, тестовые сценарии, журнал обмена, алерты и ручной резервный сценарий на случай, если одна сторона недоступна. Деплой я бы делал по шагам: тестовые данные, ограниченный трафик, потом полный поток.
И еще один вопрос, который я всегда задаю подрядчику: где лог, как идут повторы, какой план отката, как тестируется отказ одной системы. Если ответ расплывчатый, интеграция пока сырая, даже если демо выглядит убедительно.
В ближайшие 3 дня сделайте одну вещь: соберите список сущностей, напротив каждой укажите источник истины и допустимую задержку, а потом спросите команду, что будет, если одна система исчезнет на 47 минут. Если ответ звучит как импровизация, код писать рано.
