Siirry sisältöön
Dignita

Integraatio-opas

Versio 1.0 · 1. lokakuuta 2026

Vastaanota hälytykset omiin järjestelmiinne

Dignita Alkolarm lähettää valitsemanne hälytykset ja tapahtumat webhookeina HTTPS-päätepisteeseenne. Kukin POST-pyyntö sisältää yhden UTF-8-koodatun JSON-objektin.

Sopikaa Dignitan yhteyshenkilönne kanssa webhook-osoitteesta, tunnuksesta ja vastaanotettavista tapahtumista.

Yhteys ja päätepiste

Yhteyden muodostaminen

Toimittakaa Dignitalle täydellinen webhook-osoite, esimerkiksi https://receiver.example.com/dignita/alarms. Sopikaa vastaanotettavista tapahtumista. Dignita toimittaa tunnuksen erikseen.

Päätepisteen osoitevaatimukset

Päätepisteen osoitteen on käytettävä HTTPS:ää sekä voimassa olevaa varmennetta, oikeaa palvelinnimeä ja luotettua varmenneketjua. Itse allekirjoitettuja varmenteita ei hyväksytä oletuksena. URL saa sisältää enintään 500 UTF-8-tavua eikä käyttäjänimeä, salasanaa tai fragmenttia (#).

Päätepisteen on oltava julkisesti saavutettava. DNS tarkistetaan jokaisen toimituksen yhteydessä, ja sen on palautettava sallittuja julkisia IP-osoitteita. Yksityiset, paikalliset, varatut ja loopback-osoitteet hylätään. Päätepisteen on vastattava suoraan; uudelleenohjauksia ei seurata.

Todennus

Tunnuksen tarkistus

Jokainen pyyntö sisältää otsakkeen Authorization: <TOKEN>. Tarkista jokaisesta pyynnöstä, että tunnus vastaa Dignitalta saatua arvoa. Hylkää pyynnöt, joiden tunnus puuttuu tai on virheellinen, esimerkiksi HTTP 401 -vastauksella, käsittelemättä hälytystä tai tapahtumaa. Säilytä tunnus niin, että vain valtuutetuilla käyttäjillä on pääsy siihen, ja varmista, ettei sen arvo näy lokeissa.

Saatte tunnuksen erikseen Dignitalta. Tarkistakaa jokaisesta pyynnöstä, että koko tunnuksen arvo vastaa saamaanne arvoa.

Määrityksen ja tunnuksen muutokset

Ottakaa yhteyttä Dignitan yhteyshenkilöönne tunnuksen vaihdon suunnittelua varten. Koordinoikaa vaihto IT-osastonne tai järjestelmätoimittajanne kanssa, jotta hälytysten ja tapahtumien vastaanotto ei keskeydy.

JSON ja kentät

Viesti sisältää device- ja notification-objektit. Sijaintitiedot ovat notification.position-objektissa. Esimerkki näyttää hylätyn AL-100-testin, jossa on sijainti ja alkoholiarvo.

Tapahtumatunnukset, ajat, nimet ja sijaintiarvot voivat puuttua tai olla null. Hyväksy myös uudet JSON-kentät tulevia laajennuksia varten. Validoikaa viesti taulukon vaatimusten mukaisesti. Järjestelmänne ei saa vaatia valinnaisiksi merkittyjä kenttiä.

Käytä notification.type-kentän arvoa määrittääksesi, miten tapahtuma käsitellään. Kunkin asiakkaan määrityksen tulee olla liitetty sovittuun päätepisteeseen ja tunnukseen.

Viestin kentät

device
objectPakollinen
Laitteen tiedot.
device.id
number | stringValinnainen / voi puuttua
Laitetunnus. Käsittele tunnisteena.
device.uniqueId
stringPakollinen
Ei-tyhjä merkkijono, yleensä IMEI. Säilytä alkunollat.
device.name
string | nullValinnainen / voi puuttua
Laitteen nykyinen nimi; ei yksilöllinen tunniste. Voi olla null.
notification
objectPakollinen
Tapahtuman tiedot.
notification.id
number | stringValinnainen / voi puuttua
Lähteen tapahtumatunnus. Ei maailmanlaajuisesti yksilöllinen; voi puuttua tai olla null.
notification.type
stringPakollinen
Ei-tyhjä täsmällinen tapahtumatyyppi, jonka kirjainkoolla on merkitystä.
notification.eventTime
Lähteen muotoValinnainen / voi puuttua
Tapahtuma-aika. Voi puuttua tai olla null; muoto voi vaihdella.
notification.serverTime
numberPakollinen
Äärellinen luku. Välitysaika Unix-aikana millisekunteina.
notification.position
objectValinnainen / voi puuttua
Tapahtuman sijaintitiedot. Sijaintikentät voivat puuttua tai olla null.
notification.position.id
number | stringValinnainen / voi puuttua
Lähteen sijaintitunnus. Voi puuttua tai olla null.
notification.position.time
Lähteen muotoValinnainen / voi puuttua
Sijainnin mittausaika. Voi puuttua tai olla null; muoto voi vaihdella.
notification.position.latitude
numberValinnainen / voi puuttua
Leveysaste. Voi puuttua tai olla null.
notification.position.longitude
numberValinnainen / voi puuttua
Pituusaste. Voi puuttua tai olla null.
notification.additionalInfo
objectValinnainen / voi puuttua
Vain neljä AL-100-testityyppiä. Voidaan jättää pois.
notification.additionalInfo.bac
numberValinnainen / voi puuttua
Numeerinen alkoholiarvo. Käytä promillearvona perMille-kenttää.
notification.additionalInfo.perMille
numberValinnainen / voi puuttua
Promillearvo: bac × 10, enintään neljä desimaalia.

Ajat, sijainti ja alkoholiarvot

Aikamuodot

notification.serverTime ilmaisee välityksen ajankohdan. Aika ilmoitetaan Unix-aikana millisekunteina. notification.eventTime kertoo tapahtuman ajankohdan ja notification.position.time sijainnin mittausajankohdan.

Tapahtuma- ja sijaintiajat voivat puuttua tai olla eri muodoissa. Esimerkeissä käytetään ISO 8601 -muotoa ja UTC-aikaa (Z), mutta vastaanottamissanne viesteissä voidaan käyttää muita aikamuotoja. Tarkista muodot yhteystestin aikana ja säilytä alkuperäiset arvot.

Järjestelmänne tulee pystyä käsittelemään puuttuvia aikatietoja ja arvoja, joita ei voida tulkita. Tulkitse aikavyöhykkeetön aika paikallisajaksi vain, jos olette sopineet tästä Dignitan kanssa.

Puuttuvat sijainnit

Sijainti voi perustua aiempaan sijaintimittaukseen. Tarkista notification.position.time-kentästä, milloin sijainti mitattiin. Kun sijainti puuttuu, kaikki neljä sijaintikenttää ovat null. Myös yksittäisiä sijaintikenttiä voidaan jättää pois. Puuttuva sijainti ei tarkoita koordinaattia 0, 0.

Promillearvot ja testitulokset

Numeriset bac- ja perMille-arvot sisältävä additionalInfo toimitetaan vain tyypeille al_test_passed, al_test_failed, al_retest_passed ja al_retest_failed. Käytä promillearvona perMille-kenttää: perMille = bac × 10, pyöristettynä enintään neljään desimaaliin. bac 0.08 vastaa arvoa perMille 0.8.

Lue testitulos notification.type-kentästä myös silloin, kun alkoholiarvo on nolla. Älä määritä tulosta oman raja-arvon perusteella. Jos additionalInfo puuttuu, alkoholiarvoa ei ole lähetetty mukana. Tämä koskee myös alco_test_failed-tyyppiä.

Kuittaus ja toimitusvirheet

Tarkista viesti

Vastaanota viesti POST-pyynnöllä sovittuun polkuun ja tarkista ensin tunnus. Validoi sitten JSON-sisältö:

  • device- ja notification-kenttien on oltava objekteja.
  • device.uniqueId- ja notification.type-kenttien on oltava ei-tyhjiä merkkijonoja.
  • notification.serverTime-kentän on oltava äärellinen luku.

Virheellinen JSON tai virheelliset pakolliset kentät hylätään yleensä HTTP 400 -vastauksella. Sijainti, alkoholiarvo, nimi, lähdetunnus ja lähdeaika ovat valinnaisia, eikä niitä saa vaatia viestin vastaanottamiseksi.

Tallenna ennen vastaanoton kuittaamista

Tallenna alkuperäinen viesti ja vastaanottoaika pysyvään jonoon tai tietokantaan ennen kuin vastaat HTTP 204 No Content -vastauksella. Jatka sitten käsittelyä taustalla.

Jo tallennettu ja kaksoiskappaleeksi varmistettu viesti voidaan myös kuitata HTTP 204 -vastauksella. Jos tallennus epäonnistuu, vastaa HTTP 500- tai 503-tilakoodilla, älä 2xx-sarjan tilakoodilla.

Päätä HTTP-vastaus

Kaikki HTTP-vastaukset tilalla 200–299 lasketaan onnistuneiksi koko vastauksen valmistuttua, vaikka taustakäsittely myöhemmin epäonnistuisi. 204 on suositeltu; myös 200 ja 202 toimivat. Vastausrunkoa ei tulkita eikä erityistä JSON-muotoa tarvita. Päätä vastaus heti: avoin tai suoratoistettu vastaus voi aikakatkaistua myös 2xx-otsakkeiden jälkeen.

Aikarajat ja vastauksen koko

Koko HTTPS-pyynnön aikaraja on 10 sekuntia, mukaan lukien yhteys, TLS, lähetys ja koko vastaus. DNS:llä on erillinen 5 sekunnin raja. Vastausrunko saa olla enintään 64 KiB (65 536 tavua). Pyri tallentamaan ja kuittaamaan noin sekunnissa normaalitilanteessa. Tämä ei takaa aikaa ajoneuvon tapahtumasta vastaanottoon.

Epäonnistuneet toimitukset

Verkko- ja aikakatkaisuvirheet sekä virhetilakoodit tarkoittavat epäonnistunutta toimitusta. Aikakatkaisun yhteydessä vastaanotin on saattanut jo tallentaa viestin, vaikka Dignita ei saanut kuittausta.

Kaksoiskappaleet ja järjestys

Pyynnöt voivat saapua samanaikaisesti eikä järjestystä taata. Lähdetapahtuma voi tulla useita kertoja. notification.id ei ole maailmanlaajuisesti yksilöllinen eikä idempotency-key-otsaketta lähetetä.

Jos lähdekenttiä on riittävästi, yhdistä asiakasmääritys, device.uniqueId, notification.id, notification.type ja notification.eventTime kaksoiskappaleiden tunnistamiseen. Varmista avain todellisilla tiedoilla. Älä sisällytä serverTime-kenttää; se voi muuttua yritysten välillä. Jos tunnus ja aika eivät riitä, säilytä tapahtumat yhdistämättä samanlaisia viestejä automaattisesti.

HTTP-vastauksen käsittely

2xx
Onnistunut toimitus koko vastauksen päätyttyä. 204 on suositeltu.
3xx
Epäonnistunut toimitus. Uudelleenohjauksia ei seurata.
4xx
Epäonnistunut toimitus, myös 400, 401 ja 403. Ei automaattista uusintayritystä.
429
Epäonnistunut toimitus. Retry-After ei käynnistä uusintayritystä.
5xx
Epäonnistunut toimitus. Ei automaattista uusintayritystä.

AL-100-tapahtumat

Taulukko näyttää notification.type-kentän täsmälliset arvot. Vain integraatiollenne aktivoidut tapahtumat lähetetään. Kirjainkoolla on merkitystä.

Luettelo sisältää 46 tapahtumatyyppiä. Esiintyvät tapahtumat riippuvat laitteen ominaisuuksista. HS tarkoittaa käsiyksikköä (handset) ja CB ohjausyksikköä (control box). Käytä täsmälleen vastaanotettua nimeä, kuten al_engine_blocked tai al_engine_unblocked.

Tallenna ja kuittaa kelvolliset viestit, joilla on uusi tai tuntematon tapahtumatyyppi. Merkitse ne liiketoimintakartoitusta varten hylkäämisen sijaan.

46 / 46 tapahtumatyyppiä

AL-100-tapahtumat
Vastaanotettu notification.typeKuvaus
al_test_passedPuhallustesti hyväksytty.
al_test_failedPuhallustesti hylätty.
al_retest_passedUusintatesti hyväksytty.
al_retest_failedUusintatesti hylätty.
al_hs_connected_cb_after_calibrationKäsiyksikkö yhdistetty kalibroinnin jälkeen.
al_memory_fullMuisti täynnä.
al_handset_disconnectedKäsiyksikkö irrotettu.
al_handset_reconnectedKäsiyksikkö yhdistetty uudelleen.
al_invalid_breath_sampleVirheellinen puhallusnäyte.
al_out_of_working_temperature_hsKäsiyksikön lämpötila käyttöalueen ulkopuolella.
al_out_of_working_temperature_cbOhjausyksikön lämpötila käyttöalueen ulkopuolella.
al_main_power_on_cb_turned_onOhjausyksikön virta kytketty päälle.
al_low_battery_detectedAlhainen akun varaustaso havaittu.
al_ignition_turned_offSytytys kytketty pois.
al_ignition_turned_onSytytys kytketty päälle.
al_main_power_on_cb_turned_offOhjausyksikön virta kytketty pois.
al_start_of_engineMoottorin käynnistys.
al_starter_relay_openedKäynnistysrele avattu.
al_starter_relay_closedKäynnistysrele suljettu.
al_vehicle_movement_detectedAjoneuvon liike havaittu.
al_hs_cb_connected_with_new_timestampKäsiyksikkö ja ohjausyksikkö yhdistetty uudella aikaleimalla.
al_device_errorLaitevirhe.
al_hs_exchangedKäsiyksikkö vaihdettu.
al_cb_connected_with_computerOhjausyksikkö yhdistetty tietokoneeseen.
al_serialnumber_not_matched_between_cb_and_hsKäsi- ja ohjausyksikön sarjanumerot eivät vastaa toisiaan.
al_retest_requestedUusintatesti pyydetty.
al_retest_not_deliveredPyydettyä uusintatestiä ei toimitettu.
al_vehicle_movement_detected_without_breath_testAjoneuvon liike ilman puhallustestiä.
al_early_service_is_occurredEnnenaikainen huolto tapahtunut.
al_remainingtime_for_service_due_is_less_than_24_hoursHuoltoon alle 24 tuntia.
al_grace_period_started_after_expiry_of_service_dateHuoltopäivän jälkeinen lisäaika alkanut.
al_service_date_including_grace_period_expiredHuoltopäivä lisäaikoineen umpeutunut.
al_hs_cb_connected_with_new_setting_valuesKäsi- ja ohjausyksikkö yhdistetty uusilla asetuksilla.
al_service_date_reset_by_new_timestampHuoltopäivä nollattu uudella aikaleimalla.
al_calibration_done_with_new_timestampKalibrointi tehty uudella aikaleimalla.
al_serialnumber_of_hs_changed_with_new_pairKäsiyksikön sarjanumero muuttunut uuden parituksen yhteydessä.
al_serialnumber_of_cb_changed_with_new_pairOhjausyksikön sarjanumero muuttunut uuden parituksen yhteydessä.
al_log_data_deletedLokitiedot poistettu.
al_forced_override_activatedPakotettu override aktivoitu.
al_forced_override_expiredPakotettu override päättynyt.
al_handset_disconnected_during_engine_run_movementKäsiyksikkö irrotettu moottorin käydessä ja ajoneuvon liikkuessa.
al_handset_disconnected_during_engine_run_accKäsiyksikkö irrotettu moottorin käydessä ja ACC:n ollessa päällä.
al_engine_unblockedMoottorin esto poistettu.
al_engine_blockedMoottorin esto aktivoitu.
al_temporary_override_activatedTilapäinen override aktivoitu.
al_temporary_override_endedTilapäinen override päättynyt.

Muut hälytykset ja mallit

Vastaanotettavat hälytykset riippuvat laitemallista ja integraatiollenne aktivoiduista tapahtumista. Useimmat näistä hälytyksistä vaativat aktivoidun seurannan. Seuranta on lisämaksullinen lisäpalvelu, joka mahdollistaa säännöllisen GPS-seurannan hälytysten yhteydessä saatavien sijaintitietojen lisäksi. Kaikki laitteet eivät tue kaikkia hälytyksiä.

Hylätystä testistä AL-100 lähettää tyypin al_test_failed. Jotkin muut mallit lähettävät tyypin alco_test_failed ilman alkoholiarvoja sisältävää additionalInfo-objektia.

AL-100:ssa voitte vastaanottaa al_ignition_turned_on-tapahtuman, kun sytytysvirta kytketään päälle, ja al_ignition_turned_off-tapahtuman, kun se kytketään pois. Tapahtumat lähetetään, kun ne on aktivoitu integraatiollenne.

Geofence- ja nopeushälytykset sisältävät tapahtumatyypin ja mahdollisen sijainnin. JSON ei sisällä geofence-tunnusta, mitattua nopeutta tai raja-arvoa.

Muut hälytykset ja mallit
Vastaanotettu notification.typeKuvaus
deviceOfflinedeviceSleepOnOffline tai lepotila.
deviceOnlineOnline tai herännyt.
vibrationLiike tai tärinä.
lowBatterySisäisen akun varaustaso alhainen.
powerOnpowerOffdeviceChargeOndeviceChargeOffUlkoinen virta tai lataus päälle/pois.
geofenceEntergeofenceExitGeofence-alueelle saapuminen tai sieltä poistuminen.
deviceOverspeedYlinopeus.
alco_test_failedHylätty testi joissakin muissa malleissa.
alco_physical_bypassFyysinen ohitus sitä tukevissa malleissa.

Testaus ja käyttöönotto

Vastaanottimen testaus

Tallenna JSON-esimerkki nimellä alarm-example.json. Aseta ALARM_ENDPOINT testipäätepisteeseenne ja ALARM_FORWARDING_TOKEN oikeaan tunnukseen. Älä lisää oikeita tunnuksia lähdekoodiin tai dokumentaatioon. Komento testaa vastaanottimen; odotettu vastaus on 204 ilman vastausrunkoa.

Yhteinen yhteystesti

Curl-testi ei korvaa Dignitan kanssa tehtävää toimitustestiä, mukaan lukien DNS ja TLS. Testaa täsmällisellä URL:llä, voimassa olevalla varmenteella, oikealla tunnuksella, yritykseen liitetyllä todellisella laitteella ja vähintään yhdellä tarkoitetulla hälytyksellä. Varmista sekä tapahtuman tallennus että lähettäjän saama täydellinen 2xx-vastaus 10 sekunnissa.

Valitse vain tarvitsemanne tapahtumat ja tarkista mallin tuki sekä mahdolliset seurantavaatimukset. Jo alkanut toimitus voi käyttää aiempia asetuksia.

Tarkista ennen käyttöönottoa

  • Kelvollinen tunnus ja AL-100-testi: tallenna oikea tyyppi, tunnisteet ja alkoholiarvot, vastaa 2xx.

  • Ilman sijaintia: tallenna null, älä 0, 0.

  • Puuttuva tunnus, nimi, lähdeaika tai sijaintikenttä: hyväksy, jos ydinkentät ovat kelvollisia.

  • Virheellinen tai puuttuva tunnus: hylkää käynnistämättä liiketoimintatoimintoja.

  • Virheellinen JSON tai ydinkenttä: hylkää yleensä 400-vastauksella.

  • Ylimääräinen JSON-kenttä tai tuntematon tyyppi: tallenna, kuittaa ja merkitse kartoitustarve.

  • Sama lähdetapahtuma kahdesti: vältä kaksinkertaisia liiketoimintatoimintoja, jos tapahtuma voidaan tunnistaa varmasti.

  • Samanaikaiset ja viivästyneet tapahtumat: säilytä kaikki olettamatta järjestystä.

  • Pysyvän tallennuksen virhe: älä vastaa onnistuneella 2xx:llä ja varmista virheen valvonta.

Käyttö ja vianmääritys

Kirjaa vastaanottoaika, device.uniqueId, notification.type, lähteen tapahtumatunnus sen ollessa saatavilla sekä käsittelyn tulos. Peitä tunnus. Seuraa tallennus- ja HTTP-virheitä, vastausaikoja ja taustakäsittelyn virheitä.

Heartbeat-viestejä ei ole. Tapahtumien puuttuminen ei todista yhteyden toimivan. Virheet ja aikakatkaisut eivät käynnistä automaattisia uusintayrityksiä.

Jos hälytys puuttuu

Ota yhteyttä Dignitaan, jos hälytys puuttuu. Dignita tarkistaa, että laite kuuluu integraatioonne, mitkä tapahtumat on aktivoitu ja mikä toimituksen tila on. Vastaanottimen puolella tarkistakaa saatavuus, tunnus, varmenne ja pysyvä tallennus.