REST API в корпоративном обучении: как связать LMS и системы компании без дублей

Как спроектировать обмен с LMS: сценарий, идентификаторы, права, события завершения, повторы и проверка данных на примере приглашения.

REST API в корпоративном обучении: как связать LMS и системы компании без дублей

В CRM менеджер отметил, что партнёру нужно пройти обучение. Дальше он вручную создаёт приглашение, отправляет ссылку и позже ищет подтверждение завершения. API может связать эти шаги, но для этого нужно описать весь процесс, а не просто получить ключ доступа.

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

Заявка partner-request-217 связана с идентификатором приглашения, проверенным событием завершения и единственным обновлением результата.

Технический идентификатор связывает системы, а политика повторов сохраняет единственность бизнес-действия.

Сначала событие и результат, затем список методов

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

Для примера с партнёром результат состоит из созданного приглашения, сохранённой связи и подтверждённого завершения. Автоматическое письмо или закрытие задачи CRM могут быть следующими действиями, но их нужно согласовать отдельно. API не должен выполнять их только потому, что разработчик нашёл подходящий метод.

В публичном описании интеграции Edumotion подтверждён сценарий гостевых приглашений и подписанных уведомлений о завершении. Его стоит проверять на своей аудитории и доступных настройках. Наличие этого сценария не означает универсальный обмен любыми данными организации.

Сохраните связь между объектами систем

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

В реализации внешних приглашений Edumotion используется поле externalId для связи с внешней системой. Но наличие этого поля не стоит автоматически считать защитой от любого повторного создания. Нужно проверить поведение конкретного запроса, поиск существующего объекта и правила повторной попытки.

В условном примере внешняя заявка имеет ключ partner-request-217. После создания система сохраняет рядом идентификатор приглашения. При следующем обращении она сначала проверяет уже выполненный шаг. Если один партнёр проходит несколько программ, правило ключей должно различать эти процессы.

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

Права доступа определяют на уровне приложения

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

Для Edumotion конкретные маршруты, ограничения и доступность функций сверяют с актуальным описанием и настройками организации. Не стоит копировать ключ другой компании ради проверки или выводить доступность операции только из названия тарифа в старой статье.

Полезно проверить отрицательные сценарии: неизвестный объект, отозванный ключ, другая организация и недопустимое действие. Успешный запрос подтверждает только свой путь. Корректный отказ столь же важен для интеграции, которая работает с несколькими клиентами или подразделениями.

Открыть интерактив отдельно

Уведомление о завершении требует сверки

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

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

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

Разделите отказ, задержку и неизвестный результат

Самый сложный случай: запрос принят, а ответ потерян. Слепой повтор создания способен дать дубль. Лучше сначала сверить существующую связь и доступный способ поиска. Если результат нельзя установить, процесс должен остановиться для разбора, а не объявить действие несуществующим.

СитуацияДействие интеграции
Запрос отвергнут из-за поляИсправить данные, сохранить причину
Ограничение частотыПовторить по согласованной политике ожидания
Ответ создания потерянСверить уже созданный объект
Событие пришло повторноНе выполнять бизнес-действие второй раз
Связь объекта не найденаНаправить в очередь исключений

Технический журнал должен помогать найти конкретную обработку, не собирая лишние персональные сведения и секреты. Для сотрудника достаточно понятного состояния и следующего шага; подробности оставляют уполномоченному специалисту.

Пройдите один сценарий до конца

Создайте тестовую внешнюю заявку, получите приглашение, проверьте вход участника и результат обучения. Затем повторите запрос, прервите соединение и обработайте дублирующее событие. Сверьте финальное состояние в обеих системах и отсутствие повторных действий.

Перед расширением интеграции запишите владельца обмена, разрешённые поля и порядок реакции на сбой. У каждой новой операции должен быть собственный критерий результата. Успешный вызов сервера не доказывает, что бизнес-процесс завершён правильно.

Для начала можно сравнить этот путь с интеграцией Edumotion и API и подготовить свои исходные события. Следующий полезный результат: согласованный контракт обмена и проверка одной цепочки приглашения. Остальные подключения оценивают после её подтверждения.

Частые вопросы

API означает готовую интеграцию с любой системой?

Нет. Нужно сопоставить доступные операции, поля, полномочия и события обеих сторон. Иногда стандартного сценария достаточно, иногда требуется отдельная разработка. Сам ключ доступа не описывает процесс.

Зачем хранить внешний идентификатор?

Чтобы связать объект обучения с исходной заявкой и не искать его по имени. Но правила уникальности и повторного создания нужно проверить отдельно. Название поля не гарантирует нужное поведение автоматически.

Достаточно ли получить событие о завершении?

Нужно проверить его источник, связь с объектом и повторную обработку. Затем выполнить только согласованное действие. Уведомление без сверки может обновить не ту заявку или создать дубль следующего шага.

Как принимать такую интеграцию?

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