Система Монитор предоставляет REST API для интеграции с системами клиентов.
Содержание
Доступ к swagger: https://monitor-api.web.monitorsystem.ru/swagger. (Что такое Swagger?)
Получить ключ доступа, обратившись в отдел поддержки.
Все запросы к API (кроме /healthStatus) требуют API-ключ. Передать ключ можно двумя способами:
X-API-KEY: ваш_ключ?apikey=ваш_ключВсе списочные эндпоинты поддерживают пагинацию и возвращают ответ в формате:
{
"items": [...],
"page": {
"pageNumber": 0,
"pageSize": 50,
"totalPages": 5,
"totalRecords": 230
}
}Параметры запроса:
page — номер страницы (начиная с 0)size — количество элементов на страницеsort — сортировка (через запятую, префикс - для сортировки по убыванию)filter — фильтрацияПолный список эндпоинтов:
| Метод | Эндпоинт | Описание |
|---|---|---|
| GET | /objects | Получить список объектов мониторинга |
| GET | /objects/lastData | Получить текущие состояния объектов (координаты, скорость, направление) |
| GET | /zones | Получить список геозон с GeoJSON |
| GET | /objects/zones | Получить текущие зоны нахождения объектов |
| GET | /reports/summary/parameters | Получить список доступных параметров сводного отчёта |
| POST | /reports/summary/build | Запустить формирование сводного отчёта |
| GET | /reports/ticket | Обновить статус тикета отчёта |
| GET | /reports/summary/report | Получить готовый сводный отчёт |
| POST | /reports/zones/build | Запустить формирование отчёта по посещению зон |
| GET | /reports/zones/report | Получить готовый отчёт по посещению зон |
| GET | /healthStatus | Проверка работоспособности сервиса (без аутентификации) |
Возвращает список объектов мониторинга (транспортных средств) с поддержкой пагинации.
Дополнительный параметр:
externalSystem — фильтрация по внешней системе интеграцииОтвет:
{
"items": [
{
"id": "dd156edf-6ecf-4992-b07b-fe3c2fe6d537",
"externalId": null,
"model": "Mitsubishi L200",
"number": "а 123 аа 24"
}
],
"page": { "pageNumber": 0, "pageSize": 50, "totalPages": 1, "totalRecords": 4 }
}Возвращает последние данные навигации для каждого объекта: координаты, скорость, направление движения, адрес и геозоны.
Необязательные параметры запроса:
ids — массив ID объектов для фильтрации (формат: ?ids=guid1&ids=guid2)externalIds — массив внешних ID объектов (требует externalSystem)externalSystem — название внешней системы интеграции (обязательно при использовании externalIds)filter — строковый фильтр по имени или госномеру объектаОтвет:
{
"items": [
{
"objectId": "dd156edf-6ecf-4992-b07b-fe3c2fe6d537",
"objectName": "Mitsubishi L200 а 123 аа 24",
"deviceTime": "2024-10-30T12:30:00",
"lat": 56.0184,
"lon": 92.8672,
"direction": 180,
"speed": 60,
"address": "ул. Промышленная, 5, Красноярск",
"zones": [
{ "id": "a1b2c3d4-...", "name": "База" }
]
}
],
"page": { ... }
}Возвращает список геообъектов компании, включая GeoJSON-геометрию.
Ответ:
{
"items": [
{
"id": "a1b2c3d4-...",
"name": "Склад №1",
"geoJson": "{\"type\":\"Polygon\",\"coordinates\":[[[92.85,56.01],[92.87,56.01],[92.87,56.02],[92.85,56.02],[92.85,56.01]]]}"
}
],
"page": { ... }
}Возвращает информацию о том, в каких геозонах сейчас находится каждый объект.
Ответ:
{
"items": [
{
"objectId": "dd156edf-...",
"objectName": "Mitsubishi L200 а 123 аа 24",
"zones": [
{ "id": "a1b2c3d4-...", "name": "Склад №1", "geoJson": "..." }
]
}
],
"page": { ... }
}Возвращает список всех параметров, которые можно запросить в сводном отчёте. Этот список нужно получить один раз.
Ответ (массив):
[
{ "id": "Connection.OnlineTime", "name": "Время на связи", "unit": "ч." },
{ "id": "Connection.OfflineTime", "name": "Время без связи", "unit": "ч." },
{ "id": "Movement.Mileage", "name": "Пробег", "unit": "км." },
{ "id": "Movement.MaxSpeed", "name": "Макс. скорость", "unit": "км/ч." },
{ "id": "Movement.TotalPark", "name": "Общая стоянка", "unit": "" }
]Запускает асинхронную генерацию сводного отчёта. Возвращает тикет, который нужно обновлять не реже раза в 30 секунд.
Запрос:
{
"start": "2024-10-30T00:00:00+07:00",
"end": "2024-10-31T00:00:00+07:00",
"parameters": ["Movement.Mileage", "Movement.MaxSpeed", "Movement.TotalPark"],
"objects": ["dd156edf-6ecf-4992-b07b-fe3c2fe6d537", "aa2d2e68-f169-4ff3-b9ce-0f414c1e9270"],
"externalSystem": null
}Важно: часовые пояса start и end должны совпадать.
Ответ — тикет отчёта:
{
"id": "f47ac10b-...",
"percentage": 0,
"status": "Wait",
"description": null
}Статусы тикета: Wait → Running → Completed / Failed
Параметр: ticketId — идентификатор тикета.
Возвращает обновлённое состояние тикета. Поллить до статуса Completed или Failed.
Параметр: ticketId — идентификатор завершённого тикета.
Ответ:
{
"objects": [
{
"id": "dd156edf-...",
"externalId": null,
"model": "Mitsubishi L200",
"number": "а 123 аа 24",
"reports": [
{
"range": { "id": "...", "name": "...", "start": "...", "end": "..." },
"report": [
{ "id": "Movement.Mileage", "name": "Пробег", "unit": "км.", "value": "295,44" },
{ "id": "Movement.MaxSpeed", "name": "Макс. скорость", "unit": "км/ч.", "value": "63" },
{ "id": "Movement.TotalPark", "name": "Общая стоянка", "unit": "", "value": "17:04:27" }
]
}
]
}
]
}Запускает асинхронную генерацию отчёта по посещению геозон. Работает аналогично сводному отчёту — возвращает тикет.
Запрос:
{
"start": "2024-10-30T00:00:00+07:00",
"end": "2024-10-31T00:00:00+07:00",
"objects": ["dd156edf-6ecf-4992-b07b-fe3c2fe6d537"],
"externalSystem": null
}Ответ: тикет отчёта (аналогично сводному отчёту).
Параметр: ticketId — идентификатор завершённого тикета.
Ответ:
{
"objects": [
{
"id": "dd156edf-...",
"externalId": null,
"model": "Mitsubishi L200",
"number": "а 123 аа 24",
"range": { "start": "2024-10-30T00:00:00", "end": "2024-10-31T00:00:00" },
"zones": [
{
"id": "a1b2c3d4-...",
"name": "Склад №1",
"start": "2024-10-30T08:15:00",
"end": "2024-10-30T09:30:00"
},
{
"id": "a1b2c3d4-...",
"name": "Склад №1",
"start": "2024-10-30T16:00:00",
"end": "2024-10-30T17:15:00"
}
]
}
]
}Примеры использования представлены на языке C#, но работать с API можно на любом языке.
Для удобства работы с API рекомендуем пользоваться генератором кода (NSwag, расширения для VS (REST API Client Code Generator for VS 2022 - Visual Studio Marketplace), VS Code или любое другое)
Подготовка:
1. Создаем пустой проект.
2. Генерируем классы API с помощью генератора.
using MonitorApiTest;
var http = new HttpClient();
// настраиваем клиент - указываем адрес
http.BaseAddress = new Uri("https://monitor-api.web.monitorsystem.ru");
// настраиваем клиент - добавляем ключ апи
http.DefaultRequestHeaders.Add("X-API-KEY", "demokey");
// для генерации клиента используем тулинг
//
// Generated REST API Client Code Generator v1.15.0.0
// Using the tool NSwag v14.1.0
//
var client = new MonitorSystemApiClient(http);
// получаем список объектов
var objects = await client.GetObjectsAsync(null, null, null, null, null);
Console.WriteLine("Список объектов:");
foreach (var obj in objects.Items)
{
Console.WriteLine($"{obj.Id}, {obj.Model}, {obj.Number}");
}// получаем текущие координаты всех объектов
var lastData = await client.GetObjectsLastDataAsync(null, null, null, null);
Console.WriteLine("Текущие координаты:");
foreach (var item in lastData.Items)
{
Console.WriteLine($"{item.ObjectName}: lat={item.Lat}, lon={item.Lon}, скорость={item.Speed} км/ч, время={item.DeviceTime}");
}// получаем список геозон
var zones = await client.GetZonesAsync(null, null, null, null);
Console.WriteLine("Геозоны:");
foreach (var zone in zones.Items)
{
Console.WriteLine($"{zone.Name} (id: {zone.Id})");
}
// проверяем в каких зонах сейчас находятся объекты
var objectZones = await client.GetObjectsZonesAsync(null, null, null, null);
foreach (var obj in objectZones.Items)
{
var zoneNames = string.Join(", ", obj.Zones.Select(z => z.Name));
Console.WriteLine($"{obj.ObjectName}: {(zoneNames.Length > 0 ? zoneNames : "вне зон")}");
}Для получения любого отчёта в системе необходимо пройти три этапа:
Completed или Failed.Completed), то получить отчёт, передав в качестве параметра Id тикета.using MonitorApiTest;
var http = new HttpClient();
// настраиваем клиент - указываем адрес
http.BaseAddress = new Uri("https://monitor-api.web.monitorsystem.ru");
// настраиваем клиент - добавляем ключ апи
http.DefaultRequestHeaders.Add("X-API-KEY", "demokey");
// для генерации клиента используем тулинг
//
// Generated REST API Client Code Generator v1.15.0.0
// Using the tool NSwag v14.1.0
//
var client = new MonitorSystemApiClient(http);
// получаем список объектов
var objects = await client.GetObjectsAsync(null, null, null, null, null);
Console.WriteLine("Список объектов:");
foreach (var obj in objects.Items)
{
Console.WriteLine($"{obj.Id}, {obj.Model}, {obj.Number}");
}
// получаем список возможных колонок сводного отчета. это нужно взять один раз чтобы понять что мы можем получать
var allAvailableParams = await client.GetAvailableSummaryParametersAsync();
Console.WriteLine($"Формируем отчет по пробегу за вчерашний день {DateTime.Today.AddDays(-1)}-{DateTime.Today}");
var ticket = await client.BuildSummaryReportAsync(new BuildSummaryReportRequest()
{
Start = new DateTimeOffset(DateTime.Today.AddDays(-1), TimeSpan.FromHours(7)), // указываем начало периода - вчера 00:00 часовой пояс +7 UTC
End = new DateTimeOffset(DateTime.Today, TimeSpan.FromHours(7)), // указываем конец периода - сегодня 00:00 часовой пояс +7 UTC
Parameters = new List<string>() { "Movement.Mileage", "Movement.MaxSpeed", "Movement.TotalPark" }, // указываем колонки сводного отчета для формирования
Objects = new List<string>(objects.Items.Select(f => f.Id)) // указываем список объектов
});
// пока статус тикета - не завершен обновляем тикет раз в секунду
while (ticket.Status != ReportTicketStatus.Completed && ticket.Status != ReportTicketStatus.Failed)
{
await Task.Delay(1000);
ticket = await client.UpdateReportTicketAsync(ticket.Id);
}
if (ticket.Status == ReportTicketStatus.Completed)
{
// если отчет сформирован успешно - берем результат
var report = await client.GetReportAsync(ticket.Id);
// выбираем все уникальные колонки
var columns = report.Objects.SelectMany(f => f.Reports).SelectMany(f => f.Report)
.Select(f => new { Id = f.Id, Name = f.Name }).Distinct().ToList();
// рисуем шапку
Console.WriteLine("Объект".PadRight(40) + string.Join("", columns.Select(f => f.Name + " ")));
foreach (var obj in report.Objects)
{
// пишем строку отчета
// объект
Console.Write($"{obj.Model} {obj.Number}".PadRight(40, ' '));
// столбцы
foreach (var col in columns)
{
var value = obj.Reports.First().Report.FirstOrDefault(f => f.Id == col.Id)?.Value ?? "";
Console.Write(value.ToString().PadRight(col.Name.Length + 4));
}
Console.WriteLine();
}
}
Console.ReadLine();Результат:
Список объектов:
dd156edf-6ecf-4992-b07b-fe3c2fe6d537, Mitsubishi L200, а 123 аа 24
aa2d2e68-f169-4ff3-b9ce-0f414c1e9270, Sitrak, е 232 кк 24
d4c2c010-1818-4f09-89a5-fecba67502de, КАМАЗ, р 236 кк 24
c9b0ef55-ccd9-45e0-977b-c255f1c1685f, Nissan NV200, в 321 ко 99
Формируем отчет по пробегу за вчерашний день 30.10.2024 0:00:00-31.10.2024 0:00:00
Объект Пробег Макс. скорость Общая стоянка
Mitsubishi L200 а 123 аа 24 295,44 63 17:04:27
Sitrak е 232 кк 24 629,47 109 15:50:06
КАМАЗ р 236 кк 24 49,03 37 20:57:54
Nissan NV200 в 321 ко 99 57 102 22:17:24
// формируем отчёт по посещению зон за вчерашний день
var zonesTicket = await client.BuildZonesReportAsync(new BuildZonesReportRequest()
{
Start = new DateTimeOffset(DateTime.Today.AddDays(-1), TimeSpan.FromHours(7)),
End = new DateTimeOffset(DateTime.Today, TimeSpan.FromHours(7)),
Objects = new List<string>(objects.Items.Select(f => f.Id))
});
// поллим статус
while (zonesTicket.Status != ReportTicketStatus.Completed && zonesTicket.Status != ReportTicketStatus.Failed)
{
await Task.Delay(1000);
zonesTicket = await client.UpdateReportTicketAsync(zonesTicket.Id);
}
if (zonesTicket.Status == ReportTicketStatus.Completed)
{
var zonesReport = await client.GetZonesReportAsync(zonesTicket.Id);
foreach (var obj in zonesReport.Objects)
{
Console.WriteLine($"\n{obj.Model} {obj.Number}:");
foreach (var zone in obj.Zones)
{
Console.WriteLine($" {zone.Name}: {zone.Start:HH:mm} - {zone.End:HH:mm}");
}
}
}Пример на языке 1С:Предприятие — получение текущих координат, адресов и зон нахождения транспорта.
// Функция получения данных API Монитор
// Возвращает массив структур с координатами, адресами и зонами объектов
//
Функция ПолучитьКоординатыТранспорта() Экспорт
АдресСервера = "monitor-api.web.monitorsystem.ru";
КлючAPI = "ваш-api-ключ";
// Создаём HTTP-соединение
Соединение = Новый HTTPСоединение(АдресСервера, 443, , , , 30, Новый ЗащищенноеСоединениеOpenSSL());
// Формируем запрос
Запрос = Новый HTTPЗапрос("/objects/lastdata");
Запрос.Заголовки.Вставить("x-api-key", КлючAPI);
// Выполняем запрос
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния <> 200 Тогда
ВызватьИсключение "Ошибка API: " + Ответ.КодСостояния;
КонецЕсли;
// Разбираем JSON ответ
ЧтениеJSON = Новый ЧтениеJSON();
ЧтениеJSON.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку());
Результат = ПрочитатьJSON(ЧтениеJSON);
ЧтениеJSON.Закрыть();
Возврат Результат.items;
КонецФункции
// Основная процедура — вывод координат, адресов и зон всех ТС
//
Процедура ПолучитьТранспортСАдресами() Экспорт
Объекты = ПолучитьКоординатыТранспорта();
Для Каждого Объект Из Объекты Цикл
// Координаты и адрес приходят в ответе API
Стр = Объект.objectName
+ " | " + Формат(Объект.lat, "ЧРД=.; ЧГ=") + ", " + Формат(Объект.lon, "ЧРД=.; ЧГ=")
+ " | " + ?(Объект.speed = Null, "стоит", Строка(Объект.speed) + " км/ч")
+ " | " + Объект.address;
// Зоны, в которых находится объект
Если Объект.zones <> Неопределено И Объект.zones.Количество() > 0 Тогда
ИменаЗон = "";
Для Каждого Зона Из Объект.zones Цикл
ИменаЗон = ИменаЗон + ?(ИменаЗон = "", "", ", ") + Зона.name;
КонецЦикла;
Стр = Стр + " | Зоны: " + ИменаЗон;
КонецЕсли;
Сообщить(Стр);
КонецЦикла;
КонецПроцедурыРезультат выполнения:
Камаз 966 7м3 | 56.096770, 93.066013 | стоит | ул. Промышленная, 5, Красноярск | Зоны: База
Shacman 488 13м3 | 56.096858, 93.065901 | 0 км/ч | ул. Промышленная, 5, Красноярск | Зоны: База
MAN 606 9 м3 | 56.284446, 95.704994 | 79 км/ч | Автодорога Р-255, Канский район
Ларгус Игорь | 56.042471, 93.357173 | 0 км/ч | ул. Ленина, 12, Красноярск | Зоны: ОфисОписание полей ответа /objects/lastData:
| Поле | Тип | Описание |
|---|---|---|
objectId | string | Идентификатор объекта |
objectName | string | Название объекта (модель + госномер) |
deviceTime | datetime | Время последних данных от трекера (UTC) |
lat | number | Широта |
lon | number | Долгота |
direction | int? | Направление движения (градусы, 0-360) |
speed | int? | Скорость (км/ч), null если данных нет |
address | string | Адрес местоположения |
zones | array | Геозоны, в которых находится объект (id, name) |