Примеры кода для интеграции с Waliot API: обработка кодов ответа на языке 1С, формат ошибок и права ключа, примеры запросов к основным методам — организация, состояния объектов, трек, отчеты. Пригодится разработчику, который подключает учетную систему к Waliot.
Примеры кода на 1С для подключения учетной системы к Waliot API: обработка ответов, ошибки и запросы к основным методам.
Как обработать ответ Waliot API в 1С: проверка кода ответа, разбор тела в формате JSON и ошибок.
Если Ответ.КодСостояния = 200 Тогда
ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(ТелоОтвета);
Если ЧтениеJSON.Read() Тогда
ДанныеОтвета = ЧтениеJSON.Получить();
Сообщить("Получен ответ: " + ТелоОтвета);
Иначе
Сообщить("Ошибка разбора JSON ответа.");
КонецЕсли;
ИначеЕсли Ответ.КодСостояния = 400 Тогда
Сообщить("Ошибка: Неверный запрос (400 Bad Request). Проверьте параметры запроса.");
ИначеЕсли Ответ.КодСостояния = 401 Тогда
Сообщить("Ошибка: Неавторизован (401 Unauthorized). Проверьте ключ API: 401 возможен и при блокировке пользователя или организации.");
ИначеЕсли Ответ.КодСостояния = 403 Тогда
Сообщить("Ошибка: Доступ запрещен (403 Forbidden). Проверьте права доступа.");
ИначеЕсли Ответ.КодСостояния = 404 Тогда
Сообщить("Ошибка: Ресурс не найден (404 Not Found). Проверьте URL и идентификаторы.");
ИначеЕсли Ответ.КодСостояния >= 500 Тогда
Сообщить("Ошибка сервера (" + Ответ.КодСостояния + "). Попробуйте повторить запрос позже.");
Иначе
Сообщить("Ошибка выполнения запроса. Код состояния: " + Ответ.КодСостояния);
КонецЕсли;
Ошибка API приходит с кодом 4xx или 5xx, как правило с телом в формате JSON: status, error.code, error.name, error.message и error.details. Логику интеграции стройте на error.code и error.name; текст error.details может меняться, его не стоит показывать пользователям. Ответы инфраструктуры (например, 502 или 504) могут прийти без тела.
Время в запросах передавайте в ISO 8601; ответы по объектам, состояниям и трекам приходят в UTC, а отчеты — в часовом поясе параметра time-zone (по умолчанию GMT+03:00). Подробнее об авторизации — на странице Интеграционные возможности.
В примерах вместо значений стоят подстановки: <ключ API>, <ORG_ID> — идентификатор организации, <OBJECT_ID> — идентификатор объекта мониторинга.
WaliotApiСервер = "api.waliot.com";
Соединение = Новый HTTPСоединение(WaliotApiСервер, 443, , , , 0, Новый ЗащищенноеСоединениеOpenSSL());
WaliotApiКлюч = "<ключ API>";
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "ApiKey " + WaliotApiКлюч);
Заголовки.Вставить("Accept", "application/json;charset=UTF-8");
WaliotApiАдрес = "/api/customers/organizations/organization";
Запрос = Новый HTTPЗапрос(WaliotApiАдрес, Заголовки);
Ответ = Соединение.ВызватьHTTPМетод("GET", Запрос);
ОтветJSON = ПреобразоватьОтветJSON(Ответ);
Метод группы States возвращает массив состояний объектов организации; параметр tree=true добавляет объекты дочерних организаций. Для получения актуальных данных состояния опрашивают периодически.
WaliotApiСервер = "api.waliot.com";
Соединение = Новый HTTPСоединение(WaliotApiСервер, 443, , , , 0, Новый ЗащищенноеСоединениеOpenSSL());
WaliotApiКлюч = "<ключ API>";
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "ApiKey " + WaliotApiКлюч);
Заголовки.Вставить("Accept", "application/json;charset=UTF-8");
WaliotApiАдрес = "/api/states?org-id=<ORG_ID>&tree=false";
Запрос = Новый HTTPЗапрос(WaliotApiАдрес, Заголовки);
Ответ = Соединение.ВызватьHTTPМетод("GET", Запрос);
ОтветJSON = ПреобразоватьОтветJSON(Ответ);
Метод группы Tracks возвращает начальную и конечную точки, промежуточные точки и события за период. Параметры from и to обязательны; необязательные filtration-tolerance (степень фильтрации точек) и event-types (события вместе с треком, например FUEL_ADD и FUEL_LEAK).
WaliotApiСервер = "api.waliot.com";
Соединение = Новый HTTPСоединение(WaliotApiСервер, 443, , , , 0, Новый ЗащищенноеСоединениеOpenSSL());
WaliotApiКлюч = "<ключ API>";
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "ApiKey " + WaliotApiКлюч);
Заголовки.Вставить("Accept", "application/json;charset=UTF-8");
WaliotApiАдрес = "/api/tracks/<OBJECT_ID>?from=<начало периода, ISO 8601 с Z>&to=<конец периода, ISO 8601 с Z>";
Запрос = Новый HTTPЗапрос(WaliotApiАдрес, Заголовки);
Ответ = Соединение.ВызватьHTTPМетод("GET", Запрос);
ОтветJSON = ПреобразоватьОтветJSON(Ответ);
Метод группы Reports возвращает конфигурации доступных отчетов и их параметры. Значение параметра type для построения отчета берут из этого списка; соответствие типов и названий отчетов в веб-приложении — в описании метода в документации.
WaliotApiСервер = "api.waliot.com";
Соединение = Новый HTTPСоединение(WaliotApiСервер, 443, , , , 0, Новый ЗащищенноеСоединениеOpenSSL());
WaliotApiКлюч = "<ключ API>";
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "ApiKey " + WaliotApiКлюч);
Заголовки.Вставить("Accept", "application/json;charset=UTF-8");
WaliotApiАдрес = "/api/reports/list";
Запрос = Новый HTTPЗапрос(WaliotApiАдрес, Заголовки);
Ответ = Соединение.ВызватьHTTPМетод("GET", Запрос);
ОтветJSON = ПреобразоватьОтветJSON(Ответ);
В теле запроса обязательны orgId (числом), objects (массив идентификаторов объектов) и intervals (массив периодов с from и to); столбцы и итоги берутся из стандартной конфигурации выбранного типа отчета, а не из ваших настроек в Навигаторе. Пример рассчитан на формат JSON. Границы периода передаются моментами времени, в примере — в UTC (Z); параметр time-zone (по умолчанию GMT+03:00) определяет, по какому календарю в отчете считаются сутки. Сутки 4 сентября по Москве (GMT+03:00) — это период от 2024-09-03T21:00:00.000Z до 2024-09-04T20:59:59.000Z.
WaliotApiСервер = "api.waliot.com";
Соединение = Новый HTTPСоединение(WaliotApiСервер, 443, , , , 0, Новый ЗащищенноеСоединениеOpenSSL());
WaliotApiКлюч = "<ключ API>";
Заголовки = Новый Соответствие;
Заголовки.Вставить("Authorization", "ApiKey " + WaliotApiКлюч);
Заголовки.Вставить("Accept", "application/json;charset=UTF-8");
Заголовки.Вставить("Content-Type", "application/json;charset=UTF-8");
ПараметрыЗапроса = Новый Соответствие;
ПараметрыЗапроса.Вставить("type", "GROUP_FUEL_CONSUMPTION");
ПараметрыЗапроса.Вставить("format", "JSON");
ПараметрыЗапроса.Вставить("version", "VER_3");
ТелоЗапроса = Новый Структура;
ТелоЗапроса.Вставить("orgId", <ORG_ID>); // число
Интервалы = Новый Массив;
Интервал = Новый Структура;
Интервал.Вставить("from", "<начало периода, ISO 8601 с Z>");
Интервал.Вставить("to", "<конец периода, ISO 8601 с Z>");
Интервалы.Добавить(Интервал);
ТелоЗапроса.Вставить("intervals", Интервалы);
Объекты = Новый Массив;
Объекты.Добавить(<OBJECT_ID>);
ТелоЗапроса.Вставить("objects", Объекты);
ЗаписьJSON = Новый ЗаписьJSON;
ПараметрыЗаписи = Новый ПараметрыЗаписиJSON(ПереносСтрокJSON.Авто, "", Истина);
ЗаписьJSON.УстановитьСтроку(ПараметрыЗаписи);
ЗаписатьJSON(ЗаписьJSON, ТелоЗапроса);
Тело = ЗаписьJSON.Закрыть();
WaliotApiАдрес = "/api/reports";
Запрос = Новый HTTPЗапрос(WaliotApiАдрес, Заголовки);
Запрос.Метод = "POST";
Для Каждого Параметр Из ПараметрыЗапроса Цикл
Запрос.ПараметрыURL.Вставить(Параметр.Ключ, Параметр.Значение);
КонецЦикла;
Запрос.УстановитьТелоИзСтроки(Тело, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
Ответ = Соединение.ВызватьHTTPМетод("POST", Запрос);
ОтветJSON = ПреобразоватьОтветJSON(Ответ);