==== Аутентификация ====
В 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?limit=:limit&offset=:offset&account_num=:account_num&is_no_paper_invoice=:is_no_paper_invoice
// Ответ 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,
"is_exemption" : "N",
"is_no_paper_invoice": "N"
},
{
"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",
"is_exemption" : "Y",
"is_no_paper_invoice": "Y",
"locks": [ // Блокировка ЛС. Поле доступно, если в query передано account_num. Для расшифровки полей см раздел Блокировки.
{
"ail_id": "31",
"created_on_tz": "2025-05-15T09:07:37.211Z",
"updated_on_tz": "2025-05-15T09:41:49.803Z",
"partner_hash": "639959f4a1e37fe503843dcbd7e8a6e7",
"status": "0",
"lock_type": "2",
"func_arr": [
"camera",
"devaccess",
"visitor_human",
"visitor_auto",
"nocontact_entry",
"videophone"
],
"note": "Апрель 2025, должники",
"updated_by_username": "Столыпина Марина",
"acc_note": "У вас есть задолженность по оплате коммунальных услуг в размере: %сумма%. Оплатите её, чтобы восстановить доступ ко всем возможностям приложения.",
"items": [
{
"aili_id": "1139",
"ail_id": "31",
"account_num": "210618100357",
"phone": null,
"status": "0",
"updated_on_tz": "2025-05-15T09:36:58.904Z",
"updated_by_username": "Столыпина Марина",
"max_debt_amount": "20749.46"
}
]
}
]
},
]
// ai_id - идентификатор ЛС
// account_num - номер ЛС
// address_type - тип адреса к которому привязан ЛС
// address_str - адрес к которому привязан ЛС
// is_deleted - признак удаления ЛС Y/N
// is_exemption - признак льготного ЛС Y/N
// is_no_paper_invoice - признак отказа от бумажных квитанций Y(отказался от бум квитанций)/N(не отказался)
// secret - код верификации
// phones - номера телефонов, для которых доступно добавление ЛС
// @address_type | String | - Необязательный ключ. тип адреса может принимать значения null (по умолчанию) / "Квартира" / "Машиноместо" / "Нежилое помещение" / "Кладовка" / "Паркинг" / "Апартаменты" / "Офис", влияет на формирование сервисного счета для оплаты страховки
----
=== Передать список лицевых счетов ===
POST domain.ru/billacc
// Запрос
[
{
"account_num": "00024xxГП",
"address_str": "г Екатеринбург, Амундсена д.1б, кв.1500",
"phones": "9231234567;9231234568",
"is_deleted": "Y",
"is_exemption" : "Y",
"is_no_paper_invoice" : "N",
"address_type" : null
},
{
"account_num": "00025xgГП",
"address_str": "г Екатеринбург, Амундсена д.1б, кв.1501",
"secret":"secret_verify_code",
"is_deleted": "N",
"address_type" : "Квартира"
}
]
// @account_num | String | - номер лицевого счета. Обязательный ключ.
// @address_str | String | - Адрес. Необязательный ключ. Но именно этот адрес затем будет указан в реестрах с оплатами и чеках.
// @phones | String | - Необязательный ключ. Список номеров телефона для которых доступно добавление лицевого счета
// @secret | String | - Необязательный ключ. Код для верификации ЛС.
// @is_exemption | String | - Необязательный ключ. Признак льготного ЛС
// @address_type | String | - Необязательный ключ. тип адреса может принимать значения null (по умолчанию) / "Квартира" / "Машиноместо" / "Нежилое помещение" / "Кладовка" / "Паркинг" / "Апартаменты" / "Офис", влияет на формирование сервисного счета для оплаты страховки
// Ответ 200/ok
{
"ok": "true",
"processed_items": 1
}
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**
----
=== Передать информацию о состоянии лицевых счетов ===
POST domain.ru/bills/debt
// Запрос
{
"date": "2020-10-03", // Так же можно передать время "date": "2020-10-03 12:34:02"
"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",
"trans_type": 1
},
{
"account_num": "00026xgГП",
"end_amount": "50.00",
"details": [],
"trans_type": 8
},
{
"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-MM-DD либо YYYY-MM-DD HH24:mi:ss | - Дата. Обязательный ключ.
// @data | Array | - Массив с объектами c информацией о состоянии ЛС. Обязательный ключ
// @account_num | String | - Номер ЛС. Обязательный ключ.
// @end_amount | Numeric (38,2) | - Задолженность. Обязательный ключ
// @last_pay_amount | Numeric (38,2) | - Сумма последнего платежа. Необязательный ключ,
// @last_pay_date | String | - Дата последнего платежа. Необязательный ключ.
// @trans_type | Numeric | - Тип начисления. Необязательный ключ. Если не передать, то начисление - ЖКУ
// Варианты значений: 1 - ЖКУ, 2 - Страховка, 8 - Капитальный ремонт, 102 - Пени
// @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 мин.
*/
==== Блокировки лицевых счетов ====
=== Получить список блокировок ===
Пример запроса:
GET domain.ru/locks?account_num=123&phone=9000000000&func_arr=camera,devaccess&start_date=2025-01-01&end_date=2025-01-01&limit=50&offset=0&statuses=0
Пример ответа:
// Ответ 200/ok
[
{
"ail_id": "31",
"created_on_tz": "2025-05-15T09:07:37.211Z",
"updated_on_tz": "2025-05-15T09:41:49.803Z",
"partner_hash": "639959f4a1e37fe503843dcbd7e8a6e7",
"status": "0", // "0" - Активна, "1" - Не активна, "2" - удалена
"lock_type": "2", // "1" - Обычная блокировка, "2" - По сумме задолженности
"func_arr": [ // Enum блокируемых функций
"camera", // Просмотр камер
"devaccess", // Открытие по кнопке
"visitor_human", // Пропуска на вход
"visitor_auto", // Пропуска на въезд
"nocontact_entry", // Бесконтактный проход
"videophone" // Видеодомофония
],
"note": "Апрель 2025, должники" // Заметка, отображаемая в CRM
}
]
=== Получить детали блокировки ===
Пример запроса:
GET domain.ru/locks/:ail_id
Пример ответа:
// Ответ 200/ok
{
"ail_id": "31",
"created_on_tz": "2025-05-15T09:07:37.211Z",
"updated_on_tz": "2025-05-15T09:41:49.803Z",
"partner_hash": "639959f4a1e37fe503843dcbd7e8a6e7",
"status": "0", // "0" - Активна, "1" - Не активна, "2" - удалена
"lock_type": "2", // "1" - Обычная блокировка, "2" - По сумме задолженности
"func_arr": [ // Enum блокируемых функций
"camera", // Просмотр камер
"devaccess", // Открытие по кнопке
"visitor_human", // Пропуска на вход
"visitor_auto", // Пропуска на въезд
"nocontact_entry", // Бесконтактный проход
"videophone" // Видеодомофония
],
"note": "Апрель 2025, должники", // Заметка, отображаемая в CRM
"updated_by_username": "Иван Иванов",
"acc_note": "У вас есть задолженность по оплате коммунальных услуг в размере: %сумма%. Оплатите её, чтобы восстановить доступ ко всем возможностям приложения." // Уведомление для жителя
}
=== Создать блокировку ===
Пример запроса:
POST domain.ru/locks
{
"lock_type": "1", // "1" - Обычная блокировка, "2" - По сумме задолженности. Обязательное поле
"func_arr": ["camera"], // Enum блокируемых функций. "camera" - Просмотр камер, "devaccess" - Открытие по кнопке, "visitor_human" - Пропуска на вход, "visitor_auto" - Пропуска на въезд, "nocontact_entry" - Бесконтактный проход, "videophone" - Видеодомофония. Обязательное поле
"note": "Заметка", // Заметка, отображаемая в CRM. Не обязательное поле
"acc_note": "Уведомление для жителя" // Уведомление для жителя. Не обязательное поле
}
Пример ответа:
// Ответ 200/ok
{"ok": true, "ail_id": "123"}
=== Редактировать блокировку ===
Пример запроса:
PUT domain.ru/locks/:ail_id
{
"lock_type": "1", // "1" - Обычная блокировка, "2" - По сумме задолженности.
"func_arr": ["camera"], // Enum блокируемых функций. "camera" - Просмотр камер, "devaccess" - Открытие по кнопке, "visitor_human" - Пропуска на вход, "visitor_auto" - Пропуска на въезд, "nocontact_entry" - Бесконтактный проход, "videophone" - Видеодомофония.
"note": "Заметка", // Заметка, отображаемая в CRM.
"acc_note": "Уведомление для жителя" // Уведомление для жителя.
}
Пример ответа:
// Ответ 200/ok
{"ok": true}
=== Список заблокированных клиентов ===
Пример запроса:
GET domain.ru/locks/:ail_id/items?statuses=0,1&account_num=123&phone=9000000000&limit=50&offset=0
Пример ответа:
// Ответ 200/ok
[
{
"aili_id": "1140",
"ail_id": "31",
"account_num": "210618100359", // Номер ЛС
"phone": null, // Телефон
"status": "1", // "0" - Активна, "1" - Не активна, "2" - удалена
"updated_on_tz": "2025-05-22T11:07:31.925Z",
"updated_by_username": "Иван Иварнов",
"max_debt_amount": "27769.66" // Сумма задолженности для блокировки
},
{
"aili_id": "1140",
"ail_id": "31",
"account_num": null, // Номер ЛС
"phone": "210618100359", // Телефон
"status": "1", // "0" - Активна, "1" - Не активна, "2" - удалена
"updated_on_tz": "2025-05-22T11:07:31.925Z",
"updated_by_username": "Иван Иварнов",
"max_debt_amount": null
}
]
=== Добавить заблокированного клиента ===
Пример запроса:
POST domain.ru/locks/:ail_id/items
{
"account_num": "12443", // Обязательно, если нет phone
"phone": "9000000000", // Обязательно, если нет account_num
"status": 0, // "0" - Активна, "1" - Не активна, "2" - удалена. Не обязательное поле
"max_debt_amount": "300" // Сумма задолженности для блокировки. Не обязательное поле
}
Пример ответа:
// Ответ 200/ok
{"ok": true, "aili_id": "123"}
=== Изменить заблокированного клиента ===
Пример запроса:
PUT domain.ru/locks/:ail_id/items/:aili_id
{
"account_num": "12443",
"phone": "9000000000",
"status": 0, // "0" - Активна, "1" - Не активна, "2" - удалена.
"max_debt_amount": "300" // Сумма задолженности для блокировки.
}
Пример ответа:
// Ответ 200/ok
{"ok": true}
=== Удалить заблокированного клиента ===
Пример запроса:
DELETE domain.ru/locks/:ail_id/items/:aili_id
Пример ответа:
// Ответ 200/ok
{"ok": true}