Liczniki

Czym są liczniki?

Liczniki pozwalają śledzić odczyty liczników dla Twoich nieruchomości: elektryczność, woda, gaz, ogrzewanie i inne media. Każdy licznik przechowuje numer seryjny, odczyt początkowy i historię wszystkich odczytów.

Strefy taryfowe energii elektrycznej

Dla liczników energii elektrycznej możesz wybrać różne typy taryf w zależności od możliwości licznika.

Jak utworzyć licznik?

Dodawanie odczytów

Po utworzeniu licznika możesz dodawać odczyty, aby śledzić zużycie w czasie.

Korekty i poprawki

Czasami odczyty liczników wymagają korekty z powodu cofnięcia licznika, wymiany lub korekt od dostawcy usług.

Kiedy używać korekt?

• Wymiana licznika - nowy licznik zaczyna od niższej wartości
• Cofnięcie licznika po osiągnięciu maksymalnej wartości
• Korekta od dostawcy usług po przeliczeniu
• Korekta błędu w poprzednio wprowadzonym odczycie

Odczyty powiązane z naliczeniami

Gdy naliczenie jest tworzone na podstawie odczytów licznika, system automatycznie wiąże odczyt z naliczeniem.

Zasady powiązania

Tworzenie naliczeń

Podczas tworzenia naliczenia dla wydatków z licznikami wybierasz istniejący odczyt zamiast wprowadzania wartości ręcznie. Zapewnia to integralność danych i prawidłowe śledzenie.

Tworzenie naliczeń przez 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]
}

Prawa dostępu

Różni uczestnicy nieruchomości mają różne uprawnienia do liczników i odczytów.

Uprawnienia do liczników

Uprawnienia do odczytów

Status licznika

Liczniki mogą być aktywowane lub dezaktywowane w zależności od tego, czy są obecnie używane.

Kiedy dezaktywować licznik?

• Licznik został zastąpiony nowym
• Licznik jest tymczasowo niesprawny
• Licznik nie jest już odpowiedni dla nieruchomości

Usuwanie licznika

Aby zachować integralność danych, liczniki z powiązanymi opłatami nie mogą być usunięte.

REST API

Wszystkie endpointy API wymagają uwierzytelnienia JWT.

Uwaga dotycząca warstwy usługowej

API liczników

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 odczytów

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

Dokumenty licznika

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

Dokumenty odczytu

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

Przykład: Tworzenie licznika

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"
}

Przykład: Dodawanie odczytu

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
}

Dokumenty licznika: 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 }

Dokumenty odczytu: 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 }

Przykładowa odpowiedź

{
  "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"
}

Powiązane sekcje

Swagger / OpenAPI

Pełna dokumentacja API jest dostępna w Swagger UI: /api/v1/doc