API за Home Assistant и други програми

Данните от твоята система – инвертори, батерии, клетки, мрежа и консумация – в JSON формат, за Home Assistant, Node-RED или твои програми. API-то е само за четене: през него не могат да се променят настройки.

Локално API – в домашната мрежа, директно от устройството, без интернет. Безплатно. Идва с нов софтуер на устройството.

Облачно API – през нашия сървър, работи отвсякъде. Включва се при поръчка или от „Моите устройства“ → „API“, където се създава и ключът.

Достъп

Всяка заявка трябва да носи твоя API ключ в заглавието Authorization: Bearer sm_… (или X-API-Key: sm_…). Ключът виждаш целия само веднъж, когато го създадеш – пази го като парола. Ако изтече, изтрий го от профила и създай нов.

Ограничения: до 12 заявки в минута на ключ и до 30 заявки за история в час. Данните „сега“ се обновяват около веднъж в минута, така че за Home Assistant 30–60 секунди интервал е напълно достатъчен.

Адреси

Адрес	Какво връща
`GET /api/v1/devices`	Твоите устройства и до кога е активно облачното API
`GET /api/v1/devices/{№}/now`	Сега: панели, товар, мрежа, батерии (W), добив днес, напрежения, заряд
`GET /api/v1/devices/{№}/inverters`	Всеки инвертор с всички стойности, които чете устройството
`GET /api/v1/devices/{№}/batteries`	Всяка батерия: заряд, напрежение, ток, мощност, температури, всяка клетка
`GET /api/v1/devices/{№}/history?metric=pv&hours=24`	История: `pv`, `load`, `grid` или `battery` за 6, 24, 72 или 168 часа

{№} е номерът на устройството, напр. 28848597D10C. Мощностите са във ватове: grid_power_w > 0 значи купуваш от мрежата, battery_power_w > 0 значи батериите се зареждат.

Пример

curl -H "Authorization: Bearer sm_ТВОЯТ_КЛЮЧ" https://solarmonitor.pro/api/v1/devices/28848597D10C/now

{
  "device": "28848597D10C",
  "updated": "2026-10-03T20:45:12+03:00",
  "pv_power_w": 12840,
  "load_power_w": 7470,
  "grid_power_w": -420,
  "battery_power_w": 4950,
  "pv_today_kwh": 61.3,
  "battery_soc": 78,
  "battery_voltage_v": 52.91
}

Home Assistant

Добави в configuration.yaml (ключът е в secrets.yaml като solarmonitor_key: "Bearer sm_…") и рестартирай Home Assistant:

rest:
  - resource: https://solarmonitor.pro/api/v1/devices/28848597D10C/now
    headers:
      Authorization: !secret solarmonitor_key
    scan_interval: 60
    sensor:
      - name: "Solar PV мощност"
        value_template: "{{ value_json.pv_power_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Solar товар"
        value_template: "{{ value_json.load_power_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Solar мрежа"
        value_template: "{{ value_json.grid_power_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Solar батерии мощност"
        value_template: "{{ value_json.battery_power_w }}"
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
      - name: "Solar заряд на батериите"
        value_template: "{{ value_json.battery_soc }}"
        unit_of_measurement: "%"
        device_class: battery
      - name: "Solar добив днес"
        value_template: "{{ value_json.pv_today_kwh }}"
        unit_of_measurement: "kWh"
        device_class: energy
        state_class: total_increasing

Грешки

Код	Значение
401	Липсва или е грешен API ключ
402	Облачното API не е активно или е изтекло – поднови го от профила
404	Няма такова устройство в профила ти или такъв адрес
429	Твърде много заявки – изчакай (виж заглавието `Retry-After`)