Hoppa till innehållet
Dignita

Integrationsguide

Version 1.0 · 1 oktober 2026

Ta emot larm i era egna system

Dignita Alkolarm skickar de larm och händelser som ni har valt som webhooks till er HTTPS-endpoint. Varje POST-anrop innehåller ett JSON-objekt, kodat i UTF-8.

Stäm av med er kontaktperson hos Dignita vilken webhook-adress och token ni ska använda samt vilka händelser ni vill ta emot.

Anslutning och endpoint

Så ansluter ni

Lämna en fullständig webhook-adress till Dignita, till exempel https://receiver.example.com/dignita/alarms. Kom överens om vilka händelser ni vill ta emot. Dignita lämnar er token separat.

Krav på endpoint-adressen

Endpoint-adressen måste använda HTTPS med ett giltigt certifikat, korrekt värdnamn och en betrodd certifikatkedja. Självsignerade certifikat accepteras inte som standard. URL:en får vara högst 500 UTF-8-byte och får inte innehålla användarnamn, lösenord eller ett fragment (#).

Endpointen ska vara publikt nåbar. DNS kontrolleras vid varje leverans och måste ge tillåtna publika IP-adresser. Privata, lokala, reserverade adresser och loopback avvisas. Endpointen ska svara direkt; omdirigeringar följs inte.

Autentisering

Kontrollera token

Varje anrop innehåller Authorization: <TOKEN>. Kontrollera vid varje anrop att token matchar det värde ni fått från Dignita. Avvisa anrop med saknad eller felaktig token, exempelvis med HTTP 401, utan att behandla larmet eller händelsen. Förvara token så att bara behöriga kan komma åt den och se till att dess värde inte syns i loggar.

Ni får er token separat från Dignita. Kontrollera vid varje anrop att hela tokenvärdet matchar det ni har fått.

Ändringar och tokenbyte

Kontakta er kontaktperson hos Dignita för att planera ett byte av token. Samordna bytet med er IT-avdelning eller systemleverantör för att undvika avbrott i mottagningen av larm och händelser.

JSON och fält

Meddelandet innehåller objekten device och notification. Positionsinformation finns i notification.position. Exemplet visar ett underkänt AL-100-prov med position och alkoholvärde.

Händelse-ID, tider, namn och positionsvärden kan saknas eller vara null. Acceptera även nya JSON-fält för framtida utökningar. Utgå från tabellens krav när ni validerar meddelandet. Fält som är markerade som valfria ska inte krävas av ert system.

Använd värdet i notification.type för att avgöra hur händelsen ska hanteras. Varje kunds konfiguration ska vara kopplad till den överenskomna endpointen och token.

Fält i meddelandet

device
objectObligatoriskt
Information om enheten.
device.id
number | stringValfritt / kan saknas
Enhets-ID. Behandla som identifierare.
device.uniqueId
stringObligatoriskt
Icke-tom sträng, normalt IMEI. Bevara inledande nollor.
device.name
string | nullValfritt / kan saknas
Enhetens aktuella namn; inte en unik identifierare. Kan vara null.
notification
objectObligatoriskt
Information om händelsen.
notification.id
number | stringValfritt / kan saknas
Källans händelse-ID. Inte globalt unikt; kan saknas eller vara null.
notification.type
stringObligatoriskt
Icke-tom, exakt och skiftlägeskänslig händelsetyp.
notification.eventTime
Format från källanValfritt / kan saknas
Tidpunkten för händelsen. Kan saknas eller vara null; formatet kan variera.
notification.serverTime
numberObligatoriskt
Ändligt tal. Tidpunkten för vidarebefordran som Unix-tid i millisekunder.
notification.position
objectValfritt / kan saknas
Positionsinformation för händelsen. Positionsfält kan saknas eller vara null.
notification.position.id
number | stringValfritt / kan saknas
Källans positions-ID. Kan saknas eller vara null.
notification.position.time
Format från källanValfritt / kan saknas
Tidpunkten för positionsmätningen. Kan saknas eller vara null; formatet kan variera.
notification.position.latitude
numberValfritt / kan saknas
Latitud. Kan saknas eller vara null.
notification.position.longitude
numberValfritt / kan saknas
Longitud. Kan saknas eller vara null.
notification.additionalInfo
objectValfritt / kan saknas
Endast de fyra AL-100-provtyperna. Kan utelämnas.
notification.additionalInfo.bac
numberValfritt / kan saknas
Numeriskt alkoholvärde. Använd perMille för promillehalten.
notification.additionalInfo.perMille
numberValfritt / kan saknas
Promillevärde: bac × 10, högst fyra decimaler.

Tider, position och alkoholvärden

Tidsformat

notification.serverTime anger tidpunkten för vidarebefordran. Tiden anges som Unix-tid i millisekunder. notification.eventTime visar när händelsen inträffade, och notification.position.time visar när positionen uppmättes.

Händelse- och positionstider kan saknas eller anges i olika format. Exemplen använder ISO 8601 med UTC (Z), men de meddelanden ni tar emot kan ha andra tidsformat. Kontrollera formaten vid anslutningstestet och bevara originalvärdena.

Ert system ska kunna hantera saknade tidsuppgifter och värden som inte går att tolka. Tolka bara en tid utan tidszon som lokal tid om ni har kommit överens om det med Dignita.

När position saknas

Positionen kan komma från en tidigare positionsmätning. Kontrollera notification.position.time för att se när positionen uppmättes. När position saknas är de fyra positionsfälten null. Enskilda positionsfält kan också utelämnas. En saknad position är inte koordinaten 0, 0.

Promille och provresultat

additionalInfo med numeriska bac och perMille förekommer endast för al_test_passed, al_test_failed, al_retest_passed och al_retest_failed. Använd perMille för promille: perMille = bac × 10, avrundat till högst fyra decimaler. bac 0.08 motsvarar perMille 0.8.

Använd notification.type för att läsa av provresultatet, även när alkoholvärdet är noll. Avgör inte resultatet med ett eget gränsvärde. Om additionalInfo saknas har inget alkoholvärde skickats med, vilket även gäller typen alco_test_failed.

Kvittens och leveransfel

Kontrollera meddelandet

Ta emot meddelandet via POST på överenskommen sökväg och kontrollera token först. Validera sedan JSON-innehållet:

  • device och notification ska vara objekt.
  • device.uniqueId och notification.type ska vara icke-tomma strängar.
  • notification.serverTime ska vara ett ändligt tal.

Ogiltig JSON eller felaktiga obligatoriska fält avvisas normalt med HTTP 400. Position, alkoholvärde, namn, käll-ID och källtid är valfria och ska inte krävas för att ta emot meddelandet.

Spara innan ni bekräftar mottagningen

Spara originalmeddelandet och mottagningstiden i en beständig kö eller databas innan ni svarar med HTTP 204 No Content. Fortsätt sedan med behandlingen i bakgrunden.

En verifierad dubblett som redan är sparad kan också bekräftas med HTTP 204. Om lagringen misslyckas ska ni svara med HTTP 500 eller 503, inte med en statuskod i 2xx-serien.

Avsluta HTTP-svaret

Alla HTTP-svar med status 200–299 räknas som lyckade när hela svaret är färdigt, även om er bakgrundsbearbetning senare misslyckas. 204 rekommenderas; 200 och 202 fungerar också. Svarskroppen tolkas inte och behöver inget visst JSON-format. Avsluta svaret direkt: ett öppet eller strömmande svar kan nå timeout även efter 2xx-rubriker.

Tidsgränser och svarsstorlek

Gränsen är 10 sekunder för hela HTTPS-anropet: anslutning, TLS, sändning och fullständigt svar. DNS har en separat gräns på 5 sekunder. Svarskroppen får vara högst 64 KiB (65 536 byte). Sikta på att spara och kvittera inom ungefär en sekund vid normal drift. Detta är ingen garanti för tiden från händelsen i fordonet till mottagning.

Misslyckade leveranser

Nätverksfel, timeout och felstatus räknas som misslyckad leverans. Vid timeout kan meddelandet redan ha sparats hos er, trots att Dignita inte fick någon kvittens.

Dubbletter och ordning

Anrop kan ske samtidigt och ordningen är inte garanterad. En källhändelse kan komma flera gånger. notification.id är inte globalt unikt och något idempotency-key-header skickas inte.

Om tillräckliga källfält finns kan ni kombinera kundkonfiguration, device.uniqueId, notification.id, notification.type och notification.eventTime för dubblettkontroll. Verifiera nyckeln mot verklig data. Ta inte med serverTime; det kan ändras mellan försök. Om ID och tid inte räcker, bevara händelserna utan att automatiskt slå ihop liknande meddelanden.

Så tolkas ert HTTP-svar

2xx
Lyckad leverans när hela svaret avslutats. 204 rekommenderas.
3xx
Misslyckad leverans. Omdirigering följs inte.
4xx
Misslyckad leverans, även 400, 401 och 403. Ingen automatisk retry.
429
Misslyckad leverans. Retry-After leder inte till omsändning.
5xx
Misslyckad leverans. Ingen automatisk retry.

AL-100-händelser

Tabellen visar de exakta värdena i notification.type. Endast händelser som aktiverats för er integration skickas. Namnen är skiftlägeskänsliga.

Listan innehåller 46 händelsetyper. Vilka som förekommer beror på enhetens funktioner. HS betyder handenhet (handset) och CB styrenhet (control box). Använd det exakta mottagna namnet, till exempel al_engine_blocked eller al_engine_unblocked.

Spara och kvittera giltiga meddelanden med nya eller okända händelsetyper. Markera dem för komplettering av er verksamhetsmappning i stället för att tappa dem.

46 av 46 händelsetyper

AL-100-händelser
Mottagen notification.typeBeskrivning
al_test_passedUtandningsprov godkänt.
al_test_failedUtandningsprov underkänt.
al_retest_passedÅtertest godkänt.
al_retest_failedÅtertest underkänt.
al_hs_connected_cb_after_calibrationHandenheten ansluten efter kalibrering.
al_memory_fullMinnet fullt.
al_handset_disconnectedHandenheten frånkopplad.
al_handset_reconnectedHandenheten återansluten.
al_invalid_breath_sampleOgiltigt utandningsprov.
al_out_of_working_temperature_hsHandenhetens temperatur utanför arbetsområdet.
al_out_of_working_temperature_cbStyrenhetens temperatur utanför arbetsområdet.
al_main_power_on_cb_turned_onStrömmen till styrenheten påslagen.
al_low_battery_detectedLågt batteri upptäckt.
al_ignition_turned_offTändningen avstängd.
al_ignition_turned_onTändningen påslagen.
al_main_power_on_cb_turned_offStrömmen till styrenheten avstängd.
al_start_of_engineMotorstart.
al_starter_relay_openedStartrelä öppnat.
al_starter_relay_closedStartrelä stängt.
al_vehicle_movement_detectedFordonsrörelse upptäckt.
al_hs_cb_connected_with_new_timestampHandenhet och styrenhet anslutna med ny tidsstämpel.
al_device_errorEnhetsfel.
al_hs_exchangedHandenheten utbytt.
al_cb_connected_with_computerStyrenheten ansluten till dator.
al_serialnumber_not_matched_between_cb_and_hsSerienumren för handenhet och styrenhet matchar inte.
al_retest_requestedÅtertest begärt.
al_retest_not_deliveredBegärt återtest ej levererat.
al_vehicle_movement_detected_without_breath_testFordonsrörelse utan utandningsprov.
al_early_service_is_occurredTidig service har inträffat.
al_remainingtime_for_service_due_is_less_than_24_hoursMindre än 24 timmar till service.
al_grace_period_started_after_expiry_of_service_dateUppskovsperiod efter servicedatum har börjat.
al_service_date_including_grace_period_expiredServicedatum inklusive uppskovsperiod har passerat.
al_hs_cb_connected_with_new_setting_valuesHandenhet och styrenhet anslutna med nya inställningar.
al_service_date_reset_by_new_timestampServicedatum återställt med ny tidsstämpel.
al_calibration_done_with_new_timestampKalibrering utförd med ny tidsstämpel.
al_serialnumber_of_hs_changed_with_new_pairHandenhetens serienummer ändrat vid ny parkoppling.
al_serialnumber_of_cb_changed_with_new_pairStyrenhetens serienummer ändrat vid ny parkoppling.
al_log_data_deletedLoggdata raderad.
al_forced_override_activatedForcerad override aktiverad.
al_forced_override_expiredForcerad override avslutad.
al_handset_disconnected_during_engine_run_movementHandenheten frånkopplad vid motordrift och rörelse.
al_handset_disconnected_during_engine_run_accHandenheten frånkopplad vid motordrift och ACC på.
al_engine_unblockedMotorblockering avaktiverad.
al_engine_blockedMotorblockering aktiverad.
al_temporary_override_activatedTillfällig override aktiverad.
al_temporary_override_endedTillfällig override avslutad.

Övriga larm och modeller

Vilka larm ni kan ta emot beror på enhetsmodellen och vad som aktiverats för er integration. De flesta av dessa larm kräver aktiverad tracking. Tracking är en tilläggstjänst mot extra kostnad som ger möjlighet till regelbunden GPS-spårning, utöver position vid larm. Alla enheter stöder inte alla larm.

Vid ett underkänt prov skickar AL-100 al_test_failed. Vissa andra modeller skickar alco_test_failed, utan additionalInfo med alkoholvärden.

För AL-100 kan ni ta emot al_ignition_turned_on när tändningen slås på och al_ignition_turned_off när den slås av. Händelserna skickas när de aktiverats för er integration.

Geofence- och hastighetslarm innehåller händelsetyp och eventuell position. JSON innehåller inte geofence-ID, uppmätt hastighet eller gränsvärde.

Övriga larm och modeller
Mottagen notification.typeBeskrivning
deviceOfflinedeviceSleepOnOffline eller viloläge.
deviceOnlineOnline eller väckt.
vibrationRörelse eller vibration.
lowBatteryLågt internt batteri.
powerOnpowerOffdeviceChargeOndeviceChargeOffExtern ström eller laddning på/av.
geofenceEntergeofenceExitInträde i eller utträde ur geofence.
deviceOverspeedÖverhastighet.
alco_test_failedUnderkänt prov på vissa andra modeller.
alco_physical_bypassFysisk bypass på modeller som stöder det.

Testa och driftsätt

Testa er mottagare

Spara JSON-exemplet som alarm-example.json. Sätt miljövariablerna ALARM_ENDPOINT till er testendpoint och ALARM_FORWARDING_TOKEN till rätt token. Lägg aldrig riktiga token i källkod eller dokumentation. Kommandot testar er mottagare; förväntat svar är 204 utan svarskropp.

Gemensamt anslutningsprov

Ett curl-test ersätter inte det gemensamma leveranstestet från Dignita, inklusive DNS och TLS. Testa med exakt URL, giltigt certifikat, rätt token, en verklig enhet kopplad till företaget och minst ett av de avsedda larmen. Bekräfta både att ni har sparat händelsen och att avsändaren fått ett fullständigt 2xx-svar inom 10 sekunder.

Välj bara de händelser ni behöver och kontrollera modellens stöd samt eventuella trackingkrav. En leverans som redan påbörjats kan använda tidigare inställningar.

Kontrollera före driftsättning

  • Giltig token och AL-100-prov: spara rätt typ, identifierare och alkoholvärden, svara 2xx.

  • Utan position: spara null, inte 0, 0.

  • Saknat ID, namn, källtid eller positionsfält: acceptera om kärnfälten är giltiga.

  • Felaktig eller saknad token: avvisa utan verksamhetsåtgärd.

  • Ogiltig JSON eller kärnfält: avvisa, normalt med 400.

  • Extra JSON-fält eller okänd typ: spara, kvittera och markera behov av verksamhetsmappning.

  • Samma källhändelse två gånger: undvik dubbla verksamhetsåtgärder när den säkert kan identifieras.

  • Samtidiga och fördröjda händelser: bevara alla utan antaganden om ordning.

  • Fel i beständig lagring: svara inte med lyckad 2xx och kontrollera att felet övervakas.

Drift och felsökning

Logga mottagningstid, device.uniqueId, notification.type, källans händelse-ID när det finns och resultatet av bearbetningen. Maskera token. Följ upp lagringsfel, HTTP-fel, svarstider och fel i bakgrundsbearbetningen.

Det finns ingen heartbeat. Frånvaro av händelser bevisar inte att anslutningen fungerar. Fel och timeout leder inte till automatisk omsändning.

Om ett larm saknas

Kontakta Dignita om ett larm saknas. Dignita kontrollerar att enheten ingår i er integration, vilka händelser som aktiverats och leveransens status. Hos mottagaren kontrollerar ni tillgänglighet, token, certifikat och beständig lagring.