{{tag>livion livionkey orbiq integration}}
====== Livion Key ======

[[https://livionkey.com/api-integration|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:

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

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

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

===== 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. |