Группа базовых запросов

В данную группу входят следующие запросы:

Запрос	URL
events	<url_smartroad>/api/<version>1.Версии/events
status	<url_smartroad>/api/<version>/status
stat	<url_smartroad>/api/<version>/stat
sensors	<url_smartroad>/api/<version>/sensors

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

Дополнительные параметры запроса

Возможны следующие дополнительные параметры:

• sensorId
• sensorName DEPRECATED
• project_id
• startDate / from
• endDate / to
• timeZone

Формат параметров запроса

Временной интервал:

Параметры startDate/endDate

-----------------------------
startDate | 14.03.2025 13:00
endDate   | 14.03.2025 13:15
-----------------------------

Возможные варианты параметров:

• startDate/endDate

Возможные варианты значений:

• 14.03.2025 13:00 / 14.03.2025 14:00
• 14.03.2025 13 / 14.03.2025 14
• 14.03.2025 13:00:00 / 14.03.2025 14:00:00

Параметры from/to

-----------------------------
from | 2025-03-14T13:00:00
to   | 2025-03-14T13:15:00
-----------------------------

Возможные варианты параметров:

• from/to

Возможные варианты значений:

• 2025-03-14T13:00:00 / 2025-03-14T14:00:00
• 2025-03-14T13:00 / 2025-03-14T14:00
• 2025-03-14T13 / 2025-03-14T14
• 2025-03-14 13:00:00 / 2025-03-14 14:00:00
• 2025-03-14 13:00 / 2025-03-14 14:00
• 2025-03-14 13 / 2025-03-14 14

Перечисленные параметры идут только парой. Обязательно передавать начало и конец временного промежутка. Параметры регистронезависимы.

Параметр timeZone

--------------------------
timezone | Europe/Moscow
--------------------------

Возможные варианты параметров:

• timeZone

Возможные варианты значений:

• Europe/Moscow - по умолчанию
• UTC
• Chile/Continental
• America/Indiana/Knox

В качестве значения допускается аббревиатура или полное название часового пояса. Допускается передавать только одно значение. Параметр регистронезависим.

Далее в таблице приведены примеры некоторых вариантов часовых поясов. Значение из таблицы записываются в следующем порядке: <регион>/<страна>/<город>. При отсутствии значения в порядке записи, значение опускается.

Примеры значений

Сдвиг	Регион	Страна, острова, территория	Город, станция, территория
0	UTC
+3	Europe		Istanbul, Moscow
	Asia		Istanbul
+4	Europe		Samara, Astrakhan, Ulyanovsk, Saratov
+7	Asia		Tomsk, Novokuznetsk, Krasnoyarsk, Barnaul, Novosibirsk
	Indian	Christmas
+10	Asia		Vladivostok, Ust-Nera
-3		Chile	Continental
		Brazil	East
-9.5	Australia	North

Данные проекта:

Параметр project_id

------------------------------------------------
project_id | 00112233-4455-6677-8899-aabbccddeeff
------------------------------------------------

Возможные варианты параметра:

• project_id

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

Данные детектора:

Параметр sensorId

------------------------------------------------
sensorId | 00112233-4455-6677-8899-aabbccddeeff
------------------------------------------------

Возможные варианты параметра:

• sensorId
• sensorID
• sensor_id

Допускается передавать несколько значений:

00112233-4455-6677-8899-aabbccddeeff,99887766-5544-3322-1100-ffeeddccbbaa

Значения разделяются запятой, без пробелов. Параметр регистронезависим.

Параметр sensorName

------------------------
sensorName | example
------------------------

Возможные варианты параметра:

• sensorName
• name

Параметр регистронезависим. Допускается передавать несколько значений. При добавлении в запрос нескольких детекторов, важно чтобы все перечисленные детекторы были из одного проекта, иначе запрос вернет ответ 400 Bad Request.

Обработка ошибок

При отправке лишь начала временного промежутка

--------------------------------
startDate | 14.03.2025 13:00
          |     //отсутствие endDate
--------------------------------

должен быть получен следующий ответ:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "Ошибка проверки параметров: Указано начало периода, но не указано окончание"
}

При отправке лишь конца временного промежутка

--------------------------------
        |     //отсутствие startDate
endDate | 14.03.2025 14:00
--------------------------------

должен быть получен следующий ответ:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "Ошибка проверки параметров: Указано окончание периода, но не указано начало"
}

При отправке параметра времени, не соответствующего формату

--------------------------------
startDate | 2025-03-14T13:00:00
endDate   | 2025-03-14T14:00:00
--------------------------------

или

--------------------------------
from | 14.03.2025 13:00
to   | 14.03.2025 14:00
--------------------------------

должен быть получен следующий ответ:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "JSON transformation failed: Error processing rule for filters.range_start: date/time field value out of range: \"14.03.2025 13:00\""
}

При отправке параметра «ID детектора», не соответствующего формату

-------------------------------------------------
sensorId | 00112233-4455-6677-8899-aabbccddeef
         |    //UUID wrong length (short)
-------------------------------------------------

-------------------------------------------------
sensorId | 00112233-4455-6677-8899-aabbccddeeffg
         |    //UUID wrong length (long)
-------------------------------------------------

должен быть получен следующий ответ:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "JSON transformation failed: Invalid UUID format for filters.sensors: \"<sensorId>\""
}

При отправке параметра «ID проекта», не соответствующего формату

-------------------------------------------------
project_id | 00112233-4455-6677-8899-aabbccddeef
           |    //UUID wrong length (short)
-------------------------------------------------

-------------------------------------------------
project_id | 00112233-4455-6677-8899-aabbccddeeffg
           |    //UUID wrong length (long)
-------------------------------------------------

должен быть получен следующий ответ:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "JSON transformation failed: Invalid UUID format for filters.projects: \"<project_id>\""
}

При отправке запроса:

• с неверным именем или ID детектора
• с детектором, для доступа к которому у пользователя нет прав
• с детекторами из разных проектов

должен быть получен следующий ответ:

400 Bad Request:400
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "Ошибка проверки параметров: Указанные параметры или права пользователя не позволяют однозначно определить ИД проекта"
}

При отправке часового пояса, не соответствующего формату, должен быть получен следующий ответ:

400 Bad Request:
{
    "code": "400",
    "details": "ERROR",
    "hint": "",
    "message": "invalid value for parameter \"TimeZone\": \"<incorrect_timezone>\""
}

---

1. В качестве версии API может быть указан номер протокола (2.0) либо иной эндпоинт (например, integration) на усмотрение организации, использующей API.↩