Интеграции для системного аналитика: REST, SOAP, очереди и описание обмена между системами

Частое заблуждение новичков: интеграция описана, если в Swagger есть метод с полями. Контракт фиксирует один вызов, а интеграция — сценарий целиком: порядок вызовов, источник правды для каждого поля, поведение при недоступности партнёра, способ сверить данные. Сбои чаще всего случаются в промежутке, когда запрос ушёл, а ответ не пришёл, и именно его аналитик обязан описать для обеих сторон.

Что аналитик решает, когда системы нужно связать

Работа начинается с вопросов, а не с выбора технологии. Аналитик выясняет, какое событие запускает обмен, нужен ли результат сразу, сколько сообщений ожидается в обычный день и в пик, какая система владеет данными и кто узнаёт о сбое. От ответов зависят протокол, таймауты и формат ошибок. Затем он рисует диаграмму последовательности, составляет таблицу соответствия полей, согласует контракт с командой партнёра и описывает обработку ошибок. Если в спецификации не сказано, что делать при повторной доставке, каждая сторона решит это по-своему.

REST, SOAP, gRPC или очередь: когда что

Способ обмена чаще задаёт партнёр или архитектура компании, чем вкус аналитика. Внешние платёжные и логистические сервисы обычно дают REST API, банки и старые корпоративные системы нередко работают через SOAP, внутри микросервисной платформы выбирают gRPC или брокер сообщений. Таблица показывает, что придётся описывать в каждом случае.

Отдельно стоит ESB — сервисная шина предприятия. Системы общаются не напрямую, а через центральный узел, который принимает сообщение, преобразует формат и доставляет получателям. Аналитик тогда описывает два участка, до шины и после неё, и правило преобразования внутри. Новую систему подключают один раз, зато любое изменение проходит через команду шины. Устройство gRPC, брокеров, OpenAPI и Postman разобрано в отдельных статьях сайта.

Синхронно или асинхронно

При синхронном вызове клиент отправляет запрос и ждёт ответа: создал заказ — сразу получил номер. Это легко описать и отладить, но системы связаны жёстко: если партнёр отвечает десять секунд, столько же ждёт пользователь. При асинхронном обмене отправитель оставляет сообщение в очереди или получает ответ «принято», а результат приходит позже — событием из брокера или входящим HTTP-уведомлением, вебхуком. Он выдерживает пики и сбои, но аналитику нужно описать промежуточные статусы, идентификатор связи запроса с ответом и то, что видит пользователь до результата. В платёжных сценариях оба подхода сочетаются: команда уходит синхронно, итог приходит асинхронно.

Учебный пример: заказ, оплата и учётная система

Ситуация учебная. Интернет-магазин создаёт платёж у провайдера и передаёт оплаченный заказ в учётную систему склада. Шаги записаны в порядке событий, потому что так их потом проверяет тестировщик: каждый шаг — отдельная точка, где обмен может сломаться.

1. Магазин синхронно вызывает REST-метод провайдера «создать платёж» и получает ссылку на оплату.
2. Покупатель платит, провайдер присылает вебхук со статусом «оплачен».
3. Магазин проверяет статус платежа отдельным запросом и только потом меняет статус заказа.
4. Магазин кладёт сообщение «заказ оплачен» в очередь, учётная система забирает его и резервирует товар.

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

Маппинг полей: где теряются данные

Таблица маппинга показывает, какое поле источника становится каким полем получателя и по какому правилу. Ошибки здесь тихие: обмен проходит, но на складе оказывается не та сумма. Фрагмент для шага 4:

Чаще всего ломаются даты без часового пояса: заказ, оформленный в 01:30 по Москве, в UTC относится к предыдущему дню. Дальше идут суммы в разных единицах, расходящиеся справочники и разница между пустой строкой, null и отсутствующим полем.

Ошибки, таймауты и повторы

Ответ 4xx означает, что запрос неверен, и повторять его без изменений бессмысленно. Ответы 5xx и обрыв соединения означают, что результат неизвестен: сервер мог выполнить операцию и не успеть ответить. Повтор нужен, но он не должен создать второй платёж. Защиту от дублей называют идемпотентностью: клиент передаёт уникальный ключ, и сервер, увидев его снова, возвращает результат первого запроса.

Как это превращается в конкретные правила, видно в документации API ЮKassa: ключ передают в заголовке Idempotence-Key для запросов POST и DELETE, длина — не больше 64 символов, рекомендуемый формат — UUID версии 4, идемпотентность действует 24 часа после первого запроса, затем повтор обрабатывается как новый. Там же сказано, что ответ 500 приходит, если за 30 секунд нельзя дать точный ответ, и он не говорит ни об успехе, ни о неудаче операции.

В рекомендациях ЮKassa по обработке ответов при 500 советуют повторить запрос с теми же данными и тем же ключом или запросить объект методом GET, а если статус не меняется, повторять с возрастающим интервалом. После 4xx запрос повторяют с новым ключом и новыми данными, разобравшись в причине. Если в ТЗ магазина записать «при ошибке 500 показать „оплата не прошла“», покупатель может заплатить второй раз, хотя первый платёж уже проведён.

Входящие уведомления устроены зеркально. По описанию вебхуков ЮKassa получатель отвечает кодом 200, любой другой код считается невалидным, и доставка продолжается 24 часа с момента события. Значит, обработчик в учебном примере должен быть идемпотентным сам: повторное уведомление не должно второй раз списать товар.

Что включить в спецификацию интеграции в ТЗ

Раздел читают разработчики двух команд, тестировщики и поддержка, поэтому он идёт от общей картины к деталям и заканчивается действиями при сбое.

1. Назначение обмена, участники и владелец данных по каждому объекту.
2. Диаграмма последовательности с успешным и ошибочными сценариями.
3. Протокол и ссылка на контракт: OpenAPI, WSDL, .proto или AsyncAPI.
4. Таблица маппинга и справочники значений.
5. Таблица ошибок: код, причина, действие клиента, интервал и предел повторов.
6. Объёмы, частота, таймауты, авторизация, адреса стендов.
7. Мониторинг и ежедневная сверка данных двух систем.

С чего начать и в каком порядке осваивать

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

1. Разберите HTTP: методы, коды ответа, заголовки, тело запроса.
2. Освойте JSON и XML, научитесь читать JSON Schema и XSD.
3. Выполните в Postman успешный и ошибочный запрос к любому публичному API.
4. Опишите учебную интеграцию двух систем: диаграмма последовательности и маппинг.
5. Добавьте таблицу ошибок с правилами повторов и идемпотентности.
6. Перепишите тот же обмен через очередь или вебхук и сравните описания.

Упражнения и типичные ошибки

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

Типичные ошибки: описан только успешный сценарий, нет таймаута, «повторить при ошибке» без различия 4xx и 5xx, нет идентификатора связи запроса и ответа, не решено, какая система главная при расхождении. Проверка простая: если тестировщик пишет по спецификации негативные проверки, не задав ни одного вопроса, раздел готов.

Чему учат на курсах

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

На онлайн-курсе Skillbox «Системный аналитик + ИИ» за восемь месяцев проходят клиент-серверную архитектуру, интеграции, HTTP, REST, SOAP, диаграммы последовательности и проектирование API, а в портфолио есть OpenAPI-документ.

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

У Skillfactory на курсе «Профессия Системный аналитик» в модуле «Подготовка к разработке» заявлены работа с API и согласование интеграций, среди инструментов — REST API, Swagger и Postman, в портфолио — схемы интеграций. Сроки обучения на странице указаны по-разному, их стоит уточнить у школы.

Брокеры сообщений ни в одной из трёх программ по описанию отдельно не выделены. Если команда работает с очередями, асинхронный обмен, скорее всего, придётся доучивать самостоятельно.

Короткий вариант для тех, кто уже работает в IT, — онлайн-курс TeachMeSkills «Системный аналитик»: два месяца, 60 академических часов вживую без записей, модуль «Интеграция систем и документирование API» с XML, JSON, OpenAPI, REST, SOAP, Swagger и Postman.

Как навык влияет на доход

Отдельной надбавки «за интеграции» нет: умение описывать обмен входит в требования к системному аналитику. Влияет оно через задачи: тому, кто разбирается в ошибках и повторах, раньше доверяют связку с внешним партнёром. Ориентир даёт калькулятор зарплат Хабр Карьеры: медиана системного аналитика уровня Junior — 103 250 ₽ в месяц по 342 анкетам, половина ответов — от 75 000 до 136 666 ₽ (Россия без фильтра по городу, октябрь 2026 года). Это зарплаты из анкет, а не вилки вакансий, и цифра описывает профессию, а не навык.

Как выбрать обучение

Сравнить школы по цене, длительности и проверке работ поможет рейтинг онлайн-школ по системной аналитике. Перед оплатой попробуйте описать учебный пример с оплатой: если вы можете объяснить, почему ответ 500 не означает отказ и что делать с повторным вебхуком, база для программы среднего уровня у вас уже есть.