| Оглавление |
|---|
Общие сведения
Сервисы используют методы GET, POST и PUT, отвечающие стандарту RFC 7231. Путь к сервису должен соответствовать шаблону «api/[version]/[controller]», например, «api/v1/metering_devices». Тело запроса содержит json-объект, соответствующий описанию сервиса, наименования свойств объектов формируются по правилам snake_case. Свойства со значениями по умолчанию исключаются из сериализации. Все операции по лицевым счетам проводятся исключительно по соответствующим платежным кодам. Все запросы должны быть авторизованы, ограничения по данным накладываются в разрезе платежного кода.
...
Требования к методу
...
...
GET
...
POST
...
PUT
...
Имеет тело запроса
...
Нет
...
Да
...
Да
...
Имеет тело ответа
...
Да
...
Да
...
Нет
...
Безопасный
...
Да
...
Нет
...
Нет
...
Идемпотентный
...
Да
...
Нет
...
Да
Требования по аутентификации
Обращения к сервисам доступны только по HTTPS протоколу. Аутентификация сторонней системы производится самоподписным доверенным сертификатом на уровне nginx.
Аутентификация конечного пользователя производится методом передачи заголовка Authorization (используется базовая аутентификация) на уровне прикладной системы. Для базовой авторизации пользователя предлагается использовать платежный код в качестве имени пользователя и результат слияния фамилии и номера квартиры через разделитель “@”.
Пример:
...
Аутентификация пользователя
...
Построение заголовка
Basic Base64([платежный код]:[фамилия]@[квартира])
Пример для пользователя с фамилией «Иванов», квартирой «64А» и платежным кодом «810123456»:
Password = “иванов@64а”
Token = “810123456:иванов@64а”
Base64String = “ODEwMTIzNDU2OtC40LLQsNC90L7QskA2NNCw”
...
Результат
...
Authorization: Basic ODEwMTIzNDU2OtC40LLQsNC90L7QskA2NNCw
Обработка ошибок
В качестве ответов для всех сервисов резервируются следующие коды ответов, для каждого из методов набор ошибок может быть расширен:
...
Зарезервированные коды ответов
...
Код ответа
...
Описание ответа
...
400 (Bad Request)
...
Запрос подписан неверным сертификатом сторонней системы
...
401 (Unauthorized)
...
Введен неверный платежный код, фамилии или номера квартиры
...
403 (Forbidden)
...
Запрошенные данные недоступны
...
404 (Not Found)
...
Запрошенный объект не найден
...
408 (Request Timeout)
...
Запрос не отработал за отведенный промежуток времени
...
422 (Unprocessable entity)
...
Объект распознан, но не может быть обработан
В теле ответа неуспешные ответы могут быть дополнены информацией, детализирующей возникшие в процессе обработки ошибки. Тело ответа представляется json массивом объектов и состоит из свойств, описанных в таблице:
...
Описание объекта ошибки
...
Свойство
...
Тип
...
Описание
...
Id
...
UInt32
...
Идентификатор объекта
...
Code
...
Int32
...
Идентификатор ошибки
...
Comment
...
String
...
Детализация ошибки
...
Пример
...
[
{
"id": 500,
"code": 10000,
"comment": "Целая часть введенного показания превышает разрядность прибора учета"
}
]
Перечень сервисов
Реализуются следующие сервисы:
...
Сервис данных о ЛС
...
1.
...
Маршрут
...
api/VoiceAssistant/GetPersonalAccountInfo
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение информации по лицевому счету
...
Тело запроса
Описание объекта запроса | ||
Свойство | Тип | Описание |
street | строка | Улица, обязательное поле, без префиксов: ул, улица, ул. |
numHouse | строка | Номер дома, без префиксов |
numApartment | строка | Номер квартиры, без префиксов |
numRoom | строка | Номер комнаты, без префиксов |
surname | строка | Фамилия, только фамилия |
shortNum | строка | Обязательное поле, последние 4 цифры ПК |
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
personalAccount | строка | ПК |
dateOpen | dateTime | Дата открытия ЛС |
square | decimal | Общая площадь |
countRoom | int | Кол-во комнат |
...
Пример
[
{
"personalAccount": "8103841319",
"dateOpen": "2022-03-12T14:41:08.701441",
"square": 58.5,
"countRoom": 3
}
]
...
Сервис данных о ЛС
...
2.
...
Маршрут
...
/api/VoiceAssistant/GetPayment/{publicPersonalAccount}
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение списка оплат (3 последние)
...
Тело запроса
Описание объекта запроса | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
itemNumber | int | Номер строки |
sum | decimal | Сумма оплаты |
date | dateTime | Дата оплаты |
source | строка | Где оплачивали |
...
Пример
...
[
{
"itemNumber": 1,
"sum": 5312.95,
"date": "2022-04-15T00:00:00",
"source": " - "
},
{
"itemNumber": 2,
"sum": 10541.24,
"date": "2022-03-10T00:00:00",
"source": " - "
},
{
"itemNumber": 3,
"sum": 5316.24,
"date": "2022-01-24T00:00:00",
"source": " - "
}
]
...
Сервис данных о ЛС
...
3
...
Маршрут
...
/api/VoiceAssistant/GetCounters
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Список ПУ у абонента
...
Тело запроса
Описание объекта запроса | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
itemNumber | int | Номер строки |
serviceName | string | Наименование услуги |
number | string | Заводской номер ПУ |
value | decimal | Показание |
dateUchet | dateTime | Дата учета показания |
verificationDateNext | dateTime | Дата следующей поверки |
...
Пример
...
[
{
"itemNumber": 1,
"serviceName": "Холодное водоснабжение",
"number": "0001672369",
"value": "133.00000",
"dateUchet": "2022-05-01T00:00:00",
"verificationDateNext": "2026-04-01T00:00:00"
},
{
"itemNumber": 2,
"serviceName": "Электроснабжение",
"number": "37527720",
"value": "2 566.00000",
"dateUchet": "2022-05-01T00:00:00",
"verificationDateNext": "2035-12-24T00:00:00"
}
]
...
Сервис данных о ЛС
...
4
...
Маршрут
...
/api/VoiceAssistant/SaveValue
...
Метод
...
POST
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Сохранение показания ПУ
...
Тело запроса
Описание объекта запроса | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
counterNumber | строка | Заводской номер ПУ |
counterValue | Вещественное число | Показание ПУ |
...
Тело ответа
...
Описание объекта ответа
...
Свойство
...
Тип
...
Описание
...
Успешно
...
строка
...
«Показание успешно сохранено»
...
Неуспешно
...
«Прибор учета с номером не был найден»
«Для прибора учета с номером предыдущие показания не найдены»
«У прибора учета с номером предыдущее показание больше, чем текущее»
«Неверный сальдовый месяц и год: месяц.год»
...
Пример
...
Сервис данных о ЛС
...
5
...
Маршрут
...
api/VoiceAssistant/ChargesPerMonth
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение начислений за определенный месяц и год
...
Тело запроса
Описание объекта запроса | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
month | Целое число | месяц |
year | Целое число | год |
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
sum | decimal | Начислено к оплате |
sumMonth | decimal | Начислено за месяц |
sumBalance | decimal | Начислено в т.ч долг/переплата |
date | dateTime | Месяц начислений |
...
Пример
...
{
"sum": 5312.95,
"sumMonth": 5312.95,
"sumBalance": 10533.23,
"date": "2022-03-01T00:00:00"
}
...
Сервис данных о ЛС
...
6
...
Маршрут
...
api/VoiceAssistant/GetChargesDescription
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение расшифровки начислений за предыдущий месяц
...
Тело запроса
Описание объекта запроса | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
serviceName | строка | Наименование услуги |
serviceNumber | Целое число | Идентификатор услуги |
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
Charges | строка | Начисление |
Description | строка | Расшифровка начисления |
Пример |
/api/VoiceAssistant/GetChargesDescription?publicPersonalAccount=9050000042&serviceName=Электроснабжение&serviceNumber= |
{ "Charges": 719.98, "Description": " К оплате 719.98 рублей, в том числе 684.80 рублей за текущий месяц,35.18 рублей долг за прошлый период. Начислено 35.18 по следующим данным : тариф 3.20 рублей * расход 214.00" } |
Перечень сервисов и примеры вызовов см здесь Список сервисов портала Наш дом для голосового робота.docx