Pomiary w Twojej aplikacji.

1. Token organizacji i ID sensora

1. Otwórz panel i wybierz Tokeny API.
2. Dodaj token, nadaj mu nazwę i opcjonalnie ustaw datę wygaśnięcia. Token musi być aktywny i przypisany do organizacji.
3. Po zapisaniu skopiuj pełną wartość tokena. Nie jest przechowywana do ponownego odczytu — jeśli ją zgubisz, utwórz nowy token i dezaktywuj poprzedni.
4. W sekcji Temperatura → Sensory skopiuj Device ID wybranego sensora.

Użyj tokena organizacji w nagłówku X-Api-Token. Device ID identyfikuje sensor; nie jest kluczem dostępu. Sekret urządzenia i jego token JWT służą do komunikacji urządzenia, nie do odczytu tego API.

Odczyt wymaga dostępu do API i danych sensora w abonamencie organizacji. Token nie daje dostępu do sensorów innej organizacji.

Przechowuj token po stronie serwera, w zmiennych środowiskowych lub magazynie sekretów. Nie dodawaj go do repozytorium, kodu przeglądarki ani logów. Dla produkcyjnego API używaj HTTPS.

2. Pierwsze zapytanie do REST API

GET https://sensor.besmartand.pro/api/client/sensors/{id}/history

Ustaw SENSOR_API_TOKEN i SENSOR_ID w środowisku, a następnie wykonaj:

curl 'https://sensor.besmartand.pro/api/client/sensors/'"$SENSOR_ID"'/history' \
  -H 'Accept: application/json' \
  -H "X-Api-Token: $SENSOR_API_TOKEN"

Przykładowa odpowiedź:

{
  "items": [
    {
      "sensor": "Chłodnia A",
      "temperature": 4.2,
      "humidity": 51.5,
      "datetime": "2026-10-12T12:00:00+02:00"
    }
  ]
}

sensor to etykieta sensora, temperature to temperatura w °C, a humidity to wilgotność względna w %. Wilgotność i data mogą mieć wartość null. Pusta historia ma postać {"items": []}.

Endpoint zwraca maksymalnie 200 ostatnich pomiarów. Nie udostępnia paginacji ani filtrów dat. Jeśli zapisujesz własne archiwum, dobierz częstotliwość odczytu do częstotliwości pomiarów i limitu API w abonamencie.

3. Biblioteka dla PHP

besmartand-pro/bsap-sensor-client działa z PHP 8.4 lub nowszym. Nie wymaga frameworka. Poniższy przykład używa Guzzle jako transportu HTTP i Nyholm jako fabryki żądań.

composer require 'besmartand-pro/bsap-sensor-client:~1.0.0' guzzlehttp/guzzle nyholm/psr7

<?php

use BeSmartAndPro\BsapSensorClient\SensorClient;
use GuzzleHttp\Client;
use Nyholm\Psr7\Factory\Psr17Factory;

require 'vendor/autoload.php';

$client = new SensorClient(
    new Client(['timeout' => 10, 'connect_timeout' => 5]),
    new Psr17Factory(),
    getenv('SENSOR_API_TOKEN') ?: '',
);

foreach ($client->getSensorHistory('SENSOR_UUID') as $measurement) {
    echo $measurement->getSensor() . ': '
        . $measurement->getTemperature() . ' °C' . PHP_EOL;
}

Zastąp SENSOR_UUID skopiowanym Device ID. Klient domyślnie łączy się z https://sensor.besmartand.pro; czwarty argument konstruktora pozwala wskazać inne środowisko.

Każdy pomiar jest obiektem SensorMeasurement z metodami getSensor(), getTemperature(), getHumidity() i getDatetime(). Data jest obiektem DateTimeImmutable lub ma wartość null.

Pakiet w Packagist · Kod i README klienta

4. Integracja z Symfony

besmartand-pro/bsap-sensor-bundle dodaje konfigurację i autowiring klienta w Symfony 7.4 oraz 8.x. Wymaga PHP 8.4 lub nowszego i korzysta z biblioteki klienta w wersji 1.0.x.

Bundle nie jest jeszcze opublikowany w Packagist. Poniższe polecenie instalacji będzie dostępne po publikacji pakietu.

composer require besmartand-pro/bsap-sensor-bundle

W config/bundles.php dodaj wpis do istniejącej tablicy:

BeSmartAndPro\BsapSensorBundle\BsapSensorBundle::class => ['all' => true],

Utwórz config/packages/bsap_sensor.yaml:

bsap_sensor:
    api_token: '%env(SENSOR_API_TOKEN)%'
    base_uri: 'https://sensor.besmartand.pro'
    timeout: 10.0
    http_client: 'http_client'

Ustaw SENSOR_API_TOKEN w środowisku aplikacji lub Symfony Secrets. Tylko api_token jest wymagany; pozostałe wartości powyżej są domyślne. Aplikacja musi mieć włączony HttpClient, np. framework: { http_client: ~ }.

Wstrzyknij klienta do serwisu:

<?php

namespace App\Service;

use BeSmartAndPro\BsapSensorClient\SensorClientInterface;

final readonly class SensorHistoryService
{
    public function __construct(private SensorClientInterface $sensorClient)
    {
    }

    public function read(string $sensorId): array
    {
        return $this->sensorClient->getSensorHistory($sensorId);
    }
}

Bundle konfiguruje osobny transport Symfony HttpClient z timeoutem i wyłączonymi przekierowaniami. Opcja http_client pozwala wskazać istniejący klient HTTP aplikacji.

Repozytorium bundla

5. Błędy i limity

• 200 — pomiary zostały zwrócone.
• 401 — token jest nieprawidłowy, wygasł lub został dezaktywowany.
• 403 — brak uprawnień, sensor spoza organizacji lub brak wymaganej funkcji w abonamencie. Żądanie bez tokena może również otrzymać tę odpowiedź.
• 404 — sensor o podanym ID nie istnieje.
• 429 — został przekroczony limit zapytań API w planie organizacji.
• 5xx — błąd po stronie serwera.

Biblioteka zgłasza ApiException dla odpowiedzi innej niż 200. Kod odczytasz przez getStatusCode(). Metoda getRetryAfter() zwraca nagłówek Retry-After, jeśli serwer go przesłał; może zwrócić null.

Niepoprawna odpowiedź zgłasza InvalidResponseException, a problemy z połączeniem wyjątek transportu PSR-18. Klient nie ponawia zapytań automatycznie. Po 429 ogranicz częstotliwość odczytu; ponawianie bez przerwy nie zwiększy limitu planu.