Интеграция сайта — это договорённость систем о данных и действиях. Мы описываем событие, ожидаемый результат и обработку неуспешного обмена до подключения формы, оплаты или внешнего сервиса.
Определяем границы обмена
Сначала выясняем, какая система создаёт объект и кто отвечает за его дальнейшее состояние. Это помогает избежать параллельных противоречивых процессов.
Для каждой интеграции фиксируем полезное действие пользователя. Передача технического события не должна автоматически означать создание новой сделки или подтверждение оплаты.
Описываем операцию обмена на уровне бизнеса: создание обращения, изменение заказа или получение статуса. Определяем инициатора, получателя и владельца результата. Если обе системы могут менять одно поле, правило разрешения конфликта согласуем до подключения, а не после первого расхождения. При удалении объекта отдельно определяем, нужно ли физическое удаление, архивирование или запрет дальнейшего изменения: одинаковая команда может иметь разные последствия.
Сопоставляем имена, типы и обязательность данных в обеих системах. Отдельно описываем неизвестное значение и недостающую информацию.
Проверяем идентификаторы и справочники. Одинаковое название статуса не всегда означает одинаковый смысл для сайта, CRM и учётного сервиса.
Согласуем поля
Для каждого поля указываем тип, обязательность, допустимые значения и преобразование. Проверяем пустую строку, отсутствующее значение, неожиданную валюту и длинный комментарий. Совпадающее название поля не гарантирует одинакового смысла: дата создания записи может отличаться от даты пользовательского действия. В словаре полей сохраняем примеры допустимых значений и единицы измерения, чтобы число без контекста не превратилось в другую сумму или срок.
Нужно понимать, принято ли событие и завершена ли операция. Доступность конечного адреса сама по себе не подтверждает корректное создание объекта.
В журнале сохраняем достаточно сведений для разбора, не раскрывая лишние данные. Ответственный должен отличать сбой сети от ошибки полей или доступа.
Допустим, сайт передал заказ, но соединение оборвалось до получения ответа. Повторная отправка не должна создавать ещё один заказ. Согласуем устойчивый идентификатор операции и проверяем, как получатель возвращает уже созданный результат, когда тот же запрос приходит повторно. В условном повторе получатель также проверяет соответствие параметров: одинаковый идентификатор с другим составом заказа нельзя молча считать прежней успешной операцией.
Пользователь может повторно отправить форму, а сервис — доставить одно событие ещё раз. Описываем, какое действие действительно требуется при таком повторе.
Обрабатываем повторы
Уникальный идентификатор связываем с бизнес-операцией. Проверка только внешнего вида кнопки не защищает от повторной обработки на стороне получателя.
Ответ системы интерпретируем по контракту, отделяя транспортный успех от выполнения бизнес-операции. Получение ответа без ошибки соединения ещё не означает, что запись создана с нужными полями. Проверяем подтверждающий идентификатор и способ найти объект на стороне получателя. Для создания записи проверяем заполнение обязательных бизнес-полей, поскольку система может принять объект, но оставить его вне рабочей очереди команды продаж.
Для временной ошибки определяем повторную попытку, очередь или ручную проверку. Для некорректных данных нужен иной путь, чем бесконечная повторная отправка.
Уведомление должно содержать понятную причину и владельца разбора. Иначе технически обнаруженная ошибка продолжает оставлять обращение клиента без обработки.
Для временной недоступности проектируем очередь, ограниченные повторы и переход в ручной разбор. Не повторяем бесконечно запрос с заведомо неверным полем. Сотрудник должен видеть причину остановки и понимать, можно ли безопасно перезапустить операцию после исправления исходных данных. Уведомление об остановке содержит ссылку на исходную операцию и объяснение доступного действия, а не только технический код исключения внешнего сервиса.
Проектируем восстановление
Если сведения теряются выборочно, сопоставляем журналы отправителя и получателя по идентификатору операции. Проверяем преобразование полей, ограничения длины и последовательность обновлений. Различаем отсутствие события, отклонённый запрос и последующее перезаписывание данных другой интеграцией. Отдельно проверяем обновления, выполняемые по расписанию: ночная выгрузка может перезаписывать корректные значения, созданные через интерфейс сайта в течение рабочего дня.
Проверяем путь от формы до нужного объекта, статуса и уведомления. При оплате отдельно рассматриваем отказ, отмену и повторное сообщение сервиса.
Передаём схему обмена и порядок замены доступов. Интеграция требует сопровождения при изменении полей, прав и интерфейсов участвующих систем.
Сквозная приёмка начинается реальным действием в интерфейсе и заканчивается проверкой записи в рабочей системе. Затем проверяем обновление, отмену и повторное событие. Успешный тест отдельного API-запроса не подтверждает, что правильно работает вся цепочка с пользовательским вводом. Если результат содержит документ или платёж, сверяем его связь с исходным пользователем: технически созданный объект может принадлежать неверному клиенту.
Передаём схему обмена, словарь полей, правила повторов и примеры подтверждённых операций. В инструкции описываем поиск ошибки, ручное восстановление и смену доступов. Владелец интеграции должен понимать, какое изменение внешнего контракта потребует повторной проверки маршрута. Для смены доступа описываем проверку после замены и отзыв прежнего ключа, чтобы восстановление интеграции не зависело от личной учётной записи разработчика.
Часто задаваемые вопросы
Что делать, если сервис не имеет API?
Проверить разрешённые способы обмена: штатное подключение, импорт или экспорт. Ограничения устойчивости нужно обозначить до реализации.
Почему форма отправилась, а заявки в CRM нет?
Нужно проверить подтверждение получателя, обязательные поля и журнал обработки. Сообщение интерфейса может отражать только локальное событие.
Нужен ли тестовый контур?
Он позволяет проверять ошибки без создания настоящих заказов и сообщений. Доступность такого контура зависит от подключаемых систем.