Hopp til innholdet
Dignita

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

device
objectPåkrevd
Informasjon om enheten.
device.id
number | stringValgfritt / kan mangle
Enhets-ID. Behandle som identifikator.
device.uniqueId
stringPåkrevd
Ikke-tom streng, normalt IMEI. Bevar innledende nuller.
device.name
string | nullValgfritt / kan mangle
Enhetens gjeldende navn; ikke en unik identifikator. Kan være null.
notification
objectPåkrevd
Informasjon om hendelsen.
notification.id
number | stringValgfritt / kan mangle
Kildens hendelses-ID. Ikke globalt unik; kan mangle eller være null.
notification.type
stringPåkrevd
Ikke-tom, nøyaktig hendelsestype som skiller mellom store og små bokstaver.
notification.eventTime
Format fra kildenValgfritt / kan mangle
Tidspunktet for hendelsen. Kan mangle eller være null; formatet kan variere.
notification.serverTime
numberPåkrevd
Endelig tall. Tidspunktet for videresending som Unix-tid i millisekunder.
notification.position
objectValgfritt / kan mangle
Posisjonsinformasjon for hendelsen. Posisjonsfelter kan mangle eller være null.
notification.position.id
number | stringValgfritt / kan mangle
Kildens posisjons-ID. Kan mangle eller være null.
notification.position.time
Format fra kildenValgfritt / kan mangle
Tidspunktet for posisjonsmålingen. Kan mangle eller være null; formatet kan variere.
notification.position.latitude
numberValgfritt / kan mangle
Breddegrad. Kan mangle eller være null.
notification.position.longitude
numberValgfritt / kan mangle
Lengdegrad. Kan mangle eller være null.
notification.additionalInfo
objectValgfritt / kan mangle
Bare de fire AL-100-prøvetypene. Kan utelates.
notification.additionalInfo.bac
numberValgfritt / kan mangle
Numerisk alkoholverdi. Bruk perMille for promilleverdien.
notification.additionalInfo.perMille
numberValgfritt / 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

AL-100-hendelser
Mottatt notification.typeBeskrivelse
al_test_passedUtåndingsprøve godkjent.
al_test_failedUtåndingsprøve underkjent.
al_retest_passedNy prøve godkjent.
al_retest_failedNy prøve underkjent.
al_hs_connected_cb_after_calibrationHåndsett tilkoblet etter kalibrering.
al_memory_fullMinnet fullt.
al_handset_disconnectedHåndsett frakoblet.
al_handset_reconnectedHåndsett tilkoblet igjen.
al_invalid_breath_sampleUgyldig utåndingsprøve.
al_out_of_working_temperature_hsHåndsettets temperatur utenfor driftsområdet.
al_out_of_working_temperature_cbStyreenhetens temperatur utenfor driftsområdet.
al_main_power_on_cb_turned_onStrøm til styreenheten slått på.
al_low_battery_detectedLavt batterinivå oppdaget.
al_ignition_turned_offTenningen slått av.
al_ignition_turned_onTenningen slått på.
al_main_power_on_cb_turned_offStrøm til styreenheten slått av.
al_start_of_engineMotorstart.
al_starter_relay_openedStartrelé åpnet.
al_starter_relay_closedStartrelé lukket.
al_vehicle_movement_detectedKjøretøybevegelse oppdaget.
al_hs_cb_connected_with_new_timestampHåndsett og styreenhet tilkoblet med nytt tidsstempel.
al_device_errorEnhetsfeil.
al_hs_exchangedHåndsett byttet.
al_cb_connected_with_computerStyreenhet tilkoblet datamaskin.
al_serialnumber_not_matched_between_cb_and_hsSerienumrene til håndsett og styreenhet samsvarer ikke.
al_retest_requestedNy prøve forespurt.
al_retest_not_deliveredForespurt ny prøve ikke levert.
al_vehicle_movement_detected_without_breath_testKjøretøybevegelse uten utåndingsprøve.
al_early_service_is_occurredTidlig service har inntruffet.
al_remainingtime_for_service_due_is_less_than_24_hoursUnder 24 timer til service.
al_grace_period_started_after_expiry_of_service_dateUtsettelsesperiode etter servicedato startet.
al_service_date_including_grace_period_expiredServicedato inkludert utsettelsesperiode utløpt.
al_hs_cb_connected_with_new_setting_valuesHåndsett og styreenhet tilkoblet med nye innstillinger.
al_service_date_reset_by_new_timestampServicedato tilbakestilt med nytt tidsstempel.
al_calibration_done_with_new_timestampKalibrering utført med nytt tidsstempel.
al_serialnumber_of_hs_changed_with_new_pairHåndsettets serienummer endret ved ny paring.
al_serialnumber_of_cb_changed_with_new_pairStyreenhetens serienummer endret ved ny paring.
al_log_data_deletedLoggdata slettet.
al_forced_override_activatedTvungen override aktivert.
al_forced_override_expiredTvungen override avsluttet.
al_handset_disconnected_during_engine_run_movementHåndsett frakoblet ved motordrift og bevegelse.
al_handset_disconnected_during_engine_run_accHåndsett frakoblet ved motordrift med ACC på.
al_engine_unblockedMotorblokkering deaktivert.
al_engine_blockedMotorblokkering aktivert.
al_temporary_override_activatedMidlertidig override aktivert.
al_temporary_override_endedMidlertidig 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.

Andre alarmer og modeller
Mottatt notification.typeBeskrivelse
deviceOfflinedeviceSleepOnOffline eller hvilemodus.
deviceOnlineOnline eller vekket.
vibrationBevegelse eller vibrasjon.
lowBatteryLavt internt batterinivå.
powerOnpowerOffdeviceChargeOndeviceChargeOffEkstern strøm eller lading på/av.
geofenceEntergeofenceExitInngang i eller utgang fra geofence.
deviceOverspeedFor høy hastighet.
alco_test_failedUnderkjent prøve på enkelte andre modeller.
alco_physical_bypassFysisk 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.