Когда API есть, а интеграция всё равно не работает

Иллюзия спецификации: Что скрывается за наличием документации

В техническом задании на интеграцию иногда встречается почти обнадёживающая формулировка: «У системы есть API. Документация предоставлена».

После этого возникает естественное ожидание: осталось вызвать несколько endpoint — и системы начнут обмениваться данными. На практике всё часто оказывается гораздо сложнее.

Наличие API означает только одно: у системы существует некоторый программный интерфейс для взаимодействия. Это ещё не означает, что две конкретные системы легко соединить.

Поэтому интеграция — это не соединение двух endpoint.

Это сквозное согласование ключевых архитектурных слоев между двумя системами:

• › Согласование данных
• › Согласование правил
• › Согласование идентификаторов
• › Согласование безопасности
• › Согласование ошибок
• › Согласование состояний
• › Согласование зон ответственности между двумя независимыми системами

API — это интерфейс, а не готовая интеграция

Самая распространённая ошибка начинается с неправильного понимания самого API.

API — это контракт, по которому одна система может обратиться к другой.

Кажется, что задача решена. Но на практике необходимо ещё выяснить множество скрытых параметров взаимодействия:

• › Какие поля обязательны?
• › Какие типы данных используются?
• › Какие значения допустимы?
• › Какие справочники применяются?
• › Как определяется клиент?
• › Как передаётся дата?
• › В какой валюте указывается сумма?
• › Какие статусы существуют?
• › Какие права нужны?
• › Как обрабатываются ошибки?
• › Сколько запросов разрешено отправлять?
• › Можно ли повторять запрос?
• › Как получить конечный результат операции?

И только после этого становится понятно, насколько две системы действительно совместимы.

Главная проблема — системы могут по-разному понимать одни и те же данные

Представим, одна система передаёт заказ:

{
  "customer": "12345",
  "amount": 150000,
  "currency": "RUB",
  "status": "new"
}

{
  "clientId": "C-12345",
  "total": 150000.00,
  "currencyCode": 643,
  "state": "CREATED"
}

На первый взгляд всё просто. Но принимающая система ожидает совершенно другие ключи и типы данных. Здесь уже скрыто несколько критических различий:

А значит, простого пересылания JSON недостаточно.

REQUIRED_PROCESS: DATA_TRANSFORMATION_LAYER_ENGAGED

Формат данных — только верхний слой проблемы

Даже если обе системы используют JSON, это не означает, что они совместимы.

JSON описывает синтаксис. Но не определяет бизнес-смысл данных.

Что именно означает эта дата?

Формально обе передают корректный JSON. Но итоговый бизнес-результат из-за разной интерпретации может оказаться абсолютно неправильным.

Поэтому при интеграции нужно согласовывать не только формат, но и семантику данных.

REQUIRED_PROCESS: METADATA_SEMANTIC_ALIGNMENT

Одна из самых дорогих проблем — разные справочники

Представим структуру справочников в разных контурах.

1 — Москва
2 — Санкт-Петербург
3 — Екатеринбург

MOW — Москва
LED — Санкт-Петербург
SVX — Екатеринбург

Технически API может прекрасно работать. Запросы принимаются. Ответы приходят. Но между системами нет общего справочника. Значит, интеграционный слой должен осуществлять сквозной маппинг:

И таких справочников в корпоративных системах могут быть сотни:

• › Подразделения
• › Склады
• › Страны
• › Валюты
• › Единицы измерения
• › Виды документов
• › Статусы
• › Типы клиентов
• › Категории товаров

Поэтому интеграционный проект часто оказывается в значительной степени проектом согласования данных.

REQUIRED_PROCESS: MASTER_DATA_ALIGNMENT

Идентификаторы тоже не совпадают сами собой

Особенно хорошо это видно на примере клиентов.

customer_id = 15273

partner_id = 000045821

external_id = C-98231

Для человека это одна и та же организация. Для систем — три разных идентификатора. Поэтому интеграция должна иметь механизм сопоставления:

Если такой mapping не спроектирован, система может создавать дубли.

Авторизация — ещё один отдельный уровень

Предположим, endpoint существует. Но кто имеет право его вызвать?

API может требовать различные механизмы проверки подлинности:

• › API key;
• › Basic Authentication;
• › OAuth 2.0;
• › JWT;
• › client certificate;
• › HMAC-подпись;
• › mTLS;
• › корпоративную систему идентификации.

И даже после успешной аутентификации остаётся вопрос прав.

Система может прекрасно видеть пользователя или сервис, но запрещать ему конкретную операцию.

Иногда проблема вообще не в API, а в сети

Особенно часто это встречается в корпоративном контуре.

API может быть опубликован и документирован, но доступ к нему разрешён только:

• › из определённой сети;
• › через VPN;
• › с конкретных IP;
• › через proxy;
• › через защищённый шлюз;
• › по клиентскому сертификату.

Например:

Поэтому при интеграции необходимо проверять не только документацию разработчика, но и реальный сетевой контур.

API может быть доступен, но не подходить по производительности

Допустим, интеграции нужно передать 2 миллиона записей.

Получается следующая схема выполнения:

При проектировании больших потоков данных нужно учитывать:

• › rate limit;
• › размер страницы;
• › pagination;
• › время ответа;
• › ограничения на параллельные запросы;
• › временные блокировки;
• › допустимую нагрузку на источник.

API может быть функционально подходящим, но эксплуатационно непригодным для нужного сценария.

Rate limit — не ошибка системы

Разработчик иногда видит:

и воспринимает это как неисправность. На самом деле сервер сообщает: Вы отправили слишком много запросов за определённый период. Ограничение может быть введено специально.

Интеграция должна уметь корректно работать с такими ограничениями.

Для этого на уровне архитектуры могут использоваться:

• › ограничение скорости запросов;
• › очереди;
• › повторные попытки;
• › exponential backoff;
• › пакетная обработка;
• › инкрементальная синхронизация.

Ошибка HTTP не всегда означает ошибку бизнес-операции

Есть ещё одна неприятная ситуация. Предположим, интеграция отправила:

Идентификация запроса может происходить, например, через уникальный идентификатор операции:

Request ID: 8A7F-291C

HTTP-коды — только часть контракта

Даже если API использует стандартные HTTP-коды, этого может быть недостаточно.

Система может вернуть ложный положительный ответ:

{
  "success": false,
  "errorCode": "CLIENT_BLOCKED"
}

Интеграция должна понимать оба уровня.

Версия API может изменить всё

Предположим, сегодня используется:

В новой версии происходят кардинальные изменения:

• › переименовано поле;
• › изменён формат даты;
• › удалён старый статус;
• › другой механизм авторизации;
• › изменена структура ответа.

Нужно заранее понимать: как долго поддерживается версия, как сообщается о breaking changes и как будет выполняться миграция.

«API есть» не означает «API покрывает нужный бизнес-процесс»

Это, пожалуй, самая важная проблема. Предположим, бизнесу нужно:

На первый взгляд всё есть. Но отдельного метода:

[ «Зарезервировать остаток» ] ──► ОТСУТСТВУЕТ

Значит, одного API недостаточно. Для решения этой архитектурной коллизии:

Именно здесь заканчивается задача «подключить API» и начинается интеграционное проектирование.

Иногда между системами нужен дополнительный слой

Представим топологию взаимодействия:

Такой слой может выполнять сразу несколько критических задач:

• › преобразование форматов;
• › сопоставление идентификаторов;
• › маршрутизацию;
• › авторизацию;
• › обработку ошибок;
• › повторные попытки;
• › ограничение нагрузки;
• › логирование;
• › аудит;
• › работу с очередями;
• › версионурование контрактов.

Это особенно полезно, когда одна система должна взаимодействовать не с одной, а с несколькими внешними системами.

Почему не стоит связывать всё напрямую

Представим предприятие, где одновременно функционируют:

• › ERP;
• › CRM;
• › WMS;
• › MES;
• › интернет-магазин;
• › сервис доставки.

If каждая система напрямую интегрируется со всеми остальными, формируется хаотичная топология связей:

Количество связей быстро растёт. Каждая интеграция начинает иметь собственную локальную логику.

Интеграционный слой позволяет эффективно централизовать часть этой трансляционной логики:

Его задача — изолированно управлять взаимодействием систем, а не скрывать дефекты плохой архитектуры.

Когда прямой API вполне достаточен

Не каждую интеграцию нужно усложнять.

Если в проекте присутствуют:

• › две системы;
• › стабильный контракт;
• › совпадающие модели данных;
• › понятная авторизация;
• › небольшое количество операций;
• › предсказуемая нагрузка;
• › простая обработка ошибок;

прямой вызов API может быть лучшим решением. Например:

Хорошая архитектура — не та, в которой больше компонентов.

Она та, в которой сложность строго соответствует реальной задаче.

Когда без интеграционного слоя уже сложно

Дополнительная прослойка начинает становиться оправданной, когда появляются:

• › несколько систем-источников;
• › разные форматы данных;
• › сложное сопоставление справочников;
• › очереди;
• › повторная обработка;
• › разные модели авторизации;
• › высокая нагрузка;
• › требования к аудиту;
• › сложная маршрутизация;
• › разные версии API;
• › необходимость централизованного мониторинга.

Тогда интеграция окончательно становится самостоятельным архитектурным компонентом.

Синхронная интеграция не всегда подходит

Ещё одна распространённая ошибка — пытаться сделать весь обмен данных синхронным.

Но асинхронность требует уже другой архитектурной модели:

REQUIRED_CONTROLS: СТАТУСЫ // ПОВТОРЫ // ИДЕМПОТЕНТНОСТЬ // КОНТРОЛЬ_ДОСТАВКИ

Что делать с ошибками

Надёжная интеграция должна заранее отвечать на вопрос: Что произойдёт, если соседняя система не отвечает?

Недостаточно написать: «В случае ошибки повторить запрос». Нужно четко определить регламент обработки:

• › сколько раз;
• › через какой интервал;
• › какие ошибки повторять;
• › какие не повторять;
• › где хранить неуспешные сообщения;
• › как уведомлять операторов;
• › как предотвращать дубли;
• › как восстановить обработку после сбоя.

Например:

Логирование интеграции должно быть полноценным

Если интеграция перестала работать, вопрос обычно звучит так: «А что именно произошло?»

Для оперативного ответа необходимо непрерывно логировать ключевые метрики транзакции:

• › идентификатор операции;
• › время;
• › источник;
• › получателя;
• › endpoint;
• › статус;
• › время выполнения;
• › тип ошибки;
• › идентификатор корреляции;
• › результат обработки.

В enterprise-среде сквозная наблюдаемость должна жестко сочетаться с контролем доступа к самим журналам.

Интеграция должна переживать изменения

Хорошая интеграция — это не та, которая работает в день запуска.

Она должна неизменно оставаться работоспособной, когда:

• › изменяется версия API;
• › добавляются новые поля;
• › меняются справочники;
• › растёт объём данных;
• › меняется нагрузка;
• › обновляется система-получатель;
• › временно недоступен внешний сервис.

Поэтому ещё на этапе проектирования полезно определить регламенты сопровождения контрактов:

API-контракт — это договор между системами

Полезно воспринимать API именно как договор.

Проблема возникает, когда договор формально существует, но его бизнес-смысл не согласован.

Что означает 3?

Если интерпретация кода в системах не совпадает, технически запрос может пройти без единой ошибки. И именно такие коллизии особенно опасны.

Поэтому перед интеграцией нужно проверять не только документацию

Хорошая подготовка интеграционного проекта начинается примерно с такого набора вопросов:

Только после такой сквозной проверки можно адекватно и реалистично оценить сложность работ.

Почему оценка интеграции часто оказывается заниженной

В коммерческих предложениях иногда встречается формулировка: «Интеграция с системой X через API — 40 часов».

На первый взгляд всё понятно. Но на самом деле абсолютно неизвестно, что именно технически входит в эти 40 часов.

В полноценный скоуп работ по сквозной интеграции входит:

• › анализ модели данных;
• › mapping;
• › авторизация;
• › обработка ошибок;
• › повторные попытки;
• › очереди;
• › журналирование;
• › контроль дублей;
• › синхронизация справочников;
• › миграция существующих данных;
• › мониторинг;
• › тестовый контур;
• › поддержка нескольких версий API.

Поэтому оценивать масштаб интеграции только по количеству endpoint — примерно как оценивать архитектуру и строительство здания по количеству дверей.

Самая сложная часть интеграции часто находится не в коде

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

Именно поэтому интеграция — это не только примитивная задача для разработчиков.

REQUIRED_EXPERTISE: Она требует обязательного участия людей, которые досконально понимают сквозные процессы и данные обеих смежных систем.

Что на самом деле означает «интеграция работает»

Интеграцию нельзя считать успешной только потому, что транспорт возвращает статус:

Успешная интеграция на промышленном уровне означает, что:

• › данные передаются корректно;
• › бизнес-смысл сохраняется;
• › права работают правильно;
• › дубли контролируются;
• › ошибки обрабатываются;
• › временная недоступность переживается;
• › нагрузка находится в допустимых пределах;
• › изменения API контролируются;
• › операции можно диагностировать;
• › данные остаются согласованными.

Именно поэтому между поверхностным «API есть» и реальным «системы надёжно интегрированы» лежит довольно большая и сложная инженерная дистанция.

API — только одна часть интеграции

Когда компания говорит: «У нашей системы есть API, поэтому интеграция простая», правильнее задать несколько дополнительных вопросов.

• › Какие бизнес-операции реально доступны через API?
• › Совпадают ли модели данных?
• › Как сопоставляются идентификаторы?
• › Кто отвечает за справочники?
• › Какие ограничения есть по частоте и объёму запросов?
• › Как обрабатываются ошибки и повторные запросы?
• › Как контролируются версии?
• › Что происходит при недоступности одной из систем?
• › Нужно ли синхронное взаимодействие или лучше очередь?
• › Можно ли безопасно связать системы напрямую?

И только после ответов становится понятно, что именно предстоит строить.

Потому что хорошая интеграция — это не ситуация, когда одна система умеет вызвать endpoint другой. Это ситуация, когда две разные информационные системы начинают согласованно выполнять общий бизнес-процесс.

🔒 Данные и доступ к системам заказчика обрабатываются в соответствии с согласованными требованиями к безопасности и конфиденциальности. Условия доступа, хранения и обработки данных определяются архитектурой проекта и договором.

Сайт носит исключительно информационный характер и не является публичной офертой в соответствии со статьёй 437 Гражданского кодекса РФ. Цены, состав и условия предоставления услуг уточняются при проектировании решения и фиксируются в договоре. Условия технического сопровождения и уровень сервиса могут дополнительно определяться отдельным соглашением (SLA).