Интеграции веб-сервиса: что согласовать до обмена данными с другими системами
Пользователь отправил обращение в онлайн-сервисе, а сотрудник должен увидеть его в CRM. Кажется, что достаточно передать заполненные поля. Однако нужно определить, кто создаёт запись, что считать подтверждением, как обновлять сведения и что делать, если принимающая система временно не отвечает. Именно эти договорённости превращают обмен в рабочую часть процесса.
При обсуждении проекта полезно сверить состав услуги с задачей. На странице разработка онлайн-сервиса студия «Гуси-Лебеди» описывает проектирование API и интеграций, правила доступа и сценарии отказа. Для конкретного обмена всё равно нужны сведения о подключаемых системах и согласованные требования. Упоминание интеграций не подтверждает, что любая внешняя система поддерживает нужные операции.
Определите результат обмена
Начните с рабочего действия. В условном примере результатом будет обращение, доступное ответственному сотруднику в CRM с нужными сведениями. Запишите, какие поля он должен увидеть и что сможет сделать дальше. Если задача требует назначения исполнителя, одной передачи имени и телефона может оказаться недостаточно.
Разделите создание записи, её обработку и конечный результат для пользователя. Успешная передача не означает, что сотрудник уже ответил клиенту. Аналогично подтверждение в интерфейсе отправителя не доказывает появление записи у получателя. Для каждого этапа нужен свой наблюдаемый признак.
Найдите источник актуальных данных
Уточните, какая система хранит основное значение каждого важного поля. Например, контакт может впервые появиться в онлайн-сервисе, а дальнейший статус обращения меняться в CRM. Это условная модель: в реальном проекте источники определяются существующими правилами компании.
Обсудите исправления и противоречия. Если сотрудник поменял контакт, а пользователь позже отправил другой вариант, нужно заранее знать, какое изменение применяется и кто вправе решить спор. Без такой договорённости разные команды могут считать актуальными разные сведения, хотя обмен технически происходит.
Проверьте доступные операции
Получите актуальное описание способов подключения от владельца внешней системы. Выясните, доступны ли нужные чтение, создание и изменение записей, какие данные обязательны и какие ограничения действуют. Не выбирайте способ обмена только по названию продукта или чужому похожему примеру.
Отдельно уточните разрешения, среду проверки и ответственного за подключение. Иногда для нужной операции требуется участие администратора или настройка со стороны владельца системы. Пока эти условия неизвестны, оценка интеграции должна учитывать пробел, а не скрывать его обещанием готовности.
Согласуйте состав передаваемых сведений
Для каждого поля определите назначение, формат и допустимые значения. Обсудите, что происходит при отсутствии информации или неверном значении. Не нужно переносить все доступные данные только потому, что их можно получить: состав должен отвечать рабочей задаче и согласованным ограничениям.
Уточните связь между объектами разных систем. Команде нужен способ понять, к какому обращению относится обновление, и отличить новое событие от изменения существующей записи. Как именно это реализуется, определяют разработчики после изучения доступных механизмов. В требованиях важен ожидаемый результат связи.
Опишите момент и направление обмена
Запишите, какое событие запускает передачу и кто получает изменение. Это может быть отправка обращения пользователем или смена статуса сотрудником. Уточните, должен ли обмен происходить сразу, по согласованному расписанию или после отдельного подтверждения. Подход выбирают исходя из процесса и возможностей систем.
Опишите, что видит пользователь до получения ответа. Если операция ещё обрабатывается, интерфейс не должен создавать необоснованное впечатление о завершении. Состояния ожидания, подтверждения и ошибки нужно связать с наблюдаемыми событиями, которые команда сможет проверить.
Договоритесь о повторных операциях
Сотрудник может повторить действие, пользователь нажать отправку ещё раз, а система возобновить передачу после сбоя. Уточните, что должно произойти с уже созданной записью: сохраниться, обновиться или получить отдельное обращение по правилам процесса. Не считайте повтор автоматически новой бизнес-задачей.
Разработчикам нужно сообщить, какие дубли недопустимы и по каким признакам команда обнаруживает их. Способ обработки повторов зависит от возможностей обеих сторон. Важен проверяемый сценарий: что происходит при повторной передаче тех же сведений и как участники узнают результат.
Определите действия при ошибке
Разделите разные ситуации: данные отклонены, ответа нет, доступ изменился или внешняя система недоступна. Пользователь и сотрудник могут нуждаться в разных сообщениях. Уточните, какие операции можно повторить, какие требуют исправления сведений и кто разбирает неясный результат.
Назначьте владельца проблемы и место наблюдения за состоянием обмена. Если ошибку видно только разработчику, сотрудник может продолжать работу с неполными сведениями. При этом сообщения и журналы должны соответствовать ограничениям доступа и не раскрывать лишние данные. Конкретный состав обсуждается с командой.
Проверьте результат с обеих сторон
Подготовьте разрешённые тестовые данные и согласованную среду. Передайте обращение, найдите соответствующую запись у получателя и сверьте поля. Затем проверьте нужные обновления, повторные действия и безопасно воспроизводимые ошибки. Список проверок должен соответствовать договорённому охвату.
Фиксируйте ограничения наблюдения. Если проверена только отправка, не утверждайте, что обработка в CRM завершена. Если тестовая среда отличается от рабочей, отдельно согласуйте проверку перед запуском. При неизвестном результате сначала выясняйте состояние существующей операции, чтобы проверка сама не создала дубли.
Подготовьте сопровождение изменений
Обмен может зависеть от настроек и правил другой системы. Договоритесь, кто получает сведения об изменениях, оценивает их влияние и проверяет совместимость. Определите порядок обновления описания интеграции и ответственного за актуальные условия подключения.
В рабочем описании должны остаться назначение обмена, источники данных, события, доступы, поведение при ошибке и способ проверки результата. Такой документ помогает обсуждать реализацию и сопровождение предметно. Готовность интеграции подтверждается наблюдаемым результатом согласованных операций, а не наличием её названия в перечне функций.