API

ZiggyMeter udostępnia proste i bezpieczne REST API do konfiguracji, sprawdzania statusu oraz integracji. Ta strona podsumowuje, jak połączyć się i uwierzytelnić przed rozpoczęciem korzystania z punktów końcowych (endpoints).

Pełną listę punktów końcowych znajdziesz w rozdziale Endpointy.

Transport

• Tylko HTTPS: wszystkie żądania przesyłane są przez TLS na porcie 443.
• Domyślnie JSON: wysyłaj nagłówek Content-Type: application/json i oczekuj odpowiedzi w formacie JSON, chyba że zaznaczono inaczej.

Uwierzytelnianie

Format nagłówka:

Authorization: Bearer <token>

Ważność tokena:

• Tokeny są ograniczone czasowo. Odpowiedź na logowanie zwraca pozostałą ważność w sekundach pod kluczem expires_in_secs.
• Odśwież token przed jego wygaśnięciem lub obsłuż błąd 401 Unauthorized, logując się ponownie.

Przykład odpowiedzi logowania:

{
    "token": "<token>",
    "expires_in_secs": 3600
}

Szybki start

1. Pobierz token

   curl -X POST \
   https://<host>/login \
   -H "Content-Type: application/json" \
   -d '{
       "username": "<username>",
       "password": "<password>"
   }'

2. Wywołaj dowolne API z tokenem

   curl -X GET \
   https://<host>/api/v1/system/status \
   -H "Authorization: Bearer <token>" \
   -H "Accept: application/json"

   Jeśli token jest brakujący lub nieprawidłowy, API zwróci błąd uwierzytelniania.

3. Wyloguj się

   curl -X POST \
   https://<host>/api/v1/system/logout \
   -H "Authorization: Bearer <token>"

Wywołanie logout natychmiast unieważnia bieżący token; kolejne żądania z tym tokenem zakończą się błędem uwierzytelniania. Aby kontynuować, pobierz nowy token, logując się ponownie.

TIP

Do celów testowych możesz rozważyć dodanie opcji -k do curl, która pozwala na połączenia z certyfikatami samopodpisanymi lub w inny sposób niezaufanymi.

Bezpieczniejsze alternatywy: zainstaluj ważny certyfikat na serwerze lub wskaż curl zaufany urząd certyfikacji za pomocą --cacert <ca.pem> (lub użyj systemowego magazynu zaufanych certyfikatów).

Aktualizacja (Upgrade)

Podczas wykonywania aktualizacji oprogramowania należy ograniczyć szybkość przesyłania danych; w przeciwnym razie urządzenie zgłosi błąd. Poniższy przykład pokazuje dławienie (throttling) za pomocą opcji --limit-rate wtyczki curl.

curl -X POST  \
https://<host>/api/v1/system/ota \
-H "Authorization: Bearer <token>" \
--data-binary "@XXXX-YYYY-00320-20250324T195250-ZiggyMeter-1.2.320.ota" \
--limit-rate 1024