Bills-ha – Opłaty dla Home Assistant

Custom integration (dodatek) do Home Assistant umożliwiający ręczne prowadzenie listy opłat/rachunków oraz potwierdzanie przelewów z automatycznym zapisem daty wykonania.

---

Funkcjonalność

• Przechowywanie opłat z polami: nazwa, kwota, termin płatności, notatka, cykliczność.
• Oznaczanie opłaty jako zapłaconej (automatycznie zapisuje datę i godzinę przelewu).
• Oznaczanie opłaty jako niezapłaconej (czyści datę przelewu).
• Sensory agregujące:
  • Opłaty – Niezapłacone – liczba niezapłaconych opłat.
  • Opłaty – Przeterminowane – liczba niezapłaconych opłat po terminie.
  • Opłaty – Najbliższy termin – data najbliższego terminu płatności.
• Dane przetrwają restart Home Assistanta (zapis w .storage).

---

Instalacja

Ręczna

1. Pobierz lub sklonuj repozytorium.
2. Skopiuj folder custom_components/oplats/ do katalogu custom_components/ w konfiguracji Home Assistant.
3. Uruchom ponownie Home Assistant.
4. Przejdź do Ustawienia → Urządzenia i usługi → Dodaj integrację i wyszukaj Opłaty.

HACS (opcjonalnie)

1. W HACS przejdź do Integracje → Trzy kropki → Repozytoria niestandardowe.
2. Dodaj URL: https://github.com/CodekExplor/Bills-ha i kategorię Integration.
3. Zainstaluj integrację i uruchom ponownie HA.

---

Konfiguracja

Po instalacji dodaj integrację z poziomu UI:

1. Ustawienia → Urządzenia i usługi → Dodaj integrację.
2. Wyszukaj „Opłaty" i kliknij.
3. Wpisz nazwę (domyślnie: „Opłaty") i kliknij Zatwierdź.

Integracja dopuszcza tylko jedną instancję.

---

Usługi (Services)

Wszystkie usługi dostępne są w Developer Tools → Services pod domeną oplats.

oplats.add_bill – Dodaj opłatę

service: oplats.add_bill
data:
  nazwa: "Czynsz"
  kwota: 1500.00
  termin_platnosci: "2025-05-10"
  notatka: "Przelew na konto zarządcy"
  cyklicznosc: "miesięczna"

oplats.update_bill – Aktualizuj opłatę

service: oplats.update_bill
data:
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  kwota: 1600.00
  termin_platnosci: "2025-06-10"

oplats.delete_bill – Usuń opłatę

service: oplats.delete_bill
data:
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

oplats.mark_paid – Oznacz jako zapłacone

Automatycznie ustawia zaplacone=true oraz data_przelewu na aktualną datę i godzinę.

service: oplats.mark_paid
data:
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

oplats.mark_unpaid – Oznacz jako niezapłacone

Czyści data_przelewu i ustawia zaplacone=false.

service: oplats.mark_unpaid
data:
  id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Wskazówka: ID opłaty znajdziesz w atrybutach sensorów (np. sensor.oplaty_niezaplacone → atrybut oplaty).

---

Przykładowa karta Lovelace

Poniższa karta prezentuje trzy sensory agregujące. Wklej ją w edytorze YAML kart:

type: entities
title: 💸 Opłaty
entities:
  - entity: sensor.oplaty_niezaplacone
    name: Niezapłacone
    icon: mdi:cash-remove
  - entity: sensor.oplaty_przeterminowane
    name: Przeterminowane
    icon: mdi:alert-circle-outline
  - entity: sensor.oplaty_najblizszy_termin
    name: Najbliższy termin
    icon: mdi:calendar-clock

Dokładne nazwy encji zależą od nazwy instancji integracji. Sprawdź je w Ustawienia → Urządzenia i usługi → Opłaty.

---

Struktura plików

custom_components/
└── oplats/
    ├── __init__.py          # Konfiguracja integracji + rejestracja usług
    ├── manifest.json        # Metadane integracji
    ├── config_flow.py       # Konfiguracja przez UI
    ├── const.py             # Stałe
    ├── coordinator.py       # Logika danych + zapis w .storage
    ├── sensor.py            # Encje sensorów
    ├── services.yaml        # Definicje usług
    └── translations/
        └── pl.json          # Tłumaczenia polskie

---

Licencja

MIT