Введение
В этой документации описано взаимодействие с API яЭнергетик версии 2 (JSON-RPC).
Взаимодействие с API
Взаимодействие с API производится отправкой HTTP POST запроса со строкой в формате JSON в теле запроса (тип данных application/json, кодировка UTF-8, экранировать юникод не обязательно) по адресу https://app.yaenergetik.ru/api?v2.
Ответом всегда будет json строка в кодировке UTF-8, при условии что возвращен код состояния HTTP 200.
Если возвращен иной код состояния, то следует считать что произошла непредвиденная ошибка.
Json строки запроса/ответа формируются в соответствии с протоколом JSON-RPC 2.0 (на русском). Можно использовать готовую библиотеку, которая предоставляет возможности клиента JSON-RPC, либо написать реализацию под свои задачи, протокол относительно прост. Поддерживаются практически все возможности протокола.
Совместимость:
- Не поддерживаются позиционные параметры
by-position. Параметры должны быть именованнымиby-name, т.е.paramsдолжен быть json-объектом. - При множественных вызовах
batchимеется ограничение в 100 вызовов в одном запросе. - Методы аутентификации
auth.*не поддерживают множественные вызовы.
Термины
| Термин | Значение |
|---|---|
| Запрос | HTTP запрос |
| Вызов | Вызов метода (в одном запросе может быть несколько вызовов) |
| Json-объект | Тип данных |
| Объект | Объект в сети на яЭнергетик |
| ПУ | Прибор учета - реальное устройство, которое соответствует счетчику на яЭнергетик |
| id | Идентификатор типа int для данных на яЭнергетик (сеть, объект, счетчик, ...)Не связан с id вызова |
Типы данных datatypes
- все доступные в json типы
- дата со временем указывается строкой в соответствии с RFC 3339
- дата указывается строкой в формате
ГГГГ-ММ-ДД - месяц указывается строкой в формате
ГГГГ-ММ - год указывается целым числом, полностью
Обработка ошибок
Сервер возвращает все ошибки в соответствии с протоколом JSON-RPC 2.0. Может быть возвращена любая ошибка, описанная в спецификации протокола, а также следующие ошибки конкретной реализации (implementation-defined server errors):
Пример ошибки
{
"jsonrpc": "2.0",
"error": {
"code": 10102,
"message": "Authentication failed"
},
"data": {
"details": "Неправильный пароль"
},
"id": 1
}
| Код | Сообщение | Наиболее вероятная причина |
|---|---|---|
| -32000 | Too many requests in batch | Превышено ограничение в 100 множественных вызовов в пределах одного запроса |
| -32001 | Method can not be processed in batch | Вызываемый метод не поддерживает множественные вызовы |
| -32011 | Unauthorized | В запросе не передан идентификатор сессии |
| -32012 | Session expired | Сессия недействительна, необходимо пройти аутентификацию заново |
Аутентификация
Обычно вызов метода требует прохождения аутентификации (за исключением метода auth.login).
Чтобы сообщить о том, что аутентификация пройдена, необходимо добавить к HTTP запросу идентификатор сессии.
Это может быть сделано добавлением HTTP заголовка X-Session-Id со значением идентификатора сессии, либо добавлением параметра sessionId в строку запроса, если нет возможности добавить заголовок.
В этом случае адрес запроса будет выглядеть подобным образом https://app.yaenergetik.ru/api?v2&sessionId=ufj428rt29r7f2f23td123
Идентификатор сессии может быть получен в результате прохождения аутентификации. Сессия действительна до тех пор, пока совершаются запросы с указанием соответствующего ей идентификатора. Сессия становится недействительной, когда такие запросы не совершались дольше тайм-аута сессии (см. таблицу ниже). Если сессия стала недействительной, следует пройти аутентификацию еще раз и получить идентификатор новой сессии.
Методы auth
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| auth.login | string | Аутентификация с созданием сессии |
| auth.logout | null | Завершение текущей сессии |
Режимы аутентификации
| Режим | Название | Тайм-аут сессии | Ограничение попыток | Превышение ограничения |
|---|---|---|---|---|
| Пользовательский | user | 30 суток | 3 попытки | Ввод кода подтверждения |
| Серверный | server | 24 часа | 5 попыток | Блокировка на 5 минут |
Название режима аутентификации передается в параметре mode при вызове метода auth.login.
Возможные ошибки
| Код | Режим | Сообщение | Наиболее вероятная причина |
|---|---|---|---|
| 10101 | любой | User not found | Пользователь не существует |
| 10102 | любой | Authentication failed | Аутентификация не пройдена по разным причинам, следует смотреть data.details |
| 10104 | любой | Invalid state | В запросе содержащем вызов метода аутентификации уже указана сессия |
| 10105 | любой | Invalid credentials | Неправильно указаны данные для авторизации |
| 10103 | серверный | Authentication request limit reached | Превышено ограничение попыток аутентификации |
| 10201 | пользовательский | Verification code required | Необходимо указать код подтверждения |
| 10202 | пользовательский | Invalid verification code | Неправильно указан код подтверждения |
| 10203 | пользовательский | Invalid password | Неправильно указан пароль |
Пользовательский режим
Вызов метода
{
"jsonrpc": "2.0",
"method": "auth.login",
"params": {
"mode": "user",
"user": "ivan@example.com",
"password": "secret",
"verifyCode": null
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": "ugjuorliu0m3s75ql52ddjnoph4",
"id": 1
}
Ошибка, когда необходим код подтверждения
{
"jsonrpc": "2.0",
"error": {
"code": 10201,
"message": "Verification code required"
},
"data": {
"verifyImage": "iVBORw0KGgoAAAA..."
},
"id": 1
}
Метод auth.login.
В пользовательском режиме для аутентификации необходимо передать email пользователя яЭнергетик и его пароль.
После нескольких неудачных попыток аутентификации может потребоваться вместе с email и паролем передавать код подтверждения - код, показанный на картинке (капче). Если передан неправильный код или неправильный пароль, то при следующем вызове нужно будет передать уже новый код, изображение с которым пришло в ошибке.
Картинка с кодом подтверждения возвращается в объекте data ошибки в значении verifyImage. Картинка является изображением в формате png, закодированным в base64 строку. Коды ошибок, в которых она может присутствовать: 10102, 10201, 10202.
Параметры
Все параметры обязательны, кроме verifyCode, когда не требуется код подтверждения.
| Параметр | Тип данных | Описание |
|---|---|---|
| mode | string | режим аутентификации, принимает значение user |
| user | string | email пользователя яЭнергетик |
| password | string | пароль пользователя яЭнергетик |
| verifyCode | string|null | код подтверждения (указывается только по требованию) |
Результат
Cтрока - идентификатор сессии.
Серверный режим
Вызов метода
{
"jsonrpc": "2.0",
"method": "auth.login",
"params": {
"mode": "server",
"user": "ivan@example.com",
"apiKey": "iguxyXjan1_Ut3xoFth7t-fGIZ5Zif0Yw-PBT1jQK53eTm6n"
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": "sqnq9o4tipc15hm83cgb2bplgl2",
"id": 1
}
Ошибка, когда превышено ограничение попыток
{
"jsonrpc": "2.0",
"error": {
"code": 10103,
"message": "Authentication request limit reached"
},
"id": 1
}
Метод auth.login.
Серверный режим аутентификации по умолчанию отключен. Его можно включить и настроить на странице приложения https://app.yaenergetik.ru/user/api.
В серверном режиме для аутентификации необходимо передать email пользователя яЭнергетик и ключ, полученный при настройке в приложении.
Параметры
Все параметры обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| mode | string | режим аутентификации, принимает значение server |
| user | string | email пользователя яЭнергетик |
| apiKey | string | ключ |
Результат
Строка - Идентификатор сессии.
Общая информация
Общие ошибки
Существует несколько общих ошибок, которые возникают при работе с данными при помощи любых методов.
| Код | Сообщение | Наиболее вероятная причина |
|---|---|---|
| 20101 | Not found | Данные с переданным в вызове идентификатором не найдены |
| 20102 | Access denied | У текущего пользователя нет доступа к выбранным данным |
| 20103 | Too many data requested | Метод не может вернуть запрошенный объем данных, добавьте ограничивающие параметры или постраничный вывод |
| 20104 | Unsupported feature | Счетчик (ПУ) не поддерживает возможность, необходимую для вызова метода с переданными параметрами |
Общие структуры данных
Постраничный вывод page
Методы, которые могут вернуть большой объем данных, обычно поддерживают постраничный вывод.
Для того чтобы им воспользоваться, следует добавить параметр page (json-объект) к запросу.
Структура параметра page:
└── page object
├── size int Количество данных на одну страницу, от 1 до 1000*
└── index int Текущая страница, нумерация начинается с 1
* Максимальное количество данных на одну страницу не должно превышать 1000, но также оно не должно превышать максимальное количество данных, возвращаемых методом.
Если использовался постраничный вывод, то вызов вернет результат не в виде массива json-объектов как обычно, а в виде json-объекта следующей структуры:
├── pageCount int Общее количество страниц ├── valueCount int Общее количество данных ├── page int Текущая страница, нумерация начинается с 1 └── values object[] Данные текущей страницы
Период period
Некоторые методы могут возвращать информацию за определенный период времени (например, список показаний).
Желаемый период передается в параметре period в виде json-объекта следующей структуры:
└── period object
├── type string Тип периода
├── value зависит от типа Значение
└── strict boolean Строгий поиск
| Тип периода | Тип данных value |
Описание |
|---|---|---|
| moment | Строка, дата+время | Момент времени |
| hour | Строка, дата+время без минут и секунд | Час (время начала часа) |
| day | Строка, дата | День |
| month | Строка, описание месяца | Месяц |
| year | Целое число, год | Год |
Если значение value не указано, то будет выбран текущий период.
Значение value может быть массивом из двух элементов соответствующих типов.
Тогда первое значение будет выбрано для определения начала периода, а второе - для конца.
Строгий поиск по умолчанию выключен, если значение strict не указано.
Строгий поиск применяется там, где важен выбор данных на концах периодов.
Например, при запросе расхода по показаниям в строгом режиме, для расчета расхода будут использоваться только показания попадающие ровно на концы периода,
а в ином случае будут использоваться ближайшие к концам показания, которые попадают в период.
Концы периода считаются включительно, если в описании метода не указано обратного.
Компания company
Информация о компании возвращается в виде объекта, где указано название компании и ИНН (если он есть в системе).
Структура параметра company:
└── company
├── name string|null Название компании
└── inn string|null ИНН
Часовые пояса
Система яЭнергетик поддерживает работу с разными часовыми поясами. Во время исполнения метода, часовой пояс выбирается на основании настроек сети и настроек пользователя. Например, если запрашиваются показания определенного счетчика, то даты будут возвращены в часовом поясе, настроенном у сети, к которой относится этот счетчик.
Можно вручную установить часовой пояс для использования в последующих вызовах в пределах одного запроса (см. множественный вызов). Для этого перед вызовом остальных методов, нужно вызвать метод system.setTimezone. В следующих запросах часовой пояс снова станет выбираться на основании настроек.
Множественный вызов
Запрос с вызовом двух методов
[
{
"jsonrpc": "2.0",
"method": "user.info",
"id": 1
},
{
"jsonrpc": "2.0",
"method": "network.list",
"id": 2
}
]
Ответ на множественный вызов
[
{
"jsonrpc": "2.0",
"result": {
"name": "Иванов Иван Иванович",
"singleNetwork": true
},
"id": 1
},
{
"jsonrpc": "2.0",
"result": [
{
"id": 123,
"name": "АСКУЭ пользователя Иванов Иван Иванович",
"owner": "Иванов Иван Иванович",
"address": "Архангельск",
"objectView": true
}
],
"id": 2
}
]
Можно вызвать несколько методов в одном запросе (кроме методов группы auth).
Для этого достаточно передать массив с json-объектами вызовов.
В ответ будет получен массив с json-объектами результатов и/или ошибок.
При множественном вызове существует ограничение в 100 вызовов в пределах одного запроса.
Пользователь
Методы user
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| user.info | object | Получение информации о текущем пользователе |
| user.listContractors | object | Получение списка контрагентов пользователя |
Информация о пользователе
Вызов метода
{
"jsonrpc": "2.0",
"method": "user.info",
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": {
"name": "Иванов Иван Иванович",
"singleNetwork": true,
"company": {
"name": "ООО \"Эртрейд\"",
"inn": "1234567890"
}
},
"id": 1
}
Метод user.info.
Параметры
Метод не принимает параметров.
Результат
Json-объект с информацией о пользователе.
├── name string Полное имя пользователя ├── singleNetwork boolean Признак того, что у пользователя может быть только одна сеть (но не обязательно есть) └── company object Информация о компании
Список контрагентов
Вызов метода
{
"jsonrpc": "2.0",
"method": "user.listContractors",
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"id": 5,
"fullName": "ИП Иванов И.И.",
"lastName": "Иванов",
"firstName": "Иван",
"middleName": "Иванович",
"contractorTypeId": 1,
"ogrn": "xxxx",
"ogrnDate": "2021-01-01",
"inn": "3664069397",
"kpp": "773301001",
"registeredAddress": "г. Москва",
"postAddress": "г. Москва",
"email": "example@example.com",
"phone": "+79993335511",
},
{
"id": 6,
"fullName": "ООО Рога и Копыта",
"lastName": null,
"firstName": null,
"middleName": null,
"contractorTypeId": 1,
"ogrn": "xxxx",
"ogrnDate": "2021-02-01",
"inn": "3664069397",
"kpp": "773301001",
"registeredAddress": "г. Москва",
"postAddress": "г. Москва",
"email": "example@example.com",
"phone": "+79993335511",
}
],
"id": 1
}
Метод user.listContractors.
Параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| filter | object[] | Фильтр контрагентов |
Фильтры
Структура фильтра:
├── type string Тип фильтра └── value зависит от типа Желаемое значение
Типы фильтров:
| Тип | Возможные значения | Описание |
|---|---|---|
| "id" | int|int[] | Будут возвращены только контрагенты с таким(и) id |
Результат
Массив json-объектов информацией о контрагентах пользователя.
├── id int id для использования в других вызовах ├── fullName string Полное наименование контрагента ├── name string краткое наименование ├── lastName null|string фамилия ├── firstName null|string имя ├── middleName null|string отчество ├── contractorTypeId int тип ├── ogrn null|string номер ЕГРИП/ЕГРЮЛ ├── ogrnDate null|date дата ЕГРИП/ЕГРЮЛ ├── inn null|string ИНН ├── kpp null|string КПП ├── registeredAddress null|string юридический адрес/адрес прописки ├── postAddress null|string почтовый адрес ├── email null|string адрес эл. почты ├── phone null|string номер телефона
Система
Методы system
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| system.setTimezone | null | Устанавливает часовой пояс для последующих вызовов в пределах одного запроса |
| system.versions | object[] | Возвращает список версий групп методов |
Установка часового пояса
Вызов метода
{
"jsonrpc": "2.0",
"method": "system.setTimezone",
"params": {
"name": "Europe/Moscow"
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
Метод system.setTimezone.
Параметры
Параметр name обязателен и должен содержать название существующего часового пояса.
Названия можно посмотреть в этом списке.
| Параметр | Тип данных | Описание |
|---|---|---|
| name | string | Название часового пояса |
Результат
Вызов метода всегда возвращает null.
При этом часовой пояс с указанным названием устанавливается для последующих вызовов в пределах этого же запроса.
Список версий
Вызов метода
{
"jsonrpc": "2.0",
"method": "system.versions",
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": {
"auth": 1,
"user": 3,
"network": 1,
"meter": 4,
"reading": 2
},
"id": 1
}
Метод system.versions.
Параметры
Метод не принимает параметров.
Результат
Json-объект со списком версий групп вызываемых методов.
Сети
Методы network
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| network.list | object[] | Получение списка сетей текущего пользователя |
Список сетей
Вызов метода
{
"jsonrpc": "2.0",
"method": "network.list",
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"id": 123,
"name": "АСКУЭ пользователя Иванов Иван Иванович",
"owner": "Иванов Иван Иванович",
"company": {
"name": "ООО \"Эртрейд\"",
"inn": "1234567890"
},
"address": null,
"objectView": true,
"features": [
"price"
]
}
],
"id": 1
}
Метод network.list.
Параметры
Метод не принимает параметров.
Результат
Массив json-объектов с информацией о сетях.
├── id int id для использования в других вызовах ├── name string Название сети ├── owner string Полное имя пользователя - владельца сети ├── company object Информация о компании - владельце сети ├── address string|null Адрес, указанный в настройках сети ├── objectView boolean Включен ли режим показа объектов (когда в одном объекте может быть несколько счетчиков) └── features string[] Названия возможностей сети
Возможности сети:
| Название | Описание |
|---|---|
| price | Ценовые категории |
Объекты
Методы object
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| object.list | object[] | Получение списка объектов |
| object.update | object | Обновление атрибутов объекта |
Список объектов
Вызов метода
{
"jsonrpc": "2.0",
"method": "object.list",
"params": {
"filter": [
{
"type": "networkId",
"value": 123
},
{
"type": "search",
"value": "Ввод"
}
]
},
"id": 1
}
Результат - массив объектов
{
"jsonrpc": "2.0",
"result": [
{
"id": 2,
"name": "Ввод в серверную",
"account": "56844315",
"contractor": "Петров П.П.",
"addressSiteValue": null,
"city": "Зарайск",
"street": "ул. Данилова",
"house": "58",
"building": "58",
"flat": "74",
"office": "33",
"additionAddr": "Доп. адрес",
"objectType": "ПС",
"uniqueDeliveryPointIdentifier": "3f97bb3a-1f1f-479f-9fdf-2cd0d791155c",
"voltageLevel": "ВН",
"powerLevel": "Свыше 10 МВт",
"priceCategory": "VI ЦК"
}
],
"id": 1
}
Метод object.list позволяет запросить список объектов в сети.
Параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| filter | object[] | Фильтр объектов |
| page | object | Постраничный вывод |
Фильтры
Структура фильтра:
├── type string Тип фильтра или источника └── value зависит от типа Желаемое значение у объекта
Типы фильтров:
| Тип | Возможные значения | Описание |
|---|---|---|
| "id" | int|int[] | Будут возвращены только объекты с таким id |
| "networkId" | int|int[] | Будут возвращены только объекты с таким(и) id сети |
| "search" | null|string | Поиск по названию объекта |
Результат
Список объектов
Структура:
├── id null|int id [объекта](#f3693d378a) ├── name string название ├── account int лицевой счет ├── contractor null|int имя [контрагента](#4a9d299c2d) ├── addressSiteValue null|string расположение ├── city null|string город ├── street null|string улица ├── house null|string дом ├── building null|string корпус ├── flat null|string расположение ├── office null|string офис ├── additionAddr null|string дополнительная адресная информация ├── objectType null|string Тип объекта в схеме ├── uniqueDeliveryPointIdentifier null|string Уникальный идентификатор точки поставки ├── voltageLevel null|string Тарифное напряжение ├── powerLevel null|string Диапазон максимальной мощности ├── priceCategory null|string Ценовая категория
Обновление атрибутов объекта
Вызов метода
{
"jsonrpc": "2.0",
"method": "object.update",
"params": {
"id": 62,
"name": "Объект-763",
"addressSiteValue": null,
"city": "Дмитров",
"street": "Зиновьева Street",
"house": "44",
"building": "30",
"flat": "54",
"office": "78",
"additionAddr": null,
"objectType": null,
"uniqueDeliveryPointIdentifier": "428793c1-824d-4246-9846-7b23948f3943",
"voltageLevel": "СН1",
"powerLevel": "Менее 670 кВт (150)",
"priceCategory": "I ЦК"
},
"id": 1
}
Результат - объект
{
"jsonrpc": "2.0",
"result": {
"id": 62,
"name": "Объект-763",
"account": "56844315",
"contractor": "Петров П.П.",
"addressSiteValue": null,
"city": "Дмитров",
"street": "Зиновьева Street",
"house": "44",
"building": "30",
"flat": "54",
"office": "78",
"additionAddr": null,
"objectType": null,
"uniqueDeliveryPointIdentifier": "428793c1-824d-4246-9846-7b23948f3943",
"voltageLevel": "СН1",
"powerLevel": "Менее 670 кВт (150)",
"priceCategory": "I ЦК"
},
"id": 1
}
Метод object.udpate позволяет обновить атрибуты объекта.
Параметры
Все параметры кроме идентификатора явдяются не обязательными.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | id объекта |
| name | string | название |
| city | null|string | город |
| street | null|string | улица |
| house | null|string | дом |
| building | null|string | корпус |
| flat | null|string | расположение |
| office | null|string | офис |
| additionAddr | null|string | дополнительная адресная информация |
| objectType | null|string | Тип объекта в схеме |
| uniqueDeliveryPointIdentifier | null|string | Уникальный идентификатор точки поставки |
| voltageLevel | null|string | Тарифное напряжение |
| powerLevel | null|string | Диапазон максимальной мощности |
| priceCategory | null|string | Ценовая категория |
Результат
Объект
Структура:
├── id int id [объекта](#f3693d378a) ├── name string название ├── account int лицевой счет ├── contractor null|int имя [контрагента](#4a9d299c2d) ├── addressSiteValue null|string расположение ├── city null|string город ├── street null|string улица ├── house null|string дом ├── building null|string корпус ├── flat null|string расположение ├── office null|string офис ├── additionAddr null|string дополнительная адресная информация ├── objectType null|string Тип объекта в схеме ├── uniqueDeliveryPointIdentifier null|string Уникальный идентификатор точки поставки ├── voltageLevel null|string Тарифное напряжение ├── powerLevel null|string Диапазон максимальной мощности ├── priceCategory null|string Ценовая категория
Счетчики
Методы meter
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| meter.list | object[] | Получение списка счетчиков |
| meter.sources | object[] | Получение списка источников для фильтрации счетчиков |
| meter.update | object | Обновление атрибутов счетчика |
Список счетчиков
Вызов метода
{
"jsonrpc": "2.0",
"method": "meter.list",
"params": {
"network": 123,
"group": ["object"],
"include": ["ascueState", "zones"],
"filter": [
{
"type": "site",
"value": 1
},
{
"type": "mounted",
"value": {
"type": "month",
"value": "2018-01"
}
}
]
},
"id": 1
}
Результат - массив групп со счетчиками
{
"jsonrpc": "2.0",
"result": [
{
"name": "Ввод в серверную",
"source": {
"type": "object",
"value": 13855
},
"values": [
{
"id": 13857,
"num": "015600",
"mark": "Нева МТ 324",
"remark": "Питание оргтехники",
"object": "Питание оргтехники",
"address": "Поморская, д. 22, оф. 31",
"location": null,
"type": "Электросчетчик",
"unit": "кВтч",
"electric": true,
"ktt": 1,
"ktn": 1,
"uniqueIdentifierOfInstallationLocation": "bb366228-022d-4496-b38d-f9836c920a1b",
"measures": [
"A+",
"A-",
"R+",
"R-"
],
"zones": [
{
"id": 232,
"name": "день"
},
{
"id": 233,
"name": "ночь"
}
],
"ascueState": ...
}
]
},
{
"name": "Кондиционирование и вентиляция",
"source": {
"type": "object",
"value": 13856
},
"values": [
{
"id": 13856,
"num": "003594",
"mark": "Нева МТ 123",
"remark": "Кондиционирование",
"object": "Кондиционирование и вентиляция",
"address": "Поморская, д. 22, оф. 31",
"location": null,
"type": "Электросчетчик",
"unit": "кВтч",
"electric": true,
"ktt": 1,
"ktn": 1,
"uniqueIdentifierOfInstallationLocation": "87b87378-4dc4-4c18-a33f-ccdd3389a0ce",
"measures": [
"A+",
"A-"
],
"zones": [
{
"id": 250,
"name": "Т1"
},
{
"id": 251,
"name": "Т2"
},
{
"id": 252,
"name": "Т3"
}
],
"ascueState": ...
}
]
}
],
"id": 1
}
Метод meter.list позволяет запросить список счетчиков в сети.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яЭнергетик |
| group | string[] | Названия источников для группировки счетчиков, порядок имеет значение, более общие группы имеет смысл ставить в приоритете |
| include | string[] | Дополнительная информация для каждого счетчика |
| filter | object[] | Фильтр счетчиков |
| sort | string | Порядок счетчиков в результате |
| page | object | Постраничный вывод |
Группировка
| Значение | Описание |
|---|---|
| "object" | Объект, к которому относится счетчик |
| "site" | Участок, к которому относится объект и его счетчики |
Дополнительная информация
| Значение | Описание |
|---|---|
| "zones" | Список названий тарифных зон ПУ |
| "ascueState" | Состояние АСКУЭ для счетчика |
Фильтры
Структура фильтра:
├── type string Тип фильтра или источника └── value зависит от типа Желаемое значение у счетчика
Типы фильтров:
| Тип | Возможные значения | Описание |
|---|---|---|
| "id" | int|int[] | Будут возвращены только счетчики с таким(и) id |
| "site" | int|int[] | Будут возвращены только счетчики с таким(и) id участка |
| "object" | int|int[] | Будут возвращены только счетчики с таким(и) id объекта |
| "mounted" | null|object | Будут возвращены только установленные (смонтированные на реальном объекте) на данный момент (null) либо на определенный период времени счетчики |
| "search" | null|string | Поиск по номеру счетчика, названию и адреса объекта |
Порядок счетчиков meter-sort
Параметр sort может принимать одно из трех значений: 'id', 'num' или 'object'.
В зависимости от того, какое значение указано, счетчики в результате вызова метода будут отсортированы по тому или иному признаку.
Значения параметра совпадают с названиями значений в структуре счетчика.
По умолчанию счетчики представлены в порядке возрастания числового идентификатора id.
Параметр sort принимают и другие методы, выводящие список счетчиков (например, показания счетчиков reading.all),
что позволяет использовать постраничный вывод в нескольких вызовах одновременно.
Результат
Если была запрошена группировка, то возвращается массив json-объектов с описанием групп.
Элементами группы являются либо также группы (если была запрошена группировка по нескольким источникам), либо описания счетчиков.
Среди групп может быть одна группа где к счетчику не привязан указанный источник (например, в такую группу попадут счетчики без участка).
В этом случае значения, которые отмечены в структуре группы как null, будут null.
Структура группы:
├── name string|null Название группы ├── source object Источник из которого сформирована группа (например, участок) │ ├── type string Тип источника (например, "site") │ └── value int|null id источника └── values object[] Массив с элементами группы
Структура описания счетчика:
├── id int id для использования в других вызовах ├── num string Серийный номер ПУ ├── mark string|null Марка ПУ (если указана) ├── remark string|null Примечание ├── object string Название объекта, к которому привязан счетчик ├── address string Краткий адрес объекта, к которому привязан счетчик ├── location string|null Расположение счетчика (если указано) ├── type string Название типа ПУ ├── unit string|null Единицы измерения показаний ├── electric boolean Является ли счетчик электросчетчиком ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков) ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков) ├── uniqueIdentifierOfInstallationLocation string|null Уникальный идентификатор места установки прибора учета ├── measures string[] Каналы измерения включенные на счетчике ├── zones object[]|null Тарифные зоны ПУ (только для электросчетчиков) │ ├── id int id зоны │ └── name string Название зоны └── ascueState object|null Состояние АСКУЭ (если запрошено) ├── enabled boolean АСКУЭ настроена и включена └── requests object Информация о запросах ├── readings object Показания │ ├── scheduled boolean Включено ли расписание опроса показаний │ └── lastSuccess дата со временем Последнее успешное показание └── powerProfile object Профиль мощности ├── scheduled boolean Включено ли расписание опроса профиля мощности └── lastSuccess дата со временем Последний успешный срез профиля мощности
Список источников
Вызов метода
{
"jsonrpc": "2.0",
"method": "meter.sources",
"params": {
"types": ["site"]
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"type": "site",
"values": [
{
"name": "Участок 1",
"value": 1,
"count": 3
},
{
"name": "Участок 2",
"value": 2,
"count": 4
},
{
"name": null,
"value": null,
"count": 2
}
]
}
],
"id": 1
}
Метод meter.sources.
При помощи этого метода можно получить список возможных значений для фильтрации списка счетчиков. Например, можно этим методом получить все объекты в сети и потом при помощи метода meter.list с фильтром получить все счетчики, соответствующие определенному объекту.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
Если параметр types не указан, то будут возвращены источники по всем типам.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яЭнергетик |
| types | string[] | Типы источников |
| filter | object[] | Фильтр источников |
Фильтры
Структура фильтра:
├── type string Тип фильтра └── value зависит от типа Желаемое значение
Типы фильтров:
| Тип | Возможные значения | Описание |
|---|---|---|
| "id" | int|int[] | Будут возвращены только объекты с таким(и) id |
Результат
Массив json-объектов с описанием источников.
Структура:
├── type string Тип источника
└── values object[] Возможные значения
├── name string|null Название источника
├── value int|null Значение для использования в фильтре
└── count int Количество счетчиков, соответствующих этому фильтру
Название источника и значение для фильтра могут быть null. Это означает что есть счетчики, для которых этот источник не указан. Например, счетчики, не относящиеся ни к одному участку.
Редактирование атрибутов счетчика
Вызов метода
{
"jsonrpc": "2.0",
"method": "meter.update",
"params": {
"id": 71,
"num": 1566788869,
"mark": "Нева МТ 324",
"remark": "Питание оргтехники",
"location": "оф 20",
"ktt": 10,
"ktn": 20,
"digit": 1,
"decimal": 4,
"dateSetup": "2022-01-06",
"dateCheck": "2024-07-01",
"dateCheckNext": "2025-07-01",
"uniqueDeliveryPointIdentifier": "ad1f762c-9629-437f-9f69-442d5f17791f"
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": {
"id": 71,
"num": 1566788869,
"mark": "Нева МТ 324",
"remark": "Питание оргтехники",
"location": "оф 20",
"ktt": 10,
"ktn": 20,
"digit": 1,
"decimal": 4,
"dateSetup": "2022-01-06",
"dateCheck": "2024-07-01",
"dateCheckNext": "2025-07-01",
"uniqueDeliveryPointIdentifier": "ad1f762c-9629-437f-9f69-442d5f17791f",
"measures": [
"A+"
],
"zones": null,
"ascueState": null
},
"id": 1
}
Метод meter.update.
При помощи этого метода можно обновить атрибуты счетчика.
Параметры
Все параметры кроме идентификатора явдяются не обязательными.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | id счетчика |
| num | string | Серийный номер ПУ |
| mark | string | Марка ПУ |
| remark | string | Примечание |
| location | string | Расположение счетчика |
| ktt | string | Коэффициент трансформации по току (только для электросчетчиков) |
| ktn | string | Коэффициент трансформации по напряжению (только для электросчетчиков) |
| digit | string | Разрядность |
| decimal | string | Кол-во знаков после запятой |
| dateSetup | string | Дата установки |
| dateCheck | string | Дата гос. поверки |
| dateCheckNext | string | Дата след. поверки |
| uniqueDeliveryPointIdentifier | string | Уникальный идентификатор места установки прибора учета |
Результат
json-объект с описанием счетчика.
Структура:
├── id int id для использования в других вызовах ├── num string Серийный номер ПУ ├── mark string|null Марка ПУ (если указана) ├── remark string|null Примечание ├── object string Название объекта, к которому привязан счетчик ├── address string Краткий адрес объекта, к которому привязан счетчик ├── location string|null Расположение счетчика (если указано) ├── type string Название типа ПУ ├── unit string|null Единицы измерения показаний ├── electric boolean Является ли счетчик электросчетчиком ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков) ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков) ├── uniqueIdentifierOfInstallationLocation string|null Уникальный идентификатор места установки прибора учета ├── measures string[] Каналы измерения включенные на счетчике ├── zones object[]|null Тарифные зоны ПУ (только для электросчетчиков) │ ├── id int id зоны │ └── name string Название зоны └── ascueState object|null Состояние АСКУЭ (если запрошено) ├── enabled boolean АСКУЭ настроена и включена └── requests object Информация о запросах ├── readings object Показания │ ├── scheduled boolean Включено ли расписание опроса показаний │ └── lastSuccess дата со временем Последнее успешное показание └── powerProfile object Профиль мощности ├── scheduled boolean Включено ли расписание опроса профиля мощности └── lastSuccess дата со временем Последний успешный срез профиля мощности
Показания
Методы reading
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| reading.list | object[] | Получение показаний для определенного счетчика |
| reading.consumption | object[] | Получение расходов для определенного счетчика |
| reading.all | object[] | Получение показаний для счетчиков сети |
| reading.allConsumption | object[] | Получение расхода по показаниям для счетчиков сети |
Список показаний
Вызов метода
{
"jsonrpc": "2.0",
"method": "reading.list",
"params": {
"meter": 13855,
"include": ["zones", "errors"],
"period": {
"type": "month",
"value": "2017-09"
},
"mode": "archive",
"sort": "asc"
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"date": "2017-09-01T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 18533.55,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 267,
"value": 13637.84,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 268,
"value": 4895.71,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
},
{
"date": "2017-09-02T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 18564.62,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 267,
"value": 13660.45,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 268,
"value": 4904.17,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
},
{
"date": "2017-09-03T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"error": {
"code": 20002,
"message": "Ошибка АСКУЭ. Этап: опрос счетчика. Счетчик не отвечает"
}
},
{
"date": "2017-09-04T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 18587.72,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 267,
"value": 13675.85,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 268,
"value": 4911.87,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
}
],
"id": 1
}
Метод reading.list.
Параметры
Параметр meter обязателен.
| Параметр | Тип данных | Описание |
|---|---|---|
| meter | int | id счетчика, можно получить из списка счетчиков |
| include | string[] | Дополнительная информация в результате |
| period | object | Период, без strict |
| mode | string | Режим поиска показаний |
| sort | string | Порядок показаний |
| page | object | Постраничный вывод |
Дополнительная информация
| Значение | Описание |
|---|---|
| "zones" | В показании будут присутствовать значения тарифных зон |
| "errors" | Вместе с показаниями будут выведены ошибки опроса |
Режим поиска показаний
| Значение | Описание |
|---|---|
| "all" | Все показания |
| "archive" | Только архивные показания (на 00:00 каждого дня или месяца - в зависимости от настроек счетчика) |
Порядок показаний
По умолчанию показания выводятся по убыванию даты.
| Значение | Описание |
|---|---|
| "asc" | По возрастанию даты |
| "desc" | По убыванию даты |
Результат
Массив json-объектов с описанием показаний и ошибок (если они были запрошены).
Показание:
├── date string Дата и время показания ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков) ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков) ├── value float Значение показания по прямой активной энергии (сумма значений тарифных зон, если счетчик многотарифный) ├── reverseValue float Значение показания по обратной активной энергии (сумма значений тарифных зон, если счетчик многотарифный), если на счетчике включен сбор показаний по данному виду энергии ├── reactiveValue float Значение показания по прямой реактивной энергии (сумма значений тарифных зон, если счетчик многотарифный), если на счетчике включен сбор показаний по данному виду энергии ├── reactiveReverseValue float Значение показания по обратной реактивной энергии (сумма значений тарифных зон, если счетчик многотарифный), если на счетчике включен сбор показаний по данному виду энергии └── zones object[]|null Значения тарифных зон показания (если они есть у счетчика и были запрошены) по всем видам энергии включенных на счетчике
Ошибка:
├── date string Дата и время попытки опроса показания └── error object ├── code int Код ошибки АСКУЭ. Не связан с кодами ошибок методов API и протокола. └── message string Сообщение об ошибке.
Список расходов
Вызов метода
{
"jsonrpc": "2.0",
"method": "reading.consumption",
"params": {
"meter": 13855,
"period": {
"type": "month",
"value": "2017-09"
},
"subperiod": "day",
"sort": "asc"
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"period": {
"type": "day",
"value": "2017-09-01"
},
"readings": null,
"consumption": 31.07,
"zones": null
},
{
"period": {
"type": "day",
"value": "2017-09-02"
},
"readings": null,
"consumption": 23.1,
"zones": null
},
{
"period": {
"type": "day",
"value": "2017-09-03"
},
"readings": null,
"consumption": 23.3,
"zones": null
}
],
"id": 1
}
Метод reading.consumption позволяет получить расходы счетчика по показаниям за каждый день, месяц или год.
Параметры
Параметр meter обязателен.
| Параметр | Тип данных | Описание |
|---|---|---|
| meter | int | id счетчика, можно получить из списка счетчиков |
| include | string[] | Дополнительная информация в результате |
| period | object | Период |
| subperiod | string | Тип периода (кроме "moment"), за который будут рассчитаны расходы в пределах периода period |
| sort | string | Порядок периодов с расходами |
| page | object | Постраничный вывод |
Дополнительная информация
| Значение | Описание |
|---|---|
| "zones" | Значения тарифных зон показаний |
| "readings" | Начальные и конечные показания, по которым был рассчитан каждый из расходов |
| "average" | Средние (расчетные) расходы, когда между двумя показаниями прошло большее время, чем указано в subperiod |
Порядок периодов с расходами
По умолчанию расходы выводятся по убыванию даты периода.
| Значение | Описание |
|---|---|
| "asc" | По возрастанию даты |
| "desc" | По убыванию даты |
Результат
Массив json-объектов с расходом, периодом за который этот расход посчитан и описанием показаний, если они были запрошены. В результате вызова метода некоторые периоды могут быть без расходов и без одного или обоих показаний.
Структура:
├── period object Период, за который был рассчитан расход │ ├── type string │ └── value string|int ├── consumption float|null Расход в кВт·ч ├── zones float[]|null Расход в кВт·ч по зонам, если они были запрошены └── readings object|null Первое и последнее показания, если они были запрошены ├── first object|null Начальное показание, если оно было найдено │ ├── date string │ ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков) │ ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков) │ ├── value float Значение показания по прямой активной энергии │ ├── reverseValue float Значение показания по обратной активной энергии, если на счетчике включен сбор показаний по данному виду энергии │ ├── reactiveValue float Значение показания по прямой реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии │ ├── reactiveReverseValue float Значение показания по обратной реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии │ └── zones object[]|null Значения тарифных зон показания (если они есть у счетчика и были запрошены) по всем видам энергии включенных на счетчике └── last object|null Конечное показание, если оно было найдено ├── date string ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков) ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков) ├── value float Значение показания по прямой активной энергии ├── reverseValue float Значение показания по обратной активной энергии, если на счетчике включен сбор показаний по данному виду энергии ├── reactiveValue float Значение показания по прямой реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии ├── reactiveReverseValue float Значение показания по обратной реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии └── zones object[]|null Значения тарифных зон показания (если они есть у счетчика и были запрошены) по всем видам энергии включенных на счетчике
Показания счетчиков
Вызов метода
{
"jsonrpc": "2.0",
"method": "reading.all",
"params": {
"meters": [13855, 18242],
"include": ["zones"],
"mode": "last",
"period": {
"type": "month",
"value": "2017-07",
"strict": true
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"meter": 13855,
"reading": {
"date": "2017-08-01T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 17644.77,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 267,
"value": 12999.96,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 268,
"value": 4644.81,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
}
},
{
"meter": 18242,
"reading": null
}
],
"id": 1
}
Метод reading.all возвращает показания конкретных либо всех счетчиков сети.
Для каждого счетчика будет найдено не более одного показания.
В ответе могут присутствовать счетчики без показания.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
Если конкретные счетчики не указаны в параметре meters, то будут возвращены все счетчики сети.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети |
| meters | int[] | id счетчиков |
| period | object | Период поиска показаний |
| position | string | С какой стороны искать показания в пределах периода |
| include | string[] | Дополнительная информация |
| sort | string | Порядок счетчиков в результате |
| pagination | object | Постраничный вывод |
Сторона показаний
| Значение | Описание |
|---|---|
| "first" | Искать первые показания периода |
| "last" | Искать последние показания периода |
Дополнительная информация
| Значение | Описание |
|---|---|
| "zones" | Значения тарифных зон показаний |
Результат
Массив json-объектов с id счетчика и описанием показания.
Структура:
├── meter int id счетчика └── reading object|null Показание, если оно было найдено ├── date string ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков) ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков) ├── value float Значение показания по прямой активной энергии ├── reverseValue float Значение показания по обратной активной энергии, если на счетчике включен сбор показаний по данному виду энергии ├── reactiveValue float Значение показания по прямой реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии ├── reactiveReverseValue float Значение показания по обратной реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии └── zones object[]|null Значения тарифных зон показания (если они есть у счетчика и были запрошены) по всем видам энергии включенных на счетчике
Расходы счетчиков
Вызов метода
{
"jsonrpc": "2.0",
"method": "reading.allConsumption",
"params": {
"meters": [13855, 18242],
"include": ["zones", "readings"],
"period": {
"type": "month",
"value": "2017-07",
"strict": true
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"meter": 13855,
"readings": {
"first": {
"date": "2017-09-01T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 18533.55,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 267,
"value": 13637.84,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 268,
"value": 4895.71,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
},
"last": {
"date": "2017-10-01T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 19340.84,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 267,
"value": 14223.27,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 268,
"value": 5117.57,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
}
},
"consumption": 807.29,
"zones": [
585.43,
221.86
]
},
{
"meter": 18242,
"readings": {
"first": {
"date": "2017-09-01T00:00:00+03:00",
"ktt": "1",
"ktn": "1",
"value": 123.45,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0,
"zones": [
{
"id": 69,
"value": 100.4,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
},
{
"id": 70,
"value": 23.05,
"reverseValue": 0,
"reactiveValue": 0,
"reactiveReverseValue": 0
}
]
},
"last": null
},
"consumption": null,
"zones": null
}
],
"id": 1
}
Метод reading.allConsumption возвращает расход счетчиков по соответствующим первым и последним показаниям периода.
Расход - это разность показаний, рассчитанная по определенному алгоритму и умноженная на КТТ и КТН счетчика.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
Если конкретные счетчики не указаны в параметре meters, то будут возвращены все счетчики сети.
Параметр period обязателен.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети |
| meters | int[] | id счетчиков |
| period | object | Период поиска показаний |
| include | string[] | Дополнительная информация |
| sort | string | Порядок счетчиков в результате |
| pagination | object | Постраничный вывод |
Дополнительная информация
| Значение | Описание |
|---|---|
| "zones" | Значения тарифных зон показаний |
| "readings" | Первое и последнее показание, из которых был рассчитан расход |
Результат
Массив json-объектов с id счетчика, расходом и описанием показаний, если они были запрошены.
Структура:
├── meter int id счетчика
├── consumption float|null Расход в кВт·ч
├── zones float[]|null Расход в кВт·ч по зонам, если они были запрошены
└── readings object|null Первое и последнее показания, если они были запрошены
├── first object|null Начальное показание, если оно было найдено
│ ├── date string
│ ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков)
│ ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков)
│ ├── value float Значение показания по прямой активной энергии
│ ├── reverseValue float Значение показания по обратной активной энергии, если на счетчике включен сбор показаний по данному виду энергии
│ ├── reactiveValue float Значение показания по прямой реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии
│ ├── reactiveReverseValue float Значение показания по обратной реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии
│ └── zones object[]|null Значения тарифных зон показания (если они есть у счетчика и были запрошены) по всем видам энергии включенных на счетчике
└── last object|null Конечное показание, если оно было найдено
├── date string
├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков)
├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков)
├── value float Значение показания по прямой активной энергии
├── reverseValue float Значение показания по обратной активной энергии, если на счетчике включен сбор показаний по данному виду энергии
├── reactiveValue float Значение показания по прямой реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии
├── reactiveReverseValue float Значение показания по обратной реактивной энергии, если на счетчике включен сбор показаний по данному виду энергии
└── zones object[]|null Значения тарифных зон показания (если они есть у счетчика и были запрошены) по всем видам энергии включенных на счетчике
Мгновенные значения
Методы currentValue
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| currentValue.list | object[] | Получение списка поддерживаемых мгновенных значений |
| currentValue.data | object | Перечисление мгновенных значений |
Список мгновенных значений счетчика
Вызов метода
{
"jsonrpc": "2.0",
"method": "currentValue.list",
"params": {
"meter": 13855
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"name": "voltage",
"symbol": "Uф",
"description": "Фазное напряжение",
"unit": "В"
},
{
"name": "current",
"symbol": "I",
"description": "Сила тока",
"unit": "А"
},
{
"name": "activePower",
"symbol": "P",
"description": "Активная мощность",
"unit": "кВт"
},
{
"name": "reactivePower",
"symbol": "Q",
"description": "Реактивная мощность",
"unit": "кВАр"
},
{
"name": "powerFactor",
"symbol": "cosφ",
"description": "Коэффициент мощности",
"unit": null
},
{
"name": "angle",
"symbol": "∠",
"description": "Угол между фазными напряжениями",
"unit": "°"
},
{
"name": "frequency",
"symbol": "F",
"description": "Частота сети",
"unit": "Гц"
}
],
"id": 2
}
Метод currentValue.list возвращает список мгновенных значений, поддерживаемых данным счетчиком.
Параметры
Параметр meter обязателен.
| Параметр | Тип данных | Описание |
|---|---|---|
| meter | int | id счетчика, можно получить из списка счетчиков |
Результат
Массив объектов с описанием поддерживаемых значений.
Структура объекта:
├── name string Название значений для метода currentValue.data ├── symbol string Краткое обозначение ├── description string Описание └── unit string|null Единицы измерения, если есть
Перечисление мгновенных значений
Вызов метода
{
"jsonrpc": "2.0",
"method": "currentValue.data",
"params": {
"meter": 13855,
"name": "voltage",
"period": {
"type": "hour",
"value": "2017-10-01T00:00:00+03:00"
},
"limit": 5
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": {
"headers": [
{
"type": "date",
"name": null
},
{
"type": "value",
"name": "A"
},
{
"type": "value",
"name": "B"
},
{
"type": "value",
"name": "C"
}
],
"data": [
[
"2017-10-01T00:00:12+03:00",
229.09,
230.32,
230.66
],
[
"2017-10-01T00:12:02+03:00",
228.95,
230.26,
230.83
],
[
"2017-10-01T00:24:03+03:00",
229.55,
230.04,
230.43
],
[
"2017-10-01T00:36:04+03:00",
230.8,
229.88,
230.59
],
[
"2017-10-01T00:48:05+03:00",
230.17,
230.14,
230.7
]
]
},
"id": 1
}
Метод currentValue.data возвращает мгновенные значения для построения графиков и отчетов.
Количество значений в результате можно ограничить, тогда если реальных значений больше, чем было запрошено,
то значение каждой точки будет вычислено как среднее из ближайших точек.
Вызов этого метода может вернуть ошибку 20104 (Unsupported feature), если счетчик не поддерживает запрашиваемые значения.
Например, такая ошибка будет возвращена при попытке запроса углов между фазными напряжениями у однофазного счетчика.
Параметры
Параметры meter, name и period обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| meter | int | id счетчика, можно получить из списка счетчиков |
| name | string | Название запрашиваемых значений |
| period | object | Период, без strict |
| limit | int | Ограничение количества точек |
| timestamp | boolean | Вернуть unix timestamp (временные метки) вместо строки с датой и временем |
Результат
Объект с заголовками и с массивом точек.
Структура:
├── headers object[] Заголовки, описывающие каждое значение в точке │ ├── type string Тип значения, 'date' - момент времени, 'value' - значение в точке │ └── name string|null Название значения, сюда записывается фаза └── data array[] Массив точек. Каждая точка - также массив, элементы которого соответствуют заголовкам
Фазы:
| Название | Описание | Пример |
|---|---|---|
null |
Фаза упускается (null) в заголовке, описывающем момент времени |
|
| 'one' | 'one' ставится, если счетчик однофазный, либо если значение не разбивается по фазам | Частота сети |
| 'sum' | 'sum' ставится для значений по сумме всех трех фаз | Активная мощность по сумме фаз |
| 'A' | Фаза A | Напряжение по фазе A |
| 'B' | Фаза B | Напряжение по фазе B |
| 'C' | Фаза C | Напряжение по фазе C |
| 'AB' | Фазы A и B | Угол между фазными напряжениями фаз A и B |
| 'BC' | Фазы B и C | Угол между фазными напряжениями фаз B и C |
| 'CA' | Фазы C и A | Угол между фазными напряжениями фаз C и A |
| 'AC' | Фазы A и C | Угол между фазными напряжениями фаз A и C |
Профиль мощности
Методы powerProfile
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| powerProfile.data | object | Перечисление значений профиля мощности |
Значения профиля мощности
Вызов метода
{
"jsonrpc": "2.0",
"method": "powerProfile.data",
"params": {
"meter": 13859,
"include": ["reactive"],
"period": {
"type": "day",
"value": "2017-10-01"
},
"group": 3600
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": {
"headers": [
{
"type": "date",
"name": null
},
{
"type": "value",
"name": "activePower"
},
{
"type": "value",
"name": "reactivePower"
}
],
"group": 3600,
"data": [
[
"2017-10-01T01:00:00+03:00",
1.98,
0.36
],
[
"2017-10-01T02:00:00+03:00",
3.62,
1.06
],
[
"2017-10-01T03:00:00+03:00",
2.58,
0.52
],
[
"2017-10-01T04:00:00+03:00",
1.52,
0.02
],
...
[
"2017-10-02T00:00:00+03:00",
0.88,
0
]
]
},
"id": 1
}
Метод powerProfile.data возвращает значения профиля мощности счетчика для построения графиков и отчетов.
Чтобы получить из мощности (кВт) энергию (кВт·ч), достаточно поделить значение профиля мощности на 3600 и умножить на период интегрирования в секундах.
Параметры
Параметры meter и period обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| meter | int | id счетчика, можно получить из списка счетчиков |
| period | object | Период, без strict |
| group | int | Желаемый период интегрирования профиля мощности |
| include | string[] | Дополнительная информация |
| timestamp | boolean | Вернуть unix timestamp (временные метки) вместо строки с датой и временем |
Период интегрирования
Период интегрирования профиля мощности указывается в секундах. Он должен иметь значение от 1 до 3600 и 3600 должно делиться на него без остатка. Обычно у счетчика настроен период интегрирования 3600, 1800 или 900 секунд.
Используемый период интегрирования возвращается в ответе.
- Если желаемый период интегрирования больше фактического, то значения в ответе будут приведены к желаемому периоду интегрирования.
- Если желаемый период интегрирования больше фактического, но он несовместим с фактическим (что очень маловероятно), то будет возвращена ошибка
20104. - Если желаемый период интегрирования оказался меньше фактического, то будет использоваться фактический период интегрирования.
- Если желаемый период интегрирования не указан, то будет использоваться фактический период интегрирования.
Дополнительная информация
| Значение | Описание |
|---|---|
| "reactive" | Включить в ответ реактивную мощность |
| "reverse" | Включить в ответ обратную мощность |
Реактивные и обратные мощности поддерживаются не всеми счетчиками.
Если данный счетчик их не поддерживает, то вместо соответствующих значений будет null.
На данный момент нет возможности заранее определить какие мощности поддерживаются счетчиком.
Результат
Объект с заголовками и массивом точек.
Момент времени точки соответствует окончанию периода интегрирования значения. Например, при периоде интегрирования 3600 сек. "2018-01-01T01:00:00+03:00" соответствует мощности за 00:00 - 01:00.
Часть точек может отсутствовать, если профиль мощности отсутствует (не был опрошен) в это время.
Структура:
├── headers object[] Заголовки, описывающие каждое значение в точке │ ├── type string Тип значения, 'date' - момент времени, 'value' - значение в точке │ └── name string|null Название значения ├── group int|null Период интегрирования либо null, если значений нет и желаемый период не указан └── data array[] Массив точек. Каждая точка - также массив, элементы которого соответствуют заголовкам
Значения
| Название | Дополнительная информация | Описание |
|---|---|---|
null |
не применимо | Название упускается (null) в заголовке, описывающем момент времени |
| activePower | возвращается всегда | Активная мощность |
| reactivePower | "reactive" | Реактивная мощность |
| activeReversePower | "reverse" | Активная обратная мощность |
| reactiveReversePower | "reactive" и "reverse" | Реактивная обратная мощность |
Интервальный учет
Методы
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| energyProfile.object | object[] | Получение интервального учета по объекту |
| energyProfile.meter | object[] | Получение интервального учета по счетчику |
Получение интервального учета по объекту
Вызов метода
{
"jsonrpc": "2.0",
"method": "energyProfile.object",
"params": {
"object": 13855,
"period": {
"type": "month",
"value": "2023-08-01"
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
...,
{
"object": {
"id": 13855,
"name": "Ввод в серверную",
"address": "Архангельск, Поморская, д. 22, оф. 31",
},
"values": {
"headers": [
{
"type": "date",
"name": null
},
{
"type": "value",
"name": "energyValue"
},
{
"type": "value",
"name": "energyReverseValue"
},
{
"type": "value",
"name": "energyReactiveValue"
},
{
"type": "value",
"name": "energyReactiveReverseValue"
}
],
"data": [
[
"2023-08-01T01:00:00+03:00",
42.595,
10.783000000000001,
1.728,
1.864
],
[
"2023-08-01T02:00:00+03:00",
48.892999999999994,
10.120000000000001,
2.786,
4.185
],
[
"2023-08-01T03:00:00+03:00",
45.248000000000005,
11.239999999999998,
2.0780000000000003,
1.48
],
...
[
"2023-08-30T23:00:00+03:00",
46.003,
10.256,
4.087000000000001,
2.018
],
[
"2023-08-31T00:00:00+03:00",
45.650999999999996,
10.240000000000002,
1.8840000000000001,
1.1199999999999999
]
]
},
},
...
],
"id": 1
}
Метод energyProfile.object.
Используется для получения расчитаного интеврального учета.
Параметры
Параметры object и period обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| object | int | id объекта на яэнергетик |
| period | object | описание периода, можно использовать типы периода "month" и "day" |
| applyLosses | boolean | учитывать потери ПУ |
Результат
Возвращается массив json-объектов со значениями срезов профиля энергии.
Структура описания объекта:
├── month string месяц, за который произведен расчет ├── object object описание объекта. ├── id int id объекта на яэнергетик ├── name string название объекта └── address string адрес └── values object срез профиля энергии для объекта за период
Получение интервального учета по счетчику
Вызов метода
{
"jsonrpc": "2.0",
"method": "energyProfile.meter",
"params": {
"meter": 45855,
"period": {
"type": "month",
"value": "2023-08-01"
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
...,
{
"meter": {
"id": 45855,
"num": "1016107294",
"mark": "Меркурий 203",
},
"values": {
"headers": [
{
"type": "date",
"name": null
},
{
"type": "value",
"name": "energyValue"
},
{
"type": "value",
"name": "energyReverseValue"
},
{
"type": "value",
"name": "energyReactiveValue"
},
{
"type": "value",
"name": "energyReactiveReverseValue"
}
],
"data": [
[
"2023-08-01T01:00:00+03:00",
42.595,
10.783000000000001,
1.728,
1.864
],
[
"2023-08-01T02:00:00+03:00",
48.892999999999994,
10.120000000000001,
2.786,
4.185
],
[
"2023-08-01T03:00:00+03:00",
45.248000000000005,
11.239999999999998,
2.0780000000000003,
1.48
],
...
[
"2023-08-30T23:00:00+03:00",
46.003,
10.256,
4.087000000000001,
2.018
],
[
"2023-08-31T00:00:00+03:00",
45.650999999999996,
10.240000000000002,
1.8840000000000001,
1.1199999999999999
]
]
},
},
...
],
"id": 1
}
Метод energyProfile.meter.
Используется для получения расчитаного интеврального учета .
Параметры
Параметры meter и period обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| meter | int | id объекта на яэнергетик |
| period | object | описание периода, можно использовать типы периода "month" и "day" |
| applyLosses | boolean | учитывать потери ПУ |
Результат
Возвращается массив json-объектов со значениями срезов профиля энергии.
Структура описания объекта:
├── month string месяц, за который произведен расчет ├── meter object[]|null описание счетчиков (приборов учета) объекта, если они были запрошены ├── id int id счетчика на яэнергетик ├── num string серийный номер прибора учета └── mark string|null марка прибора учета └── values object срез профиля энергии для счетчика за период
Ценовые категории
Методы
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| price.contracts | object[] | Получение информации о договорах с энергокомпаниями в сети |
| price.objects | object[] | Получение информации по ЦК об объектах в сети |
| price.listObjects | object[] | Получение расчетов по ЦК для объектов за определенный месяц |
| price.listPeriods | object[] | Получение расчетов по ЦК для определенного объекта за период |
Информация о договорах с энергокомпаниями
Вызов метода
{
"jsonrpc": "2.0",
"method": "price.contracts",
"params": {
"active": true
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"id": 267,
"active": true,
"num": "1-602203",
"type": 2,
"powerCompany": {
"name": "ПАО \"Архэнергосбыт\"",
"inn": null
},
"company": {
"name": "ООО \"Эртрейд\"",
"inn": "2903008195"
}
},
{
"id": 268,
"active": true,
"num": "123321",
"type": 4,
"powerCompany": {
"name": "ООО \"АСЭП\"",
"inn": null
},
"company": {
"name": "ООО \"Эртрейд\"",
"inn": "2903008195"
}
},
...
],
"id": 1
}
Метод price.contracts.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яЭнергетик |
| active | boolean | Запрос только активных, только неактивных либо всех договоров (если параметр не указан либо null) |
Результат
Возвращается массив json-объектов с описанием договоров с энергокомпаниями.
Структура описания договора:
├── id int id договора на яэнергетик ├── active boolean активен ли договор ├── num string|null номер договора, если есть ├── type int id типа договора ├── powerCompany object описание энергокомпании (на данный момент в системе отсутствуют ИНН) └── company object описание вашей компании, с которой заключен этот договор
Типы договоров:
| id | Описание |
|---|---|
| 1 | Договор энергоснабжения (с гарантирующим поставщиком) |
| 2 | Договор купли-продажи (с гарантирующим поставщиком) |
| 3 | АРБП - акт разграничения балансовой принадлежности (с сетевой организацией) |
| 4 | Договор передачи (с сетевой организацией) |
Информация об объектах
Вызов метода
{
"jsonrpc": "2.0",
"method": "price.objects",
"params": {
"active": true,
"include": ["parameters", "meters"]
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"id": 13855,
"name": "Ввод в серверную",
"address": "Архангельск, Поморская, д. 22, оф. 31",
"active": true,
"parameters": {
"primaryContract": 267,
"secondaryContract": 268,
"priceCategory": 5,
"secondaryPriceCategory": -2,
"voltageLevel": 1,
"powerLevel": 1,
"basePowerCompany": null,
"basePriceCategory": 1,
"baseVoltageLevel": null,
"basePowerLevel": null
},
"meters": [
{
"id": 13855,
"num": "015610",
"mark": "Нева МТ 324",
"transit": false,
"parameters": {
"lossShortCircuit": 1,
"lossIdle": 10,
"baseLossShortCircuit": null,
"baseLossIdle": null
}
}
]
},
{
"id": 13859,
"name": "Ввод №1",
"address": "Архангельск, Поморская, д. 22, оф. 31",
"active": true,
"parameters": {
"primaryContract": 267,
"secondaryContract": 268,
"priceCategory": 4,
"secondaryPriceCategory": -2,
"voltageLevel": 1,
"powerLevel": 1,
"basePowerCompany": null,
"basePriceCategory": 2,
"baseVoltageLevel": null,
"basePowerLevel": null
},
"meters": [
{
"id": 13859,
"num": "09338257",
"mark": "Меркурий 230ART-03PQRSIDN",
"transit": false,
"parameters": {
"lossShortCircuit": 2,
"lossIdle": null,
"baseLossShortCircuit": null,
"baseLossIdle": null
}
}
]
},
...
],
"id": 1
}
Метод price.objects.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яэнергетик |
| contract | int | id договора на яэнергетик |
| active | boolean | Запрос только активных в ЦК, только неактивных в ЦК либо всех объектов (если параметр не указан либо null) |
| include | string[] | Дополнительная информация |
| page | object | Постраничный вывод |
Дополнительная информация (include):
| Значение | Описание |
|---|---|
| "parameters" | вернуть параметры ЦК объекта и счетчиков |
| "meters" | вернуть счетчики (приборы учета) для каждого объекта |
Результат
Возвращается массив json-объектов с описанием объектов сети.
Структура описания объекта:
├── id int id объекта на яэнергетик ├── name string название объекта ├── address string адрес ├── active boolean активен ли объект в ЦК ├── parameters object|null параметры ЦК объекта, если они были запрошены │ ├── primaryContract int|null id договора с гарантирующим поставщиком на яэнергетик │ ├── secondaryContract int|null id договора с сетевой организацией на яэнергетик │ ├── priceCategory int|null id ценовой категории на яэнергетик ├── secondaryPriceCategory int|null id ценовой категории договора на передачу на яэнергетик │ ├── voltageLevel int|null id уровня напряжения на яэнергетик │ ├── powerLevel int|null id диапазона максимальной мощности на яэнергетик │ ├── basePowerCompany object|null описание энергокомпании, базис* │ ├── basePriceCategory int|null id ценовой категории на яэнергетик, базис* │ ├── baseVoltageLevel int|null id уровня напряжения на яэнергетик, базис* │ └── basePowerLevel int|null id диапазона максимальной мощности на яэнергетик, базис* └── meters object[]|null описание счетчиков (приборов учета) объекта, если они были запрошены ├── id int id счетчика на яэнергетик ├── num string серийный номер прибора учета ├── mark string|null марка прибора учета ├── transit boolean является ли счетчик транзитным потребителем (т.е. не принадлежащим к этому объекту, но запитанным через него) └── parameters object|null параметры ЦК счетчика, если они были запрошены ├── lossShortCircuit float|null потери короткого замыкания в процентах ├── lossIdle float|null потери холостого хода в кВтч ├── baseLossShortCircuit float|null потери короткого замыкания в процентах, базис* └── baseLossIdle float|null потери холостого хода в кВтч, базис*
* базис - параметр ЦК объекта или прибора учета, который был у них до перехода на более выгодную ценовую категорию.
Нужен для расчета экономии. Если такой параметр имеет значение null, то это значит что он идентичен фактическому параметру (не изменился).
Ценовые категории:
| id | Категория | Описание |
|---|---|---|
| -2 | Двухставочный тариф | Используется для расчетов по договору передачи, соответствует IV и VI ЦК |
| -1 | Одноставочный тариф | Используется для расчетов по договору передачи, соответствует I-III и V ЦК |
| 1 | I ЦК | Первая ценовая категория |
| 2 | II ЦК (2 зоны) | Вторая ценовая категория, 2 зоны (день, ночь) |
| 3 | II ЦК (3 зоны) | Вторая ценовая категория, 3 зоны (полупик, пик, ночь) |
| 4 | III ЦК | Третья ценовая категория |
| 5 | IV ЦК | Четвертая ценовая категория |
| 6 | V ЦК | Пятая ценовая категория |
| 7 | VI ЦК | Шестая ценовая категория |
Уровни напряжения:
| id | Уровень |
|---|---|
| 1 | НН |
| 2 | СН-1 |
| 3 | СН-2 |
| 4 | ВН |
| 5 | ГН (не используется в расчетах) |
Диапазоны максимальной мощности:
| id | Диапазон | Диапазон, с июля 2018 |
|---|---|---|
| 1 | Менее 150 кВт | Менее 670 кВт |
| 2 | От 150 кВт до 670 кВт | Менее 670 кВт |
| 3 | От 670 кВт до 10 МВт | От 670 кВт до 10 МВт |
| 4 | Свыше 10 МВт | Свыше 10 МВт |
Расчеты по объектам
Вызов метода
{
"jsonrpc": "2.0",
"method": "price.listObjects",
"params": {
"month": "2017-05",
"minimalLevel": 1,
"include": ["parameters", "meters", "categories"]
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"month": "2017-05",
"object": {
"id": 13855,
"name": "Ввод в серверную",
"address": "Архангельск, Поморская, д. 22, оф. 31",
"active": true,
"parameters": {
"primaryContract": 267,
"secondaryContract": 268,
"priceCategory": 5,
"secondaryPriceCategory": -2,
"voltageLevel": 1,
"powerLevel": 1,
"basePowerCompany": null,
"basePriceCategory": 1,
"baseVoltageLevel": null,
"basePowerLevel": null
},
"meters": [
{
"id": 13855,
"num": "015610",
"mark": "Нева МТ 324",
"transit": false,
"parameters": {
"lossShortCircuit": 1,
"lossIdle": 10,
"baseLossShortCircuit": null,
"baseLossIdle": null
},
"readings": {
"first": {
"T1": 11229.86,
"T2": 3970.66
},
"last": {
"T1": 11245.86,
"T2": 3977.46
}
}
}
]
},
"values": {
"energy": 773.1914,
"lossShortCircuit": 0,
"lossIdle": 0,
"energyTotal": 773.1914,
"energy2Day": 556.3593,
"energy2Night": 216.8321,
"energy3HalfPeak": 280.2951,
"energy3Peak": 276.0642,
"energy3Night": 216.8321,
"powerTransport": 1.5589,
"powerGenerator": 1.5734,
"plan": 773.1914,
"planOverFact": 0,
"factOverPlan": 0,
"planFactDiffSum": 0
},
"primaryContract": {
"level": 3,
"categories": [
{
"category": 1,
"cost": 1686.7655,
"valueCosts": {
"energy": 1686.7655
}
},
{
"category": 2,
"cost": 1733.0234,
"valueCosts": {
"energy2Day": 1383.2459,
"energy2Night": 349.7775
}
},
{
"category": 3,
"cost": 1744.1148,
"valueCosts": {
"energy3HalfPeak": 632.7228,
"energy3Peak": 761.6144,
"energy3Night": 349.7775
}
},
{
"category": 4,
"cost": 1895.8383,
"valueCosts": {
"energy": 1298.4584,
"powerGenerator": 597.3799
}
},
{
"category": 5,
"cost": 1895.8383,
"valueCosts": {
"energy": 1298.4584,
"powerGenerator": 597.3799
}
},
{
"category": 6,
"cost": 1902.7334,
"valueCosts": {
"energy": 1305.3535,
"powerGenerator": 597.3799
}
},
{
"category": 7,
"cost": 1902.7334,
"valueCosts": {
"energy": 1305.3535,
"powerGenerator": 597.3799
}
}
],
"cost": 1895.8383,
"baseCost": 1686.7655,
"valueCosts": {
"energy": 1298.4584,
"powerGenerator": 597.3799
}
},
"secondaryContract": {
"level": 3,
"categories": [
{
"category": -1,
"cost": 2981.8358,
"valueCosts": {
"energy": 2981.8358
}
},
{
"category": -2,
"cost": 1522.9815,
"valueCosts": {
"energy": 518.4016,
"powerTransport": 1004.5798
}
}
],
"cost": 1522.9815,
"baseCost": 2981.8358,
"valueCosts": {
"energy": 518.4016,
"powerTransport": 1004.5798
}
}
},
...
],
"id": 1
}
Метод price.listObjects.
Используется для получения сохраненных в системе расчетов по ЦК за определенный месяц для объектов сети.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
Параметры month и minimalLevel обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яэнергетик |
| month | string | месяц, за который запрашиваются данные |
| minimalLevel | int | минимальный уровень расчетов (расчет производится поэтапно и может остановиться на одном из этапов из-за ошибки) |
| filter | object | фильтр объектов по id на яэнергетик либо по id договора на яэнергетик |
| include | string[] | дополнительная информация |
| forcePrimarySum | boolean | сложить все стоимости в договор с гарантирующим поставщиком, как если бы это был договор энергоснабжения |
| page | object | Постраничный вывод |
Уровни расчета:
| Уровень | Описание |
|---|---|
| 1 | произведен расчет физических параметров |
| 2 | произведен расчет стоимости по текущим параметрам ЦК объекта |
| 3 | произведен расчет по базису (для вычисления экономии) |
Дополнительная информация (include):
| Значение | Описание |
|---|---|
| "parameters" | вернуть параметры ЦК объекта и счетчиков |
| "meters" | вернуть счетчики (приборы учета) для каждого объекта |
| "categories" | подробный расчет стоимости по всем ценовым категориям |
Результат
Массив json-объектов со значениями физических параметров и стоимостью.
Структура описания:
├── month string месяц, за который произведен расчет ├── object object описание объекта идентичное возвращаемому методом price.objects. За исключением того, что для счетчиков указаны показания на начало и конец расчетного периода (readings) и указана текущая ЦК по договору передачи (secondaryPriceCategory). ├── values object значения физических параметров ├── primaryContract object стоимость ЦК по договору с гарантирующим поставщиком │ ├── level int уровень расчета │ ├── categories object[]|null стоимости по каждой ценовой категории (если запрошено и уровень расчета не ниже 2) │ │ ├── category int id категории на яэнергетик (от 1 до 7) │ │ ├── cost float стоимость │ │ └── valueCosts object стоимости для физических параметров │ ├── cost float|null стоимость по текущей ценовой категории (если уровень расчета не ниже 2) │ ├── baseCost float|null базис, стоимость по старой ценовой категории (если уровень расчета не ниже 3) └── valueCosts object стоимости для физических параметров по текущей ценовой категории (если уровень расчета не ниже 2) └── secondaryContract object|null стоимость ЦК по договору передачи (с сетевой организацией) ├── level int уровень расчета ├── categories object[]|null стоимости по каждому тарифу (если запрошено и уровень расчета не ниже 2) │ ├── category int id тарифа на яэнергетик (от -2 до -1) │ ├── cost float стоимость │ └── valueCosts object стоимости для физических параметров ├── cost float|null стоимость по текущей ценовой категории (если уровень расчета не ниже 2) ├── baseCost float|null базис, стоимость по старой ценовой категории (если уровень расчета не ниже 3) └── valueCosts object стоимости для физических параметров по текущей ценовой категории (если уровень расчета не ниже 2)
Физические параметры:
| Параметр | Обозначение | Единицы измерения | Описание |
|---|---|---|---|
| energy | W | кВтч | Расход за месяц без учета потерь |
| lossShortCircuit | W | кВтч | Потери короткого замыкания |
| lossIdle | W | кВтч | Потери холостого хода |
| lossW2 | W | квТч | Потери W2 |
| energyTotal | W | кВтч | Расход за месяц с учетом потерь |
| energy2Day | Wд | кВтч | Расход по 2 зонам, день |
| energy2Night | Wн | кВтч | Расход по 2 зонам, ночь |
| energy3Peak | Wпп | кВтч | Расход по 3 зонам, полупик |
| energy3HalfPeak | Wп | кВтч | Расход по 3 зонам, пик |
| energy3Night | Wн | кВтч | Расход по 3 зонам, ночь |
| powerTransport | Pтр | кВт | Генераторная мощность |
| powerGenerator | Pгн | кВт | Транспортная мощность |
| plan | ∑Wп | кВтч | Сумма плановых часов |
| planOverFact | ΔWп-ф | кВтч | Превышение план над факт |
| factOverPlan | ΔWф-п | кВтч | Превышение факт над план |
| planFactDiffSum | ∑|ΔWф-п| | кВтч | Сумма абсолютных значений разностей фактических и плановых объемов |
Расчеты за период
Вызов метода
{
"jsonrpc": "2.0",
"method": "price.listPeriods",
"params": {
"object": 13855,
"minimalLevel": 1,
"period": {
"type": "year",
"value": 2017
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
...,
{
"month": "2017-05",
"object": {
"id": 13855,
"name": "Ввод в серверную",
"address": "Архангельск, Поморская, д. 22, оф. 31",
"active": true,
"parameters": null,
"meters": null
},
"values": {
"energy": 773.1914,
"energy2Day": 556.3593,
"energy2Night": 216.8321,
"energy3HalfPeak": 280.2951,
"energy3Peak": 276.0642,
"energy3Night": 216.8321,
"powerTransport": 1.5589,
"powerGenerator": 1.5734,
"plan": 773.1914,
"planOverFact": 0,
"factOverPlan": 0,
"planFactDiffSum": 0
},
"primaryContract": {
"level": 3,
"categories": null,
"cost": 1895.8383,
"baseCost": 1686.7655
},
"secondaryContract": {
"level": 3,
"categories": null,
"cost": 1522.9815,
"baseCost": 2981.8358
}
},
...
],
"id": 1
}
Метод price.listPeriods.
Используется для получения сохраненных в системе расчетов по ЦК за период для определенного объекта.
Если на указанный период в системе расчетов не найдено - будет возвращена только информация по объекту.
Параметры
Параметры object и minimalLevel обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| object | int | id объекта на яэнергетик |
| period | object | описание периода, можно использовать типы периода "year" и "month" |
| minimalLevel | int | минимальный уровень расчетов (расчет производится поэтапно и может остановиться на одном из этапов из-за ошибки) |
| include | string[] | дополнительная информация |
| forcePrimarySum | boolean | сложить все стоимости в договор с гарантирующим поставщиком, как если бы это был договор энергоснабжения |
| page | object | Постраничный вывод |
Минимальные уровни и дополнительная информация описана в методе price.listObjects
Результат
Структура данных в результате работы метода идентична возвращаемой методом price.listObjects.
Потребление
Методы
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| consumption.object | object[] | Получение расхода электроэнергии по объекту |
Расход электроэнергии по объекту
Вызов метода
{
"jsonrpc": "2.0",
"method": "consumption.object",
"params": {
"object": 13855,
"minimalLevel": 1,
"period": {
"type": "year",
"value": 2020
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
...,
{
"month": "2020-01",
"object": {
"id": 13855,
"name": "Ввод в серверную",
"address": "Архангельск, Поморская, д. 22, оф. 31",
"meters": null
},
"values": {
"energy": 95221,
"lossShortCircuit": 0,
"lossIdle": 0,
"lossW2": 0,
"energyTotal": 95221,
"energy2Day": 68046,
"energy2Night": 27175,
"energy3HalfPeak": 32962,
"energy3Peak": 35084,
"energy3Night": 27175,
"powerTransport": 209,
"powerGenerator": 198
}
},
...
],
"id": 1
}
Метод consumption.object.
Используется для получения сохраненной информации о расходе электроэнергии определенного объекта.
Если на указанный период в системе расчетов не найдено - будет возвращена только информация по объекту.
Параметры
Параметры object и minimalLevel обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| object | int | id объекта на яэнергетик |
| period | object | описание периода, можно использовать типы периода "year" и "month" |
| minimalLevel | int | минимальный уровень расчетов (расчет производится поэтапно и может остановиться на одном из этапов из-за ошибки) |
| include | string[] | дополнительная информация |
Уровни расчета:
| Уровень | Описание |
|---|---|
| 1 | произведен расчет физических параметров |
| 2 | произведен расчет стоимости по текущим параметрам ЦК объекта |
| 3 | произведен расчет по базису (для вычисления экономии) |
Дополнительная информация (include):
| Значение | Описание |
|---|---|
| "meters" | вернуть счетчики (приборы учета) |
Результат
Возвращается массив json-объектов со значениями потребления и физических параметров.
Структура описания объекта:
├── month string месяц, за который произведен расчет ├── object object описание объекта. ├── id int id объекта на яэнергетик ├── name string название объекта ├── address string адрес └── meters object[]|null описание счетчиков (приборов учета) объекта, если они были запрошены ├── id int id счетчика на яэнергетик ├── num string серийный номер прибора учета ├── mark string|null марка прибора учета ├── transit boolean является ли счетчик транзитным потребителем (т.е. не принадлежащим к этому объекту, но запитанным через него) ├── parameters object|null потери ├── lossShortCircuit float|null потери короткого замыкания в процентах ├── lossIdle float|null потери холостого хода в кВтч └── lossW2 float|null потери W2, рассчитываемые как процент от потребления в квадрате ├── readings object значения показаний └── values object значения физических параметров └── values object значения физических параметров
Текущее потребление
Методы
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| currentConsumption.object | object[] | Получение текущего расхода электроэнергии по объекту |
Текущий расход электроэнергии по объекту
Вызов метода
{
"jsonrpc": "2.0",
"method": "consumption.object",
"params": {
"object": 13855,
"period": {
"type": "month",
"value": "08-2023"
}
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
...,
{
"object": {
"id": "251",
"name": "Объект-587",
"address": "Лотошино, Власов Street, д. 26, к. 47, кв. 29, оф. 69",
"meters": [
{
"id": 252,
"num": "1016107294",
"mark": null,
"readings": {
"first": {
"269": {
"zoneName": "T1",
"value": 614.0692
},
"270": {
"zoneName": "T2",
"value": 614.0692
},
"271": {
"zoneName": "T3",
"value": 614.0692
},
"272": {
"zoneName": "T4",
"value": 614.0692
},
"273": {
"zoneName": "T5",
"value": 614.0692
}
},
"last": {
"269": {
"zoneName": "T1",
"value": 1949.9084
},
"270": {
"zoneName": "T2",
"value": 1949.9084
},
"271": {
"zoneName": "T3",
"value": 1949.9084
},
"272": {
"zoneName": "T4",
"value": 1949.9084
},
"273": {
"zoneName": "T5",
"value": 1949.9084
}
}
},
"parameters": {
"lossShortCircuit": 0.066,
"lossIdle": 2.9,
"lossW2": null
},
"values": {
"energy": 13204,
"powerTransport": 184
}
},
{
"id": 256,
"num": "1307832690",
"mark": null,
"readings": {
"first": {
"289": {
"zoneName": "T1",
"value": 624.7462
},
"290": {
"zoneName": "T2",
"value": 624.7462
},
"291": {
"zoneName": "T3",
"value": 624.7462
},
"292": {
"zoneName": "T4",
"value": 624.7462
},
"293": {
"zoneName": "T5",
"value": 624.7462
}
},
"last": {
"289": {
"zoneName": "T1",
"value": 1959.7874
},
"290": {
"zoneName": "T2",
"value": 1959.7874
},
"291": {
"zoneName": "T3",
"value": 1959.7874
},
"292": {
"zoneName": "T4",
"value": 1959.7874
},
"293": {
"zoneName": "T5",
"value": 1959.7874
}
}
},
"parameters": {
"lossShortCircuit": 0.092,
"lossIdle": 1.5,
"lossW2": null
},
"values": {
"energy": 13204,
"powerTransport": 184
}
}
]
},
"values": {
"lossShortCircuit": 0.066,
"lossIdle": 2.9,
"lossW2": null,
"energy": 26709,
"powerTransport": 267
}
},
...
],
"id": 1
}
Метод currentConsumption.object.
Используется для получения текущей информации о расходе электроэнергии определенного объекта.
Параметры
Параметры object и period обязательны.
| Параметр | Тип данных | Описание |
|---|---|---|
| object | int | id объекта на яэнергетик |
| period | object | описание периода, можно использовать тип "month" |
| applyLosses | boolean | учитывать потери ПУ |
| include | string[] | дополнительная информация |
Дополнительная информация (include):
| Значение | Описание |
|---|---|
| "meters" | вернуть счетчики (приборы учета) |
Результат
Возвращается массив json-объектов со значениями потребления и физических параметров.
Структура описания объекта:
├── object object описание объекта.
├── id int id объекта на яэнергетик
├── name string название объекта
├── address string адрес
└── meters object[]|null описание счетчиков (приборов учета) объекта, если они были запрошены
├── id int id счетчика на яэнергетик
├── num string серийный номер прибора учета
├── mark string|null марка прибора учета
├── parameters object|null потери
├── lossShortCircuit float|null потери короткого замыкания в процентах
├── lossIdle float|null потери холостого хода в кВтч
└── lossW2 float|null потери W2, рассчитываемые как процент от потребления в квадрате
├── readings object значения показаний
└── values object значения физических параметров для счетчика
└── values object значения физических параметров
Импорт
Методы import
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| import.objects | int[] | Импорт объектов |
| import.counters | int[] | Импорт счетчиков |
| import.contractors | int[] | Импорт контрагентов |
Импорт объектов
Вызов метода
{
"jsonrpc": "2.0",
"method": "import.objects",
"params": {
"network": 1,
"objects": [
{
"name": "Объект 1",
"account": 123456,
"contractor": 5,
"addressSiteValue": "Расположение",
"region": "Область",
"city": "Город",
"street": "Улица",
"house": "Дом",
"building": "Корпус",
"flat": "Квартира",
"office": "Офис",
"additionAddr": "Доп. адрес",
"addressSite": "Участок",
"maxPowerValue": 1000.0001,
"objectCategory": "Категория объекта",
},
{
"account": 123456,
"contractor": 5,
"addressSiteValue": "Расположение",
"region": "Область",
"city": "Город",
"street": "Улица",
"house": "Дом",
"building": "Корпус",
"flat": "Квартира",
"office": "Офис",
"additionAddr": "Доп. адрес",
"addressSite": "Участок",
"maxPowerValue": 1000.0001,
"objectCategory": "Категория объекта",
}
]
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"success": true,
"id": 33
},
{
"success": false,
"error": "Необходимо заполнить поле «Наименование».",
}
],
"id": 1
}
Метод import.objects.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яЭнергетик |
| objects | object[] | объекты с параметрами |
Параметры объекта
Параметр id указывается только для существующих объектов, параметры которых необходимо изменить.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | null|int | id объекта для изменения или null для создания нового |
| name | string | название |
| account | int | лицевой счет |
| contractor | null|int | id контрагента или null, чтобы не прикреплять к контрагенту |
| addressSiteValue | null|string | расположение |
| city | null|string | город |
| street | null|string | улица |
| house | null|string | дом |
| building | null|string | корпус |
| flat | null|string | расположение |
| office | null|string | офис |
| additionAddr | null|string | дополнительная адресная информация |
| maxPowerValue | null|float | максимальная мощность |
| region | null|string | область |
| objectCategory | null|string | Категория объекта |
| addressSite | null|string | Участок |
Результат
Массив результатов созданния/измененния объектов.
├── success bool импорт выполнен ├── id int id счетчика в случае успешного импорта ├── error string сообщение об ошибке в случае неудачного импорта
Импорт счетчиков
Вызов метода
{
"jsonrpc": "2.0",
"method": "import.counters",
"params": {
"network": 1,
"counters": [
{
"object": 22,
"num": "123456",
"mark": "Меркурий 123",
"measures": [1, 2],
"zones": ["День", "Ночь"],
"digit": 4,
"decimal": 2,
"location": "Расположение",
"ktt": 1,
"ktn": 4,
"lossShortCircuit": 70.5,
"lossIdle": 12.5,
"dateSetup": "2021-04-15",
"dateCheck": "2021-05-01",
"dateCheckNext": "2021-11-01",
"voltageClass": "I",
"substation": "наименование ПС",
"substationConnection": "наименование присоединения ПС",
"transformerSubstation": "наименование ТП",
"transformerSubstationConnection": "наименование присоединения ТП",
"modemSerialNumber": "0123456789123",
"serialNumberOfDisplayUnit": "0123456789123",
"radioInterfacePassword": "88888888888",
"phoneNumberSim1": "+79993335511",
"phoneNumberSim2": "+79993334411",
},
{
"object": 22,
"num": "789654",
"mark": "Меркурий 456",
"measures": [1, 2],
"digit": 4,
"decimal": 2,
"location": "Расположение",
"ktt": 1,
"ktn": 4,
"lossShortCircuit": 70.5,
"lossIdle": 12.5,
"dateSetup": "2021-04-15",
"dateCheck": "2021-05-01",
"dateCheckNext": "2021-11-01"
},
]
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"success": true,
"id": 33
},
{
"success": false,
"error": "Обязательный параметр zones пуст.",
}
],
"id": 1
}
Метод import.counters.
Параметры
Параметр network обязателен, если у пользователя может быть несколько сетей.
| Параметр | Тип данных | Описание |
|---|---|---|
| network | int | id сети на яЭнергетик |
| counters | object[] | счетчики с параметрами |
Параметры счетчика
Параметр id указывается только для существующих счетчиков, параметры которых необходимо изменить.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | null|int | id счетчика для изменения или null для создания нового |
| object | int | id объекта |
| num | string | номер |
| mark | string | марка |
| measures | int[] | каналы измерения |
| zones | string[] | названия зон |
| digit | null|int | разраядность |
| decimal | null|int | разрядность после запятой |
| location | null|string | расположение |
| ktt | int | КТТ |
| ktn | int | КТН |
| lossShortCircuit | null|float | потери КЗ |
| lossIdle | null|float | потери ХХ |
| dateSetup | null|date | дата установки |
| dateCheck | null|date | дата госповерки |
| dateCheckNext | null|date | дата след. поверки |
| voltageClass | null|string | класс напряжения |
| substation | null|string | наименование ПС |
| substationConnection | null|string | наименование присоединения ПС |
| transformerSubstation | null|string | наименование ТП |
| transformerSubstationConnection | null|string | наименование присоединения ТП |
| modemSerialNumber | null|string | серийный номер модема |
| serialNumberOfDisplayUnit | null|string | серийный номер блока индикации сплит-счетчика |
| radioInterfacePassword null|string | пароль радиоинтерфейса | |
| phoneNumberSim1 | null|string | номер телефона SIM1 |
| phoneNumberSim2 | null|string | номер телефона SIM2 |
Каналы измерения
| Канал измерения | Значение |
|---|---|
| А+ (активная энергия) | 1 |
| А- (активная обратная энергия) | 2 |
| R+ (реактивная энергия) | 3 |
| R- (реактивная обратная энергия) | 4 |
Результат
Массив результатов импорта счетчиков.
├── success bool импорт выполнен ├── id int id счетчика в случае успешного импорта ├── error string сообщение об ошибке в случае неудачного импорта
Импорт контрагентов
Вызов метода
{
"jsonrpc": "2.0",
"method": "import.contractors",
"params": {
"contractors": [
{
"name": "Рога и Копыта",
"fullName": "ООО Рога и Копыта",
"contractorTypeId": 1,
"ogrn": "xxxx",
"ogrnDate": "2021-01-01",
"inn": "3664069397",
"kpp": "773301001",
"registeredAddress": "г. Москва",
"postAddress": "г. Москва",
"email": "example@example.com",
"phone": "+79993335511",
"objects": [22]
},
{
"fullName": "ООО Рога и Копыта",
"contractorTypeId": 1,
"ogrn": "xxxx",
"ogrnDate": "2021-01-02",
"inn": "3664069345",
"kpp": "773301045",
"registeredAddress": "г. Москва",
"postAddress": "г. Москва",
"email": "example2@example.com",
"phone": "+79993335522",
"objects": [22]
},
]
},
"id": 1
}
Результат
{
"jsonrpc": "2.0",
"result": [
{
"success": true,
"id": 5
},
{
"success": false,
"error": "Необходимо заполнить поле «Краткое наименование».",
}
],
"id": 1
}
Метод import.contractors.
Параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| counters | object[] | контрагенты с параметрами |
Параметры контрагента
Параметр id указывается только для существующих контрагентов, параметры которых необходимо изменить.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | null|int | id контрагента для изменения или null для создания нового |
| name | string | краткое наименование |
| fullName | string | полное наименование |
| contractorTypeId | int | тип |
| ogrn | null|string | номер ЕГРИП/ЕГРЮЛ |
| ogrnDate | null|date | дата ЕГРИП/ЕГРЮЛ |
| inn | null|string | ИНН |
| kpp | null|string | КПП |
| registeredAddress | null|string | юридический адрес/адрес прописки |
| postAddress | null|string | почтовый адрес |
| null|string | адрес эл. почты | |
| phone | null|string | номер телефона |
| objects | null|int[] | массив с id объектов, к которым нужно прикрепить контрагента |
Тип контрагента
| Тип | Значение |
|---|---|
| Юридическое лицо | 1 |
| ИП | 2 |
| Физическое лицо | 3 |
Результат
Массив результатов импорта контрагентов.
├── success bool импорт выполнен ├── id int id контрагента в случае успешного импорта ├── error string сообщение об ошибке в случае неудачного импорта