Меню

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

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


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

    1. Веб-сервис — сервис приема показаний и автообзвона должников.

    2. 1С — конфигурация, подключающаяся к веб-сервису.

    3. Пользователь — управляющая организация, являющаяся пользователем веб-сервиса и 1C.

    4. Абонент — получатель услуг Пользователя.

    5. ПУ — прибор учёта.


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

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


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

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

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

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

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

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


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

    1. Лицевой счёт: идентификатор и номер.

    2. Адрес: улица, дом, квартира.

    3. Список ПУ. По каждому из них:

      1. идентификатор,

      2. наименование счетчика,

      3. тарифность,

      4. разрядность,

      5. услуга,

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

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

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


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

    1. Лицевой счёт: идентификатор.

    2. Список ПУ. По каждому из них:

      1. идентификатор,

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

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

      4. тарифность.


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

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

    2. {

      "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 (неотрицательное) - показание по пиковому виду тарифа

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

    4. [

         {

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

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

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

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

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

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

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

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

          }

      ]

      где:

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

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

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

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

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

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

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


  7. Запросы.


Доступные 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",

                   "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:”<Сообщение об ошибке>”} - обработка других ошибок.





Назад


Материалы по теме: