Skip to main content

Enpulse Data API v1 — Developer Docs

Svi endpointi su dostupni pod osnovnom putanjom /api/data/v1 na hostu https://enpulse.gep.energy/gep-service.

Svi endpointi komuniciraju JSON preko HTTPS-a.

Autentikacija​

Data API koristi autentikaciju putem API ključa. Pružite važeći API ključ izdan za vaš korisnički račun na jedan od sljedećih načina:

  • Zaglavlje zahtjeva: X-Api-Key: <your_api_key> (preporučeno)
  • Zaglavlje autorizacije: Authorization: ApiKey <your_api_key>
  • Parametar upita: ?api_key=<your_api_key>

Ako autentikacija nedostaje ili je nevažeća, zahtjev neće biti povezan s korisnikom i neće uspjeti.

Konvencije i ograničenja​

  • Vremenski parametri koriste ISO-8601 lokalni datum i vrijeme (bez vremenske zone), npr. 2025-10-05T13:00:00.
  • Vremenske oznake u odgovorima vremenskih serija su epoch milisekunde u polju ts.
  • Ograničenje perioda za upite telemetrije: razlika između from i to ne smije biti veća od 24 sata (1 dan). Zahtjevi koji prelaze ovo ograničenje rezultirat će s 400 Bad Request i porukom The requested period must not exceed 1 day.
  • Ograničenje imovine: Svi identifikatori imovine moraju pripadati autentificiranom korisniku; u suprotnom zahtjev pada s 400 Bad Request i porukom Asset does not belong to the authenticated customer.
  • Dostupnost uređaja: Imovina mora imati barem jedan pridruženi uređaj; u suprotnom telemetrijski zahtjevi padaju s 400 Bad Request i porukom Asset has no devices bound.

Napomena o razlučivosti podataka:

  • Neka imovina ima sirovu 15-minutnu razlučivost (kada je dostupan mjerni punkt). Vrijednosti ts usklađene su s temeljnim podacima; u ovoj varijanti API-ja ne primjenjuje se dodatni pomak sredine intervala.

Rukovanje greškama​

Uobičajeni odgovori na greške:

  • 400 Bad Request
    • The requested period must not exceed 1 day
    • Asset does not belong to the authenticated customer
    • Asset has no devices bound
  • 401 Unauthorized
    • Missing API key authentication
    • Invalid authenticated customer ID

Tijelo greške ima zadani (Spring) format i može uključivati polja poput timestamp, status, error, message i path.

Tipovi podataka​

  • UUID: string od 36 znakova, npr. c6e1e3a3-5b77-4f2c-9e5c-3b2b6b2a9a10.

Modeli​

  • CustomerAssetModel (odgovor na /assets):

    • id: UUID
    • name: string
    • description: string
    • createdAt: string (ISO-8601 datum/vrijeme)
    • meteringPointId: string|null
    • connectionPowerFromGrid: number|null
    • connectionPowerToGrid: number|null
    • voltageLevel: string|null
    • supplierTariffModel: object|null
    • longitude: number|null
    • latitude: number|null
    • devices: object — mapa od DeviceProfile do TbDeviceModel
      • DeviceProfile može biti REALTIME, HISTORICAL, METEO
      • TbDeviceModel:
        • id: UUID
        • deviceProfile: string
    • address: string|null
    • city: string|null
    • zipCode: string|null
    • country: string|null
    • state: string|null

  • TimeseriesItemModel:

    • ts: number — epoch milisekunde
    • value: number

Endpointi​

GET /api/data/v1/assets​

Vraća svu imovinu koja pripada autentificiranom korisniku. Pojedinosti o tarifama su minimizirane u ovom popisu.

  • Autentikacija: obavezna
  • Parametri upita: nema
  • Odgovor: 200 OK sa List<CustomerAssetModel>

Primjer zahtjeva:

curl -X GET \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets

GET /api/data/v1/assets/{assetId}/telemetry/latest​

Vraća posljednju točku podataka za zadane telemetrijske keys na jednoj imovini.

  • Autentikacija: obavezna
  • Parametri u putanji:
    • assetId: UUID — mora pripadati autentificiranom korisniku
  • Parametri upita (obavezni):
    • keys: string[] — jedan ili više telemetrijskih ključeva, npr. keys=power,energy
  • Odgovor: 200 OK s Map<string, TimeseriesItemModel>; ključevi su nazivi telemetrije

Primjer zahtjeva:

curl -G \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  --data-urlencode "keys=power" \
  --data-urlencode "keys=energy" \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets/80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f/telemetry/latest

POST /api/data/v1/assets/telemetry/latest​

Vraća posljednje točke podataka za više imovina u jednom zahtjevu.

  • Autentikacija: obavezna
  • Tijelo: JSON LatestBatchRequest
    • assetIds: UUID[] (obavezno, nije prazno)
    • keys: string[] (obavezno, nije prazno)
  • Odgovor: 200 OK s Map<UUID, Map<string, TimeseriesItemModel>>

Primjer zahtjeva:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -d '{
        "assetIds": [
          "80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f",
          "b0f3a3d0-0b25-4a5d-9c5c-5d2df0c4a5d2"
        ],
        "keys": ["power", "energy"]
      }' \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets/telemetry/latest

GET /api/data/v1/assets/{assetId}/telemetry​

Vraća vremensku seriju za zadane telemetrijske keys između from i to vremenskih oznaka.

  • Autentikacija: obavezna
  • Parametri u putanji:
    • assetId: UUID — mora pripadati autentificiranom korisniku
  • Parametri upita (svi obavezni):
    • keys: string[]
    • from: string (ISO-8601 lokalni datum/vrijeme) — uključiv početak
    • to: string (ISO-8601 lokalni datum/vrijeme) — isključiv kraj; to - from <= 24h
  • Odgovor: 200 OK s Map<string, List<TimeseriesItemModel>>

Napomene o ponašanju:

  • Ako imovina ima mjerni punkt (sirova 15-minutna razlučivost), API vraća sirove točke u tom razlučivanju za traženi period.
  • ts u svakom TimeseriesItemModel je točan epoch timestamp u milisekundama.

Logika odabira uređaja​

Prilikom dohvaćanja telemetrije za imovinu, API odabire primarni uređaj:

  • Preferira uređaj s DeviceProfile.REALTIME ako postoji
  • Inače koristi prvi dostupni uređaj imovine

Ako imovina nema uređaje, API vraća 400 Bad Request i Asset has no devices bound.

Najbolje prakse​

  • Uvijek preferirajte zaglavlje X-Api-Key za autentikaciju.
  • Održavajte keys niz što manjim radi smanjenja latencije i veličine odgovora.
  • Za veće vremenske raspona, podijelite zahtjeve na prozore koji ne prelaze 24 sata.