Как описать обмен данными: что должно быть в спецификации, чтобы работало

Интеграция “передаем данные туда‑сюда” редко работает стабильно, если не договориться о деталях. Хорошая спецификация обмена — это не “техдок для программистов”, а способ защитить бизнес от дублей, потерь и расхождения статусов.

Что обязательно должно быть в спецификации

1) Участники и ответственность
Какие системы участвуют, и за что каждая отвечает. Какая система “главная” по каждому объекту (клиент, заказ, платеж).

2) Объекты и поля
Что именно передаем: список объектов (например, заказ, платеж, клиент) и обязательные поля. Важно: форматы (дата/время, телефон, суммы), ограничения, справочники.

3) Идентификаторы
Как системы понимают, что это “тот же самый” заказ/клиент: внешний ID, внутренний ID, правила сопоставления. Без этого почти гарантированы дубли.

4) События и триггеры
Когда отправляем: “создано”, “обновлено”, “оплачено”, “отменено”. Какие изменения считаются значимыми.

5) Статусы и переходы
Список статусов и разрешенные переходы. Что делаем, если статус пришел “неожиданный”.

6) Ошибки и повторы
Что происходит при ошибке: сколько повторов, с каким интервалом, где видно “зависшие” операции. Как избегаем двойных действий при повторной отправке.

7) Валидация и правила качества данных
Что делаем, если обязательное поле пустое или формат неверный: отклоняем, ставим в очередь на разбор, уведомляем ответственного.

8) Логи и мониторинг
Где увидеть историю обмена: список отправок/получений, ошибки, причина, время. Кто отвечает за ежедневный контроль в первые недели.

Если эти пункты описаны, интеграция становится управляемой: сбои не превращаются в “магические”, а дубли и расхождения ловятся на уровне правил, а не по жалобам клиентов.