API для регистрации пользователей на портале СД

Owned by Павел Жердев (Unlicensed)
Last updated: Dec 06, 2023 by Катя Копылова (Алабугина)
4 min read

Оглавление

Общая информация

Для передачи клиентом данных с внешних систем по пользователям и пользовательской структуре реализована интеграция через API.

Передача осуществляется с помощью протокола https, то есть шифрование передаваемых данных сразу присутствует.

Проверить все точки API, вместе с ответами и описанием можно в документации к публичному API на конкретной площадке по ссылке /public/api/doc

Схема авторизации

  • При отправке запросов по урлам вида /public/api/* идёт проверка на наличие Header-а x-auth-token. Если Header присутствует, и соответствует указанному в конфиге, то авторизация проходит успешно. Ключ берется из поля “Публичный ключ API” на странице /admin/system/update.

  • При отсутствии токена, либо если он указан неверно, возвращается ошибка 401 Authorization Required

Какие запросы можно использовать

При каждом обращении, не важно, POST или GET, в заголовках запроса нужно указывать параметр X-Auth-Token с предоставленным ключом в качестве значения.

Получение списка используемых в интеграции пользователей полей

Чтобы получить список всех полей, используемых в интеграции пользователей, нужно сделать GET запрос без параметров на адрес:

  • /public/api/v1/user/fields

В ответ придёт JSON массив объектов, каждый объект будет содержать следующие свойства:

name string - системное имя поля, которое необходимо указывать при импорте
title string - название поля, указанное в административной части
type string- тип поля (доступные значения - string, text, choose, boolean, date, department, user, role), помогает понять какие данные нужно указывать в конкретном поле при импорте пользователей
multiple boolean- признак того множественное это поле или единичное, для множественных полей (таких как роли и отделы), при импорте пользователя нужно передавать массив значений
identifier boolean - признак того, является ли данное поле уникальным идентификатором
required boolean - признак того, является ли данное поле обязательным для заполнения

После обработки запроса возможны следующие коды ответов

  • 200 OK - Запрос успешно обработан

  • 401 UNAUTHORIZED - Не авторизованный запрос. Ключ авторизации либо вообще не указан, либо указан некорректно.

Передача данных по пользователям

Передача данных по пользователям для добавления и изменения пользователей осуществляется через POST запрос на адрес:

  • /public/api/v1/user

Запрос к этой точке должен содержать список полей пользователя в формате <Системное имя поля> : <Значение поля>.

<Значение поля> может быть массивом для множественных значений (роли, отделы и т.д.), так же среди этих полей обязательно должно быть поле идентификатор.

  • Если пользователь с указанным идентификатором существует, то запрос меняет существующего пользователя.

  • Если пользователь с указанным идентификатором не существует, то запрос создаёт нового пользователя.

  • Запрос на создание пользователя должен содержать в себе все и обязательные поля + любое количество не обязательных полей.

  • Запрос на изменение пользователя может содержать в себе любые поля (соответственно для пользователя будут изменены только те поля, которые указаны в запросе).

  • Порядок передаваемых полей в запросе неважен.

Назначение роли Верховный администратор через API не возможно. Верховных администраторов можно создать только руками через ПА (либо другой Верховный администратор должен произвести импорт через файл).

Пример передачи данных:

"email" : "test@ivan.ru",

"name" : "Иван",

"surname" : "Иванов"

После обработки запроса возможны следующие коды ответов:

  • 200 OK - Запрос успешно обработан

  • 400 BAD REQUEST - При обработке запроса возникли ошибки. Запрос содержит некорректные данные. Так же в ответе будут указаны возникшие ошибки.

  • 401 UNAUTHORIZED - Не авторизованный запрос. Ключ авторизации либо вообще не указан, либо указан некорректно.

Если в теле запроса передаются параметры, которые нельзя однозначно сопоставить по <Системное имя поля>, то такие параметры игнорируются, а однозначно определяемые параметры обрабатываются, и в ответе запроса передаётся информация об успешной обработке запроса.

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

Удаление пользователей

Для удаления пользователя нужно сделать POST запрос на адрес:

  • /public/api/v1/user/delete

Запрос к этой точке должен содержать уникальный идентификатор пользователя в формате <Системное поле идентификатора> : <Значение идентификатора> (пример: "email" : "alexey@start2play.ru")

После обработки запроса возможны следующие коды ответов:

  • 200 OK - Запрос успешно обработан

  • 400 BAD REQUEST - При обработке запроса возникли ошибки. Запрос содержит некорректные данные. Так же в ответе будут указаны возникшие ошибки.

  • 401 UNAUTHORIZED - Не авторизованный запрос. Ключ авторизации либо вообще не указан, либо указан некорректно.

Передача данных по структуре

Для передачи данных по структуре необходимо для каждого отдела отдельно сделать POST запрос на адрес:

  • /public/api/v1/department

Параметры запроса:

  • Запрос к этой точке должен содержать следующие данные (* - обязательные поля):

    • id* string - уникальный идентификатор отдела

    • title* string - название отдела

    • parent string - идентификатор родительского отдела, должен соответствовать созданному на портале отделу. Родительский отдел не должен находиться в подчинении у текущего отдела и всех его дочерних отделов

    • head string - идентификатор пользователя, являющегося руководителем отдела. Передаётся в формате в соответствии с полем, название которого установлено в поле “Уникальный идентификатор“ на странице Системное - Настройки системы | /admin/system/settings

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

  • Порядок передаваемых параметров в запросе неважен.

После обработки запроса возможны следующие коды ответов:

  • 200 OK - Запрос успешно обработан

  • 400 BAD REQUEST - При обработке запроса возникли ошибки. Запрос содержит некорректные данные. Так же в ответе будут указаны возникшие ошибки.

  • 401 UNAUTHORIZED - Не авторизованный запрос. Ключ авторизации либо вообще не указан, либо указан некорректно.

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

Если по какому-либо отделу данные не передались или передались с ошибкой, то это не должно блокировать передачу других отделов.

Запрос на удаление отдела

Для отправки запроса на удаление раздела необходимо отдельно для каждого отдела сделать POST запрос на адрес:

  • /public/api/v1/department/delete

Запрос к этой точке должен содержать уникальный идентификатор отдела в формате id : <Идентификатор> (пр. "id" : "00024812123")

После обработки запроса возможны следующие коды ответов

  • 200 OK - Запрос успешно обработан

  • 400 BAD REQUEST - При обработке запроса возникли ошибки. Запрос содержит некорректные данные. Так же в ответе будут указаны возникшие ошибки.

  • 401 UNAUTHORIZED - Не авторизованный запрос. Ключ авторизации либо вообще не указан, либо указан некорректно.