Головна › Налаштування об'єкта › Лічильники

7 Лічильники

Налаштуйте лічильники комунальних послуг, відстежуйте показання, керуйте тарифними зонами та одиницями виміру. Система контролює своєчасність подання показань орендарями.

Чому лічильники — це важливо

Більшість ключових комунальних витрат — електроенергія, газ, вода, опалення — розраховуються на основі показань лічильників. Точні та своєчасні показання забезпечують правильний розрахунок, запобігають суперечкам між орендодавцями та орендарями і надають прозорі дані про споживання.

Що забезпечують лічильники

Автоматичний розрахунок нарахувань на основі споживання
Підтримка багатозонних тарифів (день/ніч, пік/напівпік)
Відстеження споживання за період із середньодобовими показниками
Контроль своєчасності подання показань орендарями
Механізм коригування при заміні лічильника або виправленні помилок

Типи витрат з лічильниками

П'ять типів витрат підтримують облік за лічильниками. Кожен має одиницю виміру за замовчуванням, яку можна змінити для конкретного лічильника.

ELECTRICITY kWh — Підтримує багатозонні тарифи

GAS m3 — Споживання природного газу

COLD_WATER m3 — Холодне водопостачання

HOT_WATER m3 — Гаряче водопостачання

HEATING Gcal — Центральне або індивідуальне опалення

Поля лічильника

При створенні лічильника ви вказуєте тип витрат, серійний номер, тип тарифу та початкове показання з його датою.

expense_type_id Тип витрат (обов'язково)

serial_number Заводський серійний номер, унікальний для об'єкта

tariff_type SINGLE_ZONE, TWO_ZONE або THREE_ZONE

initial_value Початкове показання (для однозонного)

initial_value_date Дата початкового показання (обов'язково)

initial_value_t1/t2/t3 Зонні показання для багатозонних тарифів

Тарифні зони

Лічильники електроенергії підтримують багатозонні тарифи. Для двозонних і тризонних лічильників ви вводите окремі показання по зонах — загальне значення розраховується автоматично.

Тип тарифу	Зони	Поля	Опис
SINGLE_ZONE	1	`value`	Стандартний однозонний лічильник
TWO_ZONE	2	`value_t1`, `value_t2`	T1 = День, T2 = Ніч (коеф. 50%)
THREE_ZONE	3	`value_t1`, `value_t2`, `value_t3`	T1 = Пік (150%), T2 = Напівпік (100%), T3 = Ніч (40%)

Автоматичний підрахунок суми
Для багатозонних лічильників загальне значення завжди розраховується як сума зонних значень: value = value_t1 + value_t2 [+ value_t3]. Вам не потрібно вказувати загальне — воно обчислюється автоматично.

Типи показань

Система підтримує чотири типи показань лічильників, кожен з яких виконує певну роль у процесі нарахувань.

Початкове

Встановлюється при створенні лічильника. Одне на лічильник. Єдиний тип, який можна редагувати.

Звичайне

Звичайне показання. Повинно бути >= попереднього. Може бути прив'язане до нарахувань.

Коригування

Виправлення після заміни лічильника або помилки. Зберігається як від'ємна різниця. Не може бути прив'язане до нарахувань.

Розрахункове

Автоматично інтерпольоване системою для проміжних розрахункових періодів. Може бути прив'язане до нарахувань.

Правила валідації
Лише одне показання на день на лічильник. Нові показання повинні бути >= поточного значення (інакше автоматично визначається як коригування). Якщо показання менше поточного, система автоматично створює запис коригування.

Контроль своєчасності

Система відстежує, чи вчасно орендарі подають показання. Для кожного лічильника можна встановити день подання показань, і система контролює виконання.

Функції відстеження

Налаштований день подання показань (1-31) для кожного лічильника
Автоматична інтерполяція для пропущених періодів
Статистика споживання: загальна, за період, середньодобова
Фото лічильників і фото показань для верифікації

Документи

Ви можете прикріплювати документи (фото, PDF) до лічильників та їхніх показань. Документи безпечно зберігаються в S3 і доступні через підписані URL.

Документи лічильника

Прикріпіть фото лічильника, акти встановлення, документи повірки. Завантажуйте на сторінці деталей лічильника.

Документи показання

Прикріпіть фото дисплея лічильника при додаванні або перегляді показань. Завантажуйте при створенні показання або на сторінці деталей лічильника.

Обмеження файлів
Максимальний розмір файлу: 20 МБ. Підтримувані формати: JPEG, PNG, GIF, WebP, HEIC, PDF. До кожного лічильника або показання можна прикріпити кілька файлів.

API документів

POST   /properties/{propertyId}/counters/{id}/documents/upload                           # Upload counter document
POST   /properties/{propertyId}/counters/{id}/documents/{documentId}/delete              # Delete counter document
POST   /properties/{propertyId}/counters/{id}/values/{valueId}/documents/upload          # Upload reading document
POST   /properties/{propertyId}/counters/{id}/values/{valueId}/documents/{documentId}/delete  # Delete reading document

Усі завантажені документи відображаються в розділі Документи (/my/documents) і можуть бути відфільтровані за типом: «Лічильник» або «Показання лічильника».

Як додати лічильник

Перейдіть до будь-якого об'єкта, потім натисніть "Лічильники" у меню об'єкта. Звідти ви можете додати нові лічильники та подати показання.

Сторінка об'єкта > Меню об'єкта > Лічильники > Додати лічильник

Детальну документацію дивіться у розділі Лічильники бібліотеки.

Для розробників: REST API

Усі операції з лічильниками та показаннями доступні через REST API. Спочатку використовуйте демо-дані для отримання JWT-токена.

GET Список лічильників

▶

Отримати всі лічильники об'єкта з їх поточними показаннями та статусом.

GET /api/v1/properties/{propertyId}/counters

Відповідь (200 OK):

{
  "counters": [
    {
      "id": 4,
      "expense_type": {"id": 3, "code": "ELECTRICITY"},
      "serial_number": "NIK-2281-073915",

      "tariff_type": "THREE_ZONE",
      "zone_count": 3,
      "current_value": "5729.000",
      "documents_count": 2,
      "is_active": true,
      "created_at": "2026-02-20T15:45:43+00:00"
    },
    {
      "id": 5,
      "expense_type": {"id": 10, "code": "GAS"},
      "serial_number": "G4-BK-2023-041822",
      "tariff_type": "SINGLE_ZONE",
      "zone_count": 1,
      "current_value": "1612.400",
      "documents_count": 0,
      "is_active": true,
      "created_at": "2026-02-20T15:45:44+00:00"
    }
  ],
  "total": 5
}

POST Створити лічильник

▶

Створити новий лічильник із початковим показанням. Вкажіть зонні значення для багатозонних тарифів — сума розраховується автоматично.

POST /api/v1/properties/{propertyId}/counters

Заголовки:

                    Authorization: Bearer {token}
Content-Type: application/json
                

Приклад однозонного:

{
  "expense_type_id": 10,
  "serial_number": "G4-BK-2023-041822",
  "tariff_type": "SINGLE_ZONE",
  "initial_value": "1245.500",
  "initial_value_date": "2025-09-01"
}

Приклад тризонного (електроенергія):

{
  "expense_type_id": 3,
  "serial_number": "EA-2024-073915",
  "tariff_type": "THREE_ZONE",
  "initial_value_t1": "2100.000",
  "initial_value_t2": "1500.000",
  "initial_value_t3": "850.000",
  "initial_value_date": "2025-09-01"
}

Для багатозонних тарифів вкажіть initial_value_t1, initial_value_t2 (та t3 для тризонного). Загальне initial_value обчислюється як їх сума. Серійні номери повинні бути унікальними в межах об'єкта.

Відповідь (201 Created):

{
  "id": 1,
  "expense_type": {"id": 3, "code": "ELECTRICITY"},
  "serial_number": "EA-2024-073915",
  "tariff_type": "THREE_ZONE",
  "zone_count": 3,
  "initial_value": "4450.000",
  "initial_value_t1": "2100.000",
  "initial_value_t2": "1500.000",
  "initial_value_t3": "850.000",
  "initial_value_date": "2025-09-01",
  "current_value": "4450.000",
  "documents_count": 0,
  "is_active": true,
  "can_delete": true,
  "created_at": "2025-09-01T00:00:00+00:00"
}

GET Деталі лічильника

▶

Отримати повні деталі лічильника, включаючи всі показання, відсортовані за датою (найновіші спочатку).

GET /api/v1/properties/{propertyId}/counters/{id}

Відповідь (200 OK):

{
  "id": 4,
  "expense_type": {"id": 3, "code": "ELECTRICITY"},
  "serial_number": "NIK-2281-073915",
  "tariff_type": "THREE_ZONE",
  "zone_count": 3,
  "initial_value": "4450.000",
  "initial_value_t1": "2100.000",
  "initial_value_t2": "1500.000",
  "initial_value_t3": "850.000",
  "initial_value_date": "2025-08-01",
  "current_value": "5729.000",
  "documents_count": 2,
  "is_active": true,
  "has_linked_charges": false,
  "can_delete": true,
  "values": [
    {
      "id": 8,
      "value": "5729.000",
      "value_t1": "2752.100",
      "value_t2": "1851.300",
      "value_t3": "1125.600",
      "date": "2025-12-01",
      "is_initial": false,
      "is_adjustment": false,
      "documents_count": 0,
      "has_linked_charge": false,
      "can_edit": false,
      "can_delete": true
    },
    {
      "id": 5,
      "value": "4450.000",
      "value_t1": "2100.000",
      "value_t2": "1500.000",
      "value_t3": "850.000",
      "date": "2025-08-01",
      "is_initial": true,
      "is_adjustment": false,
      "documents_count": 0,
      "has_linked_charge": false,
      "can_edit": true,
      "can_delete": true
    }
  ]
}

PUT Оновити лічильник

▶

Оновити метадані лічильника (серійний номер, тип витрат, тип тарифу). Оновлюються лише надані поля.

PUT /api/v1/properties/{propertyId}/counters/{id}

Поля для оновлення:

expense_type_id integer

serial_number string (max 100)

tariff_type SINGLE_ZONE | TWO_ZONE | THREE_ZONE

Тіло запиту:

{
  "serial_number": "EA-2024-073915-NEW"
}

Відповідь (200 OK):

                    {
  "id": 4,
  "expense_type": {"id": 3, "code": "ELECTRICITY"},
  "serial_number": "EA-2024-073915-NEW",
  "tariff_type": "THREE_ZONE",
  "zone_count": 3,
  "current_value": "5729.000",
  "documents_count": 2,
  "is_active": true,
  "has_linked_charges": false,
  "can_delete": true,
  "created_at": "2026-02-20T15:45:43+00:00"
}
                

DELETE Видалити лічильник

▶

Видалити лічильник та всі його показання. Повертає 204 при успіху.

DELETE /api/v1/properties/{propertyId}/counters/{id}

Лічильник не можна видалити, якщо його показання прив'язані до нарахувань. У цьому випадку деактивуйте його через toggle-active.

POST Перемкнути активний/неактивний

▶

Перемкнути статус активності лічильника. Неактивні лічильники виключаються з автоматичного розрахунку нарахувань.

POST /api/v1/properties/{propertyId}/counters/{id}/toggle-active

Відповідь (200 OK):

{"id": 1, "is_active": false}

POST Додати показання

▶

Подати нове показання лічильника. Для однозонних лічильників вкажіть "value". Для багатозонних вкажіть зонні значення (value_t1, value_t2, value_t3) — сума обчислюється автоматично.

POST /api/v1/properties/{propertyId}/counters/{id}/values

Однозонне показання:

{
  "value": "1587.340",
  "date": "2025-11-01"
}

Багатозонне показання:

{
  "value_t1": "2280.000",
  "value_t2": "1620.000",
  "value_t3": "925.700",
  "date": "2025-11-01"
}

Якщо подане значення менше поточного показання, система автоматично створює запис коригування (значення зберігаються як від'ємна різниця). Дозволяється лише одне показання на день на лічильник.

Відповідь (201 Created):

                    {
  "id": 5,
  "value": "4825.700",
  "value_t1": "2280.000",
  "value_t2": "1620.000",
  "value_t3": "925.700",
  "date": "2025-11-01",
  "is_initial": false,
  "is_adjustment": false,
  "documents_count": 0,
  "has_linked_charge": false
}
                

PUT Оновити показання

▶

Оновити існуюче показання лічильника. Через веб-інтерфейс можна редагувати лише початкові показання; API дозволяє оновлювати будь-яке показання.

PUT /api/v1/properties/{propertyId}/counters/{id}/values/{valueId}

Тіло запиту:

{
  "value": "1590.000",
  "date": "2025-11-02"
}

Через веб-інтерфейс можна редагувати лише початкові показання (is_initial=true). Звичайні показання можна виправити лише за допомогою коригувань. API не перевіряє мінімальне значення при оновленні.

Відповідь (200 OK):

                    {
  "id": 5,
  "value": "1590.000",
  "value_t1": null,
  "value_t2": null,
  "value_t3": null,
  "date": "2025-11-02",
  "is_initial": false,
  "is_adjustment": false,
  "documents_count": 0,
  "has_linked_charge": false,
  "can_edit": true,
  "can_delete": true
}
                

DELETE Видалити показання

▶

Видалити показання лічильника. Повертає 204 при успіху.

DELETE /api/v1/properties/{propertyId}/counters/{id}/values/{valueId}

Показання, прив'язані до нарахувань, не можна видалити. Спочатку потрібно видалити прив'язане нарахування.

POST Документи лічильника

▶

POST /properties/{propertyId}/counters/{id}/documents/upload

Заголовки:

Content-Type: multipart/form-data

Тіло запиту (form-data):

                    documents[]    — file (jpg, jpeg, png, gif, webp, heic, pdf), max 20 MB
comment        — string (optional)
                

Максимальний розмір файлу: 20 МБ. Підтримувані формати: JPEG, PNG, GIF, WebP, HEIC, PDF. До кожного лічильника або показання можна прикріпити кілька файлів.

Відповідь (200 OK):

{
  "success": true,
  "uploaded": 1
}

DELETE /properties/{propertyId}/counters/{id}/documents/{documentId}/delete

                {
  "success": true
}
            

POST Документи показання

▶

POST /properties/{propertyId}/counters/{id}/values/{valueId}/documents/upload

Тіло запиту (form-data):

                    documents[]    — file (jpg, jpeg, png, gif, webp, heic, pdf), max 20 MB
comment        — string (optional)
                

Відповідь (200 OK):

{
  "success": true,
  "uploaded": 2
}

DELETE /properties/{propertyId}/counters/{id}/values/{valueId}/documents/{documentId}/delete

                {
  "success": true
}
            

Приклади cURL

▶

1. Створити лічильник (Приклад однозонного)

curl -X POST https://landlordkeeper.com/api/v1/properties/019a1b2c-3d4e-7f5a-8b9c-0123456789ab/counters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "expense_type_id": 10,
    "serial_number": "G4-BK-2023-041822",
    "tariff_type": "SINGLE_ZONE",
    "initial_value": "1245.500",
    "initial_value_date": "2025-09-01"
  }'

2. Створити лічильник (Приклад тризонного (електроенергія))

curl -X POST https://landlordkeeper.com/api/v1/properties/019a1b2c-3d4e-7f5a-8b9c-0123456789ab/counters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "expense_type_id": 3,
    "serial_number": "EA-2024-073915",
    "tariff_type": "THREE_ZONE",
    "initial_value_t1": "2100.000",
    "initial_value_t2": "1500.000",
    "initial_value_t3": "850.000",
    "initial_value_date": "2025-09-01"
  }'

3. Додати показання

curl -X POST https://landlordkeeper.com/api/v1/properties/019a1b2c-3d4e-7f5a-8b9c-0123456789ab/counters/1/values \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "value_t1": "2280.000",
    "value_t2": "1620.000",
    "value_t3": "925.700",
    "date": "2025-11-01"
  }'

4. Список лічильників

curl https://landlordkeeper.com/api/v1/properties/019a1b2c-3d4e-7f5a-8b9c-0123456789ab/counters \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

5. Документи лічильника

curl -X POST https://landlordkeeper.com/properties/019a1b2c-3d4e-7f5a-8b9c-0123456789ab/counters/4/documents/upload \
  -H "Cookie: PHPSESSID=your_session" \
  -F "documents[][email protected]" \
  -F "comment=Meter photo"

6. Документи показання

curl -X POST https://landlordkeeper.com/properties/019a1b2c-3d4e-7f5a-8b9c-0123456789ab/counters/4/values/8/documents/upload \
  -H "Cookie: PHPSESSID=your_session" \
  -F "documents[]=@reading_jan.jpg" \
  -F "documents[]=@reading_jan_2.pdf"

Замініть YOUR_TOKEN_HERE на JWT-токен з кроку автентифікації.

← Комунікації та доступи Типи витрат →