Сервисы ЖКХ: Автообзвон должников и ЖКХ: Автоматический прием показаний счетчиков можно подключить к любой программе, для этого можно использовать 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 (неотрицательное) - показание по пиковому виду тарифа
Запросы.
Политика безопасности сервиса поддерживает 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",
"val2": "23.123132",
"val3": "2342.123132"
},
{
"name": "sdf",
"values": 1,
"capacity": 22,
"service": "Газы",
"date": "2014-07-26T11:29:19.904Z",
"val1": "3.123132",
"val2": "23.123133",
"val3": "2342.123133"
}
],
"address": {"street": "Ивана Крыли", "house": "55", "apartment": 2 },
"debt": { "sum_of_debt": "15.23", "months_of_debt_count": 1333, "last_payment_date": "2016-06-26T13:29:19.904Z"},
"number": "5"
},
{
"meters": [
{
"name": "hjk",
"values": 3,
"capacity": 22,
"service": "Водя",
"date": "2016-07-02T11:29:19.904Z",
"val1": "3.123132",
"val2": "23.123132",
"val3": "2342.123132"
},
{
"id": "17b04ef0-aa78-4e88-8dab-49b1bafc09cd",
"name": "sdf",
"values": 1,
"capacity": 22,
"service": "Газы",
"date": "2014-07-26T11:29:19.904Z",
"val1": "3.123132",
"val2": "23.123133",
"val3": "2342.123133"
}
],
"address": {"street": "Ивана Крыля", "house": "33","apartment": 2 },
"debt": {"sum_of_debt": "15.23","months_of_debt_count": 1333, "last_payment_date": "2016-06-26T13:29:19.904Z"},
"number": "2"
}
],
"sum_of_debt": 1234.00,
"count_months": 5
}
Ответы:
200, {success:true} - успешный запрос, данные отправлены
400, {success:false, msg:”Data is required”} - не указан параметр data
400, {success:false, msg:”<Сообщение об ошибке>”} - обработка других ошибок.