Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Оглавление

...

Expand

...

expand
title
title
Оглавление
Table of Contents

...

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

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

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

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

...

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

...

titleСхема авторизации
  • При отправке запросов по урлам вида /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

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

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

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

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

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

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

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

Note

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

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

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

"name" : "Иван",

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

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

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

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

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

Info

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

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

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

Для удаления пользователя нужно сделать 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 - Не авторизованный запрос. Ключ авторизации либо вообще не указан, либо указан некорректно.

Info

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

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

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

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

  • /public/api/v1/department/delete

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

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

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

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

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