Läs anläggningens data

Nyckel per motpart

Varje integration får sin egen nyckel. Nyckeln bär tre rättigheter och en lista med de anläggningar den ser — tom lista betyder alla anläggningar hos den som utfärdade den. Nyckeln lagras bara som SHA-256, så klartexten visas en enda gång när den skapas. Den har en giltighetstid och ett tak per minut, båda satta när den utfärdas. Databasen filtrerar dessutom varje läsning på nyckelns anläggningar (RLS), inte bara API-lagret.

Nycklar utfärdas av FRESAB på begäran av anläggningens ägare. Ring 010-200 81 32 och berätta vilket system som ska integreras och vad det behöver läsa.

Regler

Åtta regler gäller alla ändpunkter lika, och de prövas i den här ordningen på varje anrop. En klient som följer dem pollar med andrad_efter och If-None-Match och får i normalfallet 304 eller en tom lista — det kostar en nyckelslagning och en indexerad fråga, inte tusentals rader.

1. 1
   En nyckel per motpart

   Rättigheter, anläggningar och giltighetstid sitter på nyckeln. Nyckeln kan gå ut på ett datum utan att någon behöver spärra den.

   Spärrad eller utgången nyckel: 401. Saknad rättighet: 403.

2. 2
   Tak per minut

   Standard 120 anrop per kalenderminut och nyckel. Räknas före rättighetskontrollen, så avvisade anrop kostar också. Behöver ni mer, säg till — taket sätts per nyckel.

   Över taket: 429 med Retry-After i sekunder. Varje svar bär X-RateLimit-Limit, -Remaining och -Reset.

3. 3
   ETag på alla GET

   Spara ETag ur svaret och skicka tillbaka den som If-None-Match nästa gång.

   Oförändrat svar: 304 utan kropp. Det sparar överföringen — databasfrågan körs ändå för att veta om något ändrats.

4. 4
   Hämta delta, inte allt

   andrad_efter på varden och larm ger bara det som rört sig; svaret bär hamtad (serverns tid) att skicka tillbaka nästa gång. Historik fortsätts med nasta_fran.

   En pollande motpart får ett tomt svar när ingenting hänt — inte hela listan varje minut.

5. 5
   Listor har tak

   Varje lista säger trunkerad: true när taket slog till. limit höjer till max, efter och nasta_fran fortsätter där förra svaret slutade.

   Ett svar som tystnat vid 5000 rader ska aldrig se ut som ett svar med 5000 rader i databasen.

6. 6
   Räkna aldrig på quality bad

   stale är ett reservvärde när insamlingen tystnat; bad med error är ett värde som finns men inte ska litas på.

   Ett avbrottsvärde från en oansluten givare ser ut som 177,8 °C. Det är inte en temperatur.

7. 7
   Ingenting i molnet skriver till en PLC

   En skrivbegäran köas och utförs på plats genom vaktkedjan nedan.

   202 Accepted med id; utfallet hämtas på /skrivningar/{id}.

8. 8
   Inga webhooks

   Motparten hämtar det den behöver, när den behöver det. Larm levereras som mejl av larmvakten.

   Ett larmsystem pollar larm?aktiv=true&andrad_efter=… — med ETag blir det ett 304 i minuten.

GET https://portal.fresab.se/api/v1/varden?kalla=<källa>&andrad_efter=2026-09-25T06:00:00Z
Authorization: Bearer <nyckel>
If-None-Match: W/"3f9c1a2b0e7d4c5b6a81"

HTTP/1.1 304 Not Modified
ETag: W/"3f9c1a2b0e7d4c5b6a81"
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1790316060

Ändpunkter

Lita på värdena — och inte

Varje värde bär ett quality: good är en färsk avläsning, stale är ett reservvärde när insamlingen tystnat, och bad betyder att värdet finns men inte ska litas på — till exempel ett avbrottsvärde från en givare som inte är inkopplad. Räkna aldrig på ett bad-värde. Är error satt står skälet där.

Mätarställningar (MWh, m³) är ackumulerande räknare. Förbrukning är skillnaden mellan två ställningar — läs steg=dygn och använd sist, inte medel. En skillnad som blir negativ betyder mätarbyte eller överrullning, inte minusförbrukning.

Att begära ett börvärde

Ingenting i molnet skriver till en PLC. En begäran läggs i kö och hämtas av insamlaren på plats, som utför den genom sin vaktkedja:

1. punkten är märkt skrivbar i katalogen
2. värdet ligger inom punktens min och max
3. ändringstakten håller sig under punktens tak
4. spärrtaggen (till exempel värmepumpens blockerande A-larm) är noll och färsk
5. enheten ekar skrivningen och återläsningen stämmer

Utfallet blir skriven, avvisad (vakten sa nej, med motivering) eller misslyckad (fältet svarade inte som väntat), och hämtas på GET /api/v1/skrivningar/{id}. Varje begäran loggas med vem, vad och när, och loggen går inte att redigera.

curl -X POST https://portal.fresab.se/api/v1/skrivningar \
  -H "Authorization: Bearer <nyckel>" \
  -H "Content-Type: application/json" \
  -d '{"kalla":"<källa>","tag":"<tagg>","varde":35,"skal":"effekttak"}'

HTTP/1.1 202 Accepted
{ "id": "…", "status": "vantar" }

Historik och upplösning

Finns fler rader än limit är trunkerad: true och nasta_fran sista tidsstämpeln, att skicka som fran i nästa anrop. Insamlingen loggar vid förändring, så en punkt som stått still saknar rader — värdet gällde ändå hela tiden.

Att leverera egna mätvärden

Har ni själva mätvärden som hör till anläggningen — inomhustemperaturer, undermätare, närvaro — kan de pushas in i portalen och visas tillsammans med resten. Källan skapas av admin, och nya punkter dyker upp i katalogen automatiskt.

curl -X POST https://portal.fresab.se/api/v1/varden \
  -H "Authorization: Bearer <nyckel>" \
  -H "Content-Type: application/json" \
  -d '{"kalla":"<källa>","varden":[
        {"tag":"medel_inne_temp","value":21.4,"unit":"°C","ts":"2026-09-23T10:00:00Z"},
        {"tag":"lgh_12_temp","value":20.9,"unit":"°C"}
      ]}'

ts utelämnad betyder nu. value: null lagras som quality bad. Svaret listar nya punkter och avvisade rader.