Паспорт интеграции: как задокументировать системы, доступы и сценарий восстановления

Единый документ, который экономит часы при каждом сбое и передаче проекта

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

Зачем вообще нужен отдельный документ на каждую интеграцию

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

Аналитики, описывающие требования к интеграциям, отдельно подчёркивают, что интеграционные потоки должны быть отражены в общей ИТ-архитектуре компании, а не существовать только в переписке между разработчиками [1]. Паспорт интеграции — это способ зафиксировать такой поток не абстрактно на схеме, а конкретно: с владельцами, полями, лимитами и планом действий при сбое.

Что такое паспорт интеграции простыми словами

Паспорт интеграции — карточка одной конкретной связи «система А ↔ система Б» со всей операционной информацией, нужной не на этапе разработки, а на этапе эксплуатации: поддержка, диагностика инцидентов, передача проекта новому исполнителю, аудит информационной безопасности.

Чем он отличается от ТЗ и от документации API

Техническое задание описывает, как построить интеграцию: архитектуру, эндпоинты, бизнес-логику. Документация API описывает, как её вызывать: методы, параметры, форматы ответов. Хороший шаблон такой документации должен содержать необходимый и достаточный минимум для быстрой разработки, без избыточных деталей [2].

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

Из каких разделов состоит паспорт интеграции

Системы и владельцы

Таблица участников: система-источник и система-приёмник, версия или тарифный план (если это SaaS), технический владелец, бизнес-владелец, контакт поддержки на стороне вендора.

Поля и схема данных

Сопоставление полей (data mapping): что передаётся, в каком формате, что обязательно, какие правила валидации и трансформации применяются. При проектировании интеграций отдельно выделяют согласование входных параметров, проверок и выходных параметров как ключевую часть спецификации обмена [2].

Расписание обмена

Режим обмена: реального времени (webhook, событие) или по расписанию (пакетная выгрузка); окна обслуживания, в которые обмен не выполняется; порядок действий при плановых работах на одной из сторон.

Доступы и аутентификация

Как система А аутентифицируется в системе Б. Если используется OAuth 2.0, фиксируются: тип потока (для связок «система-система» обычно client credentials), срок жизни access-токена, механизм обновления через refresh-токен, где хранится секрет клиента. Протокол в целом решает задачу — дать одному приложению доступ к данным другого без прямой передачи пароля [3]. Отдельно стоит зафиксировать регламент ротации ключей и ответственного за их продление: интеграция чаще останавливается из-за забытого просроченного секрета, чем из-за бага.

Лимиты

Квоты на стороне каждой системы: сколько запросов допустимо и что происходит при превышении. Стандартный ответ при превышении — код 429, который сообщает, что клиент отправил слишком много запросов за заданный период [4]. К такому ответу может прилагаться заголовок Retry-After — время, которое клиент должен подождать перед повтором [5]. Многие API дополнительно отдают в каждом ответе текущее состояние квоты через отдельные заголовки лимита, остатка и времени сброса окна [6]. Эти значения стоит перенести в паспорт вместе с реальными цифрами конкретного партнёра — выяснять их во время инцидента уже поздно.

Журнал ошибок

Не просто код, а таблица известных ошибок: код/статус, человекочитаемое значение, типичная причина, что делать дежурному инженеру. Описание возможных ошибок с пояснением причин — обязательная часть качественной документации API [7]; в паспорте интеграции этот словарь дополняется конкретными действиями по каждой ошибке.

Повторная отправка (retry)

Политика retry отвечает на три вопроса: какие сбои повторять, сколько ждать между попытками и когда остановиться [8]. Повторять стоит только ошибки, которые могут исчезнуть со временем — 5xx, 429, сетевые таймауты; повторять 4xx (кроме 429) не имеет смысла — это лишь более медленный способ получить тот же отказ [8]. Задержку между попытками принято увеличивать экспоненциально с добавлением случайного джиттера — это снижает риск «шторма» одновременных повторов, если событий отказало сразу много [9]. Общее число попыток ограничивается, после чего сообщение уходит не в бесконечный повтор, а в отдельное состояние для ручной обработки — dead-letter [8].

Отдельно нужна идемпотентность: приёмник должен уметь распознать повторную доставку одного и того же события и не выполнять действие дважды. Практический паттерн — уникальный идентификатор события, который приёмник фиксирует в таблице с уникальным индексом до начала обработки; если запись с таким ID уже существует, событие считается дублем [10]. В паспорте интеграции стоит явно зафиксировать, какое поле служит ключом идемпотентности и на какой стороне выполняется дедупликация.

Сценарий восстановления

Что делать при полном отказе интеграции, а не при единичной ошибке. Здесь фиксируются целевые показатели: RTO (Recovery Time Objective) — сколько времени допустимо на восстановление, и RPO (Recovery Point Objective) — сколько данных допустимо потерять. Время восстановления складывается из нескольких последовательных этапов: обнаружения инцидента (от сбоя до фиксации проблемы мониторингом), принятия решения о сценарии восстановления и собственно технического восстановления [11]. Чем критичнее бизнес-процесс, который зависит от интеграции, тем жёстче должны быть целевые RTO/RPO — и тем выше стоимость их достижения за счёт резервирования и репликации [12]. Практика восстановления после сбоев рекомендует определять приоритет бизнес-процессов заранее, а не в момент аварии [13].

В паспорте этот раздел должен содержать: контакты на эскалацию, пошаговый чек-лист «что проверить в первую очередь», способ ручного дозапуска пропущенных сообщений после простоя, критерий, по которому фиксируется, что инцидент закрыт и данные между системами согласованы.

Российская специфика: персональные данные и журналирование

Если через интеграцию передаются персональные данные — ФИО, телефон, email, адрес доставки, — паспорт должен фиксировать дополнительный блок, связанный с требованиями 152-ФЗ «О персональных данных».

Во-первых, правовое основание передачи: между операторами персональных данных для передачи третьей стороне нужно отдельное основание, а не общее согласие пользователя, полученное для других целей [14]. Во-вторых, каждый интеграционный вызов — потенциальный канал утечки, и требования 152-ФЗ к защите персональных данных применяются к нему в полной мере [14]. Требование о локализации персональных данных граждан РФ на серверах в России действует уже несколько лет (с изменений 2015 года) и напрямую касается интеграций, где одна из сторон — облачный сервис с обработкой за рубежом; это стоит проверять отдельно для каждой интеграции, а не считать формальностью.

Отдельная практическая рекомендация — журналирование доступа к персональным данным по формуле «кто-что-когда-где-как»: какой пользователь или сервисный аккаунт, какие данные, в какой момент, с какого устройства, каким способом [15]. Такой журнал — не просто хорошая практика: при проверке Роскомнадзора он служит доказательством того, что организация контролирует доступ к персональным данным [15]. В паспорте интеграции достаточно сослаться, где и как ведётся такой журнал и кто отвечает за его хранение.

Формулировки и сроки 152-ФЗ меняются, а актуальную редакцию закона и разъяснения регулятора нужно проверять на момент внедрения — этот раздел не заменяет юридическую консультацию.

Как вести паспорт на практике

Для небольшого числа интеграций (до 10–15) достаточно единого шаблона — таблицы в общей вики компании, по одной странице на интеграцию, с обязательными разделами, перечисленными выше. Важно, чтобы шаблон был одинаковым для всех интеграций — иначе поиск нужной информации в критический момент превращается в лотерею.

Когда интеграций становится больше двух-трёх десятков, а команда — распределённой, стоит рассмотреть специализированные инструменты: единый каталог API для обмена с партнёрами как часть платформы интеграции [16], либо инструменты класса CMDB/ITSM, где паспорт интеграции — это карточка конфигурационной единицы со связями к другим системам.

Отдельный класс инструментов автоматически инвентаризирует системы и интеграции компании и подсвечивает, где в этих связях есть персональные данные и риски несоответствия 152-ФЗ — это полезно для компаний, где число интеграций растёт быстрее, чем документация за ним успевает [17]. Такой инструмент не заменяет ручной паспорт интеграции, но помогает не пропустить сам факт появления новой связи между системами.

Практические этапы внедрения

1. Инвентаризация. Составить список всех действующих интеграций — часто на этом шаге обнаруживаются забытые связи.
2. Приоритизация. Определить, какие интеграции критичны для бизнеса, и начать с них.
3. Шаблон. Согласовать единый шаблон паспорта с разделами: системы/владельцы, поля, расписание, доступы, лимиты, ошибки, retry, восстановление.
4. Заполнение. Завести паспорт на каждую критичную интеграцию с привлечением владельцев систем с обеих сторон.
5. Тестирование сценария восстановления. Хотя бы раз воспроизвести сбой в тестовой среде и проверить, что план из паспорта действительно укладывается в заявленный RTO.
6. Поддержка в актуальном состоянии. Назначить ответственного за обновление паспорта при каждом изменении интеграции.

Частые ошибки и риски

• Паспорт заводят один раз и забывают обновлять, хотя реальные лимиты, контакты и коды ошибок меняются.
• Retry без идемпотентности: повторная отправка гарантирует доставку минимум один раз, но без ключа идемпотентности на стороне приёмника это означает дубли заказов, платежей, уведомлений [10].
• Бесконечные повторы без dead-letter: если endpoint отказывает системно несколько раз подряд, это уже не повод для очередного retry, а сигнал эскалации [8].
• Секреты доступа без владельца и срока ротации — ключ, который «просто где-то есть», рано или поздно протухает или утекает.
• Отсутствие раздела про персональные данные — особенно рискованно для интеграций, которые изначально считались «техническими» (например, сайт ↔ служба доставки), но фактически передают ФИО и адрес клиента.
• RTO/RPO определены «на глаз», а не исходя из критичности процесса, — решения в момент аварии принимаются наугад.

Когда хватает шаблона, а когда нужна разработка или отдельный сервис

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

Команда «Пятого фактора» может изучить существующий у компании набор интеграций, помочь описать критичные из них в виде паспортов, спроектировать политику retry и восстановления под конкретную архитектуру и, если потребуется, разработать или доработать инструмент для автоматической инвентаризации интеграций и данных, которые через них проходят.

Вывод

Паспорт интеграции — не бюрократия ради бюрократии, а страховка на момент, когда что-то ломается вечером в пятницу, а человек, который делал интеграцию, давно работает в другой компании. Основные разделы — системы и владельцы, поля данных, расписание, доступы, лимиты, журнал ошибок, retry и сценарий восстановления — складываются из устоявшихся практик документирования API и обработки сбоев в распределённых системах. Для российских компаний к этому списку добавляется блок про персональные данные: правовое основание передачи, локализацию и журналирование доступа. Чтобы обсудить задачу или получить консультацию, свяжитесь с командой «Пятого фактора» любым удобным способом.

Источники

[1] habr.com — Базовое проектирование и разработка требований к интеграции систем — https://habr.com/ru/articles/712504/

[2] habr.com — Удачный шаблон документации на API, который будут читать — https://habr.com/ru/articles/667884/

[3] elma365.com — OAuth 2.0 — что это и как работает — https://elma365.com/ru/baza-znaniy/oauth-2-0/

[4] developer.mozilla.org — 429 Too Many Requests — https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429

[5] zuplo.com — HTTP 429 Too Many Requests: Causes, Headers & Retry Logic — https://zuplo.com/learning-center/http-429-too-many-requests-guide

[6] bugmojo.com — What Is Rate Limiting? 429, Algorithms & Client Retry — https://www.bugmojo.com/blog/glossary/what-is-rate-limiting

[7] documenterra.ru — Документация API: для чего нужна, инструменты для создания — https://documenterra.ru/organizuem-api-documentaciu/

[8] wpwebhooks.org — Webhook Retry Policy: Exponential Backoff & Schema — https://wpwebhooks.org/blog/webhook-retry-policy-exponential-backoff/

[9] hookdeck.com — Webhook Retry Best Practices for Sending Webhooks — https://hookdeck.com/outpost/guides/outbound-webhook-retry-best-practices

[10] hookray.com — Webhook Retry Policy: Backoff, Idempotency & Dead Letter Code — https://hookray.com/blog/webhook-retry-strategies-2026

[11] it-grad.kz — RTO и RPO: что это, основные отличия метрик, расчет и оценка — https://it-grad.kz/blog/bezopasnost/rto-i-rpo-chto-eto-i-v-chem-otlichiya

[12] nubes.ru — Метрики RTO и RPO: что это такое, как определить и в чем разница — https://nubes.ru/blog/articles/rto-pro

[13] cisoclub.ru — RTO и RPO в DR-плане: резервные копии, тестирование и отказоустойчивость — https://cisoclub.ru/disaster-recovery-inzhenernyj-podhod-k-nepreryvnosti-biznesa/

[14] hallpe.ru — 152-ФЗ требования 2026: персональные данные, AI и автоматизация — https://hallpe.ru/blog/152-fz-i-avtomatizaciya-personalnyh-dannyh-trebovaniya-2026.html

[15] stakhanovets.ru — 152-ФЗ о защите персональных данных: требования и штрафы в 2026 году — https://stakhanovets.ru/blog/152-fz-o-zashhite-personalnyh-dannyh-trebovaniya-i-shtrafy-v-2026-godu/

[16] q.diasoft.ru — Непрерывная интеграция и CI/CD: 8 инструментов для разработки ПО — https://q.diasoft.ru/mediacenter/knowledge/integratsionnye-platformy-2026-reyting-10-resheniy-i-kriterii-vybora/

[17] productradar.ru — профиль сервиса «Пятый фактор» — https://productradar.ru/product/pyatyj-faktor/