| Оглавление |
|---|
Общие сведения
Сервисы используют методы 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
3. Обработка ошибок
В качестве ответов для всех сервисов резервируются следующие коды ответов, для каждого из методов набор ошибок может быть расширен:
Зарезервированные коды ответов | |
Код ответа | Описание ответа |
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/PersonalAccount/GetPersonalAccountInfo
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение информации по лицевому счету
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
street | строка | Улица, обязательное поле, без префиксов: ул, улица, ул. |
numHouse | строка | Номер дома, без префиксов |
numApartment | строка | Номер квартиры, без префиксов |
numRoom | строка | Номер комнаты, без префиксов |
surname | строка | Фамилия, только фамилия |
shortNum | строка | Обязательное поле, последние 4 цифры ПК |
...
Пример
[
{
"personalAccount": "8103841319",
"dateOpen": "2022-03-12T14:41:08.701441",
"square": 58.5,
"countRoom": 3
}
]
...
Сервис данных о ЛС
...
2.
...
Маршрут
...
/api/Payment/GetPayment/{publicPersonalAccount}
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение списка оплат (3 последние)
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
...
Пример
...
[
{
"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/Counter/GetCounters
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Список ПУ у абонента
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
...
Пример
...
[
{
"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/Counter/SaveValue
...
Метод
...
POST
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Сохранение показания ПУ
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
counterNumber | строка | Заводской номер ПУ |
counterValue | Вещественное число | Показание ПУ |
...
Пример
...
Сервис данных о ЛС
...
5
...
Маршрут
...
api/Charge/ChargesPerMonth
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение начислений за определенный месяц и год
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
month | Целое число | месяц |
year | Целое число | год |
...
Пример
...
{
"sum": 5312.95,
"sumMonth": 5312.95,
"sumBalance": 10533.23,
"date": "2022-03-01T00:00:00"
}
...
Сервис данных о ЛС
...
6
...
Маршрут
...
api/Charge/GetChargesDescription
...
Метод
...
GET
...
Заголовки
...
Аутентификации пользователя
...
Описание
...
Получение расшифровки начислений за предыдущий месяц
...
Тело ответа
Описание объекта ответа | ||
Свойство | Тип | Описание |
publicPersonalAccount | строка | ПК, обязательный |
serviceName | строка | Наименование услуги |
serviceNumber | Целое число | Идентификатор услуги |
Пример |
/api/VoiceAssistant/GetChargesDescription?publicPersonalAccount=9050000042&serviceName=Электроснабжение&serviceNumber= |
{ "Charges": 719.98, "Description": " К оплате 719.98 рублей, в том числе 684.80 рублей за текущий месяц,35.18 рублей долг за прошлый период. Начислено 35.18 по следующим данным : тариф 3.20 рублей * расход 214.00" } |
Список сервисов
...
№
...
Наименование
...
Описание
...
1
...
GetLs (pUlica,pNdom, pnKvar,pfio)
...
Предоставление информации по лицевому счету по адресу (улица, номер дома и номер квартиры. фамилии собственника или ответственного квартиросъемщика)
...
2
...
GetBalance(pNumLs, pDatMonth)
...
Предоставление суммы начисления к оплате по лицевому счету за месяц
...
3
...
GetCounters(pNumLs)
...
Получение списка приборов учета по лицевому счету
...
4
...
GetPlat(pNumLs)
...
Получение списка последних 3-х оплат по лицевому счету
...
5
...
GetSumDetails(pNumLs,kod)
...
Получение расшифровки суммы начисления по услуге
...
6
...
SaveCountersVal(pNumLs,pNumCnt,pValue)
...
Сохранить показание прибора учета
...
7
...
SaveClaim(pNumLs,pNote)
...
Сохранить заявку
GetLs (pUlica,pNdom, pnKvar,pfio)
Входные параметры
Наименование | Тип | Обязательность | Описание | Пример |
pUlica | Строка(80) | Да | Улица | амирхана |
pNdom | Строка(10) | Да | Дом | 5 |
pnKvar | Строка(10) | Да | Квартира | 1 |
pFam | Строка(60) | Да | Фамилия | иванов |
Выходные параметры
Наименование | Тип | Обязательность | Описание | Пример |
pNumLs | Строка(10) | Да | Номер лицевого счета | 5016123456 |
pDateOpen | Дата | Да | Дата открытия лиц счета | 10.02.2001 |
pDateClose | Дата | Нет | Дата закрытия лиц счета | 30.01.2020 |
pSquare | Число(8,2) | Нет | Общая площадь | 54,2 |
pCountRoom | Число(2) | Нет | Количество комнат | 1 |
GetBalance(pNumLs, pDatMonth)
Входные параметры
Наименование | Тип | Обязательность | Описание | Пример |
pNumLs | Строка(10) | Да | Номер лицевого счета | 5016123456 |
pDatMonth | Строка(20) | Да | Месяц и год начисления | январь 20 года |
Выходные параметры
Наименование | Тип | Обязательность | Описание | Пример |
pSumCharge | Число(8,2) | Да | Начислено к оплате | 1000 |
pSumReal | Число(8,2) | Да | в т ч начислено за месяц | 700 |
pSumInsaldo | Число(8,2) | Да | в т ч долг / переплата | 300 |
GetCounters(pNumLs)
Входные параметры
Наименование | Тип | Обязательность | Описание | Пример |
pNumLs | Строка(10) | Да | Номер лицевого счета | 5016123456 |
Выходные параметры
Передаётся список записей со следующими атрибутами
Наименование | Тип | Обязательность | Описание | Пример |
pNum | Число(2) | Да | Номер записи в списке | 1 |
pNameService | Строка(50) | Да | Название коммунальной услуги | Холодное водоснабжение |
pNumCnt | Строка(50) | Да | Заводской номер прибора учёта | 276381298 |
pCntVal | Число(15,5) | Нет | Последнее показание | 1545 |
pDatUchet | Дата | Нет | Показание на дату | 20.10.2020 |
GetPlat(pNumLs)
Входные параметры
Наименование | Тип | Обязательность | Описание | Пример |
pNumLs | Строка(10) | Да | Номер лицевого счета | 5016123456 |
Выходные параметры
Передаётся список записей со следующими атрибутами
Наименование | Тип | Обязательность | Описание | Пример |
pNum | Число(2) | Да | Номер записи в списке | 1 |
pSumPlat | Число(15,2) | Да | Сумма оплаты | 5000 |
pDatVvod | Дата | Да | Дата оплаты | 01.10.2020 |
pSource | Строка(50) | Нет | Источник поступления | Почта РФ |
GetSumDetails(pNumLs,kod)
Входные параметры
...
Наименование
...
Тип
...
Обязательность
...
Описание
...
Пример
...
pNumLs
...
Строка(10)
...
Да
...
Номер лицевого счета
...
5016123456
...
pServiceNum
...
Чисто(10)
...
Нет
...
Номер услуги в счёт фактуре
...
10
...
pServiceName
...
Строка(50)
...
Нет
...
Название услуги в счёт фактуре
...
Обращение с ТКО
Выходные параметры
Передаётся список записей со следующими атрибутами
...
Наименование
...
Тип
...
Обязательность
...
Описание
...
Пример
...
pSumNach
...
Число(15,2)
...
Да
...
Начислено всего
...
5000
...
pDescr
...
Строка(200)
...
Да
...
Расшифровка начисления
...
К оплате 700 рублей в том числе 500 рублей начисления за текущий месяц,
150 рублей долг за прошлый месяц, 50 рублей перерасчёт за прошлый период)
Начислено 500 рублей по следующим данным:
Тариф за единицу измерения 10 рублей с квадратного метра
Общая площадь 50 квадратных метров
SaveCountersVal(pNumLs,pNumCnt,pValue)
Входные параметры
...
Наименование
...
Тип
...
Обязательность
...
Описание
...
Пример
...
pNumLs
...
Строка(10)
...
Да
...
Номер лицевого счета
...
5016123456
...
pNumCnt
...
Строка(50)
...
Да
...
Заводской номер прибора учёта
...
827873
...
pValue
...
Число(15,5)
...
Да
...
Показание прибора учёта
...
122.1
Выходные параметры
...
Наименование
...
Тип
...
Обязательность
...
Описание
...
Пример
...
pStatus
...
Логическое
...
Да
...
Статус сохранения
...
false
...
pResult
...
Строка(100)
...
Нет
...
Описание причины несохранения
...
Текущее показание не может быть меньше предыдущего (130)
SaveClaim(pNumLs,pNote)
Входные параметры
...
Наименование
...
Тип
...
Обязательность
...
Описание
...
Пример
...
pNumLs
...
Строка(10)
...
Да
...
Номер лицевого счета
...
5016123456
...
pNote
...
Строка(150)
...
Да
...
Описание заявки
...
Заказать справку о начислениях с января по декабрь 2020
Выходные параметры
...
Наименование
...
Тип
...
Обязательность
...
Описание
...
Пример
...
pStatus
...
Логическое
...
Да
...
Статус сохранения
...
true
...
pResult
...
Строка(100)
...
Нет
...
Описание причины несохранения
...
Заявка успешно сохранена. Номер обращения 287373
и примеры вызовов см здесь Список сервисов портала Наш дом для голосового робота.docx