Przejdź do treści

API eksportu

Smart Tech App udostępnia RESTful API umożliwiające programowy dostęp do funkcji eksportu danych licznikowych.

Bazowy adres URL

https://app.smart-tech.live/api/v1

Uwierzytelnianie

API obsługuje dwa sposoby uwierzytelniania:

Token API

Authorization: Token TWÓJ_TOKEN_API

Sesja przeglądarkowa

Do testów przez przeglądarkę możesz zalogować się przez interfejs webowy i uzyskać bezpośredni dostęp do API.

Dokumentacja API

Pełną dokumentację API z możliwością interaktywnego testowania znajdziesz na: https://app.smart-tech.live/api/docs

Punkty Końcowe Eksportu

API Eksportu Miesięcznego

Proste API do programowego eksportu miesięcznych odczytów liczników.

Punkt końcowy: POST /export/monthly/

Treść żądania: 

{
  "uuids": ["meter-uuid-1", "meter-uuid-2"],
  "month": "2024-01"
}

Odpowiedź: 

{
  "month": "2024-01",
  "timestamp": "2024-01-15T14:30:22.123456Z",
  "data": [
    {
      "uuid": "meter-uuid-1",
      "name": "Energia Elektryczna Budynek Główny",
      "media": "electricity",
      "values": {
        "active": {
          "value": 1500.25,
          "timestamp": "2024-01-31T23:45:00Z",
          "status": "ok",
          "days_before_period": 0
        },
        "reactive": {
          "value": 125.5,
          "timestamp": "2024-01-31T23:45:00Z",
          "status": "ok",
          "days_before_period": 0
        }
      },
      "status": "ok"
    },
    {
      "uuid": "meter-uuid-2",
      "name": "Woda Budynek Główny",
      "media": "water",
      "values": {
        "volume": {
          "value": 2500.75,
          "timestamp": "2024-01-29T10:30:00Z",
          "status": "early",
          "days_before_period": 2
        }
      },
      "status": "early"
    }
  ],
  "summary": {
    "total_requested": 2,
    "successful": 2,
    "missing": 0,
    "unauthorized": 0
  }
}

Kluczowe Funkcjonalności:

  • Automatyczny Eksport Wartości: Wszystkie dostępne wartości dla każdego typu licznika są eksportowane
  • Wartości Specyficzne dla Mediów:
  • Energia elektryczna: active, reactive
  • Ciepło: heat_kwh, heat_gj (obie jednostki automatycznie włączone)
  • Woda: volume
  • Świadome Uprawnień: Respektuje uprawnienia koncentratorów użytkownika/tokenu
  • Przetwarzanie Zbiorcze: Efektywne przetwarzanie dla dużych list UUID

Odpowiedzi Błędów

Wszystkie punkty końcowe zwracają standardowe kody stanu HTTP ze szczegółami błędów:

{
  "error": {
    "code": "INVALID_MONTH_FORMAT",
    "message": "Format miesiąca musi być YYYY-MM",
    "details": {
      "provided_format": "2024/01",
      "expected_format": "YYYY-MM"
    }
  }
}

Częste kody błędów:

  • INVALID_API_TOKEN: Uwierzytelnianie nie powiodło się
  • INVALID_MONTH_FORMAT: Błąd walidacji formatu miesiąca
  • METER_NOT_FOUND: Określony UUID licznika nie został znaleziony
  • INSUFFICIENT_PERMISSIONS: Użytkownik nie ma wymaganych uprawnień

Przykłady

Praktyczne przykłady implementacji znajdują się w: