Свернуть все меню

API сервиса приема показаний и автообзвона должников

Сервисы ЖКХ: Автообзвон должников и ЖКХ: Автоматический прием показаний счетчиков можно подключить к любой программе, для этого можно использовать API, приведенное ниже.

Обозначения.

Веб-сервис — сервис приема показаний и автообзвона должников.
1С — конфигурация, подключающаяся к веб-сервису.
Пользователь — управляющая организация, являющаяся пользователем веб-сервиса и 1C.
Абонент — получатель услуг Пользователя.
ПУ — прибор учёта.

Начало работы.

Пользователь регистрируется в веб-сервисе, получает персональный url личного кабинета. Также у пользователя имеются логин и пароль для авторизации в личном кабинете.

Общие принципы взаимодействия.

Обмен данными производится в обе стороны:

1C передаёт на веб-сервис информацию о лицевых счетах и установленных на них ПУ,
Веб-сервис передаёт в 1C информацию о полученных показаниях ПУ.

Инициатором обмена всегда является 1C. Поэтому в 1C нужно указать и хранить данные для соединения: адрес, логин, пароль.
Обмен выполняется по расписанию, заданному пользователем в 1C. Расписание задаётся отдельно для каждого направления обмена.

Состав данных, выгружаемых на веб-сервис:

Лицевой счёт: идентификатор и номер.
Адрес: улица, дом, квартира.
Список ПУ. По каждому из них:

идентификатор,
наименование счетчика,
тарифность,
разрядность,
услуга,
дата последнего показания 1-2-3 (для всех видов тарифов),
последнее показание 1-2-3 (для всех видов тарифов).

Сумма долга по услугам, дата последней оплаты, количество месяцев задолженности.

Состав данных, загружаемых с веб-сервиса:

Лицевой счёт: идентификатор.
Список ПУ. По каждому из них:

идентификатор,
дата показания 1-2-3 (для всех видов тарифов),
показание 1-2-3 (для всех видов тарифов),
тарифность.

Форматы передаваемых данных:

Выгрузка данных на сервис:

{

"accs": [

{

"id": [идентификатор л/с],

"number": [номер л/с],

"data_source_id": [идентификатор создателя записи],

"address": {

"street": [улица],

"house": [дом],

"apartment": [номер помещения]

},

"debt": {

"sum_of_debt": [сумма задолженности],

"months_of_debt_count": [количество месяцев задолженности],

"last_payment_date": [дата последней оплаты]

},

"meters": [

{

"id": [код счетчика],

"name": [наименование счетчика],

"values": [количество тарифов 1-3],

"capacity": [количество разрядов],

"service": [наименование услуги],

"date": [дата последнего показания],

"val1": [дневное показание],

"val2": [ночное показание],

"val3": [пиковое показание]

}

]

}

],

"sum_of_debt": [сумма задолженности],

"count_months": [количество месяцев задолженности]

}

где:

[идентификатор л/с] - строка - 100 - идентификатор лицевого счета.

[номер л/с] - строка - 100 - номер лицевого счета.

[идентификатор создателя записи ] - строка - 100 (неотрицательное) - идентификатор, создателя записи.

[улица] - строка - 100 - улица.

[дом] - строка - 10 - номер дома + корпус дома.

[номер помещения] - число - 9 - номер помещения лицевого счета.

[сумма задолженности] - число - 15,2 - сумма задолженности.

[количество месяцев задолженности] - число - 4 (неотрицательное) - количество месяцев задолженности.

[дата последней оплаты] - дата - дата последней оплаты.

[код счетчика] - строка - 9 - код счетчика в 1с.

[наименование счетчика] - строка - 100 - наименование счетчика в 1с.

[количество тарифов 1-3] - число - 1 (неотрицательное) - количество видов тарифов (тарифность).

[количество разрядов] - число - 2 (неотрицательное) разрядность.

[наименование услуги] - строка - 100 - наименование вида услуги в 1с.

[дата последнего показания] - дата - дата показания.

[дневное показание] - число - 18,6 (неотрицательное) - показание по дневному виду тарифа.

[ночное показание] - число - 18,6 (неотрицательное) - показание по ночному виду тарифа.

[пиковое показание] - число - 18,6 (неотрицательное) - показание по пиковому виду тарифа

Загрузка данных о показаниях ПУ с сервиса:

[

{

"id": [код счетчика],

"name": [наименование счетчика],

"values": [количество тарифов 1-3],

"date": [дата показания],

"val1": [дневное показание],

"val2": [ночное показание],

"val3": [пиковое показание],

"acc_id": [идентификатор л/с],

}

]

где:

[идентификатор л/с] - строка - 100 - идентификатор лицевого счета.

[код счетчика] - строка - 9 - код счетчика в 1с.

[количество тарифов 1-3] - число - 1 (неотрицательное) - количество видов тарифов (тарифность).

[дата показания] - дата - дата показания.

[дневное показание] - число - 18,6 (неотрицательное) - показание по дневному виду тарифа.

[ночное показание] - число - 18,6 (неотрицательное) - показание по ночному виду тарифа.

[пиковое показание] - число - 18,6 (неотрицательное) - показание по пиковому виду тарифа

Запросы.

Доступные REST API сервиса

Политика безопасности сервиса поддерживает 3 роли: неавторизованный пользователь (*), авторизованный пользователь (authenticated), авторизованный пользователь с правами администратора (admin).

Все REST API поддерживают формы отправки: GET и POST.

POST-запрос отправляется в кодировке application/x-www-form-urlencoded. Данные для передачи добавляются в body запроса.

Список API доступных неавторизованному пользователю (*):

/auth/login?login=<логин>&password=<пароль> - авторизация

Список API доступных авторизованному пользователю (authenticated):

/auth/login?login=<логин>&password=<пароль> - авторизация
/auth/logout - завершение авторизованной сессии
/users/update?login=<новый логин>&password=<новый пароль> - обновление данных своего профиля (может поменять только свой логин и пароль)
GET /rarus?<фильтрация, пейджинг, сортировка (подробнее тут)> - получение данных о показаниях ПУ
POST /rarus <данные в описанном выше формате> - отправка данных на сервис

Список API доступных авторизованному пользователю с правами администратора (admin):

/auth/login?login=<логин>&password=<пароль> - авторизация
/auth/logout - завершение авторизованной сессии
/users/create?login=<логин нового пользователя>&password=<пароль нового пользователя> - создание нового пользователя
/users/get?login=<идентификатор пользователя> - получить данные пользователя (пароли отображаются открытом виде)
/users/update?login=<идентификатор пользователя>&password=<новый пароль>&admin=<необязательный параметр, true, если нужно установить права admin> - обновление данных профиля пользователей
/users/destroy?login=<идентификатор пользователя> - удаление профиля пользователей
/meters?<фильтрация, пейджинг, сортировка (подробнее тут)> - получить данные всех счётчиков
/meters/update/<идентификатор счётчика>?<ключ обновляемого поля>=<значение> - изменение данных счётчика
/meters/destroy?id=<идентификатор счётчика> - удаление данных счётчика
/accounts?<фильтрация, пейджинг, сортировка (подробнее тут)> - получить данные аккаунтов сервиса
/accounts/destroy?id=<идентификатор аккаунта> - удаление данных аккаунта
GET /rarus?<фильтрация, пейджинг, сортировка (подробнее тут)> - получение данных о показаниях ПУ
POST /rarus <данные в описанном выше формате> - отправка данных на сервис

1) Авторизация

Запрос:

<адрес cервера>/auth/login?login=<логин>&password=<пароль>[ &referal=<идентификатор реферала, опционально>]

Ответы:

200, {success:true} - авторизация прошла успешно

400, {success:false, msg:”Check login/password” } - логин или пароль записаны неверно или отсутствуют.

401, {success:false, msg:”Invalid password”} - пароль введён не верно

404, {success:false, msg:“User not found”} - пользователь не определен

500, {success:false, msg:”Internal Server Error”}

Также можно авторизоваться добавив к запросу параметр с ключом token и значением <закодированная строка>.

Пример: https://<адрес сервера>/rarus?token=cmFydXM6cmFydXM=

Завершение авторизованной сессии устанавливается следующим образом:

Запрос:

<адрес сервера>/auth/logout

Ответы:

200, {success:true} - авторизованная сессия успешно завершена

2) Загрузка данных о показаниях ПУ с сервиса

Параметры:

date (дата и время) - отбираются записи, сформированные позднее или равные этой дате

Запрос:

GET

<адрес сервера>/rarus<фильтрация, пейджинг, сортировка (подробнее тут)>

При отправке запроса следует сначала авторизоваться и сохранить куки.

Примеры:

https://<адрес cервера>/rarus?where={“date”:{“>=”:”2016-04-01T09:12:57.571Z”}}

https://<адрес cервера>/rarus?limit=40&skip=200&sort=service DESC

https://<адрес cервера>/rarus?where={“name”:”foo”}

Ответы:

200, {success:true, data:[{...},{...}...]}- успешный запрос, данные отправлены

400, {success:false, msg:“Bad request”} - некорректны параметры запроса

401, {success:false, msg:”Authentification required”} - следует авторизоваться

3) Выгрузка данных на сервис

Параметры:

accs - в параметр добавляются передаваемые данные для выгрузки в json формате

Запрос:

POST

<адрес сервера>/rarus

POST-запрос в кодировке application/x-www-form-urlencoded. Данные для передачи добавляются в body запроса.

При отправке запроса аккаунты и счётчики у которых не задан id будут созданы, остальные аккаунты и счётчики будут обновлены. Счётчики, у которых параметр “date” раньше того, который уже находится в базе обновлены не будут.

При отправке запроса следует сначала авторизоваться и сохранить куки.

Пример: https://<адрес cервера>/rarus В body по ключу data лежат данные:

{

"accs": [

{"meters": [

{

"name": "ууууууууууууууууууууууууу",

"values": 3,

"capacity": 22,

"service": "1112222",

"date": "2016-07-01T11:29:19.904Z",

"val1": "3.123132",