Instrukcja korzystania z HTTP API centrali Sinum

Wprowadzenie

Centrala Sinum udostępnia lokalny interfejs REST API (OpenAPI 3.0), opisany za pomocą narzędzia Swagger.
Interfejs API umożliwia programowy odczyt oraz modyfikację stanu urządzeń zintegrowanych z centralą — bez użycia aplikacji mobilnej ani panelu webowego.

Uwaga!!! Konfigurację należy przeprowadzić w przeglądarce Google Chrome.
Podczas pierwszego uruchomienia wymagane jest zaakceptowanie zgody na dostęp do urządzeń w sieci lokalnej.

Interaktywna dokumentacja API dostępna jest pod adresem:
https://apidocs.sinum.tech/

Konfiguracja serwera (hostname)

Po otwarciu dokumentacji Swagger widoczna jest sekcja Server variables.

W polu hostname_or_ip wpisz odpowiednią wartość:

• • sinum.local — jeśli w sieci znajduje się tylko jedna centrala Sinum,
  • adres IP centrali (np. 10.0.62.29) — jeśli w sieci jest kilka central lub mDNS nie działa.

Uwaga:
Pole hostname_or_ip określa, do której centrali będą kierowane zapytania API.

Logowanie (uwierzytelnianie)

Większość endpointów wymaga tokenu autoryzacyjnego. Należy go uzyskać za pomocą endpointu POST /login.

Kroki

1. Przejdź do sekcji auth → POST /login.
2. Kliknij przycisk Try it out.
   
   
   
   
3. W polu Request body uzupełnij dane logowania:
   • username
   • password
   • os_info
   • device_info
   • uuid_device

Uwaga:
Pola os_info, device_info oraz uuid_device mogą zawierać dowolne wartości — nie wpływają na proces autoryzacji.

4. Kliknij Execute.

Odpowiedź

Po poprawnym zalogowaniu centrala zwraca kod 200 oraz obiekt JSON zawierający m.in.:

• session — token sesji (JWT) używany do autoryzacji kolejnych zapytań,
• refresh_token — token służący do odświeżania sesji bez ponownego logowania.

Swagger automatycznie zapisuje token i dołącza go do kolejnych zapytań w nagłówku Authorization.

Równoważne zapytanie curl

Swagger udostępnia gotowy przykład zapytania curl dla każdego endpointu.

Przykład logowania

curl -X 'POST' 
'http://10.0.62.29/api/v1/login' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-d '{
"username": "admin",
"password": "admin",
"os_info": "ios",
"device_info": "chrome",
"uuid_device": "5432-5432-5432"
}'

Autoryzacja w kolejnych zapytaniach

Dla endpointów wymagających autoryzacji należy dodać nagłówek:

-H 'Authorization: '

Przykład: pobranie wirtualnego termostatu

Znalezienie ID termostatu

1. Otwórz panel webowy centrali.
2. Przejdź do Ustawienia → Urządzenia → Urządzenia wirtualne.
3. Kliknij ikonę trzech kropek (⋯) przy wybranym termostacie.
4. Na dole listy właściwości odczytaj wartość Identyfikator (ID).

Wywołanie endpointu

1. W dokumentacji Swagger wyszukaj (Ctrl + F) sekcję GET /devices/virtual/{id}.
2. Kliknij Try it out.
3. Wprowadź ID urządzenia (np. 21).
4. Kliknij Execute.

Odpowiedź centrali

Centrala zwraca kod 200 oraz obiekt JSON zawierający pełny stan urządzenia.

Przykładowe pola:

• temperature — aktualna temperatura,
• target_temperature — temperatura zadana (wartość ×10),
• state — stan ogrzewania (true / false),
• mode — tryb pracy (heating, cooling).

Przykład zapytania curl

curl -X 'GET' 
'http://10.0.62.29/api/v1/devices/virtual/21' 
-H 'accept: application/json' 
-H 'Authorization: '

Schemat odpowiedzi — Device.VIRTUAL.Thermostat

Sekcja Responses → Schema dla endpointu GET /devices/virtual/{id} zawiera pełny opis struktury odpowiedzi.

Kluczowe pola

Uwaga:
Wartość target_temperature jest mnożona przez 10 (np. 250 = 25,0 °C).
Zakres: 50–350. Jednostka zależy od konfiguracji regionu.

Przykład: zmiana parametru wirtualnego termostatu

Zmiana parametrów odbywa się za pomocą endpointu PATCH /devices/virtual/{id}.

Kroki

1. W dokumentacji Swagger wyszukaj (Ctrl + F) sekcję PATCH /devices/virtual/{id}.
2. Kliknij Try it out.
3. Wprowadź ID urządzenia (np. 21).
4. W sekcji Request body usuń wszystkie pola, których nie chcesz zmieniać.

Uwaga:
Nie należy wysyłać pól tylko do odczytu (id, type, class, messages itd.).

5. Wprowadź wymagane zmiany, np.:

   {
   "target_temperature": 220
   }

   
   

6. Kliknij Execute.
7. Centrala zwróci kod 200 oraz zaktualizowany obiekt urządzenia.

Przykład zapytania curl

curl -X 'PATCH' 
'http://10.0.62.29/api/v1/devices/virtual/21' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Authorization: ' 
-d '{"target_temperature": 220}'

Kody odpowiedzi API

Przykład błędu 400

{
"error": {
"message": {
"text": "Invalid object ID.",
"id": 7207
}
}
}