Описание протокола OZLocks

Каталог товаров

Главная страница
•
Техническая информация
•
8. Программное обеспечение
•
8.6 Клиент-серверная система интеграции OZLocks +
•
8.6.1 Спецификация
•
Описание протокола OZLocks

Заселение гостя с выпиской карты

POST /IssueCard

Формат параметров – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
СheckIn	String	Дата и время заезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
СheckOut	String	Дата и время выезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
GuestName	String	ФИО гостя, для которого выпускается карта
	required
GuestID	Int	Идентификатор гостя в системе OZLocks. Если не задан, то будет создан новый гость, а его идентификатор будет возвращен в ответе.
NewIssue	Boolean	Тип заселения. Если установлен true, тогда происходит новое заселение, и все предыдущие гости выселяются из номера. Если установлен false, тогда происходит заселение следующего гостя без выселения предыдущих.
	required
EncoderID	String	ID энкодера, на котором выпускается карта
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required
CardIssuer	String	Имя пользователя, который выпускает карту

Пример:

{

"Room": "101",

"СheckIn": "04.09.2025 15:21",

"СheckOut": "05.09.2025 14:00",

"GuestName": "Иванов Иван",

"NewIssue": true,

"EncoderID": "001",

"WorkstationID": "ADMIN01"

"CardIssuer": "Ресепшн",

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
СheckOut	String	Дата и время выезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
Number	String	UID карты
	required
GuestID	Int	Идентификатор гостя. Будет заполнен, если не был задан в запросе.
EncoderID	String	ID энкодера, на котором выпускается карта
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"СheckOut": "05.09.2025 14:00",

"Number": "AAFF1122",

"GuestID": 12,

"EncoderID": "001",

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "1",

"EMessage": "Номер не существует"

}

Выселение гостей

POST /CheckOut

Формат параметров – JSON

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

Для онлайн замков происходит выселение в самом замке.

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
EncoderID	String	ID энкодера, на котором очищается карта
	required*
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required
CardIssuer	String	Имя пользователя, который выселяет гостей

* — Обязательно для оффлайн замков

Пример:

{

"Room": "101",

"EncoderID": "001",

"WorkstationID": "ADMIN01"

"CardIssuer": "Ресепшн",

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
СheckOut	String	Дата и время выезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
EncoderID	String	ID энкодера, на котором выпускается карта
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"СheckOut": "05.09.2025 13:40",

"EncoderID": "001",

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "1",

"EMessage": "Номер не существует"

}

Чтение карты

GET /ReadCard

Формат параметров – JSON

Параметры:

Наименование	Тип	Описание
EncoderID	String	ID энкодера, на котором выпускается карта
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"WorkstationID": "ADMIN01"

"CardIssuer": "Ресепшн",

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
CardType	Int	Тип карты, который был считан
	required
CardTypeEx	String	Расшифровка типа карты, который был считан
	required
Room	String	Наименование номера

СheckIn	String	Дата и время начала действия карты в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
СheckOut	String	Дата и время окончания действия карты в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
HolderName	String	ФИО владельца карты
	required
HolderID	Int	ID владельца карты
	required
EncoderID	String	ID энкодера, на котором выпускается карта
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"CardType": 6,

"CardTypeEx": "Карта гостя",

"Room": "101",

"СheckIn": "04.09.2025 15:21",

"СheckOut": "05.09.2025 14:00",

"HolderName": "Иванов Иван",

"HolderID": "12,

"EncoderID": "001",

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "2",

"EMessage": "Карта отсутствует на устройстве"

}

Чтение лога замка

GET /ReadLogLock

Формат параметров – JSON

Данная команда отличается для онлайн и оффлайн замков.

Для оффлайн замков у вас должна быть специальная карта чтения данных, которую нужно предварительно запрограммировать через OZLocks Hotelier Pro. Далее с помощью этой картой нужно считать лог замка и положить на программатор. Данная команда считывает карту и представит лог его в ответном сообщении.

Для онлайн замков чтение лога произойдет непосредственно с замка.

Параметры:

Наименование	Тип	Описание
EncoderID	String	ID энкодера, на котором читается карта данных
	required*
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required
Room	String	Наименование номера, лог которого нужно получить
	required
ShowErrorEntrance	Boolean	Если флаг установлен или не задан, то в логе будут отображаться записи попытки несанкционированного доступа. Если флаг снят, то такие записи не будут добавлены в лог. Прим. Не все замки поддерживают записи несанкционированного доступа. Так же ведение таких записей в лог могут быть отключены при инициализации замка.

* — Обязательно для оффлайн замков. Для онлайн — не указывать.

** — Обязательно для онлайн замков. Для оффлайн — не указывать.

Пример:

{

"EncoderID": "001",

"WorkstationID": "ADMIN01"

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
EncoderID	String	ID энкодера, на котором читается карта данных
EncoderID	required*	ID энкодера, на котором читается карта данных
WorkstationID	String	ID рабочего места с которого выполняется запрос
WorkstationID	required	ID рабочего места с которого выполняется запрос
Log	Массив LogState	Массив записей об открытии замка. Для некоторых версий замков так же попытки получения несанкционированного доступа

* — Обязательно для оффлайн замков. Для онлайн — необязательно.

Запись LogState:

Наименование	Тип	Описание
RecordType	Integer	Тип записи лога
	required
RecordTypeEx	String	Наименование типа записи лога
	required
EventTime	String	Дата и время события в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
HolderID	String	ID карты, которая выполняла действие. Для другого способа авторизации, например, по коду — ID записи ключа авторизации
	required
HolderName	String	ФИО гостя для карт гостя. Или ФИО сотрудника — для карт персонала. Если в системе OZLocks не будет найдена связь между HolderID и ФИО владельца

Пример:

{

"EncoderID": "001",

"WorkstationID": "ADMIN01",

"Log":

[

{

"RecordType": 6,

"RecordTypeEx": "Карта гостя",

"EventTime": "04.09.2025 16:21",

"HolderID": 12,

"HolderName": "Иванов Иван",

{

"RecordType": 17,

"RecordTypeEx": "Код гостя",

"EventTime": "07.09.2025 16:22",

"HolderID": 12,

"HolderName": "Иванов Иван",

]

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "2",

"EMessage": "Карта отсутствует на устройстве"

}

Заселение гостя с установка кода

POST /IssueLockCode

Формат параметров – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
СheckIn	String	Дата и время заезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
СheckOut	String	Дата и время выезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
GuestName	String	ФИО гостя, для которого выпускается нужно внести код в замок
	required
GuestID	Int	Идентификатор гостя в системе OZLocks. Если не задан, то будет создан новый гость, а его идентификатор будет возвращен в ответе.
NewIssue	Boolean	Тип заселения. Если установлен true, тогда происходит новое заселение, и все предыдущие гости выселяются из номера. Если установлен false, тогда происходит заселение следующего гостя.
	required
LockCode	String	Код замка от 6 до 8 знаков
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required
CardIssuer	String	Имя пользователя, который выпускает ключ доступа

Пример:

{

"Room": "101",

"СheckIn": "04.09.2025 15:21",

"СheckOut": "05.09.2025 14:00",

"GuestName": "Иванов Иван",

"GuestID": 12,

"NewIssue": true,

"LockCode": "481221",

"WorkstationID": "ADMIN01"

"CardIssuer": "Ресепшн",

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
СheckOut	String	Дата и время выезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
GuestID	Int	Идентификатор гостя. Будет заполнен, если не был задан в запросе.
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"СheckOut": "05.09.2025 14:00",

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "1",

"EMessage": "Номер не существует"

}

Изменение кода доступа для гостя

POST /ChangeLockCode

Формат параметров – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
Room	required	Наименование номера
GuestID	Int	Идентификатор гостя в системе OZLocks.
LockCode	String	Код замка от 6 до 8 знаков
LockCode	required	Код замка от 6 до 8 знаков
WorkstationID	String	ID рабочего места с которого выполняется запрос
WorkstationID	required	ID рабочего места с которого выполняется запрос
CardIssuer	String	Имя пользователя, который выпускает ключ доступа

Пример:

{

"Room": "101",

"GuestID": 12,

"LockCode": "481221",

"WorkstationID": "ADMIN01"

"CardIssuer": "Ресепшн",

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Наименование номера
	required
СheckOut	String	Дата и время выезда в формате «ДД.MM.ГГГГ ЧЧ:ММ»
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"СheckOut": "05.09.2025 14:00",

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "1",

"EMessage": "Номер не существует"

}

Получение состояния замка

GET /ReadState

Формат параметров – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Номер замка, состояние которого хотим получить
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"WorkstationID": "ADMIN01"

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Номер замка, состояние которого получаем
	required
LowCharge	Boolean	Если параметр установлен, то заряд батареи в замке низкий. Если параметр снят, то нормальный.
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"Opened": false,

"LowCharge": true,

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "10",

"EMessage": "Замок не в сети"

}

Дистанционное закрытие/открытие замка

POST /OpenLock

Формат параметров – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Номер замка, состояние который хотим открыть
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"WorkstationID": "ADMIN01"

}

Код ответа – 200: OK

Формат ответа – JSON

Параметры:

Наименование	Тип	Описание
Room	String	Номер замка, состояние который хотим открыть
	required
WorkstationID	String	ID рабочего места с которого выполняется запрос
	required

Пример:

{

"Room": "101",

"WorkstationID": "ADMIN01"

}

Код ответа — 400: Сервер не доступен

Код ответа — 401: Не прошла авторизация

Код ответа — 500: Ошибка данных запроса

Формат ответа – JSON

Наименование	Тип	Описание
ECode	String	Код ошибки
	required
EMessage	String	Сообщение об ошибке
	required

Пример:

{

"ECode": "10",

"EMessage": "Замок не в сети"

}