Лічильники

Що таке лічильники?

Лічильники дозволяють відстежувати показання приладів обліку для ваших об'єктів: електрика, вода, газ, опалення та інші комунальні послуги. Кожен лічильник зберігає серійний номер, початкове показання та історію всіх показань.

Тарифні зони електроенергії

Для лічильників електроенергії ви можете вибрати різні типи тарифів залежно від можливостей вашого лічильника.

Як створити лічильник?

Додавання показань

Після створення лічильника ви можете додавати показання для відстеження споживання з часом.

Коригування та виправлення

Інколи показання лічильників потрібно коригувати через відкат лічильника, заміну або коригування від постачальника послуг.

Коли використовувати коригування?

• Заміна лічильника - новий лічильник починає з меншого значення
• Відкат лічильника після досягнення максимального значення
• Корекція від постачальника послуг після перерахунку
• Виправлення помилки у раніше введеному показанні

Показання, привязані до нарахувань

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

Правила привязки

Створення нарахувань

При створенні нарахування для витрат зі лічильниками ви обираєте існуюче показання замість введення значень вручну. Це забезпечує цілісність даних та правильний облік.

Створення нарахувань через API

# 1. Get available unlinked readings:
GET /api/v1/properties/{propertyId}/expenses/{expenseId}/unlinked-readings

# Response:
{
  "has_counters": true,
  "has_unlinked_readings": true,
  "counters": [
    {
      "counter_id": 5,
      "serial_number": "ABC-123456",
      "unlinked_readings": [
        {
          "id": 12,
          "date": "2026-01-15",
          "value": "1500.00",
          "previous_value": "1350.00",
          "consumption": "150.0000"
        }
      ]
    }
  ]
}

# 2. Create charge with selected reading:
POST /api/v1/properties/{propertyId}/expenses/{expenseId}/charges
{
  "charge_date": "2026-01-21",
  "period_start": "2025-12-01",
  "period_end": "2025-12-31",
  "counter_value_ids": [12]
}

Права доступу

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

Права на лічильники

Права на показання

Статус лічильника

Лічильники можуть бути активовані або деактивовані залежно від того, чи використовуються вони в даний час.

Коли деактивувати лічильник?

• Лічильник замінено на новий
• Лічильник тимчасово не працює
• Лічильник більше не актуальний для об'єкта

Видалення лічильника

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

REST API

Усі API-ендпоінти потребують JWT-аутентифікації.

Примітка рівня обслуговування

API лічильників

GET    /api/v1/properties/{propertyId}/counters              # List counters for property
POST   /api/v1/properties/{propertyId}/counters              # Create counter
GET    /api/v1/properties/{propertyId}/counters/{id}         # Counter details with readings
PUT    /api/v1/properties/{propertyId}/counters/{id}         # Update counter
DELETE /api/v1/properties/{propertyId}/counters/{id}         # Delete counter (if no linked charges)
POST   /api/v1/properties/{propertyId}/counters/{id}/toggle  # Toggle active/inactive status

API показань

POST   /api/v1/properties/{propertyId}/counters/{counterId}/values          # Add reading
PUT    /api/v1/properties/{propertyId}/counters/{counterId}/values/{id}     # Edit reading
DELETE /api/v1/properties/{propertyId}/counters/{counterId}/values/{id}     # Delete reading

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

POST   /properties/{propertyId}/counters/{id}/documents/upload                          # Upload document (multipart/form-data)
POST   /properties/{propertyId}/counters/{id}/documents/{documentId}/delete             # Delete document

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

POST   /properties/{propertyId}/counters/{id}/values/{valueId}/documents/upload          # Upload document (multipart/form-data)
POST   /properties/{propertyId}/counters/{id}/values/{valueId}/documents/{documentId}/delete  # Delete document

Приклад: Створення лічильника

POST /api/v1/properties/1/counters
Content-Type: application/json
Authorization: Bearer <token>

{
  "expense_type_id": 1,
  "serial_number": "ABC-123456",
  "tariff_type": "TWO_ZONE",
  "initial_value": "100.500",
  "initial_value_t1": "60.300",
  "initial_value_t2": "40.200",
  "initial_value_date": "2026-01-01"
}

Приклад: Додавання показання

POST /api/v1/properties/1/counters/5/values
Content-Type: application/json
Authorization: Bearer <token>

# Single-zone counter (regular consumption):
{ "value": "1350.75", "date": "2026-01-07" }

# Multi-zone counter (total auto-calculated):
{
  "value_t1": "150.300",
  "value_t2": "80.200",
  "date": "2026-01-07"
}

# Adjustment reading (correction):
{
  "value": "50.000",
  "date": "2026-01-07",
  "is_adjustment": true
}

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

POST /properties/1/counters/5/documents/upload
Content-Type: multipart/form-data

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

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

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

POST /properties/1/counters/5/values/12/documents/upload
Content-Type: multipart/form-data

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

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

Приклад відповіді

{
  "id": 12,
  "value": "230.500",
  "value_t1": "150.300",
  "value_t2": "80.200",
  "value_t3": null,
  "date": "2026-01-07",
  "is_initial": false,
  "is_adjustment": false,
  "has_linked_charge": true,
  "expense_charge_id": 45,
  "can_edit": false,
  "can_delete": false,
  "documents_count": 2,
  "created_at": "2026-01-07T10:30:00+00:00"
}

Пов'язані розділи

Swagger / OpenAPI

Повна документація API доступна у Swagger UI: /api/v1/doc