NAV Navbar
  • Введение
  • Аутентификация
  • Общая информация
  • Пользователь
  • Система
  • Сети
  • Счетчики
  • Показания
  • Мгновенные значения
  • Профиль мощности
  • Введение

    В этой документации описано взаимодействие с 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, либо написать реализацию под свои задачи, протокол относительно прост. Поддерживаются практически все возможности протокола.

    Совместимость:

    Термины

    Термин Значение
    Запрос HTTP запрос
    Вызов Вызов метода (в одном запросе может быть несколько вызовов)
    Json-объект Тип данных
    Объект Объект в сети на яЭнергетик
    ПУ Прибор учета - реальное устройство, которое соответствует счетчику на яЭнергетик
    id Идентификатор типа int для данных на яЭнергетик (сеть, объект, счетчик, ...)
    Не связан с id вызова

    Типы данных datatypes

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

    Сервер возвращает все ошибки в соответствии с протоколом 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 В запросе содержащем вызов метода аутентификации уже указана сессия
    10103 серверный Authentication request limit reached Превышено ограничение попыток аутентификации
    10201 пользовательский Verification code required Необходимо указать код подтверждения
    10202 пользовательский Invalid verification code Неправильно указан код подтверждения

    Пользовательский режим

    Вызов метода

    {
        "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": 10203,
            "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 не указано. Строгий поиск применяется там, где важен выбор данных на концах периодов. Например, при запросе расхода по показаниям в строгом режиме, для расчета расхода будут использоваться только показания попадающие ровно на концы периода, а в ином случае будут использоваться ближайшие к концам показания, которые попадают в период.

    Концы периода считаются включительно, если в описании метода не указано обратного.

    Часовые пояса

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

    Можно вручную установить часовой пояс для использования в последующих вызовах в пределах одного запроса (см. множественный вызов). Для этого перед вызовом остальных методов, нужно вызвать метод 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,
                "balance": null
            },
            "id": 1
        },
        {
            "jsonrpc": "2.0",
            "result": [
                {
                    "id": 123,
                    "name": "АСКУЭ пользователя Иванов Иван Иванович",
                    "owner": "Иванов Иван Иванович",
                    "address": "Архангельск",
                    "objectView": true
                }
            ],
            "id": 2
        }
    ]
    

    Можно вызвать несколько методов в одном запросе (кроме методов группы auth). Для этого достаточно передать массив с json-объектами вызовов. В ответ будет получен массив с json-объектами результатов и/или ошибок.

    При множественном вызове существует ограничение в 100 вызовов в пределах одного запроса.

    Пользователь

    Методы user

    Метод Возвращаемый тип Описание
    user.info object Получение информации о текущем пользователе

    Информация о пользователе

    Вызов метода

    {
        "jsonrpc": "2.0",
        "method": "user.info",
        "id": 1
    }
    

    Результат

    {
        "jsonrpc": "2.0",
        "result": {
            "name": "Иванов Иван Иванович",
            "singleNetwork": true
        },
        "id": 1
    }
    

    Метод user.info.

    Параметры

    Метод не принимает параметров.

    Результат

    Json-объект с информацией о пользователе.

    ├── name string Полное имя пользователя
    └── singleNetwork boolean Признак того, что у пользователя может быть только одна сеть (но не обязательно есть)
    

    Система

    Методы system

    Метод Возвращаемый тип Описание
    system.setTimezone null Устанавливает часовой пояс для последующих вызовов в пределах одного запроса

    Установка часового пояса

    Вызов метода

    {
        "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. При этом часовой пояс с указанным названием устанавливается для последующих вызовов в пределах этого же запроса.

    Сети

    Методы network

    Метод Возвращаемый тип Описание
    network.list object[] Получение списка сетей текущего пользователя

    Список сетей

    Вызов метода

    {
        "jsonrpc": "2.0",
        "method": "network.list",
        "id": 1
    }
    

    Результат

    {
        "jsonrpc": "2.0",
        "result": [
            {
                "id": 123,
                "name": "АСКУЭ пользователя Иванов Иван Иванович",
                "owner": "Иванов Иван Иванович",
                "address": null,
                "objectView": true
            }
        ],
        "id": 1
    }
    

    Метод network.list.

    Параметры

    Метод не принимает параметров.

    Результат

    Массив json-объектов с информацией о сетях.

    ├── id int id для использования в других вызовах
    ├── name string Название сети
    ├── owner string Полное имя пользователя - владельца сети
    ├── address string|null Адрес, указанный в настройках сети
    └── objectView boolean Включен ли режим показа объектов (когда в одном объекте может быть несколько счетчиков)
    

    Счетчики

    Методы meter

    Метод Возвращаемый тип Описание
    meter.list object[] Получение списка счетчиков
    meter.sources 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": 13855,
                        "num": "015610",
                        "mark": "Нева МТ 324",
                        "object": "Ввод в серверную",
                        "type": "Электросчетчик",
                        "unit": "кВтч",
                        "electric": true,
                        "zones": [
                            "день",
                            "ночь"
                        ],
                        "ascueState": {
                            "requests": {
                                "readings": {
                                    "scheduled": true,
                                    "lastSuccess": "2018-02-19T05:00:00+03:00"
                                },
                                "powerProfile": {
                                    "scheduled": false,
                                    "lastSuccess": null
                                }
                            },
                            "enabled": true
                        }
                    },
                    {
                        "id": 13857,
                        "num": "015600",
                        "mark": "Нева МТ 324",
                        "object": "Питание оргтехники",
                        "type": "Электросчетчик",
                        "unit": "кВтч",
                        "electric": true,
                        "zones": [
                            "день",
                            "ночь"
                        ],
                        "ascueState": ...
                    }
                ]
            },
            {
                "name": "Кондиционирование и вентиляция",
                "source": {
                    "type": "object",
                    "value": 13856
                },
                "values": [
                    {
                        "id": 13856,
                        "num": "003594",
                        "mark": "Нева МТ 123",
                        "object": "Кондиционирование и вентиляция",
                        "type": "Электросчетчик",
                        "unit": "кВтч",
                        "electric": true,
                        "zones": [
                            "T1",
                            "T2",
                            "Т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 зависит от типа Желаемое значение у счетчика
    

    Типы фильтров:

    Тип Возможные значения Описание
    "site" int|int[] Будут возвращены только счетчики с таким(и) id участка
    "object" int|int[] Будут возвращены только счетчики с таким(и) id объекта
    "mounted" null|object Будут возвращены только установленные (смонтированные на реальном объекте) на данный момент (null) либо на определенный период времени счетчики

    Порядок счетчиков 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 Марка ПУ (если указана)
    ├── object string Название объекта, к которому привязан счетчик
    ├── type string Название типа ПУ
    ├── unit string|null Единицы измерения показаний
    ├── electric boolean Является ли счетчик электросчетчиком
    ├── ktt int|null Коэффициент трансформации по току (только для электросчетчиков)
    ├── ktn int|null Коэффициент трансформации по напряжению (только для электросчетчиков)
    ├── zones string[]|null Тарифные зоны ПУ (только для электросчетчиков)
    └── 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[] Типы источников

    Результат

    Массив json-объектов с описанием источников.

    Структура:

    ├── type string Тип источника
    └── values object[] Возможные значения
        ├── name string|null Название источника
        ├── value int|null Значение для использования в фильтре
        └── count int Количество счетчиков, соответствующих этому фильтру
    

    Название источника и значение для фильтра могут быть null. Это означает что есть счетчики, для которых этот источник не указан. Например, счетчики, не относящиеся ни к одному участку.

    Показания

    Методы 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",
                "value": 18533.55,
                "zones": [
                    13637.84,
                    4895.71
                ]
            },
            {
                "date": "2017-09-02T00:00:00+03:00",
                "value": 18564.62,
                "zones": [
                    13660.45,
                    4904.17
                ]
            },
            {
                "date": "2017-09-03T00:00:00+03:00",
                "error": {
                    "code": 20002,
                    "message": "Ошибка АСКУЭ. Этап: опрос счетчика. Счетчик не отвечает"
                }
            },
            {
                "date": "2017-09-04T00:00:00+03:00",
                "value": 18587.72,
                "zones": [
                    13675.85,
                    4911.87
                ]
            }
        ],
        "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 Дата и время показания
    ├── value float Значение показания (сумма значений тарифных зон, если счетчик многотарифный)
    └── zones float[]|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
        │   ├── value float
        │   └── zones float[]|null
        └── last object|null Конечное показание, если оно было найдено
            ├── date string
            ├── value float
            └── zones float[]|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",
                    "value": 17644.77,
                    "zones": [
                        12999.96,
                        4644.81
                    ]
                }
            },
            {
                "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
        ├── value float
        └── zones float[]|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",
                        "value": 18533.55,
                        "zones": [
                            13637.84,
                            4895.71
                        ]
                    },
                    "last": {
                        "date": "2017-10-01T00:00:00+03:00",
                        "value": 19340.84,
                        "zones": [
                            14223.27,
                            5117.57
                        ]
                    }
                },
                "consumption": 807.29,
                "zones": [
                    585.43,
                    221.86
                ]
            },
            {
                "meter": 18242,
                "readings": {
                    "first": {
                        "date": "2017-09-01T00:00:00+03:00",
                        "value": 123.45,
                        "zones": [
                            100.4,
                            23.05
                        ]
                    },
                    "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
        │   ├── value float
        │   └── zones float[]|null
        └── last object|null Конечное показание, если оно было найдено
            ├── date string
            ├── value float
            └── zones float[]|null
    

    Мгновенные значения

    Методы currentValue

    Метод Возвращаемый тип Описание
    currentValue.data object Перечисление мгновенных значений

    Перечисление мгновенных значений

    Вызов метода

    {
        "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 (временные метки) вместо строки с датой и временем

    Запрашиваемые значения

    Название Единицы измерения Описание
    voltage В Напряжение
    current А Сила тока
    activePower кВт Активная мощность
    reactivePower кВАр Реактивная мощность
    fullPower кВА Полная мощность
    powerFactor нет Коэффициент мощности
    angle ° Угол между фазными напряжениями
    frequency Гц Частота сети

    На данный момент нет возможности заранее определить какие значения поддерживаются счетчиком.

    Результат

    Объект с заголовками и с массивом точек.

    Структура:

    ├── 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
    'AC' Фазы A и C Угол между фазными напряжениями фаз A и C
    'BC' Фазы B и C Угол между фазными напряжениями фаз B и 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 секунд.

    Используемый период интегрирования возвращается в ответе.

    Дополнительная информация

    Значение Описание
    "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" Реактивная обратная мощность