pd:develop:billingstore [Диспетчер24]

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
**https://oico.app/oicobills/api-docs/ <- swagger док тут**

**https://oico.app/oicobills/api-docs/swagger.json <- swagger.json тут**

==== Аутентификация ====
В 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

<code javascript>
// Ответ 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 (по умолчанию) / "Квартира" / "Машиноместо" / "Нежилое помещение" / "Кладовка" / "Паркинг" / "Апартаменты" / "Офис", влияет на формирование сервисного счета для оплаты страховки

</code>
----

=== Передать список лицевых счетов ===
POST domain.ru/billacc
<code javascript>
// Запрос
[
 {
    "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
}
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**
----

=== Передать информацию о состоянии лицевых счетов ===
POST domain.ru/bills/debt
<code javascript>
// Запрос
{
 "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",
     "rn": "1"
    },
    {
     "service_name": "Холодная вода",
     "price": "4.00",
     "quantity": "1.50 м3",
     "amount": "6.00",
     "rn": "2"
    }
   ]
  }
 ]
}


// @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) | - Цена. Обязательный ключ
         // @rn           | Numeric (38) | - Порядковый номер. Необязательный ключ
         
// Ответ 200/ok
{
    "ok": "true",
    "processed_items": 3,
    "processed_details": 2
}
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**
----

=== Получить список начислений/проводок за последние 3 месяца ===
GET domain.ru/bills
<code javascript>
// Ответ 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",
          "rn": "1"
        }
      ]
    },
    {
      "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", 
          "rn": "1"
        },
        {
          "service_name": "Холодная вода",
          "price": "4.00",
          "quantity": "1.50 м3",
          "amount": "6.00",
          "rn": "2"          
        }
      ]
    }
]

</code>

=== Передать список бухгалтерских проводок ===
POST domain.ru/bills/accounting
<code javascript>
//Запрос
[
  {
    "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",
        "rn": "1"        
      }
    ]
  },
  {
    "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",
        "rn": "1"        
      },
      {
        "service_name": "Холодная вода",
        "price": "4.00",
        "quantity": "1.50 м3",
        "amount": "6.00",
        "rn": "2"        
      }
    ]
  }
]

                                                                    
// 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) | - Цена. Обязательный ключ
         // @rn           | Numeric (38) | - Порядковый номер. Необязательный ключ         
         
// Ответ 200/ok
{
    "ok": "true"
    "processed_items": 2,
    "processed_details": 3
}
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**
----

=== Обновить/создать начисление ===
POST domain.ru/bills/update/calc
<code javascript>
//Запрос
[
  {
    "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",
        "rn": "1"        
      }
    ]
  }
]

                                                                    
// 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
}
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**
  * Начислением не считается объект, в котором calc_amount = 0, start_amount = 0, end_amount = 0, pay_amount > 0. Проверки на стороне сервера на это нет. Попытки передачи таких начислений приведут к неконсистентности данных.
  * trans_date будет записан при первичной записи начисления и не будет обновляться при повторной записи.
----

=== Обновить/создать платежи ===
POST domain.ru/bills/update/pays
<code javascript>
//Запрос
[{
	"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
}
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**
  * trans_date передается для поиска начисления. Если начисление не было найдено - платежи все-равно запишутся. Но, если запрос был сделан с целью корректировки платежей, то предыдущие загруженные платежи не удалятся и это действие сгенерирует дубли. Т.е. необходимо для консистентсности данных передавать платежи всегда с trans_date = trans_date начисления + 1 день

----

=== Удалить бухгалтерские проводки/балансы/начисления ===
DEL domain.ru/bills?account_num=xxx&from=2022-01-01&to=2022-01-02
<code javascript>
// Необязательные параметры account_num (фильтр по лицевому счету), from, to (фильтры по датам от/до)
// Ответ 200/ok
{
    "ok": "true"
}
</code>
---

=== Получить суммы начислений по услугам ===
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)
<code javascript>
// Ответ
[
    {
        "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"
    }
]
</code>
==== Счетчики (ИПУ) ====

=== Получить список ИПУ ===

При передаче параметра 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
<code javascript>
// Ответ 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-17T00:00:00.000Z',
    last_val: 90,
    last_val2: 91,
    last_val3: 92,
    last_val_date: '2021-10-16T00: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 - запись разговора кц при передаче последнего показания
*/
</code>

----

=== Добавить ИПУ ===
POST domain.ru/meter
Если в запросе передали ext_id и счетчик с таким ext_id уже существует, то данные счетчика будут обновлены в соответствии с переданными полями. Если счетчика с указанным ext_id не найдено - он будет создан.
Пример запроса:

<code javascript>
[
    {
        "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 - запись разговора кц при передаче показания
  */
</code>

Пример запроса для массового добавления счетчиков:

<code javascript>
[
 {
   "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"
      }
  ]
 }
]
</code>

Пример успешного ответа:

<code javascript>
{ 
  "ok": "true",
  "processed_items": 2
}
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)
Если в запросе более 500 позиций, сервис после обработки первых 500 позиций отдаст http code 200, но при этом продолжит обрабатывать переданные данные, на последующие запрос по указанному в Authorization header @token сервис будет отдавать ошибку 405 до тех пор, пока не закончит обработку переданных ранее данных. (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**

Пример ответа при ошибке добавления ИПУ:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when adding meter with factory_num 777-x/124' 
}
</code>

----

=== Изменить данные ИПУ ===
PUT domain.ru/meter/:meter_id meter_id - уникальный ID ИПУ

Пример запроса PUT domain.ru/meter/3156dadb-8b78-4cf2-a6d8-d41dcf7a8c96

<code javascript>
{
  "service_str": "ГВС",
  "account_num": "111xxx",
  "val_name": "val_name", 
  "val2_name": null 
}
</code>

Пример успешного ответа:

<code javascript>
{ ok: true }
</code>

Пример ответа при ошибке изменения ИПУ:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when updating meter' 
}
</code>

=== Удалить ИПУ ===
DELETE domain.ru/meter/:meter_id meter_id - уникальный ID ИПУ

DELETE domain.ru/meter/3156dadb-8b78-4cf2-a6d8-d41dcf7a8c96

Пример успешного ответа:

<code javascript>
{ ok: true }
</code>

Пример ответа при ошибке удаления ИПУ:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when deleting meter' 
}
</code>

----

=== Получить показания по всем ИПУ ===
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.

<code javascript>
// Ответ 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 - запись разговора кц при передаче показания
*/
</code>

----

=== Получить последнее показание по всем ИПУ ===
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.

<code javascript>
// Ответ 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 - запись разговора кц при передаче показания
*/
</code>


=== Добавить показания по нескольким ИПУ ===

POST domain.ru/meter/values 

Пример запроса POST domain.ru/meter/values

<code javascript>
[
{ "meter_id": "e43965d1-a43d-44c7-9320-e0653d9163d2"
  "val": 100500, 
  "val_date": "2021-10-18", 
  "is_user": "N"
},
{ "ext_id": "x6256389"
  "val": 100400,
  "va2": 100401,
  "val3": 100402, 
  "val_date": "2021-09-18", 
  "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 - запись разговора кц при передаче показания
*/
</code>


Пример успешного ответа:

<code javascript>
{ ok: true }
</code>
**ВАЖНО. Рекомендуется в массиве передавать не более 500 позиций/записей за один http запрос (см. раздел Рекомендуемая методика отправки данных на сервер и раздел Ограничения)**

Пример ответа при ошибке добавления показания:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when add meter value for meter e43965d1-a43d-44c7-9320-e0653d9163d2' 
}
</code>

=== Добавить показания для конкретного ИПУ ===

POST domain.ru/meter/:meter_id/values 

meter_id - Уникальный идентификатор ИПУ

Пример запроса POST domain.ru/meter/e43965d1-a43d-44c7-9320-e0653d9163d2/values

<code javascript>
{ 
  "val": 100500, 
  "val2": 100501, 
  "val_date": "2021-10-18", 
  "is_user": "N",
  "phone": "9126630539",
  "record" : "http://record.com"
}
/*
val - Значение показания (тариф 1)
val2 - Значение показания (тариф 2)
val3 - Значение показания (тариф 3)
val_date - Дата показания
is_user - Признак передачи показания жителем Y/N
phone - телефон, с которого последнее показание 
record - запись разговора кц при передаче показания
*/
</code>


Пример успешного ответа:

<code javascript>
{ ok: true }
</code>

Пример ответа при ошибке добавления показания:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when add meter value for meter e43965d1-a43d-44c7-9320-e0653d9163d2' 
}
</code>
----

==== Методы для работы с ИПУ по ext_id  ====

=== Получить детали ИПУ ===
GET domain.ru/meter/ext/:ext_id ext_id - ID ИПУ в системе партнера

Пример запроса GET domain.ru/meter/ext/1
<code javascript>
// Ответ 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-17',
    last_val: 90,
    last_val: 91,
    last_val: null,
    last_val_date: '2021-10-16',
    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 - Наименование третьего тарифа
*/
</code>
=== Изменить данные ИПУ ===
PUT domain.ru/meter/ext/:ext_id ext_id - ID ИПУ в системе партнера

Пример запроса PUT domain.ru/meter/ext/1

<code javascript>
{
  service_str: "ГВС"
}
</code>

Пример успешного ответа:

<code javascript>
{ ok: true }
</code>

Пример ответа при ошибке изменения ИПУ:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when updating meter' 
}
</code>

=== Удалить ИПУ ===

DELETE domain.ru/meter/ext/:ext_id ext_id - ID ИПУ в системе партнера

Пример успешного ответа:

<code javascript>
{ ok: true }
</code>

Пример ответа при ошибке удаления ИПУ:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when deleting meter' 
}
</code>

=== Добавить показания для конкретного ИПУ ===

POST domain.ru/meter/ext/:ext_id/values ext_id - ID ИПУ в системе партнера


Пример запроса POST domain.ru/meter/1/values

<code javascript>
[{ 
  val: 100500, 
  val2: 100501, 
  val_date: '2021-10-18', 
  is_user: 'N'
}]
/*
val - Значение показания (тариф 1)
val2 - Значение показания (тариф 2)
val3 - Значение показания (тариф 3)
val_date - Дата показания
is_user - Признак передачи показания жителем Y/N
*/
</code>


Пример успешного ответа:

<code javascript>
{ ok: true }
</code>

Пример ответа при ошибке добавления показания:

<code javascript>
{ 
  ok: false, 
  message: 'Failed when add meter value for meter 1' 
}
</code>

=== Получить показания по 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.

<code javascript>
// Ответ 200/ok
[
  {
    meter_id: '8014680b-6453-4633-b235-d2d7579ee867',
    is_user: 'Y',
    val: 10,
    val2: 11,
    val3: null,
    val_date: '2021-10-17'
  },
  {
    meter_id: 'fea85cec-337b-43b2-800e-15a16e4fa697',
    is_user: 'Y',
    val: 100.25,
    val2: 12,
    val3: null,
    val_date: '2021-10-17'
  },
  {
    meter_id: '8014680b-6453-4633-b235-d2d7579ee867',
    is_user: 'N',
    val: 9,
    val2: 11,
    val3: null,
    val_date: '2021-10-16'
  },
  {
    meter_id: 'fea85cec-337b-43b2-800e-15a16e4fa697',
    is_user: 'N',
    val: 90,
    val2: 11,
    val3: null,
    val_date: '2021-10-16'
  },
  {
    meter_id: '8014680b-6453-4633-b235-d2d7579ee867',
    is_user: 'N',
    val: 8,
    val2: 11,
    val3: 33,
    val_date: '2021-10-15'
  },
  {
    meter_id: 'fea85cec-337b-43b2-800e-15a16e4fa697',
    is_user: 'N',
    val: 80,
    val2: null,
    val3: null,
    val_date: '2021-10-15'
  }
]
/*
 meter_id - Уникальный идентификатор ИПУ
 is_user - Признак передачи показания жителем Y/N
 val - Значение показания (тариф 1)
 val2 - Значение показания (тариф 2)
 val3 - Значение показания (тариф 3)
 val_date - Дата показания
*/
</code>



==== Скачивание квитанций ====

=== Получить url для скачивания квитанции ===

Для получения url на скачивание квитанции в заголовке запроса authorization должен быть токен авторизации в base64.

В запросе должны присутствовать параметры account_num - номер ЛС year - год квитанции и month - месяц квитанции

Пример запроса:

GET domain.ru?account_num=001&year=2021&month=02

Пример ответа:

<code javascript>
// Ответ 200/ok
{
    "ok": true,
    "url": "http://domain.ru/53436fa8-3f6d-423q-947b-1506382fe7b"
}

/*
 url - публичный url для скачивания квитанции. Действителен в течение 15 мин.
*/
</code>

==== Блокировки лицевых счетов ====

=== Получить список блокировок ===

Пример запроса:

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

Пример ответа:

<code javascript>
// Ответ 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
    }
 ]
</code>

=== Получить детали блокировки ===

Пример запроса:

GET domain.ru/locks/:ail_id

Пример ответа:

<code javascript>
// Ответ 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": "У вас есть задолженность по оплате коммунальных услуг в размере: %сумма%. Оплатите её, чтобы восстановить доступ ко всем возможностям приложения." // Уведомление для жителя
}
</code>

=== Создать блокировку ===

Пример запроса:

POST domain.ru/locks
<code javascript>
{
    "lock_type": "1", // "1" - Обычная блокировка, "2" - По сумме задолженности. Обязательное поле
    "func_arr": ["camera"], // Enum блокируемых функций. "camera" - Просмотр камер, "devaccess" - Открытие по кнопке, "visitor_human" - Пропуска на вход, "visitor_auto" - Пропуска на въезд, "nocontact_entry" - Бесконтактный проход, "videophone" - Видеодомофония. Обязательное поле
    "note": "Заметка", // Заметка, отображаемая в CRM. Не обязательное поле
    "acc_note": "Уведомление для жителя" // Уведомление для жителя. Не обязательное поле
}
</code>

Пример ответа:

<code javascript>
// Ответ 200/ok
{"ok": true, "ail_id": "123"}
</code>

=== Редактировать блокировку ===

Пример запроса:

PUT domain.ru/locks/:ail_id
<code javascript>
{
    "lock_type": "1", // "1" - Обычная блокировка, "2" - По сумме задолженности.
    "func_arr": ["camera"], // Enum блокируемых функций. "camera" - Просмотр камер, "devaccess" - Открытие по кнопке, "visitor_human" - Пропуска на вход, "visitor_auto" - Пропуска на въезд, "nocontact_entry" - Бесконтактный проход, "videophone" - Видеодомофония.
    "note": "Заметка", // Заметка, отображаемая в CRM.
    "acc_note": "Уведомление для жителя" // Уведомление для жителя.
}
</code>

Пример ответа:

<code javascript>
// Ответ 200/ok
{"ok": true}
</code>

=== Список заблокированных клиентов ===

Пример запроса:

GET domain.ru/locks/:ail_id/items?statuses=0,1&account_num=123&phone=9000000000&limit=50&offset=0

Пример ответа:

<code javascript>
// Ответ 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
    }
]
</code>

=== Добавить заблокированного клиента ===

Пример запроса:

POST domain.ru/locks/:ail_id/items
<code javascript>
{
    "account_num": "12443", // Обязательно, если нет phone
    "phone": "9000000000", // Обязательно, если нет account_num
    "status": 0, // "0" - Активна, "1" - Не активна, "2" - удалена. Не обязательное поле
    "max_debt_amount": "300" // Сумма задолженности для блокировки. Не обязательное поле
}
</code>

Пример ответа:

<code javascript>
// Ответ 200/ok
{"ok": true, "aili_id": "123"}
</code>

=== Изменить заблокированного клиента ===

Пример запроса:

PUT domain.ru/locks/:ail_id/items/:aili_id
<code javascript>
{
    "account_num": "12443",
    "phone": "9000000000", 
    "status": 0, // "0" - Активна, "1" - Не активна, "2" - удалена. 
    "max_debt_amount": "300" // Сумма задолженности для блокировки.
}
</code>

Пример ответа:

<code javascript>
// Ответ 200/ok
{"ok": true}
</code>

=== Удалить заблокированного клиента ===

Пример запроса:

DELETE domain.ru/locks/:ail_id/items/:aili_id

Пример ответа:

<code javascript>
// Ответ 200/ok
{"ok": true}
</code>