Общие сведения

Сервисы используют методы 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"

}