Материал описывает подходы к построению интеграций между двумя информационными системами и может служить основой при выборе способа обмена данными для новых проектов.
В конце статьи — разделы 11 и 12 с деталями по работе с каталогами и сценарию «мастер-система / приёмник».
1. Задача
При интеграции двух систем нужно определить канал обмена (файловый или через REST API) и формат данных (JSON или XML). От этого зависят скорость обработки и надёжность обмена.
2. Два основных подхода
Файловый обмен (S3, SFTP, сетевая папка)
Одна система формирует файл и размещает его в согласованном хранилище, другая — забирает и обрабатывает. Обмен не мгновенный: данные обрабатываются с задержкой от нескольких минут до нескольких часов. Подходит для регулярных выгрузок, больших объёмов данных и систем без программного интерфейса (API). Если одна система — источник данных (мастер), а другая должна запрашивать данные файлами, см. раздел 12.
REST API
Одна система обращается к другой по HTTP — как к веб-сервису: отправляет запрос и сразу получает ответ. Обмен происходит в реальном времени (обычно за секунды). Подходит для операций, где результат нужен немедленно: создание заказа, проверка статуса, получение актуальных данных.
Формат данных (JSON или XML) выбирается отдельно от канала — оба формата можно использовать и в файлах, и в REST API.
3. REST API — как это работает
REST API — это набор адресов (URL), по которым одна система обращается к другой через HTTP. Каждый адрес выполняет определённое действие.
| Действие | Пример | Когда применять |
|---|---|---|
| Создание POST | Передать новый заказ в складскую систему | Нужно сразу получить подтверждение и номер заказа |
| Чтение GET | Запросить статус отгрузки или остаток товара | Нужны актуальные данные «здесь и сейчас» |
| Изменение PUT / PATCH | Обновить адрес доставки в существующем заказе | Корректировка уже созданных данных |
Что важно при REST-интеграции
- Авторизация — системы подтверждают право на обмен (токен, ключ API или сертификат)
- Формат ответа — код результата: успех (200/201), ошибка данных (400), недоступность (503)
- Документация — адреса и форматы описываются в спецификации OpenAPI
- Защита от дублей — повторная отправка запроса не должна выполнять операцию дважды
Комбинированный вариант для больших объёмов
Если нужно передать сотни тысяч или миллионы записей, их не отправляют одним HTTP-запросом. Сначала через REST создаётся задача на загрузку, затем файл размещается в S3, после чего через REST подтверждается завершение и проверяется статус обработки.
4. Способы файлового обмена
| Способ | Когда выбирать |
|---|---|
| S3 / Object Storage | Большие объёмы; автоматическая обработка файла сразу после появления |
| SFTP | Регламент или регулятор требует защищённую передачу по SFTP; часто для XML с электронной подписью |
| Сетевая папка (SMB) | Системы в корпоративной сети используют общий каталог (\\server\integration\). Временное решение — с планом перехода на S3 или SFTP |
Для любого способа нужно согласовать: правила именования файлов, структуру каталогов, признак «файл готов», контрольную сумму и подтверждение обработки. Подробнее — в разделе 11.
5. Примеры
| # | Сценарий | Подход |
|---|---|---|
| 1 | Ежедневная выгрузка справочника товаров (~100 000 позиций) | S3, файловый обмен |
| 2 | Передача реестра платежей контрагенту | SFTP |
| 3 | Создание заказа в складской системе в момент оформления | REST API |
| 4 | Выгрузка счетов через общий сетевой каталог | SMB + промежуточный сервис |
| 5 | Массовая загрузка данных (до 1 000 000 записей) | REST API + S3 |
| 6 | Запрос статуса отгрузки (опрос или уведомление) | REST API |
| 7 | Мастер-система выгружает справочники; система-приёмник запрашивает данные файлами | S3 / SMB — раздел 12 |
6. JSON или XML?
| JSON | XML |
|---|---|
|
|
Правило: если нет требования использовать XML — выбираем JSON. XML — когда формат указан в договоре, регламенте или ТЗ.
7. Сравнение: файловый обмен и REST API
| Критерий | Файловый обмен | REST API |
|---|---|---|
| Скорость | Минуты – часы | Секунды |
| Объём данных | Гигабайты, миллионы записей в одном файле | Обычно до нескольких тысяч записей в одном запросе; для больших объёмов — комбинация с файловым обменом |
| Зависимость систем | Слабая — системы не связаны напрямую | Сильная — системы должны быть доступны одновременно |
| Система без API | Подходит | Не применим |
| Мгновенный результат | Нет | Да |
8. Рекомендуемый подход
Простые ориентиры для выбора. В каждом проекте решение уточняется с учётом объёма данных, скорости и возможностей систем.
| Ситуация | Что рекомендуем |
|---|---|
| Ежедневные операции: заказы, статусы, запросы «здесь и сейчас» | REST API + JSONОсновной вариант для новых интеграций |
| Регулярные массовые выгрузки: справочники, отчёты, реестры | S3 + JSONФайл по расписанию, автоматическая обработка |
| Регламент требует SFTP и XML | SFTP + XMLПо требованиям регулятора или регламента |
| Мастер-система выгружает справочники; система-приёмник запрашивает данные файлами | S3 / SMB, push + запрос/ответ — раздел 12 |
| Устаревшая система пишет только в общий каталог | SMBВременно; план миграции на S3 или SFTP |
Общий принцип: в первую очередь — REST API
Если обе системы могут предоставить API — начинаем с REST API. Файловый обмен — для больших выгрузок или когда API недоступен.
Независимо от способа обмена, на стороне принимающей системы данные проходят одну и ту же проверку (корректность структуры, отсутствие дублей). Формат JSON — по умолчанию. Формат XML — только если его требует регулятор, действующий регламент или техническое задание (например, установленная XSD-схема документа).
9. Ключевые риски
| Ошибка | Последствие |
|---|---|
| Отправка миллиона записей одним HTTP-запросом через REST API | Таймаут, потеря данных |
| Файловый обмен там, где нужен мгновенный результат | Задержки, нарушение SLA |
| Сетевая папка как постоянное решение без плана миграции | Конфликты при одновременной работе с файлами, простои, сложный аудит |
| Повторная отправка без защиты от дублей | Дублирование заказов и платежей |
10. Следующие шаги
- Для каждой интеграции определить: нужен ли мгновенный ответ, какой объём данных, есть ли API у систем
- Согласовать формат данных и правила обмена (структура файлов или описание REST API)
- При файловом обмене — зафиксировать структуру каталогов и правила именования файлов (см. раздел 11)
- Провести тестирование на тестовой среде до запуска в production
11. Принципы распределения файлов по каталогам
Структура каталогов — часть договорённости между системами. Её нужно согласовать до начала разработки, чтобы обе стороны одинаково понимали, куда класть файлы и откуда их забирать. Принципы ниже одинаково применимы к S3, SFTP и сетевой папке (SMB).
11.1. Роли каталогов
| Каталог | Назначение | Кто пишет |
|---|---|---|
outbox/ | Исходящие файлы, готовые к обработке потребителем | Отправитель |
inbox/ | Входящие файлы для обработки получателем | Отправитель кладёт, получатель читает |
processing/ | Файлы, взятые в работу (чтобы не прочитать повторно) | Получатель |
archive/ | Успешно обработанные файлы (для аудита и истории) | Получатель |
error/ | Файлы с ошибкой и описание причины | Получатель |
ack/ | Подтверждение успешной или неуспешной обработки | Получатель |
11.2. Два подхода к организации каталогов
| Подход | Описание |
|---|---|
| Общее хранилище | Один S3 bucket или один сетевой каталог с разделением по подпапкам для каждой системы:/master/outbox/, /receiver/inbox/, /receiver/requests/Каждая система знает, в какие каталоги писать и откуда читать. |
| Зеркальные outbox/inbox | Исходящий каталог системы A — это входящий каталог системы B (и наоборот). Система A пишет в свой outbox/ — система B читает из своего inbox/ (это один и тот же каталог или его копия). |
11.3. Жизненный цикл файла
1. Запись во временный файл: outbox/data_001.json.tmp 2. Переименование (файл готов): outbox/data_001.json 3. Контрольная сумма: outbox/data_001.json.sha256 4. Получатель перемещает в обработку: processing/data_001.json 5a. Успех → архив: archive/2026/06/17/data_001.json 5b. Ошибка → каталог ошибок: error/data_001.json + описание 6. Подтверждение отправителю: ack/ack_data_001.json
11.4. Именование файлов
Маска фиксируется в контракте: {тип}_{дата}_{номер}.{формат}, например catalog_20260617_001.json. Для связи запроса и ответа используется общий идентификатор correlationId в имени или внутри файла: request_{correlationId}.json → response_{correlationId}.json.
11.5. Обязательные правила
- Не читать файл, пока он записывается — сначала запись в
*.tmp, затем переименование - Проверять контрольную сумму SHA-256 перед обработкой
- Проверять структуру данных (JSON Schema / XSD) до передачи в бизнес-логику
- Защита от дублей: повторная обработка того же файла не должна создавать повторные операции
- Хранить обработанные файлы в archive с группировкой по дате
- Отслеживать «застрявшие» файлы во входящем каталоге и ошибки в error/
12. Сценарий: мастер-система и система-приёмник
Частый корпоративный сценарий: мастер-система (источник достоверных данных) регулярно выгружает справочники и транзакции. Система-приёмник получает эти данные, но также должна иметь возможность запрашивать данные у мастера — полностью через файловый обмен, без REST API.
12.1. Структура каталогов (двусторонний обмен)
/integration/
/master/
/outbox/ ← мастер кладёт данные (справочники, транзакции)
/inbox/requests/ ← мастер читает запросы от приёмника
/outbox/responses/ ← мастер кладёт ответы на запросы
/archive/
/receiver/
/inbox/ ← приёмник читает данные от мастера
/outbox/requests/ ← приёмник кладёт файлы запросов
/inbox/responses/ ← приёмник читает ответы от мастера
/archive/
Физически входящий каталог одной стороны может совпадать с исходящим каталогом другой (общий сетевой каталог SMB или S3 bucket с разграничением доступа).
12.2. Два потока данных
| Поток | Направление | Пример |
|---|---|---|
| Регулярная выгрузка | Мастер → Приёмник | Ежедневный справочник контрагентов, выгрузка остатков |
| Запрос – ответ | Приёмник → Мастер → Приёмник | Запрос актуальной цены, статуса документа, дополнительных данных |
12.3. Пошаговый сценарий «запрос – ответ» через файлы
| Шаг | Действие |
|---|---|
| 1 | Приёмник формирует файл запроса request_{correlationId}.json с типом запроса и параметрами |
| 2 | Запись через *.tmp, переименование, контрольная сумма — в каталог receiver/outbox/requests/ |
| 3 | Мастер обнаруживает запрос (периодическая проверка каталога или событие S3), перемещает в processing/ |
| 4 | Мастер обрабатывает запрос, формирует response_{correlationId}.json с тем же correlationId |
| 5 | Мастер кладёт ответ в master/outbox/responses/ (входящий каталог приёмника) |
| 6 | Приёмник забирает ответ, сопоставляет по correlationId, обрабатывает. При ошибке — файл отказа nack_{correlationId}.json |
| 7 | Обе стороны перемещают файлы в archive/; срок ответа фиксируется в контракте (например, 30 минут) |
12.4. Пример содержимого файлов
request_a1b2c3.json (приёмник → мастер):
{ "correlationId": "a1b2c3", "type": "GET_PRICE", "params": { "sku": "SKU-1001", "date": "2026-06-17" } }
response_a1b2c3.json (мастер → приёмник):
{ "correlationId": "a1b2c3", "status": "OK", "data": { "sku": "SKU-1001", "price": 1500.00, "currency": "RUB" } }
Ключевые требования
Один и тот же correlationId в запросе и ответе; отдельные каталоги для регулярных выгрузок и для запросов/ответов; защита от дублей на обеих сторонах; срок ожидания ответа с эскалацией при просрочке; перечень допустимых типов запросов зафиксирован в контракте.