ROBOX.CLOUD API

Robox.Cloud API представляет собой HTTP-сервис для интеграции со сторонними системами

API работает в режиме сервера

Обмен данными осуществляется посредством GET- и POST-запросов. Данные передаются в формате JSON. Некоторые функции API могут вызываться любым запросом на усмотрение пользователя

Для исключения несанкционированного доступа к данным в каждом запросе должен передаваться параметр apiKey, который генерируется в личном кабинете в разделе Настройки  ->  Интеграция по API . Он представляет собой параметр формата GUID

apiKey может передаваться двумя способами:

  • как параметр URL (?apiKey=<значение_ключа>)
  • в качестве заголовка (apiKey=<значение_ключа>)

В ответ на любой запрос возвращается поле result, содержащее флаг успешного выполнения

Если запрос был выполнен с ошибкой, то в дополнительном поле error будет приведено её текстовое описание


{
  "result": false,
  "error": "Invalid apiKey"
}

В личном кабинете доступен конструктор запросов по API, который расположен в раделе Настройки -> Интеграция по API

Основные запросы API

Отправка команды на открытие

Получение списка сотрудников

Получение списка объектов

Получение протокола доступа

Добавление сотрудников

Удаление сотрудников



Отправка команды на открытие

Запрос


https://robox.cloud/api/web/open.ashx?apiKey=123-45&uid=12345&dir=in



https://robox.cloud/api/web/open.ashx?apiKey=123-45

Тело POST-запроса

{
  "uid": 1244847,
  "dir": "out"
}

Параметр Описание Тип Значение
uid Серийный номер контроллера Числовой 1...264-1
dir Направление прохода Строковый in – вход, out – выход
Ответ

{
  "result": true,
  "uid": 12345,
  "dir": "in",
  "create_datetime": "2024-05-19T10:29:53+03:00",
  "exec_datetime": "2024-05-19T10:29:53+03:00"
}

Параметр Описание Тип Значение
uid Серийный номер контроллера Числовой 1...264-1
dir Направление прохода Строковый in – вход, out – выход
create_datetime Дата/время создания команды для контроллера Строковый Дата и время в формате ISO8601
exec_datetime Дата/время выпонения команды контроллером Строковый Дата и время в формате ISO8601

Получение списка сотрудников

Запрос


https://robox.cloud/api/web/get-users-list.ashx?apiKey=123-45&card_code=567&user_name=XXX&group_id=0

Параметр Описание Тип Значение Значение при отсутствии параметра
card_code Карта доступа Числовой 0 – любая карта, 1...232-1 – конкретная карта 0
user_name Имя пользователя Строковый Фильтр работает по фамилии, имени и отчеству
group_id Идентификатор группы сотрудников Числовой -1 – сотрудник не состоит ни в одной группе, 0 – любая группа, 1...232-1 – идентификатор группы 0
Ответ

{
  result: true,
  "items": [
    {
      "id": 879,
      "fam": "TEST",
      "name": "",
      "otch": "",
      "phone": "1111111111",
      "gos_num_auto": "",
      "card_code": 2100000000,
      "add_card_code_list": [ 123123, 222, 456 ],
      "foto_url": "/Foto/508aa05b-3225-442d-964d-307f85fe15aa/8uiPvyBTP7SQYC6fYjlehtvcJUhUZtno.JPG",
      "change_datetime": "2024-03-26T21:31:43+03:00",
      "last_accesss_datetime": "2024-02-22T12:01:24+03:00",
      "blocked": false,
      "other": "",
      "group_name": "Без группы",
      "group_id": -1,
      "calendar_name": "Без ограничений",
      "calendar_id": -1,
      "appointment": "236523",
      "schedules_list": [
        {
          "schedule_id": 12,
          "schedule_name": "Инженеры"
        },
        {
          "schedule_id": 18,
          "schedule_name": "Производство"
        }
      ]
    }
  ]
}

Параметр Описание Тип Значение
id Идентификатор сотрудника Числовой 1...231-1
fam Фамилия Строковый Макс. длина 20 символов
name Имя Строковый Макс. длина 20 символов
otch Отчество Строковый Макс. длина 20 символов
phone Номер телефона Строковый Формат +7 (123) 456-78-90
gos_num_auto Гос. номера автомобиля Строковый Несколько номеров через запятую, общая длина 50 символов, формат X847EP62
card_code Основная карта доступа Числовой 1...232-1
add_card_code_list Дополнительные карты доступа Массив чисел Максимум три элемента со значением 1...232-1
foto_url Путь к фотографии сотрудника Строковый Макс. длина 500 символов
change_datetime Дата/время последнего изменения записи сотрудника Строковый Дата и время в формате ISO8601
last_accesss_datetime Дата/время последней авторизации сотрудника Строковый Дата и время в формате ISO8601
blocked Флаг блокировки доступа сотрудника ко всем контроллерам Логический false – запись активная, true – запись заблокирована после нескольких неудачных попыток входа
other Доп. информация Строковый Макс. длина 1000 символов
group_name Имя группы сотрудников Строковый Макс. длина 50 символов
group_id Идентификатор группы сотрудников Числовой -1 – сотрудник не состоит ни в одной группе, 1...232-1 – идентификатор группы
calendar_name Название рабочего календаря Строковый Макс. длина 50 символов
calendar_id Идентификатор рабочего календаря Числовой -1 – для сотрудника не задан рабочий календарь, 1...232-1 – идентификатор группы
appointment Должность Строковый Макс. длина 100 символов
schedules_list Графики доступа Массив структур Максимум 12 элементов
schedule_id Идентификатор графика доступа Числовой 1...232-1
schedule_name Название графика доступа Строковый Макс. длина 50 символов

Получение списка объектов

Запрос


https://robox.cloud/api/web/get-objects-list.ashx?apiKey=123-45

Ответ

{
  "result": true,
  "items": [
    {
      "id": 5,
      "name": "СпецПромДизайн",
      "address": "г. Рязань, пр-д Яблочкова, д. 6",
      "time_zone": 180,
      "devices_list": [
        {
          "device_id": 1731,
          "uid": 848848,
          "device_name": "Офис 717",
          "is_link": true,
          "is_params_sync": true
        },
        {
          "device_id": 2201,
          "uid": 86400671,
          "device_name": "Офис 720",
          "is_link": true,
          "is_params_sync": true
        },
        {
          "device_id": 1474,
          "uid": 86401692,
          "device_name": "Офис 720А",
          "is_link": true,
          "is_params_sync": true
        },
        {
          "device_id": 1257,
          "uid": 86402132,
          "device_name": "Офис 718",
          "is_link": true,
          "is_params_sync": true
        }
      ]
    }
  ]
}

Параметр Описание Тип Значение
name Название объекта Строковый Макс. длина 100 символов
address Адрес объекта Строковый Макс. длина 1000 символов
time_zone Часовой пояс Числовой Смещение относительно UTC в минутах (отрицательное или положительное)
devices_list Контроллеры на объекте Массив структур
device_id Идентификатор контроллера Числовой 1...232-1
uid Серийный номер контроллера Числовой 0 – любой контроллер, 1...264-1 – с указанным серийным номером
device_name Название контроллера Строковый Макс. длина 100 символов
is_link Флаг наличия связи с контроллером Логический true – контроллеран а связи, false – связи с контроллером нет
is_params_sync Флаг синхронизации параметров контроллера Логический true – параметры синхронизированы с сервером, false – параметры не синхронизированы

Получение протокола доступа

Запрос


https://robox.cloud/api/web/get-access-protocol.ashx?apiKey=123-45&user_name=&uid=0&event_code=-1&beg_date=2024-03-25&end_date=2024-03-25

Параметр Описание Тип Значение Значение при отсутствии параметра
user_name Имя сотрудника Строковый Фильтр работает по части фамилии, имени, отчества Пустое поле
card_code Карта доступа Числовой 0 – любая карта, 1...232-1 – конкретная карта 0
uid Серийный номер контроллера Числовой 0 – любой контроллер, 1...264-1 – с указанным серийным номером 0
event_code Код события доступа Числовой -1 – любое событие, от 0 и выше см. в таблице ниже -1
beg_date Дата начала интервала событий Строковый Формат: yyyy-mm-dd Текущая дата
end_date Дата окончания интервала событий Строковый Формат: yyyy-mm-dd Текущая дата
last_id Последнее значение идентификатора Числовой 0...232-1 Идентификатор записи в выборке должен быть больше этого значения 0
Ответ

{
  "result": true,
  "events": [
    {
      "id": 649746,
      "fam": "",
      "name": "",
      "otch": "",
      "appointment": "",
      "card_code": 347,
      "event_code": 200,
      "event_text": "Дверь (гостевой пропуск)",
      "uid": 1244847,
      "device_name": "Тестовый КЕДР",
      "device_id": "Тестовый КЕДР",
      "object_name": 1474,
      "object_id": 5,
      "datetime": "2024-03-24T16:45:58+05:00"
    }
  ]
}

Параметр Описание Тип Значение
id Идентификатор записи Числовой 1...232-1
fam Фамилия Строковый Макс. длина 20 символов
name Имя Строковый Макс. длина 20 символов
otch Отчество Строковый Макс. длина 20 символов
appointment Должность Строковый Макс. длина 100 символов
card_code Код карты доступа Числовой 1...232-1
event_code Код события доступа Числовой 0...255 (см. в таблице ниже)
event_text Текстовое описание события доступа Строковый Макс. длина 100 символов
uid Серийный номер контроллера Числовой 1...264-1
device_name Название контроллера Строковый Макс. длина 100 символов
device_id Идентификатор контроллера Числовой 1...232-1
object_name Название объекта, где установлен контроллер Строковый Макс. длина 100 символов
object_id Идентификатор объекта, где установлен контроллер Числовой 1...232-1
datetime Дата/время события доступа Строковый Дата и время в формате ISO8601

Максимальный период выборки составляет 100 дней



КодОписание
0Дверь (вход)
1Дверь (выход)
2Дверь (вход кнопке)
3Шлагбаум (вход)
4Дверь (открытие через Web-интерфейс)
5Шлагбаум (выход)
6Дверь (открытие через моб. приложение)
7Турникет (вход)
8Турникет (выход)
9Незарегистрированная карта (вход)
10Незарегистрированная карта (выход)
13Турникет (вход через моб. приложение)
14Турникет (выход через моб. приложение)
17Турникет (вход через Web-интерфейс)
18Турникет (выход через Web-интерфейс)
19Отказано в доступе (вход)
20Отказано в доступе (выход)
21Шлагбаум (вход кнопке)
22Шлагбаум (выход кнопке)
23Турникет (вход кнопке)
24Турникет (выход кнопке)
25Шлагбаум (вход через Web-интерфейс)
26Шлагбаум (выход через Web-интерфейс)
27Дверь (выход кнопке)
28Шлагбаум (вход через моб. приложение)
29Шлагбаум (выход через моб. приложение)
92Открыто надолго
93Возврат в обычный режим работы
190Дверь (открытие через моб. приложение локально)
191Турникет (вход через моб. приложение локально)
192Турникет (выход через моб. приложение локально)
193Шлагбаум (вход через моб. приложение локально)
194Шлагбаум (выход через моб. приложение локально)
195Открыто надолго локально
196Возврат в обычный режим работы локально
200Дверь (гостевой пропуск)
201Турникет (вход по гостевому пропуску)
202Турникет (выход по гостевому пропуску)
203Шлагбаум (вход по гостевому пропуску)
204Шлагбаум (выход по гостевому пропуску)
210Блокировка повторного входа
211Запрет входа по минимальному времени
212Дверь (открытие через Алису)
213Турникет (вход через Алису)
214Турникет (выход через Алису)
215Шлагбаум (вход через Алису)
216Шлагбаум (выход через Алису)
240Запрет входа по QR-коду (время действия истекло)
241Дверь (открытие по QR-код)
242Турникет (вход по QR-коду)
243Шлагбаум (открытие по QR-коду)
250Открытие по команде от системы АРНЗ
255Контроллер включён


Добавление сотрудников

Запрос


https://robox.cloud/api/web/add-users.ashx?apiKey=123-45

Тело POST-запроса

{
  "items": [
    {
      "fam": "Фролов",
      "name": "Дмитрий",
      "otch": "Александрович",
      "phone": "",
      "gos_num_auto": "",
      "card_code": 2388872657,
      "add_card_code_list": [],
      "blocked": false,
      "other": "",
      "group_name": "SPD",
      "appointment": "Генеральный директор"
    }
  ]
}

Параметр Описание Тип Значение
fam Фамилия Строковый Макс. длина 20 символов
name Имя Строковый Макс. длина 20 символов
otch Отчество Строковый Макс. длина 20 символов
phone Номер телефона Строковый Формат +7 (123) 456-78-90
gos_num_auto Гос. номера автомобиля Строковый Несколько номеров через запятую, общая длина 50 символов, формат X847EP62
card_code Основная карта доступа Числовой 1...232-1
add_card_code_list Дополнительные карты доступа Массив чисел Максимум три элемента со значением 1...232-1
blocked Флаг блокировки доступа сотрудника ко всем контроллерам Логический false – запись активная, true – запись заблокированнная
other Доп. информация Строковый Макс. длина 1000 символов
group_name Имя группы сотрудников Строковый Макс. длина 50 символов
appointment Должность Строковый Макс. длина 100 символов

Максимальное количество сотрудников, которое можно добавить, составляет 3000 человек

Добавлять сотрудников можно как по одному, так и целым списком не более этого лимита

Ответ

{
  "result": true,
  "items": [
    {
      "fam": "Фролов,
      "name": "Дмитрий",
      "otch": "Александрович",
      "phone": "",
      "card_code": 2388872657,
      "add_card_code_list": [],
      "status": "replaced"
    }
  ]
}

Параметр Описание Тип Значение
fam Фамилия Строковый Макс. длина 20 символов
name Имя Строковый Макс. длина 20 символов
otch Отчество Строковый Макс. длина 20 символов
phone Номер телефона Строковый Формат +7 (123) 456-78-90
card_code Основная карта доступа Числовой 1...232-1
add_card_code_list Дополнительные карты доступа Массив чисел Максимум три элемента со значением 1...232-1
status Статус Строковый added – новый сотрудник добавлен
replaced – такой сотрудник есть в системе, данные по нему обновлены
limit – добавить сотрудника нельзя, превышен лимит в 3000 человек

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



Удаление сотрудников

Запрос


https://robox.cloud/api/web/del-users.ashx?apiKey=123-45

Тело POST-запроса

{
  "items": [
    {
      "fam": "",
      "name": "",
      "otch": "",
      "card_code": 9090902
    },
    {
      "fam": "Фролова",
      "name": "Ольга",
      "otch": "Викторовна"
    }
  ]
}

Параметр Описание Тип Значение
fam Фамилия Строковый Макс. длина 20 символов
name Имя Строковый Макс. длина 20 символов
otch Отчество Строковый Макс. длина 20 символов
card_code Карта доступа Числовой 1...232-1

Поиск сотрудника будет осуществляться как по коду карты, так и по полному совпадению Ф.И.О. в зависимости от того, что именно передано в запросе.

Ответ

{
  "result": false,
  "items": [
    {
      "fam": "",
      "name": "",
      "otch": "",
      "card_code": 9090902,
      "status": "not found"
    },
    {
      "fam": "Фролова",
      "name": "Ольга",
      "otch": "Викторовна",
      "card_code": 123,
      "status": "deleted"
    }
  ]
}
Параметр Описание Тип Значение
fam Фамилия Строковый Макс. длина 20 символов
name Имя Строковый Макс. длина 20 символов
otch Отчество Строковый Макс. длина 20 символов
card_code Карта доступа Числовой 1...232-1
status Статус Строковый delete – сотрудник удалён
no found – такой сотрудник не найден

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