Когда две системы начинают обмениваться данными, вопросы «кто кому что слает и что делать, если это не дошло» возникают сразу. Без единого документа каждая сторона трактует формат, тайминги и ошибки по-своему. Результат — недели отладки, где разработчики смотрят логи по очереди, пытаясь понять, чья это ошибка. Спецификация интеграции — это не просто описание API, а договорённость о поведении систем в норме и в сбое. Она фиксирует сценарии, контракты данных, правила ретрансляции и точные коды ошибок.
Структура документа
Эффективная спецификация интеграции состоит из четырёх основных блоков. Первый — контекст и цели: зачем нужна интеграция, какие бизнес-процессы она поддерживает и какие метрики успеха. Второй — участники и роли: кто является источником данных, кто получателем, есть ли промежуточные шины или очереди. Третий — сценарии обмена: пошаговые последовательности действий для успешных и неуспешных случаев. Четвёртый — контракты и ошибки: точные форматы сообщений, коды ответов и политики повторных попыток. Такой подход позволяет любому новому участнику быстро разобраться в логике взаимодействия, даже если он не участвовал в первоначальном проектировании.
Описание участников и архитектуры
В разделе «Участники» необходимо явно указать системы, их версии и ответственность. Важно определить, какая система является «источником истины» для каждого типа данных. Например, если CRM управляет контактами клиента, а складская система (WMS) — остатками товаров, то CRM не должна изменять остатки напрямую, а WMS не должна создавать новые карточки клиентов. Также указываются каналы связи: REST API, очередь сообщений (Kafka/RabbitMQ), файловый обмен (SFTP). Для учебного примера рассмотрим интеграцию CRM «Альфа» и WMS «Бета» через REST API с асинхронным подтверждением через webhook.
Сценарии обмена: успех и сбой
Сценарии описываются в виде последовательностей. Каждый сценарий имеет триггер, шаги и ожидаемый исход. Ниже приведён основной сценарий создания заказа в WMS по событию из CRM.
- CRM формирует объект «OrderCreated» и отправляет POST-запрос на эндпоинт
/api/v1/ordersв WMS. - WMS валидирует данные (наличие SKU, наличие склада).
- При успехе WMS возвращает HTTP 201 с телом, содержащим ID заказа в WMS (
wmsOrderId).
При ошибке валидации WMS возвращает HTTP 400 с массивом ошибок. - CRM сохраняет полученный
wmsOrderIdв своей базе данных, связывая его с локальным ID заказа. - Через N секунд WMS отправляет POST-запрос на webhook CRM с событием «OrderAccepted» или «OrderRejected».
Важно описать поведение при сетевых сбоях. Если CRM не получает ответ от WMS в течение 5 секунд, она считает запрос неудачным и ставит его в очередь повторной отправки. Повторные попытки выполняются с экспоненциальной задержкой (1 мин, 5 мин, 30 мин) максимум 3 раза. После третьего неудачного случая задача помечается как «Ошибка критическая» и требует ручного вмешательства оператора.
Контракты данных
Контракты определяют структуру передаваемых объектов. Используем JSON Schema (draft 2020-12) для описания тела запроса. Поля должны иметь явные типы, обязательность и ограничения. Например, поле quantity должно быть целым положительным числом, а sku — строкой длиной от 5 до 20 символов. Использование nullable в OpenAPI 3.0 требует явного указания, если поле может отсутствовать или содержать null. В спецификации следует избегать неоднозначных типов: если поле опциональное, лучше использовать отсутствие ключа, а не значение null, если это не предусмотрено схемой. Для валютных сумм используется тип number с точностью до двух знаков после запятой, либо целое число в минимальных единицах валюты (копейках/центах) во избежание проблем с плавающей точкой.
Матрица ошибок и обработка исключений
Раздел ошибок — сердце спецификации. Здесь перечисляются все возможные коды ответа и их семантика. Клиент обязан обрабатывать каждый код согласно политике. Таблица ниже демонстрирует типичную матрицу для REST-интеграции.
| HTTP Код | Ситуация | Действие клиента | Ретрансляция? |
|---|---|---|---|
| 200/201 | Успех | Сохранить ID, завершить сценарий | Нет |
| 400 | Ошибка валидации данных | Логировать детали, исправить данные вручную | Нет |
| 401/403 | Ошибка авторизации | Проверить credentials, алерт администратору | Нет |
| 409 | Конфликт (дубликат ID) | Проверить, существует ли уже запись | Да, если ID не найден |
| 429 | Limit exceeded | Дождаться Retry-After, повторить | Да |
| 5xx | Ошибка сервера | Повторить с задержкой | Да |
Класс HTTP-ошибки помогает диагностике, но сам по себе не определяет безопасный повтор. Например, 429 или некоторые 409 требуют согласованного ожидания, а 5xx после принятой команды может оставлять неизвестный исход. Для каждой операции описывают причину, ключ команды, сверку результата и условия следующей попытки. Повтор команды изменения выполняют только в пределах подтверждённой защиты или после достаточной проверки исхода.
Практический пример заполнения
Рассмотрим фрагмент заполненной спецификации для интеграции CRM-WMS. Этот пример показывает, как выглядят конкретные значения в документе.
## 1. Контекст
Интеграция необходима для автоматического создания резервов товара
при оформлении заказа в CRM. Цель: сократить время подтверждения
заказа с 4 часов до 5 минут.
## 2. Участники
- Источник: CRM «Альфа» v2.4 (REST Client)
- Приемник: WMS «Бета» v1.9 (REST Server)
- Канал: HTTPS, TLS 1.2+
## 3. Сценарий SC-01: Создание резерва
Триггер: Заказ оплачен в CRM.
Шаги:
1. CRM отправляет POST /v1/reserves
Headers: Authorization: Bearer <token>, Idempotency-Key: <uuid>
Body: { "orderId": "CRM-123", "items": [{"sku": "SKU-A1", "qty": 2}] }
2. WMS проверяет наличие SKU-A1 на складе WH-01.
3. Если достаточно: WMS создает резерв, возвращает 201 {
"wmsReserveId": "RES-456", "status": "HOLDING" }.
4. Если недостаточно: WMS возвращает 400 {
"errors": [{"field": "items[0].qty", "msg": "Insufficient stock"}]}.
5. CRM логирует результат. При 400 - уведомление менеджеру.
## 4. Обработка ошибок
- Таймаут: 5 сек. Ретрансляция: 3 раза (1m, 5m, 30m).
- Код 429: Уважать заголовок Retry-After.
- Код 409: Проверить по orderId, если reserve уже создан - игнорировать.
Обратите внимание на использование Idempotency-Key. Это UUID, генерируемый CRM для каждого конкретного действия. Если CRM повторно отправляет тот же запрос после сетевого сбоя, WMS видит знакомый key, понимает, что действие уже выполнено, и возвращает оригинальный ответ, создавая новый резерв. Это предотвращает двойное списание товара.
Проверка корректности спецификации
Спецификация считается готовой, если она проходит следующие проверки. Во-первых, полнота: для каждого метода API описаны все возможные коды ответа. Во-вторых, однозначность: термины определены, нет двусмысленных формулировок вроде «быстро» или «часто». Вместо них используются конкретные числа (таймауты, лимиты). В-третьих, тестируемость: каждый сценарий можно воспроизвести в тестовой среде. Рекомендуется подготовить набор тестовых данных, которые покрывают happy path и основные ошибки валидации. Если разработчики двух сторон могут независимо написать автотесты на основе спецификации, не задавая друг другу вопросов, значит, документ написан хорошо.
Типичные ошибки в спецификациях
- Отсутствие политик ретрансляции. Разработчики придумывают свои стратегии повторов, что приводит к перегрузке сервера или потере данных.
- Неидемпотентные операции без защиты. Если POST создает ресурс, но нет механизма проверки дублей, сетевые сбои приводят к множественным записям.
- Размытые описания ошибок. Сообщение «Ошибка обработки» без указания поля или причины делает отладку невозможной.
- Игнорирование времени жизни данных. Не указано, сколько сервер хранит idempotency keys или логи. Обычно это 24-48 часов.
- Смешение уровней абстракции. В одном документе описаны и низкоуровневые байтовые пакеты, и высокоуровневые бизнес-правила. Лучше разделить транспортный уровень и контрактный уровень.
Роль аналитика в процессе
Системный аналитик выступает модератором этого процесса. Его задачи включают: сбор требований от обеих сторон, разрешение конфликтов в трактовке данных, контроль версионирования контрактов. Аналитик должен убедиться, что изменения в API одной стороны не ломают другую. Для этого используется версионирование URL (/v1/..., /v2/...) или заголовков. Аналитик также отвечает за документирование «темных углов»: например, что происходит, если товар был снят с продажи между созданием заказа и попыткой резервирования. Такие кейсы часто упускаются разработчиками, сосредоточенными на «зеленом» пути.
Итог
Спецификация интеграции — это живой документ, который снижает энтропию в коммуникации между командами. Заполненный шаблон с четкими сценариями, контрактами и матрицей ошибок позволяет автоматизировать тестирование и предсказуемо обрабатывать сбои. Ключ к успеху — детализация: конкретные коды, тайминги и правила идемпотентности. Такой подход превращает интеграцию из источника головной боли в надежный механизм работы бизнеса. Начните с простого шаблона, заполните его для одного ключевого сценария и постепенно расширяйте покрытие остальных взаимодействий.
