Статья
Чек-лист интеграции веб-платформы с внешним сервисом
Надёжная интеграция начинается с владельцев данных, контракта и восстановления, а не с успешного одиночного API-запроса.
Зафиксируйте цель и владельца данных
Опишите бизнес-событие: что запускает обмен и какой подтверждённый результат нужен пользователю. Для каждого поля назначьте систему-источник и направление изменений. Если имя редактируется в двух местах, заранее установите приоритет и правило конфликта. Укажите владельцев с обеих сторон, тестовый контур, ограничения API и способ проверить актуальную документацию перед разработкой.
Согласуйте контракт до подключения
- 01. СхемаТипы, обязательность, форматы, часовые пояса и допустимые значения.
- 02. ДоступМинимальные права, хранение секретов, ротация и отзыв ключа.
- 03. ДоставкаWebhook или опрос, порядок событий, повторы и уникальные идентификаторы.
- 04. ОшибкиТаймауты, лимиты, очередь, ручной разбор и восстановление.
- 05. КонтрольЖурналы, метрики состояния, оповещения и сверка данных.
Опишите синхронизацию как набор правил
Разделяйте создание, обновление и удаление. Решите, что означает запоздалое событие и можно ли обрабатывать события не по порядку. Связывайте объекты устойчивым внешним идентификатором, а не именем или телефоном. Повторная доставка должна быть безопасной. Для удаления выберите архивирование или явный статус, если история нужна для аудита. Периодическая сверка обнаруживает пропущенные события, но не должна без отчёта перезаписывать спорные значения.
Пример: передача заявки платформы в CRM
После подтверждённой отправки анкеты платформа создаёт сделку с идентификатором заявки, контактом и ссылкой для оператора. Черновики не уходят в CRM. Если ответ потерян, повтор с тем же ключом возвращает созданную сделку вместо дубля. Изменение статуса менеджером приходит обратно только для разрешённых значений; внутренние заметки CRM не показываются кандидату. При недоступности сервиса заявка остаётся принятой на платформе, ставится в очередь, а команда видит задержку. Пользователю не обещают, что менеджер уже получил карточку.
Запускайте интеграцию с контролем сверки
Сначала используйте тестовые записи без реальных секретов и персональных данных. Затем ограничьте рабочий запуск небольшой разрешённой группой и ежедневно сверяйте исходные объекты с внешними. Подготовьте переключатель остановки отправки, сохранение очереди и инструкцию ручной обработки. Перед расширением проверьте права ключа, срок действия, лимиты, уведомления и восстановление после отключения. Документируйте версию контракта и изменения полей, чтобы обновление одной стороны не стало скрытой поломкой другой.
Подготовьте изменения и отключение контракта
Уточните, как внешний сервис сообщает о новой версии и сколько поддерживает старую. Добавление необязательного поля не должно ломать разбор ответа, а исчезновение обязательного должно давать заметную контролируемую ошибку. Проверяйте контракт автоматически на тестовых примерах без чувствительных данных. Для миграции определите период совместимости, порядок включения сторон и возможность отката. При полном отключении интеграции отзовите ключи, остановите задания, обработайте очередь и сохраните требуемую историю. Назначьте, кто удаляет временные выгрузки и подтверждает завершение обмена. Так жизненный цикл заканчивается управляемо, а забытый токен не остаётся бессрочным доступом.
Вопросы перед запуском интеграции
Webhook лучше периодического опроса?
Он быстрее доставляет события, но требует проверки подписи, повторов и порядка. Часто полезна отдельная сверка.
Где хранить ключ API?
В защищённом хранилище конфигурации, вне кода и журналов, с минимальными правами и процедурой ротации.
Как понять, что интеграция здорова?
Следить за задержкой, ошибками, размером очереди и расхождениями контрольной сверки, а не только доступностью endpoint.