Integrasjonsguide
Versjon 1.0 · 1. oktober 2026
Motta alarmer i egne systemer
Dignita Alkolarm sender de alarmene og hendelsene dere har valgt som webhooks til HTTPS-endepunktet deres. Hvert POST-kall inneholder ett JSON-objekt i UTF-8.
Avklar med kontaktpersonen deres hos Dignita hvilken webhook-adresse og hvilket token dere skal bruke, og hvilke hendelser dere vil motta.
Tilkobling og endepunkt
Slik kobler dere til
Gi Dignita en fullstendig webhook-adresse, for eksempel https://receiver.example.com/dignita/alarms. Avtal hvilke hendelser dere vil motta. Dignita oppgir token separat.
Krav til endepunktadressen
Endepunktadressen må bruke HTTPS med gyldig sertifikat, riktig vertsnavn og en betrodd sertifikatkjede. Selvsignerte sertifikater godtas ikke som standard. URL-en kan være høyst 500 UTF-8-byte og må ikke inneholde brukernavn, passord eller fragment (#).
Endepunktet må være offentlig tilgjengelig. DNS kontrolleres ved hver leveranse og må gi tillatte offentlige IP-adresser. Private, lokale, reserverte adresser og loopback avvises. Endepunktet skal svare direkte; omdirigeringer følges ikke.
Autentisering
Kontroller token
Hvert kall inneholder Authorization: <TOKEN>. Kontroller ved hvert kall at token samsvarer med verdien dere har fått fra Dignita. Avvis kall med manglende eller feil token, for eksempel med HTTP 401, uten å behandle alarmen eller hendelsen. Oppbevar token slik at bare autoriserte brukere har tilgang, og sørg for at verdien ikke vises i logger.
Dere får token separat fra Dignita. Kontroller ved hvert kall at hele tokenverdien samsvarer med den dere har fått.
Endringer og bytte av token
Ta kontakt med kontaktpersonen deres hos Dignita for å planlegge et bytte av token. Samordne byttet med IT-avdelingen eller systemleverandøren deres for å unngå avbrudd i mottaket av alarmer og hendelser.
JSON og felter
Meldingen inneholder objektene device og notification. Posisjonsinformasjon finnes i notification.position. Eksemplet viser en underkjent AL-100-prøve med posisjon og alkoholverdi.
Hendelses-ID, tider, navn og posisjonsverdier kan mangle eller være null. Godta også nye JSON-felter for fremtidige utvidelser. Følg kravene i tabellen når dere validerer meldingen. Felter som er merket som valgfrie, skal ikke kreves av systemet deres.
Bruk verdien i notification.type for å avgjøre hvordan hendelsen skal håndteres. Hver kundes konfigurasjon skal være knyttet til avtalt endepunkt og token.
Felter i meldingen
deviceobjectPåkrevd- Informasjon om enheten.
device.idnumber | stringValgfritt / kan mangle- Enhets-ID. Behandle som identifikator.
device.uniqueIdstringPåkrevd- Ikke-tom streng, normalt IMEI. Bevar innledende nuller.
device.namestring | nullValgfritt / kan mangle- Enhetens gjeldende navn; ikke en unik identifikator. Kan være null.
notificationobjectPåkrevd- Informasjon om hendelsen.
notification.idnumber | stringValgfritt / kan mangle- Kildens hendelses-ID. Ikke globalt unik; kan mangle eller være null.
notification.typestringPåkrevd- Ikke-tom, nøyaktig hendelsestype som skiller mellom store og små bokstaver.
notification.eventTimeFormat fra kildenValgfritt / kan mangle- Tidspunktet for hendelsen. Kan mangle eller være null; formatet kan variere.
notification.serverTimenumberPåkrevd- Endelig tall. Tidspunktet for videresending som Unix-tid i millisekunder.
notification.positionobjectValgfritt / kan mangle- Posisjonsinformasjon for hendelsen. Posisjonsfelter kan mangle eller være null.
notification.position.idnumber | stringValgfritt / kan mangle- Kildens posisjons-ID. Kan mangle eller være null.
notification.position.timeFormat fra kildenValgfritt / kan mangle- Tidspunktet for posisjonsmålingen. Kan mangle eller være null; formatet kan variere.
notification.position.latitudenumberValgfritt / kan mangle- Breddegrad. Kan mangle eller være null.
notification.position.longitudenumberValgfritt / kan mangle- Lengdegrad. Kan mangle eller være null.
notification.additionalInfoobjectValgfritt / kan mangle- Bare de fire AL-100-prøvetypene. Kan utelates.
notification.additionalInfo.bacnumberValgfritt / kan mangle- Numerisk alkoholverdi. Bruk perMille for promilleverdien.
notification.additionalInfo.perMillenumberValgfritt / kan mangle- Promilleverdi: bac × 10, høyst fire desimaler.
Tider, posisjon og alkoholverdier
Tidsformater
notification.serverTime angir tidspunktet for videresending. Tiden angis som Unix-tid i millisekunder. notification.eventTime viser når hendelsen inntraff, og notification.position.time viser når posisjonen ble målt.
Hendelses- og posisjonstider kan mangle eller angis i ulike formater. Eksemplene bruker ISO 8601 med UTC (Z), men meldingene dere mottar, kan ha andre tidsformater. Kontroller formatene under tilkoblingstesten og bevar originalverdiene.
Systemet deres skal kunne håndtere manglende tidsopplysninger og verdier som ikke kan tolkes. Tolk bare en tid uten tidssone som lokal tid hvis dere har avtalt dette med Dignita.
Når posisjonen mangler
Posisjonen kan komme fra en tidligere posisjonsmåling. Kontroller notification.position.time for å se når posisjonen ble målt. Når posisjonen mangler, er alle fire posisjonsfeltene null. Enkelte posisjonsfelter kan også utelates. Manglende posisjon er ikke koordinaten 0, 0.
Promille og prøveresultater
additionalInfo med numeriske bac og perMille forekommer bare for al_test_passed, al_test_failed, al_retest_passed og al_retest_failed. Bruk perMille for promille: perMille = bac × 10, avrundet til høyst fire desimaler. bac 0.08 tilsvarer perMille 0.8.
Bruk notification.type for å lese av prøveresultatet, også når alkoholverdien er null. Ikke avgjør resultatet med en egen grenseverdi. Hvis additionalInfo mangler, er ingen alkoholverdi sendt med, noe som også gjelder typen alco_test_failed.
Kvittering og leveringsfeil
Kontroller meldingen
Ta imot meldingen via POST på avtalt sti og kontroller token først. Valider deretter JSON-innholdet:
- device og notification må være objekter.
- device.uniqueId og notification.type må være ikke-tomme strenger.
- notification.serverTime må være et endelig tall.
Ugyldig JSON eller feil i obligatoriske felt avvises normalt med HTTP 400. Posisjon, alkoholverdi, navn, kilde-ID og kildetid er valgfrie og skal ikke kreves for å ta imot meldingen.
Lagre før dere bekrefter mottaket
Lagre originalmeldingen og mottakstidspunktet i en varig kø eller database før dere svarer med HTTP 204 No Content. Fortsett deretter behandlingen i bakgrunnen.
Et verifisert duplikat som allerede er lagret, kan også bekreftes med HTTP 204. Hvis lagringen mislykkes, skal dere svare med HTTP 500 eller 503, ikke med en statuskode i 2xx-serien.
Avslutt HTTP-svaret
Alle HTTP-svar med status 200–299 regnes som vellykkede når hele svaret er ferdig, selv om bakgrunnsbehandlingen senere feiler. 204 anbefales; 200 og 202 fungerer også. Svarinnholdet tolkes ikke og trenger ikke et bestemt JSON-format. Avslutt svaret straks: åpne eller strømmende svar kan få timeout selv etter 2xx-headere.
Tidsgrenser og svarstørrelse
Hele HTTPS-kallet har en grense på 10 sekunder, inkludert tilkobling, TLS, sending og fullstendig svar. DNS har en egen grense på 5 sekunder. Svarinnholdet kan være høyst 64 KiB (65 536 byte). Sikt på lagring og kvittering innen omtrent ett sekund ved normal drift. Dette er ingen garanti for tiden fra hendelsen i kjøretøyet til mottak.
Mislykkede leveranser
Nettverksfeil, timeout og feilstatus regnes som mislykket leveranse. Ved timeout kan mottakeren allerede ha lagret meldingen selv om Dignita ikke fikk noen kvittering.
Duplikater og rekkefølge
Kall kan komme samtidig, og rekkefølgen er ikke garantert. En kildehendelse kan forekomme flere ganger. notification.id er ikke globalt unik, og ingen idempotency-key-header sendes.
Hvis tilstrekkelige kildefelter finnes, kan dere kombinere kundekonfigurasjon, device.uniqueId, notification.id, notification.type og notification.eventTime for duplikatkontroll. Verifiser nøkkelen mot faktiske data. Ikke ta med serverTime; det kan endres mellom forsøk. Hvis ID og tid ikke er tilstrekkelige, bevar hendelsene uten automatisk å slå sammen lignende meldinger.
Slik tolkes HTTP-svaret deres
- 2xx
- Vellykket leveranse når hele svaret er avsluttet. 204 anbefales.
- 3xx
- Mislykket leveranse. Omdirigering følges ikke.
- 4xx
- Mislykket leveranse, også 400, 401 og 403. Ingen automatisk retry.
- 429
- Mislykket leveranse. Retry-After utløser ikke gjensending.
- 5xx
- Mislykket leveranse. Ingen automatisk retry.
AL-100-hendelser
Tabellen viser de nøyaktige verdiene i notification.type. Bare hendelser som er aktivert for integrasjonen deres, sendes. Navnene skiller mellom store og små bokstaver.
Listen inneholder 46 hendelsestyper. Hvilke som forekommer, avhenger av enhetens funksjoner. HS betyr håndsett (handset), og CB styreenhet (control box). Bruk nøyaktig mottatt navn, som al_engine_blocked eller al_engine_unblocked.
Lagre og kvitter gyldige meldinger med nye eller ukjente hendelsestyper. Merk dem for videre mapping i stedet for å miste dem.
46 av 46 hendelsestyper
| Mottatt notification.type | Beskrivelse |
|---|---|
al_test_passed | Utåndingsprøve godkjent. |
al_test_failed | Utåndingsprøve underkjent. |
al_retest_passed | Ny prøve godkjent. |
al_retest_failed | Ny prøve underkjent. |
al_hs_connected_cb_after_calibration | Håndsett tilkoblet etter kalibrering. |
al_memory_full | Minnet fullt. |
al_handset_disconnected | Håndsett frakoblet. |
al_handset_reconnected | Håndsett tilkoblet igjen. |
al_invalid_breath_sample | Ugyldig utåndingsprøve. |
al_out_of_working_temperature_hs | Håndsettets temperatur utenfor driftsområdet. |
al_out_of_working_temperature_cb | Styreenhetens temperatur utenfor driftsområdet. |
al_main_power_on_cb_turned_on | Strøm til styreenheten slått på. |
al_low_battery_detected | Lavt batterinivå oppdaget. |
al_ignition_turned_off | Tenningen slått av. |
al_ignition_turned_on | Tenningen slått på. |
al_main_power_on_cb_turned_off | Strøm til styreenheten slått av. |
al_start_of_engine | Motorstart. |
al_starter_relay_opened | Startrelé åpnet. |
al_starter_relay_closed | Startrelé lukket. |
al_vehicle_movement_detected | Kjøretøybevegelse oppdaget. |
al_hs_cb_connected_with_new_timestamp | Håndsett og styreenhet tilkoblet med nytt tidsstempel. |
al_device_error | Enhetsfeil. |
al_hs_exchanged | Håndsett byttet. |
al_cb_connected_with_computer | Styreenhet tilkoblet datamaskin. |
al_serialnumber_not_matched_between_cb_and_hs | Serienumrene til håndsett og styreenhet samsvarer ikke. |
al_retest_requested | Ny prøve forespurt. |
al_retest_not_delivered | Forespurt ny prøve ikke levert. |
al_vehicle_movement_detected_without_breath_test | Kjøretøybevegelse uten utåndingsprøve. |
al_early_service_is_occurred | Tidlig service har inntruffet. |
al_remainingtime_for_service_due_is_less_than_24_hours | Under 24 timer til service. |
al_grace_period_started_after_expiry_of_service_date | Utsettelsesperiode etter servicedato startet. |
al_service_date_including_grace_period_expired | Servicedato inkludert utsettelsesperiode utløpt. |
al_hs_cb_connected_with_new_setting_values | Håndsett og styreenhet tilkoblet med nye innstillinger. |
al_service_date_reset_by_new_timestamp | Servicedato tilbakestilt med nytt tidsstempel. |
al_calibration_done_with_new_timestamp | Kalibrering utført med nytt tidsstempel. |
al_serialnumber_of_hs_changed_with_new_pair | Håndsettets serienummer endret ved ny paring. |
al_serialnumber_of_cb_changed_with_new_pair | Styreenhetens serienummer endret ved ny paring. |
al_log_data_deleted | Loggdata slettet. |
al_forced_override_activated | Tvungen override aktivert. |
al_forced_override_expired | Tvungen override avsluttet. |
al_handset_disconnected_during_engine_run_movement | Håndsett frakoblet ved motordrift og bevegelse. |
al_handset_disconnected_during_engine_run_acc | Håndsett frakoblet ved motordrift med ACC på. |
al_engine_unblocked | Motorblokkering deaktivert. |
al_engine_blocked | Motorblokkering aktivert. |
al_temporary_override_activated | Midlertidig override aktivert. |
al_temporary_override_ended | Midlertidig override avsluttet. |
Andre alarmer og modeller
Hvilke alarmer dere kan motta, avhenger av enhetsmodellen og hva som er aktivert for integrasjonen deres. De fleste av disse alarmene krever aktivert tracking. Tracking er en tilleggstjeneste som koster ekstra og gir mulighet for regelmessig GPS-sporing, i tillegg til posisjon ved alarmer. Alle enheter støtter ikke alle alarmer.
Ved en underkjent prøve sender AL-100 al_test_failed. Enkelte andre modeller sender alco_test_failed, uten additionalInfo med alkoholverdier.
For AL-100 kan dere motta al_ignition_turned_on når tenningen slås på og al_ignition_turned_off når den slås av. Hendelsene sendes når de er aktivert for integrasjonen deres.
Geofence- og hastighetsalarmer inneholder hendelsestype og eventuell posisjon. JSON inneholder ikke geofence-ID, målt hastighet eller grenseverdi.
| Mottatt notification.type | Beskrivelse |
|---|---|
deviceOfflinedeviceSleepOn | Offline eller hvilemodus. |
deviceOnline | Online eller vekket. |
vibration | Bevegelse eller vibrasjon. |
lowBattery | Lavt internt batterinivå. |
powerOnpowerOffdeviceChargeOndeviceChargeOff | Ekstern strøm eller lading på/av. |
geofenceEntergeofenceExit | Inngang i eller utgang fra geofence. |
deviceOverspeed | For høy hastighet. |
alco_test_failed | Underkjent prøve på enkelte andre modeller. |
alco_physical_bypass | Fysisk bypass på modeller som støtter det. |
Test og sett i produksjon
Test mottakeren
Lagre JSON-eksemplet som alarm-example.json. Sett ALARM_ENDPOINT til testendepunktet og ALARM_FORWARDING_TOKEN til riktig token. Legg aldri virkelige token i kildekode eller dokumentasjon. Kommandoen tester mottakeren; forventet svar er 204 uten svarinnhold.
Felles tilkoblingstest
En curl-test erstatter ikke den felles leveringstesten fra Dignita, inkludert DNS og TLS. Test med nøyaktig URL, gyldig sertifikat, riktig token, en faktisk enhet knyttet til virksomheten og minst én av de tiltenkte alarmene. Bekreft både at hendelsen er lagret og at avsenderen har fått et fullstendig 2xx-svar innen 10 sekunder.
Velg bare hendelsene dere trenger, og kontroller modellstøtte og eventuelle trackingkrav. En leveranse som allerede har startet, kan bruke tidligere innstillinger.
Kontroller før produksjonssetting
Gyldig token og AL-100-prøve: lagre riktig type, identifikatorer og alkoholverdier, svar 2xx.
Uten posisjon: lagre null, ikke 0, 0.
Manglende ID, navn, kildetid eller posisjonsfelter: godta når kjernefeltene er gyldige.
Feil eller manglende token: avvis uten virksomhetshandlinger.
Ugyldig JSON eller kjernefelter: avvis, normalt med 400.
Ekstra JSON-felter eller ukjent type: lagre, kvitter og merk behov for mapping.
Samme kildehendelse to ganger: unngå doble virksomhetshandlinger når den kan identifiseres sikkert.
Samtidige og forsinkede hendelser: bevar alle uten å anta rekkefølge.
Feil i varig lagring: ikke svar med vellykket 2xx, og kontroller feilovervåkingen.
Drift og feilsøking
Logg mottakstid, device.uniqueId, notification.type, kildens hendelses-ID når den finnes og behandlingsresultatet. Masker token. Følg opp lagringsfeil, HTTP-feil, svartider og feil i bakgrunnsbehandlingen.
Det finnes ingen heartbeat. Fravær av hendelser beviser ikke at tilkoblingen fungerer. Feil og timeout utløser ikke automatisk gjensending.
Hvis en alarm mangler
Kontakt Dignita hvis en alarm mangler. Dignita kontrollerer at enheten inngår i integrasjonen deres, hvilke hendelser som er aktivert og leveransens status. Hos mottakeren kontrollerer dere tilgjengelighet, token, sertifikat og varig lagring.
