Livion Key

Livion Key är ett system för nyckelhantering. Systemet kan skicka händelser om nyckelskåp och nycklar till externa system. Orbiq har ett API som tar emot dessa händelser via Webhooks och omvandlar de händelser som stöds till larm.

Orbiq hanterar två typer av händelser från Livion Key:

device-alarm för larm från ett nyckelskåp.
key-status för en nyckel som inte har återlämnats eller som har återlämnats.

Händelser och larmhantering

Händelse från Livion Key	Värde	Mappning inom Orbiq	Kommentar
`device-alarm`	`state: activated`	Aktivt	Ett aktivt larm skapas för nyckelskåpet och larmtypen.
`device-alarm`	`state: deactivated`	Återgått	Det tidigare larmet för samma nyckelskåp och larmtyp återgår.
`key-status`	`state: key-not-returned`	Aktivt	Ett aktivt larm skapas för den nyckel som inte har återlämnats.
`key-status`	`state: key-returned`	Återgått	Larmet för den återlämnade nyckeln återgår.
`deviceId`	`LK-1`	Larmkälla	Värdet måste motsvara adressen för en Livion Key-larmkälla i Orbiq.
`start` `end` `time`	`2026-01-02T03:04:05.000Z`	Källtid	`start` används när ett enhetslarm aktiveras, `end` när det återgår och `time` för nyckelhändelser. Om `end` saknas används `start`. Tiden sparas som larmets källtid. Orbiq sparar dessutom en separat tid för när händelsen togs emot.

Följande larmtyper stöds för device-alarm:

`alarmType`	Text i Orbiq	Standardprioritet
`DEVICE_ERROR`	`Device error`	A
`DEVICE_POWER_DISCONNECTED`	`Power disconnected`	B
`DEVICE_LOW_POWER`	`Low power`	B
`DEVICE_MOVED`	`Device moved`	B
`DEVICE_DISCONNECTED`	`Device disconnected`	A
`DEVICE_WIFI_OFFLINE`	`Device WiFi offline`	B

Prioriteterna ovan är Orbiqs standardinställning. Systemadministratören kan ändra vilka larmtyper som får prioritet A samt vilken standardprioritet som ska användas för övriga larm.

Larmpunkt och larmtext

Orbiq grupperar händelser under en teknisk beteckning för larmpunkten. För enhetslarm används:

livion-key:{deviceId}:{alarmType}

Exempel:

livion-key:LK-1:DEVICE_ERROR

För en nyckel som inte har återlämnats används:

livion-key:{deviceId}:KEY_NOT_RETURNED:{nyckelidentifierare}

Exempel:

livion-key:LK-1:KEY_NOT_RETURNED:KEY-7

Larmpunktens beskrivning och larmhändelsens text skapas på engelska utifrån händelsens innehåll. Exempel på beskrivningar är:

Device error activated for device LK-1
Key not returned for device LK-1
Key returned for device LK-1

Larmhändelsens text innehåller även eventtyp, deviceId, status, tidsuppgifter och andra relevanta fält som finns i händelsen. Relevanta payloadfält lagras också som metadata och kan hämtas via Orbiqs API. Metadata visas normalt inte i Orbiqs användargränssnitt.

Exempel på payload

Ett aktiverat enhetslarm kan se ut så här:

{
  "type": "device-alarm",
  "deviceId": "LK-1",
  "alarmType": "DEVICE_ERROR",
  "state": "activated",
  "start": "2026-01-02T03:04:05.000Z",
  "end": null,
  "acknowledged": false
}

En händelse för en nyckel som inte har återlämnats kan se ut så här:

{
  "type": "key-status",
  "deviceId": "LK-1",
  "lockerIndex": 12,
  "state": "key-not-returned",
  "time": "2026-01-02T05:06:07.000Z",
  "keyId": "KEY-7"
}

Inställning av larmutskick

Orbiq-administratören lägger upp den API-nyckel som ska användas av Livion Key-integrationen. API-nyckeln ska därefter skickas med varje anrop i HTTP-headern x-api-key.

I Livion Key registreras Orbiqs endpoint för mottagning av händelser enligt formatet nedan. Platshållaren {orbiq_url} ska bytas ut mot den faktiska adressen till Orbiq-installationen.

https://{orbiq_url}/api/iqalarm/alarmEvent/livion-key

Livion Key ska skicka en HTTP POST med JSON-data till adressen. Följande headers ska anges:

Content-Type: application/json
x-api-key: {api_key}

I Orbiq registreras en separat larmkälla för varje Livion Key-enhet:

Aktivera Larmhantering på resursen.
Ange Livion-enhetens exakta deviceId i fältet Adress för identifiering av larmkällan.
Välj livion-key som larmformat.
Markera larmkällan som Publicerad.

Felsökning

Händelserna key-fetched, contract-update och code-entered stöds inte av integrationen. De ignoreras utan att skapa larm.

HTTP-status	Betydelse
200 med `event`	Händelsen har tagits emot och ett larm har skapats.
200 med `message: ignored`	Eventtypen, larmtypen eller nyckelstatusen stöds inte och har därför ignorerats.
400	Payloaden saknar ett obligatoriskt fält, innehåller en ogiltig tid eller hänvisar till en `deviceId` som inte matchar en Livion Key-larmkälla.
401	Headern `x-api-key` saknas eller innehåller en ogiltig API-nyckel.
409	Larmkällan i Orbiq är inte publicerad.
503	API-nyckeln har ännu inte konfigurerats i Orbiq. Kontakta Orbiq-administratören.