====== ProBonus API: Авторизация, лицензия и пользователи ======

Получение и обновление токена, информация о лицензии, управление пользователями веб-интерфейса и API, роли и права.

Общие правила (адрес, авторизация, форматы, коды ошибок) — на странице [[external:pro_bonus:10_probonus_api:20_reference|ProBonus API. Справочник методов]].

===== Список методов =====

^ Метод ^ Адрес ^ Назначение ^
| ''GET'' | ''/api/v0/auth/info'' | [[#получение_информации_о_лицензии_и_настройках_сервера_probonus|Получение информации о лицензии и настройках сервера ProBonus]] |
| ''POST'' | ''/api/v0/auth/login'' | [[#получение_токена_авторизации_на_основании_логина_и_пароля|Получение токена авторизации (на основании логина и пароля)]] |
| ''POST'' | ''/api/v0/auth/logout'' | [[#выход_пользователя_из_системы|Выход пользователя из системы]] |
| ''POST'' | ''/api/v0/auth/refresh_token'' | [[#обновление_токена_авторизации|Обновление токена авторизации]] |
| ''GET'' | ''/api/v0/license/check_license'' | [[#принудительное_обновление_информации_о_лицензии_с_сервера_лицензирования|Принудительное обновление информации о лицензии с сервера лицензирования]] |
| ''GET'' | ''/api/v0/license/info'' | [[#получение_информации_о_лицензии_на_по_probonus|Получение информации о лицензии на ПО ProBonus]] |
| ''POST'' | ''/api/v0/users/change_password'' | [[#обновление_пароля_для_пользователя_по_заданному_id|Обновление пароля для пользователя по заданному id]] |
| ''POST'' | ''/api/v0/users/delete'' | [[#удаление_пользователя_по_заданному_id|Удаление пользователя по заданному id]] |
| ''GET'' | ''/api/v0/users/get'' | [[#чтение_данных_пользователя_по_заданному_id|Чтение данных пользователя по заданному id]] |
| ''POST'' | ''/api/v0/users/insert'' | [[#добавление_нового_пользователя_insert|Добавление нового пользователя — insert]] |
| ''POST'' | ''/api/v0/users/insert_api_user'' | [[#добавление_нового_пользователя_insert_api_user|Добавление нового пользователя — insert_api_user]] |
| ''GET'' | ''/api/v0/users/list'' | [[#чтение_справочника_пользователи|Чтение справочника "Пользователи"]] |
| ''POST'' | ''/api/v0/users/update'' | [[#изменение_данных_пользователя_по_заданному_id_update|Изменение данных пользователя по заданному id — update]] |
| ''POST'' | ''/api/v0/users/update_api_user'' | [[#изменение_данных_пользователя_по_заданному_id_update_api_user|Изменение данных пользователя по заданному id — update_api_user]] |
| ''POST'' | ''/api/v0/roles/delete'' | [[#удаление_роли|Удаление роли]] |
| ''GET'' | ''/api/v0/roles/get'' | [[#чтение_роли_по_id|Чтение роли по id]] |
| ''POST'' | ''/api/v0/roles/insert'' | [[#добавление_роли|Добавление роли]] |
| ''GET'' | ''/api/v0/roles/list'' | [[#список_ролей|Список ролей]] |
| ''POST'' | ''/api/v0/roles/update'' | [[#изменение_роли|Изменение роли]] |

===== Авторизация =====

==== Получение информации о лицензии и настройках сервера ProBonus ====
**''GET /api/v0/auth/info''**\\
Авторизация: требуется

**Ответ 200** — объект ''AuthInfoDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''license'' | [[#licenseinfodto|LicenseInfoDto]] | да | Лицензия |
| ''settings'' | [[#settingsdto|SettingsDto]] | да | Настройки |

Дополнительные коды ответа: ''401'' — Unauthorized.

==== Получение токена авторизации (на основании логина и пароля) ====
**''POST /api/v0/auth/login''**\\
Авторизация: **не требуется**

Данный токен необходим для работы со всеми остальными запросами. Возвращает ''accessToken'' (передаётся в заголовке ''Authorization: Bearer <accessToken>'' во всех остальных запросах) и ''refreshToken'' для продления сессии.

**Тело запроса** — объект ''AuthLoginRequestDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин пользователя ProBonus |
| ''password'' | string | да | Пароль пользователя |

**Ответ 200** — объект ''AuthLoginResultDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''accessToken'' | string | да | Токен доступа; передаётся в заголовке ''Authorization: Bearer <accessToken>'' |
| ''expire'' | datetime | да | Дата и время окончания действия токена доступа |
| ''tokenType'' | string |  | Тип токена (''bearer''); по умолчанию ''"bearer"'' |
| ''refreshToken'' | string | да | Токен для получения новой пары токенов (метод ''/api/v0/auth/refresh_token'') |

Дополнительные коды ответа: ''401'' — Unauthorized.

==== Выход пользователя из системы ====
**''POST /api/v0/auth/logout''**\\
Авторизация: требуется

**Ответ 200:** JSON (структура в схеме не описана).

Дополнительные коды ответа: ''401'' — Unauthorized.

==== Обновление токена авторизации ====
**''POST /api/v0/auth/refresh_token''**\\
Авторизация: **не требуется**

Выдаёт новую пару токенов по действующему ''refreshToken''. Авторизация заголовком не требуется.

**Тело запроса** — объект ''AuthRefreshTokenRequestDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''accessToken'' | string | да | Токен доступа |
| ''refreshToken'' | string | да | Токен обновления сессии |

**Ответ 200** — объект ''AuthRefreshTokenResultDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''accessToken'' | string | да | Токен доступа |
| ''expire'' | datetime | да | Срок действия токена |

Дополнительные коды ответа: ''401'' — Unauthorized.

===== Лицензия =====

==== Принудительное обновление информации о лицензии с сервера лицензирования ====
**''GET /api/v0/license/check_license''**\\
Авторизация: **не требуется**

**Ответ 200** — объект ''LicenseInfoDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''online'' | boolean |  | Онлайн-проверка лицензии выполнена |
| ''valid'' | boolean |  | Лицензия действительна |
| ''status'' | string |  | Статус лицензии |
| ''expired'' | date |  | Дата окончания лицензии |
| ''message'' | string |  | Сообщение |
| ''sublicensesIds'' | string |  | Идентификаторы сублицензий |
| ''sublicensesStrs'' | string |  | Сублицензии |
| ''objectId'' | integer |  | Идентификатор объекта лицензирования |
| ''objectName'' | string |  | Наименование объекта лицензирования |
| ''projectName'' | string |  | Наименование проекта (лицензия) |
| ''projectLicenseCount'' | integer |  | Количество лицензий проекта |
| ''applicationVersion'' | string | да | Версия ProBonus |

==== Получение информации о лицензии на ПО ProBonus ====
**''GET /api/v0/license/info''**\\
Авторизация: **не требуется**

**Ответ 200** — объект ''LicenseInfoDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''online'' | boolean |  | Онлайн-проверка лицензии выполнена |
| ''valid'' | boolean |  | Лицензия действительна |
| ''status'' | string |  | Статус лицензии |
| ''expired'' | date |  | Дата окончания лицензии |
| ''message'' | string |  | Сообщение |
| ''sublicensesIds'' | string |  | Идентификаторы сублицензий |
| ''sublicensesStrs'' | string |  | Сублицензии |
| ''objectId'' | integer |  | Идентификатор объекта лицензирования |
| ''objectName'' | string |  | Наименование объекта лицензирования |
| ''projectName'' | string |  | Наименование проекта (лицензия) |
| ''projectLicenseCount'' | integer |  | Количество лицензий проекта |
| ''applicationVersion'' | string | да | Версия ProBonus |

===== Пользователи =====

==== Обновление пароля для пользователя по заданному id ====
**''POST /api/v0/users/change_password''**\\
Авторизация: требуется

**Тело запроса** — объект ''UserChangePasswordDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | integer | да | Идентификатор |
| ''newPassword'' | string | да | Новый пароль |

**Ответ 200** — объект ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

==== Удаление пользователя по заданному id ====
**''POST /api/v0/users/delete''**\\
Авторизация: требуется

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

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | строка запроса | integer | да | Идентификатор объекта |

**Ответ 200:** JSON (структура в схеме не описана).

==== Чтение данных пользователя по заданному id ====
**''GET /api/v0/users/get''**\\
Авторизация: требуется

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

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | строка запроса | integer | да | Идентификатор объекта |

**Ответ 200** — объект ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

==== Добавление нового пользователя — insert ====
**''POST /api/v0/users/insert''**\\
Авторизация: требуется

**Тело запроса** — объект ''UserInsertDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''role'' | [[#userroleid|UserRoleId]] | да | Роль |
| ''password'' | string | да | Пароль |

**Ответ 200** — объект ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

==== Добавление нового пользователя — insert_api_user ====
**''POST /api/v0/users/insert_api_user''**\\
Авторизация: требуется

Создаёт пользователя для интеграции. Его бессрочный токен передаётся в заголовке ''X-API-Key''.

**Тело запроса** — объект ''ApiUserInsertDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''role'' | [[#userroleid|UserRoleId]] | да | Роль |
| ''apiKey'' | string | да | Бессрочный токен пользователя для API |

**Ответ 200** — объект ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

==== Чтение справочника "Пользователи" ====
**''GET /api/v0/users/list''**\\
Авторизация: требуется

**Ответ 200** — массив объектов ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

==== Изменение данных пользователя по заданному id — update ====
**''POST /api/v0/users/update''**\\
Авторизация: требуется

**Тело запроса** — объект ''UserUpdateDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleid|UserRoleId]] | да | Роль |

**Ответ 200** — объект ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

==== Изменение данных пользователя по заданному id — update_api_user ====
**''POST /api/v0/users/update_api_user''**\\
Авторизация: требуется

**Тело запроса** — объект ''ApiUserUpdateDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор |
| ''role'' | [[#userroleid|UserRoleId]] | да | Роль |
| ''apiKey'' | string |  | Бессрочный токен пользователя для API |

**Ответ 200** — объект ''UserDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''login'' | string(50) | да | Логин |
| ''commentary'' | string |  | Комментарий |
| ''isSuperuser'' | boolean | да | Суперпользователь (все права) |
| ''permittedDbObjects'' | [[#userpermissionsdto|UserPermissionsDto]] |  | Объекты, доступные пользователю (например, рестораны) |
| ''createDateTime'' | datetime |  | Дата и время создания |
| ''id'' | integer | да | Идентификатор пользователя |
| ''role'' | [[#userroleidname|UserRoleIdName]] | да | Роль |
| ''kind'' | [[#userkindtype|UserKindType]] | да | Вид |

===== Роли =====

==== Удаление роли ====
**''POST /api/v0/roles/delete''**\\
Авторизация: требуется

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

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | строка запроса | string | да | Идентификатор объекта |

**Ответ 200:** JSON (структура в схеме не описана).

==== Чтение роли по id ====
**''GET /api/v0/roles/get''**\\
Авторизация: требуется

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

^ Параметр ^ Где ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | строка запроса | string |  | Идентификатор объекта; по умолчанию ''""'' |

**Ответ 200** — объект ''RoleDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string(50) | да | Наименование |
| ''comment'' | string |  | Комментарий |
| ''id'' | string |  | Идентификатор |
| ''isSystem'' | boolean | да | Системный элемент |
| ''rightGroups'' | массив [[#rolerightgroupdto|RoleRightGroupDto]] | да | Группы прав |

==== Добавление роли ====
**''POST /api/v0/roles/insert''**\\
Авторизация: требуется

**Тело запроса** — объект ''RoleInsertDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string(50) | да | Наименование |
| ''comment'' | string |  | Комментарий |
| ''allowedFullPaths'' | массив string | да |  |

**Ответ 200** — объект ''RoleDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string(50) | да | Наименование |
| ''comment'' | string |  | Комментарий |
| ''id'' | string |  | Идентификатор |
| ''isSystem'' | boolean | да | Системный элемент |
| ''rightGroups'' | массив [[#rolerightgroupdto|RoleRightGroupDto]] | да | Группы прав |

==== Список ролей ====
**''GET /api/v0/roles/list''**\\
Авторизация: требуется

**Ответ 200** — массив объектов ''RoleListItemDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string(50) | да | Наименование |
| ''comment'' | string |  | Комментарий |
| ''id'' | string |  | Идентификатор |
| ''isSystem'' | boolean | да | Системный элемент |

==== Изменение роли ====
**''POST /api/v0/roles/update''**\\
Авторизация: требуется

**Тело запроса** — объект ''RoleUpdateDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string(50) | да | Наименование |
| ''comment'' | string |  | Комментарий |
| ''allowedFullPaths'' | массив string | да |  |
| ''id'' | string | да | Идентификатор; мин. длина 1 |

**Ответ 200** — объект ''RoleDto'':

^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string(50) | да | Наименование |
| ''comment'' | string |  | Комментарий |
| ''id'' | string |  | Идентификатор |
| ''isSystem'' | boolean | да | Системный элемент |
| ''rightGroups'' | массив [[#rolerightgroupdto|RoleRightGroupDto]] | да | Группы прав |

===== Модели данных =====

Вложенные объекты и перечисления, на которые ссылаются методы этого раздела.

==== ApplicationSettingsDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''requirePhone'' | boolean | да | Телефон обязателен |
| ''requireSex'' | boolean | да | Пол обязателен |
| ''temporaryIdentifierValidMinutes'' | integer | да | Срок действия временного кода, минут |
| ''temporaryIdentifierLength'' | integer | да | Длина временного кода |
| ''language'' | string | да | Язык |
| ''dayBound'' | time | да | Время смены суток |
| ''cashShowBirthday'' | boolean | да | Показывать на кассе день рождения гостя |
| ''cashShowBirthdayDaysBefore'' | integer | да | Показывать день рождения за N дней до |
| ''cashShowBirthdayDaysAfter'' | integer | да | Показывать день рождения N дней после |
| ''specialCases'' | [[#specialcasesdto|SpecialCasesDto]] | да | Особые случаи |
| ''applicationVersion'' | string | да | Версия ProBonus |
| ''databaseVersion'' | string |  | Версия схемы БД |
| ''configOnly'' | boolean | да | Только настройки |

==== LicenseInfoDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''online'' | boolean |  | Онлайн-проверка лицензии выполнена |
| ''valid'' | boolean |  | Лицензия действительна |
| ''status'' | string |  | Статус лицензии |
| ''expired'' | date |  | Дата окончания лицензии |
| ''message'' | string |  | Сообщение |
| ''sublicensesIds'' | string |  | Идентификаторы сублицензий |
| ''sublicensesStrs'' | string |  | Сублицензии |
| ''objectId'' | integer |  | Идентификатор объекта лицензирования |
| ''objectName'' | string |  | Наименование объекта лицензирования |
| ''projectName'' | string |  | Наименование проекта (лицензия) |
| ''projectLicenseCount'' | integer |  | Количество лицензий проекта |
| ''applicationVersion'' | string | да | Версия ProBonus |

==== RoleRightGroupDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''name'' | string |  | Наименование; по умолчанию ''""'' |
| ''rights'' | массив [[#rolerightitemdto|RoleRightItemDto]] |  | Права |

==== RoleRightItemDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''enable'' | boolean |  | по умолчанию ''false'' |
| ''path'' | string |  | Путь; по умолчанию ''""'' |
| ''method'' | string |  | HTTP-метод и путь API; по умолчанию ''""'' |
| ''fullPath'' | string |  | по умолчанию ''""'' |
| ''summary'' | string |  | по умолчанию ''""'' |

==== SettingsDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''application'' | [[#applicationsettingsdto|ApplicationSettingsDto]] | да |  |
| ''user'' | [[#usersettingsdto|UserSettingsDto]] | да | Пользователь |

==== SpecialCasesDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''mealsWithSubsidies'' | boolean | да |  |
| ''loyaltyParticipants'' | boolean | да |  |

==== UserKindType ====
Перечисление (string). Значения: ''none'', ''user'', ''api_user''.
''user'' — пользователь веб-интерфейса, ''api_user'' — пользователь для интеграции по API

==== UserPermissionsDto ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''restaurants'' | массив integer |  | Рестораны |

==== UserRoleId ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | string | да | Идентификатор |

==== UserRoleIdName ====
^ Поле ^ Тип ^ Обяз. ^ Описание ^
| ''id'' | string | да | Идентификатор |
| ''name'' | string | да | Наименование |

==== UserSettingsDto ====
Без полей.