Аутентификация
В http запросе должен быть header Authorization: Bearer @token, где @token - заранее полученный partner_hash
Методы отправки HTTP запросов
- POST для отправки данных для последующей обработки на сервере
- GET для получения информации
Коды ошибок
- 200, все ок, сервер обработал запрос успешно
- 401, не авторизованные действия
- 405, сервис уже занят обработкой запроса по указанном в Authorization Header @token
- 500, ошибка на стороне сервера
Ограничения
Сервис отбивает запросы в нескольких потоках с ошибкой «data is already being processed with this partner_hash» и 405 http code, для загрузки данных требуется использовать только один поток. При получении ошибки с http code = 405, требуется либо сократить размер передаваемых данных в JSON либо повторить данную операцию позже, после того как сервис обработает предыдущий запрос.
Рекомендуемая методика отправки данных на сервер
Рекомендуется отправлять POST запросы порциями/пачками по 500 записей в массиве, например если необходимо загрузить 10 000 лицевых счетов, рекомендуется формировать JSON по 500 позиций внутри за одну итерацию и загружать данные последовательно (после получения http code 200 приступать к загрузке следующих 500 лицевых счетов), если необходимо загрузить 10 000 приборов учета, рекомендуется формировать JSON по 500 позиций внутри за одну итерацию и загружать данные последовательно (после получения http code 200 приступать к загрузке следующих 500 приборов учета)
Не рекомендуется загружать данные в нескольких потоках, если сервис занят обработкой какого либо запроса по @token то на параллельные запросы с указанным @token в Authorization Header сервис будет возвращать ошибку «data is already being processed with this partner_hash» и 405 http code
Роутер
Лицевые счета
Получить список лицевых счетов
GET domain.ru/billacc
// Ответ 200/ok [ { "ai_id": "400190", "account_num": "666yyy", "address_type": null, "address_str": "Луначарского 240 к2 кв 13", "partner_hash": "2c254b10816d6445cc7205fgdfgshjgdshjfgsd7f9a3f6", "ext_id": null, "is_deleted": "N", "secret": "secret_oico", "phones": null }, { "ai_id": "2", "account_num": "00000286002", "address_type": null, "address_str": "Шушары, Московское ш, д. 286 литер А, 2", "partner_hash": "2c254bdshkfg324324dfds5cc7205f7f9a3f6", "ext_id": null, "is_deleted": "N", "secret": null, "phones": "9231234567;9231234568" }, ] // ai_id - идентификатор ЛС // account_num - номер ЛС // address_type - тип адреса к которому привязан ЛС // address_str - адрес к которому привязан ЛС // is_deleted - признак удаления ЛС Y/N // secret - код верификации // phones - номера телефонов, для которых доступно добавление ЛС
Передать список лицевых счетов
POST domain.ru/billacc
// Запрос [ { "account_num": "00024xxГП", "address_str": "г Екатеринбург, Амундсена д.1б, кв.1500", "phones": "9231234567;9231234568", "is_deleted": "Y" }, { "account_num": "00025xgГП", "address_str": "г Екатеринбург, Амундсена д.1б, кв.1501", "secret":"secret_verify_code", "is_deleted": "N" } ] // @account_num | String | - номер лицевого счета. Обязательный ключ. // @address_str | String | - Адрес. Не обязательный ключ. Но именно этот адрес затем будет указан в реестрах с оплатами и чеках. // @phones | String | - Не обязательный ключ. Список номеров телефона для которых доступно добавление лицевого счета // @secret | String | - Не обязательный ключ. Код для верификации ЛС. // Ответ 200/ok { "ok": "true", "processed_items": 1 }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
Изменить данные лицевого счета
POST domain.ru/billacc/:ai_id
// Запрос [ { "account_num": "00024xxГП", "address_str": "г Екатеринбург, Амундсена д.1б, кв.1500", "phones": "9231234567;9231234568", "secret":"secret_verify_code", "is_deleted": "N" } // @ai_id - идентификатор лицевого счета для обновления // @account_num | String | - номер лицевого счета. // @address_str | String | - Адрес. Именно этот адрес затем будет указан в реестрах с оплатами и чеках. // @phones | String | - Список номеров телефона для которых доступно добавление лицевого счета // @secret | String | - Код для верификации ЛС. // @is_deleted | String | - Может принимать значения Y/N. Признак того что ЛС удален. // Ответ 200/ok { "ok": "true" }
Передать информацию о состоянии лицевых счетов
POST domain.ru/bills/debt
// Запрос { "date": "2020-10-03", // Так же можно передать время "date": "2020-10-03 12:34:02" "trans_type": 1, "data": [ { "account_num": "00026xgГП", "end_amount": "102.00", "last_pay_amount": 20, "last_pay_date": "2022-03-22", // можно со временем "2022-03-22 23:55:44" "details": [], "is_deleted": "N" }, { "account_num": "00026xgГП", "end_amount": "50.00", "details": [] }, { "account_num": "00027xgГП", "end_amount": "208.00", "details": [ { "service_name": "Горячая вода", "price": "7.00", "quantity": "2.00 м3", "amount": "14.00" }, { "service_name": "Холодная вода", "price": "4.00", "quantity": "1.50 м3", "amount": "6.00" } ] } ] } // @date | String YYYY-DD-MM либо YYYY-DD-MM HH24:mi:ss | - Дата. Обязательный ключ. // @trans_type | Numeric | - Тип начисления. Необязательный ключ. Если не передать, то начисление - ЖКУ // Варианты значений: 1 - ЖКУ, 2 - Страховка, 8 - Капитальный ремонт, 102 - Пени // @data | Array | - Массив с объектами c информацией о состоянии ЛС. Обязательный ключ // @account_num | String | - Номер ЛС. Обязательный ключ. // @end_amount | Numeric (38,2) | - Задолженность. Обязательный ключ // @last_pay_amount | Numeric (38,2) | - Сумма последнего платежа. Необязательный ключ, // @last_pay_date | String | - Дата последнего платежа. Необязательный ключ. // @details: | Array | - Массив с деталями начисления. Необязательный ключ // @service_name | String | - Наименование услуги. Обязательный ключ // @price | Numeric (38,2) | - Тариф. Необязательный ключ // @quantity | String | - Объем. Необязательный ключ // @amount | Numeric (38,2) | - Цена. Обязательный ключ // Ответ 200/ok { "ok": "true", "processed_items": 3, "processed_details": 2 }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
Получить список начислений/проводок за последние 3 месяца
GET domain.ru/bills
// Ответ 200/ok [ { "account_num": "00025xgГП", "trans_month": "2022-01-01", "trans_date": "2022-01-30T00:00:00", "start_amount": "100.00", "pay_amount": "0.00", "calc_amount": "14.00", "end_amount": "114.00" "trans_type": "1", "trans_type_str": "ЖКУ", "is_deleted": "N", "details": [ { "service_name": "Горячая вода", "price": "7.00", "quantity": "2.00 м3", "amount": "14.00" } ] }, { "account_num": "00026xgГП", "trans_month": "2022-01-01", "trans_date": "2022-01-30T00:00:00", "start_amount": "200.00", "pay_amount": "0.00", "calc_amount": "20.00", "end_amount": "220.00" "trans_type": "1", "trans_type_str": "ЖКУ", "is_deleted": "Y", "details": [ { "service_name": "Горячая вода", "price": "7.00", "quantity": "2.00 м3", "amount": "14.00" }, { "service_name": "Холодная вода", "price": "4.00", "quantity": "1.50 м3", "amount": "6.00" } ] } ]
Передать список бухгалтерских проводок
POST domain.ru/bills/accounting
//Запрос [ { "account_num": "00025xgГП", "trans_month": "2020-10-01", "trans_date": "2020-10-03", // Так же можно передать время "trans_date": "2020-10-03 12:34:02" "start_amount": "100.00", "pay_amount": "0.00", "calc_amount": "14.00", "end_amount": "114.00", "trans_type": "1", "last_pay_amount": 20, "last_pay_date": "2022-03-22", // можно со временем "2022-03-22 23:55:44" "details": [ { "service_name": "Горячая вода", "price": "7.00", "quantity": "2.00 м3", "amount": "14.00" } ] }, { "account_num": "00026xgГП", "trans_month": "2020-10-01", "trans_date": "2020-10-03", // Так же можно передать время "trans_date": "2020-10-03 12:34:02" "start_amount": "200.00", "pay_amount": "0.00", "calc_amount": "20.00", "end_amount": "220.00" "details": [ { "service_name": "Горячая вода", "price": "7.00", "quantity": "2.00 м3", "amount": "14.00" }, { "service_name": "Холодная вода", "price": "4.00", "quantity": "1.50 м3", "amount": "6.00" } ] } ] // body(Тело запроса)| Array | - Тело запроса - массив с бухгалтерскими проводками. // @account_num | String | - Номер ЛС. Обязательный ключ. // @trans_month | String YYYY-MM-01 | - Месяц задолженности. Необязательный ключ. // @trans_date | String YYYY-MM-DD либо YYYY-MM-DD HH24:mi:ss| - Дата начисления(совершения операции). Обязательный ключ // @start_amount | Numeric (38,2) | - Сальдо начальное. Обязательный ключ // @pay_amount | Numeric (38,2) | - Платеж. Обязательный ключ // @calc_amount | Numeric (38,2) | - Начисление. Обязательный ключ // @end_amount | Numeric (38,2) | - Сальдо конечное. Обязательный ключ // @trans_type | Numeric | - Тип начисления. Необязательный ключ. Если не передать, то начисление - ЖКУ // Варианты значений: 1 - ЖКУ, 2 - Страховка, 8 - Капитальный ремонт, 102 - Пени // @last_pay_amount | Numeric (38,2) | - Сумма последнего платежа. Необязательный ключ, // @last_pay_date | String | - Дата последнего платежа. Необязательный ключ. // @details: | Array | - Массив с деталями начисления. Необязательный ключ // @service_name | String | - Наименование услуги. Обязательный ключ // @price | Numeric (38,2) | - Тариф. Необязательный ключ // @quantity | String | - Объем. Необязательный ключ // @amount | Numeric (38,2) | - Цена. Обязательный ключ // Ответ 200/ok { "ok": "true" "processed_items": 2, "processed_details": 3 }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
Обновить/создать начисление
POST domain.ru/bills/update/calc
//Запрос [ { "account_num": "00025xgГП", "trans_month": "2020-10-01", "trans_date": "2020-10-03", // Так же можно передать время "trans_date": "2020-10-03 12:34:02" "start_amount": "100.00", "pay_amount": "0.00", "calc_amount": "14.00", "end_amount": "114.00", "trans_type": "1", "last_pay_amount": 20, "last_pay_date": "2022-03-22", // можно со временем "2022-03-22 23:55:44" "details": [ { "service_name": "Горячая вода", "price": "7.00", "quantity": "2.00 м3", "amount": "14.00" } ] } ] // body(Тело запроса)| Array | - Тело запроса - массив с бухгалтерскими проводками. // @account_num | String | - Номер ЛС. Обязательный ключ. // @trans_month | String YYYY-MM-01 | - Месяц задолженности. Необязательный ключ. // @trans_date | String YYYY-MM-DD либо YYYY-MM-DD HH24:mi:ss| - Дата начисления(совершения операции). Обязательный ключ // @start_amount | Numeric (38,2) | - Сальдо начальное. Обязательный ключ // @pay_amount | Numeric (38,2) | - Платеж. Обязательный ключ // @calc_amount | Numeric (38,2) | - Начисление. Обязательный ключ // @end_amount | Numeric (38,2) | - Сальдо конечное. Обязательный ключ // @trans_type | Numeric | - Тип начисления. Необязательный ключ. Если не передать, то начисление - ЖКУ // Варианты значений: 1 - ЖКУ, 2 - Страховка, 8 - Капитальный ремонт, 102 - Пени // @last_pay_amount | Numeric (38,2) | - Сумма последнего платежа. Необязательный ключ, // @last_pay_date | String | - Дата последнего платежа. Необязательный ключ. // @details: | Array | - Массив с деталями начисления. Необязательный ключ // @service_name | String | - Наименование услуги. Обязательный ключ // @price | Numeric (38,2) | - Тариф. Необязательный ключ // @quantity | String | - Объем. Необязательный ключ // @amount | Numeric (38,2) | - Цена. Обязательный ключ // Ответ 200/ok { "ok": "true" "processed_items": 2, "processed_details": 3 }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
- Начислением не считается объект, в котором calc_amount = 0, start_amount = 0, end_amount = 0, pay_amount > 0. Проверки на стороне сервера на это нет. Попытки передачи таких начислений приведут к неконсистентности данных.
- trans_date будет записан при первичной записи начисления и не будет обновляться при повторной записи.
—-
Обновить/создать платежи
POST domain.ru/bills/update/pays
//Запрос [{ "trans_date": "2022-11-11", "account_num": "123", "trans_type": "1", "pays": [{ "pay_date": "2022-11-11", "pay_amount": 1000 }, { "pay_date": "2022-11-12", "pay_amount": 1000 }] }] // body(Тело запроса)| Array | - Тело запроса - массив с бухгалтерскими проводками. // @account_num | String | - Номер ЛС. Обязательный ключ. // @trans_date | String YYYY-MM-DD либо YYYY-MM-DD HH24:mi:ss| - Дата для поиска начисления. Должна быть равна дате начисления + 1 день. Обязательный ключ // @trans_type | Numeric | - Тип начисления. Необязательный ключ. Если не передать, то начисление - ЖКУ // Варианты значений: 1 - ЖКУ, 2 - Страховка, 8 - Капитальный ремонт, 102 - Пени // @pays: | Array | - Массив с платежами Необязательный ключ // @pay_date | String YYYY-MM-DD либо YYYY-MM-DD HH24:mi:ss| - Дата для поиска начисления. Должна быть равна дате начисления + 1 день. Обязательный ключ // @pay_amount | Numeric (38,2) | - Сумма платежа. Обязательный ключ // Ответ 200/ok { "ok": "true" "processed_items": 1, "processed_pays": 2 }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
- trans_date передается для поиска начисления. Если начисление не было найдено - платежи все-равно запишутся. Но, если запрос был сделан с целью корректировки платежей, то предыдущие загруженные платежи не удалятся и это действие сгенерирует дубли. Т.е. необходимо для консистентсности данных передавать платежи всегда с trans_date = trans_date начисления + 1 день
Удалить бухгалтерские проводки/балансы/начисления
DEL domain.ru/bills?account_num=xxx&from=2022-01-01&to=2022-01-02
// Необязательные параметры account_num (фильтр по лицевому счету), from, to (фильтры по датам от/до) // Ответ 200/ok { "ok": "true" }
—
Получить суммы начислений по услугам
GET domain.ru/bills/service_amount_sum?month=2022-01
GET domain.ru/bills/service_amount_sum?date=2022-01-28
Возвращает массив с услугами и суммами по ним. В выборку попадут детали последних переданных начислений, trans_date которых либо равен date (YYYY-MM-DD) из query параметра, либо находится в пределах месяца month (YYYY-MM)
// Ответ [ { "service_name": "Водоотведение", "amount": "334.00" }, { "service_name": "Добровольное страхование", "amount": "335.05" }, { "service_name": "Отопление", "amount": "66.00" }, { "service_name": "Теплоэнергия для нужд ГВС", "amount": "0.00" }, { "service_name": "Управление, содержание и ремонт общего имущества", "amount": "57567.00" }, { "service_name": "Управление, содержание и ремонт общего имущества застройщик", "amount": "56.00" } ]
Счетчики (ИПУ)
Получить список ИПУ
При передаче параметра account_num будет возвращен список ИПУ для указанного ЛС. Если параметр account_num не передавался, будет возвращен список всех ИПУ для партнера
Для пагинации необходимо передать параметры limit и offset. Если параметры не переданы значение limit по умолчанию:1000.
GET domain.ru/meter?account_num=007&limit=10&offset=0&is_deleted=N&address=any_address&flat=13&search=search_string&factory_num=123&phone=9126630539,meter_id=cf39767b-7961-466a-8bfa-c7a042bf6ee1
// Ответ 200/ok [ { meter_id: 'cf39767b-7961-466a-8bfa-c7a042bf6ee1', service_str: 'Электроэнергия', factory_num: '1-2/345', deleted_on_tz: null, install_place_str: 'Коридор', created_on_tz: '2021-10-18T06:23:45.545Z', account_num: '007', is_take: 'Y', verify_date: null, ph_id: '1', ext_id:'1', current_val: 100.25, current_val2: 103, current_val3: 104.25, current_val_date: '2021-10-17T19:00:00.000Z', last_val: 90, last_val2: 91, last_val3: 92, last_val_date: '2021-10-16T19:00:00.000Z', meter_type: '3', address: 'Москва г, Василисы Кожиной ул, дом № 13, Апарт. 2460', phone: '9126630539', record : 'http://record.com' }, { meter_id: '932803d4-5319-49bb-9c49-42b084558b20', service_str: 'Горячая вода', factory_num: '1-1/456', deleted_on_tz: null, install_place_str: 'Кухня', created_on_tz: '2021-10-18T06:23:45.545Z', account_num: '007', is_take: 'Y', verify_date: null, ph_id: '1', ext_id: null, current_val: 123, current_val2: null, current_val3: null, current_val_date: null, last_val: 321, last_val2: null, last_val3: null, last_val_date: null, meter_type: '1' address: 'Москва г, Василисы Кожиной ул, дом № 13, Апарт. 2460', phone: '9126630539', record : 'http://record.com' } ] /* meter_id - уникальный идентификатор ИПУ service_str - Название услуги. Например: "Электроэнергия" factory_num - Заводской номер прибора учета account_num - Лицевой счет жителя использующего ИПУ verify_date - Дата поверки ИПУ is_take - Возможность передачи показаний Y/N install_place_str - Место установки ИПУ created_on_tz - Дата добавления счетчика current_val - Последние показания счетчика от жителя (тариф 1) current_val2 - Последние показания счетчика от жителя (тариф 2) current_val3 - Последние показания счетчика от жителя (тариф 3) current_val_date - Дата последнего показания счетчика от жителя last_val - Последние показания счетчика от УК (тариф 1) last_val2 - Последние показания счетчика от УК (тариф 2) last_val3 - Последние показания счетчика от УК (тариф 3) last_val_date - Дата последнего показания счетчика от УК ext_id - Идентификатор ИПУ в системе партнера meter_type - К-во тарифов счетчика phone - телефон, с которого передали последнее показание record - запись разговора кц при передаче последнего показания */
Добавить ИПУ
POST domain.ru/meter Если в запросе передали ext_id и счетчик с таким ext_id уже существует, то данные счетчика будут обновлены в соответствии с переданными полями. Если счетчика с указанным ext_id не найдено - он будет создан. Пример запроса:
{ "service_str": "ХВС", "factory_num": "777-x/124", "install_place_str": "Ванная", "account_num": "123", "verify_date": "2024-10-01", "ext_id":"123-x-1", "is_take":"Y", "is_deleted":"N", "meter_type": "2", "val_name": "val_name", "val2_name": "val2_name", "val3_name": "val3_name", "values":[ { "val":90, "val2":91, "val_date":"2021-11-28", }, { "val":80, "val2":93, "val_date":"2021-11-26", "phone": "9126630539", "record" : "http://record.com" }, { "val":60, "val2":95, "val_date":"2021-11-25" "is_deleted": "Y" } ] /* service_str - Название услуги. Например: "Электроэнергия" factory_num Заводской номер прибора учета. account_num - Лицевой счет жителя использующего ИПУ verify_date - Дата поверки ИПУ is_take - Возможность передачи показаний Y/N is_deleted - Y/N признак того что счетчик удален. При передаче "Y" для соответствующего ext_id можно отметить счетчик удаленным meter_type - К-во тарифов счетчика (если не передать, значение по умолчанию 1) val_name - Наименование первого тарифа val2_name - Наименование второго тарифа val3_name - Наименование третьего тарифа values - массив с показаниями по счетчику val - значение показания (тариф 1) val2 - значение показания (тариф 2) val3 - значение показания (тариф 3) val_date - дата показания is_deleted - Y/N признак того что показание удалено. При передаче is_deleted "Y" переданное показание для указанного счетчика будет отмечено удаленным phone - телефон, с которого последнее показание record - запись разговора кц при передаче показания */
Пример запроса для массового добавления счетчиков:
[ { "service_str": "ХВС", "factory_num": "777-x/124", "install_place_str": "Ванная", "account_num": "123", "is_take":"Y" }, { "service_str": "ГВС", "factory_num": "777-x/125", "install_place_str": "Ванная", "account_num": "123", "meter_type": "3", "is_take":"Y", "values":[ { "val":90, "val2":91, "val3":92, "val_date":"2021-11-28", "phone": "9126630539", "record" : "http://record.com" }, { "val":80, "val2":81, "val3":82, "val_date":"2021-11-26", "phone": "9126630539", "record" : "http://record.com" } ] } ]
Пример успешного ответа:
{ "ok": "true", "processed_items": 2 }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения) Если в запросе более 500 позиций, сервис после обработки первых 500 позиций отдаст http code 200, но при этом продолжит обрабатывать переданные данные, на последующие запрос по указанному в Authorization header @token сервис будет отдавать ошибку 405 до тех пор, пока не закончит обработку переданных ранее данных. (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
Пример ответа при ошибке добавления ИПУ:
{ ok: false, message: 'Failed when adding meter with factory_num 777-x/124' }
Изменить данные ИПУ
PUT domain.ru/meter/:meter_id meter_id - уникальный ID ИПУ
Пример запроса PUT domain.ru/meter/3156dadb-8b78-4cf2-a6d8-d41dcf7a8c96
{ "service_str": "ГВС", "account_num": "111xxx", "val_name": "val_name", "val2_name": null }
Пример успешного ответа:
{ ok: true }
Пример ответа при ошибке изменения ИПУ:
{ ok: false, message: 'Failed when updating meter' }
Удалить ИПУ
DELETE domain.ru/meter/:meter_id meter_id - уникальный ID ИПУ
DELETE domain.ru/meter/3156dadb-8b78-4cf2-a6d8-d41dcf7a8c96
Пример успешного ответа:
{ ok: true }
Пример ответа при ошибке удаления ИПУ:
{ ok: false, message: 'Failed when deleting meter' }
Получить показания по всем ИПУ
GET domain.ru/meter/values?is_user=Y&account_num=111&limit=10&offset=0&from='2022-01-01'&to='2022-01-02'&meter_id=8014680b-6453-4633-b235-d2d7579ee867
Параметр is_user позволяет получить только те показания, которые были переданы жителем
Параметр account_num позволяет получить все показания ИПУ, привязанных к указанному ЛС
Для пагинации необходимо передать параметры limit и offset. Если параметры не переданы значение limit по умолчанию:1000.
// Ответ 200/ok [ { "meter_id": "aff11d4f-ca3e-440c-8645-6b42d5eca93d", "ext_id": "d681f2be-9b78-11eb-9189-0050569a3d24", "account_num": "1000202037602", "is_user": "Y", "val": "658.7000", "val2": null, "val3": null, "val_date": "2022-06-25", "created_on_tz": "2022-06-25T20:53:10.779Z", "phone": "9281043030", "record": "http://record.com", "val_name": "val_name", "val2_name": null, "val3_name": null, }, { "meter_id": "d8b5cec1-ca84-4ad0-9bf7-02ee386b67c0", "ext_id": "c7cd1d5c-9b78-11eb-9189-0050569a3d24", "account_num": "1000202037602", "is_user": "Y", "val": "23.0000", "val2": null, "val3": null, "val_date": "2022-06-25", "created_on_tz": "2022-06-25T20:52:54.687Z", "phone": "9281043030", "record": "http://record.com", "val_name": "val_name", "val2_name": null, "val3_name": null, }, ] /* meter_id - Уникальный идентификатор ИПУ ext_id - Уникальный идентификатор ИПУ в интеграционной бд is_user - Признак передачи показания жителем Y/N val - Значение показания (тариф 1) val2 - Значение показания (тариф 2) val3 - Значение показания (тариф 3) val_date - Дата показания val_name - Наименование первого тарифа val2_name - Наименование второго тарифа val3_name - Наименование третьего тарифа phone - телефон, с которого последнее показание record - запись разговора кц при передаче показания */
Получить последнее показание по всем ИПУ
GET domain.ru/meter/values/last?is_user=Y&account_num=111&limit=10&offset=0&from='2022-01-01'&to='2022-01-02'&meter_id=8014680b-6453-4633-b235-d2d7579ee867
Параметр is_user позволяет получить только те показания, которые были переданы жителем
Параметр account_num позволяет получить все показания ИПУ, привязанных к указанному ЛС
Для пагинации необходимо передать параметры limit и offset. Если параметры не переданы значение limit по умолчанию:1000.
// Ответ 200/ok [ { "meter_id": "aff11d4f-ca3e-440c-8645-6b42d5eca93d", "ext_id": "d681f2be-9b78-11eb-9189-0050569a3d24", "account_num": "1000202037602", "is_user": "Y", "val": "658.7000", "val2": null, "val3": null, "val_date": "2022-06-25", "created_on_tz": "2022-06-25T20:53:10.779Z", "phone": "9281043030", "record": "http://record.com" }, { "meter_id": "d8b5cec1-ca84-4ad0-9bf7-02ee386b67c0", "ext_id": "c7cd1d5c-9b78-11eb-9189-0050569a3d24", "account_num": "1000202037602", "is_user": "Y", "val": "23.0000", "val2": null, "val3": null, "val_date": "2022-06-25", "created_on_tz": "2022-06-25T20:52:54.687Z", "phone": "9281043030", "record": "http://record.com" }, ] /* meter_id - Уникальный идентификатор ИПУ ext_id - Уникальный идентификатор ИПУ в интеграционной бд is_user - Признак передачи показания жителем Y/N val - Значение показания (тариф 1) val2 - Значение показания (тариф 2) val3 - Значение показания (тариф 3) val_date - Дата показания phone - телефон, с которого последнее показание record - запись разговора кц при передаче показания */
Добавить показания по нескольким ИПУ
POST domain.ru/meter/values
Пример запроса POST domain.ru/meter/values
[ { "meter_id": "e43965d1-a43d-44c7-9320-e0653d9163d2" "val": 100500, "val_date": "2021-10-18T07:44:33.553Z", "is_user": "N" }, { "ext_id": "x6256389" "val": 100400, "va2": 100401, "val3": 100402, "val_date": "2021-09-18T07:44:33.553Z", "is_user": "N", "phone": "9126630539", "record" : "http://record.com" }, ] /* meter_id - Уникальный идентификатор ИПУ val - Значение показания (тариф 1) val2 - Значение показания (тариф 2) val3 - Значение показания (тариф 3) val_date - Дата показания is_user - Признак передачи показания жителем Y/N phone - телефон, с которого последнее показание record - запись разговора кц при передаче показания */
Пример успешного ответа:
{ ok: true }
ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
Пример ответа при ошибке добавления показания:
{ ok: false, message: 'Failed when add meter value for meter e43965d1-a43d-44c7-9320-e0653d9163d2' }
Добавить показания для конкретного ИПУ
POST domain.ru/meter/:meter_id/values
meter_id - Уникальный идентификатор ИПУ
Пример запроса POST domain.ru/meter/e43965d1-a43d-44c7-9320-e0653d9163d2/values
{ "val": 100500, "val2": 100501, "val_date": "2021-10-18T07:44:33.553Z", "is_user": "N", "phone": "9126630539", "record" : "http://record.com" } /* val - Значение показания (тариф 1) val2 - Значение показания (тариф 2) val3 - Значение показания (тариф 3) val_date - Дата показания is_user - Признак передачи показания жителем Y/N phone - телефон, с которого последнее показание record - запись разговора кц при передаче показания */
Пример успешного ответа:
{ ok: true }
Пример ответа при ошибке добавления показания:
{ ok: false, message: 'Failed when add meter value for meter e43965d1-a43d-44c7-9320-e0653d9163d2' }
Методы для работы с ИПУ по ext_id
Получить детали ИПУ
GET domain.ru/meter/ext/:ext_id ext_id - ID ИПУ в системе партнера
Пример запроса GET domain.ru/meter/ext/1
// Ответ 200/ok [ { meter_id: 'cf39767b-7961-466a-8bfa-c7a042bf6ee1', service_str: 'Электроэнергия', factory_num: '1-2/345', deleted_on_tz: null, install_place_str: 'Коридор', created_on_tz: '2021-10-18T06:23:45.545Z', account_num: '007', is_take: 'Y', verify_date: null, ph_id: '1', ext_id:'1', current_val: 100.25, current_val2: 102.25, current_val3: null, current_val_date: '2021-10-17T19:00:00.000Z', last_val: 90, last_val: 91, last_val: null, last_val_date: '2021-10-16T19:00:00.000Z', meter_type : 2, val_name: "val_name", val2_name: "val2_name", val3_name: null } ] /* meter_id - уникальный идентификатор ИПУ service_str - Название услуги. Например: "Электроэнергия" factory_num - Заводской номер прибора учета account_num - Лицевой счет жителя использующего ИПУ verify_date - Дата поверки ИПУ is_take - Возможность передачи показаний Y/N install_place_str - Место установки ИПУ created_on_tz - Дата добавления счетчика current_val - Последние показания счетчика (тариф 1) current_val2 - Последние показания счетчика (тариф 2) current_val3 - Последние показания счетчика (тариф 3) current_val_date - Дата последнего показания счетчика last_val - Предыдущие показания счетчика last_val_date - Дата предыдущих показаний счетчика ext_id - Идентификатор ИПУ в системе партнера meter_type - к-во тарифов счетчика val_name - Наименование первого тарифа val2_name - Наименование второго тарифа val3_name - Наименование третьего тарифа */
Изменить данные ИПУ
PUT domain.ru/meter/ext/:ext_id ext_id - ID ИПУ в системе партнера
Пример запроса PUT domain.ru/meter/ext/1
{ service_str: "ГВС" }
Пример успешного ответа:
{ ok: true }
Пример ответа при ошибке изменения ИПУ:
{ ok: false, message: 'Failed when updating meter' }
Удалить ИПУ
DELETE domain.ru/meter/ext/:ext_id ext_id - ID ИПУ в системе партнера
Пример успешного ответа:
{ ok: true }
Пример ответа при ошибке удаления ИПУ:
{ ok: false, message: 'Failed when deleting meter' }
Добавить показания для конкретного ИПУ
POST domain.ru/meter/ext/:ext_id/values ext_id - ID ИПУ в системе партнера
Пример запроса POST domain.ru/meter/1/values
[{ val: 100500, val2: 100501, val_date: '2021-10-18T07:44:33.553Z', is_user: 'N' }] /* val - Значение показания (тариф 1) val2 - Значение показания (тариф 2) val3 - Значение показания (тариф 3) val_date - Дата показания is_user - Признак передачи показания жителем Y/N */
Пример успешного ответа:
{ ok: true }
Пример ответа при ошибке добавления показания:
{ ok: false, message: 'Failed when add meter value for meter 1' }
Получить показания по ext_id конкретного ИПУ
GET domain.ru/meter/ext/:ext_id/values?from='2022-01-01'&to='2022-01-02'
Параметр is_user позволяет получить все показания переданные жителем
Параметр account_num позволяет получить все показания ИПУ, привязанных к указанному ЛС
Для пагинации необходимо передать параметры limit и offset. Если параметры не переданы значение limit по умолчанию:1000.
// Ответ 200/ok [ { meter_id: '8014680b-6453-4633-b235-d2d7579ee867', is_user: 'Y', val: 10, val2: 11, val3: null, val_date: '2021-10-17T19:00:00.000Z' }, { meter_id: 'fea85cec-337b-43b2-800e-15a16e4fa697', is_user: 'Y', val: 100.25, val2: 12, val3: null, val_date: '2021-10-17T19:00:00.000Z' }, { meter_id: '8014680b-6453-4633-b235-d2d7579ee867', is_user: 'N', val: 9, val2: 11, val3: null, val_date: '2021-10-16T19:00:00.000Z' }, { meter_id: 'fea85cec-337b-43b2-800e-15a16e4fa697', is_user: 'N', val: 90, val2: 11, val3: null, val_date: '2021-10-16T19:00:00.000Z' }, { meter_id: '8014680b-6453-4633-b235-d2d7579ee867', is_user: 'N', val: 8, val2: 11, val3: 33, val_date: '2021-10-15T19:00:00.000Z' }, { meter_id: 'fea85cec-337b-43b2-800e-15a16e4fa697', is_user: 'N', val: 80, val2: null, val3: null, val_date: '2021-10-15T19:00:00.000Z' } ] /* meter_id - Уникальный идентификатор ИПУ is_user - Признак передачи показания жителем Y/N val - Значение показания (тариф 1) val2 - Значение показания (тариф 2) val3 - Значение показания (тариф 3) val_date - Дата показания */
Скачивание квитанций
Получить url для скачивания квитанции
Для получения url на скачивание квитанции в заголовке запроса authorization должен быть токен авторизации в base64.
В запросе должны присутствовать параметры account_num - номер ЛС year - год квитанции и month - месяц квитанции
Пример запроса:
GET domain.ru?account_num=001&year=2021&month=02
Пример ответа:
// Ответ 200/ok { "ok": true, "url": "http://domain.ru/53436fa8-3f6d-423q-947b-1506382fe7b" } /* url - публичный url для скачивания квитанции. Действителен в течение 15 мин. */
Обсуждение