Integrasjonsguide

Versjon 1.0 · 1. oktober 2026

Motta alarmer i egne systemer

Dignita sender valgte alarmer og hendelser som webhooks til HTTPS-endepunktet deres. Hvert POST-kall inneholder ett JSON-objekt i UTF-8.

Avtal mottaker-URL, token og hvilke hendelser dere vil motta med Dignita.

Tilkobling og endepunkt

Slik kobler dere til

Gi Dignita en fullstendig mottaker-URL, for eksempel https://receiver.example.com/dignita/alarms. Avtal hvilke hendelser dere vil motta. Dignita oppgir token separat. Gjennomfør en felles tilkoblingstest med Dignita før integrasjonen aktiveres.

Krav til adressen

Adressen 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: Bearer <TOKEN>. Kontroller token på hver forespørsel. Avvis manglende eller feil token, for eksempel med 401, uten å starte en virksomhetshandling. Oppbevar token i hemmelig konfigurasjon og masker den i logger.

Dignita oppgir token separat. Kontroller hele den avtalte verdien ved hvert kall.

Endringer og bytte av token

Kontakt Dignita for å bytte token. Byttet må samordnes med mottakeren deres.

Kallene har ingen HMAC-signatur eller separat signaturheader.

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. Tabellen angir minstekravene for validering; valgfrie felter må ikke bli krav hos mottakeren.

Tolk hendelsen ut fra notification.type. Knytt hver kundekonfigurasjon 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.

AL-100 · underkjent prøve

{
  "device": {
    "id": 42,
    "uniqueId": "000123456789012",
    "name": "Exempelenhet"
  },
  "notification": {
    "id": 123,
    "type": "al_test_failed",
    "eventTime": "2026-10-01T08:00:00Z",
    "serverTime": 1790841601000,
    "position": {
      "id": 321,
      "time": "2026-10-01T07:59:59Z",
      "latitude": 59.3293,
      "longitude": 18.0686
    },
    "additionalInfo": {
      "bac": 0.08,
      "perMille": 0.8
    }
  }
}

Eksempelverdier. Dignita oppgir riktig URL og token separat.

Tider, posisjon og alkoholverdier

Tidsformater

notification.serverTime angir tidspunktet for videresending som Unix-tid i millisekunder. notification.eventTime angir tidspunktet for hendelsen, og notification.position.time tidspunktet for posisjonsmålingen. Hendelses- og posisjonstider kan mangle eller ha varierende formater. ISO 8601 med UTC/Z i eksemplene er ingen formatgaranti. Kontroller faktiske formater i tilkoblingstesten og bevar originalverdiene. Håndter manglende eller uleselige tider, og ikke tolk tider uten tidssone som lokal tid uten avtale.

Når posisjonen mangler

Posisjonen kan være eldre enn hendelsen; kontroller notification.position.time. 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.

Avgjør prøveresultatet ut fra notification.type, ikke en egenberegnet grenseverdi. En alkoholverdi på null gir ingen separat kvalitetsgaranti. Manglende additionalInfo betyr at ingen alkoholverdi fulgte med. Dette gjelder også typen alco_test_failed.

Alarm uten posisjon

{
  "device": {
    "id": 42,
    "uniqueId": "000123456789012",
    "name": "Exempelenhet"
  },
  "notification": {
    "id": 456,
    "type": "lowBattery",
    "eventTime": "2026-10-01T08:05:00Z",
    "serverTime": 1790841901000,
    "position": {
      "id": null,
      "time": null,
      "latitude": null,
      "longitude": null
    }
  }
}

Eksempelverdier. Dignita oppgir riktig URL og token separat.

Kvittering og leveringsfeil

Lagre før kvittering

Lagre originalmeldingen og mottakstidspunktet i en varig kø eller database før dere svarer med 204 No Content. Kjør virksomhetslogikken i bakgrunnen etter svaret. En bekreftet duplikat som allerede er lagret, kan også kvitteres med 204. Hvis lagringen feiler, svar med 500 eller 503, ikke 2xx.

Ta imot POST på avtalt sti og kontroller token først. Valider deretter JSON: device og notification må være objekter, device.uniqueId og notification.type må være ikke-tomme strenger, og notification.serverTime et endelig tall. Ugyldig JSON eller kjernefelter avvises normalt med 400. Ikke krev posisjon, alkoholverdi, navn, kilde-ID eller kildetid.

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.

Søk i AL-100-hendelser

46 av 46 hendelsestyper

AL-100-hendelser
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 krever aktivert tracking. 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.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.

Test mottakeren deres

curl --request POST "$ALARM_ENDPOINT" \
  --header "Authorization: Bearer $ALARM_FORWARDING_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @alarm-example.json \
  --connect-timeout 3 \
  --max-time 10 \
  --include

Eksempelverdier. Dignita oppgir riktig URL og token separat.

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.