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
deviceobjectPakollinen- Laitteen tiedot.
device.idnumber | stringValinnainen / voi puuttua- Laitetunnus. Käsittele tunnisteena.
device.uniqueIdstringPakollinen- Ei-tyhjä merkkijono, yleensä IMEI. Säilytä alkunollat.
device.namestring | nullValinnainen / voi puuttua- Laitteen nykyinen nimi; ei yksilöllinen tunniste. Voi olla null.
notificationobjectPakollinen- Tapahtuman tiedot.
notification.idnumber | stringValinnainen / voi puuttua- Lähteen tapahtumatunnus. Ei maailmanlaajuisesti yksilöllinen; voi puuttua tai olla null.
notification.typestringPakollinen- Ei-tyhjä täsmällinen tapahtumatyyppi, jonka kirjainkoolla on merkitystä.
notification.eventTimeLähteen muotoValinnainen / voi puuttua- Tapahtuma-aika. Voi puuttua tai olla null; muoto voi vaihdella.
notification.serverTimenumberPakollinen- Äärellinen luku. Välitysaika Unix-aikana millisekunteina.
notification.positionobjectValinnainen / voi puuttua- Tapahtuman sijaintitiedot. Sijaintikentät voivat puuttua tai olla null.
notification.position.idnumber | stringValinnainen / voi puuttua- Lähteen sijaintitunnus. Voi puuttua tai olla null.
notification.position.timeLähteen muotoValinnainen / voi puuttua- Sijainnin mittausaika. Voi puuttua tai olla null; muoto voi vaihdella.
notification.position.latitudenumberValinnainen / voi puuttua- Leveysaste. Voi puuttua tai olla null.
notification.position.longitudenumberValinnainen / voi puuttua- Pituusaste. Voi puuttua tai olla null.
notification.additionalInfoobjectValinnainen / voi puuttua- Vain neljä AL-100-testityyppiä. Voidaan jättää pois.
notification.additionalInfo.bacnumberValinnainen / voi puuttua- Numeerinen alkoholiarvo. Käytä promillearvona perMille-kenttää.
notification.additionalInfo.perMillenumberValinnainen / 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ä
| Vastaanotettu notification.type | Kuvaus |
|---|---|
al_test_passed | Puhallustesti hyväksytty. |
al_test_failed | Puhallustesti hylätty. |
al_retest_passed | Uusintatesti hyväksytty. |
al_retest_failed | Uusintatesti hylätty. |
al_hs_connected_cb_after_calibration | Käsiyksikkö yhdistetty kalibroinnin jälkeen. |
al_memory_full | Muisti täynnä. |
al_handset_disconnected | Käsiyksikkö irrotettu. |
al_handset_reconnected | Käsiyksikkö yhdistetty uudelleen. |
al_invalid_breath_sample | Virheellinen puhallusnäyte. |
al_out_of_working_temperature_hs | Käsiyksikön lämpötila käyttöalueen ulkopuolella. |
al_out_of_working_temperature_cb | Ohjausyksikön lämpötila käyttöalueen ulkopuolella. |
al_main_power_on_cb_turned_on | Ohjausyksikön virta kytketty päälle. |
al_low_battery_detected | Alhainen akun varaustaso havaittu. |
al_ignition_turned_off | Sytytys kytketty pois. |
al_ignition_turned_on | Sytytys kytketty päälle. |
al_main_power_on_cb_turned_off | Ohjausyksikön virta kytketty pois. |
al_start_of_engine | Moottorin käynnistys. |
al_starter_relay_opened | Käynnistysrele avattu. |
al_starter_relay_closed | Käynnistysrele suljettu. |
al_vehicle_movement_detected | Ajoneuvon liike havaittu. |
al_hs_cb_connected_with_new_timestamp | Käsiyksikkö ja ohjausyksikkö yhdistetty uudella aikaleimalla. |
al_device_error | Laitevirhe. |
al_hs_exchanged | Käsiyksikkö vaihdettu. |
al_cb_connected_with_computer | Ohjausyksikkö yhdistetty tietokoneeseen. |
al_serialnumber_not_matched_between_cb_and_hs | Käsi- ja ohjausyksikön sarjanumerot eivät vastaa toisiaan. |
al_retest_requested | Uusintatesti pyydetty. |
al_retest_not_delivered | Pyydettyä uusintatestiä ei toimitettu. |
al_vehicle_movement_detected_without_breath_test | Ajoneuvon liike ilman puhallustestiä. |
al_early_service_is_occurred | Ennenaikainen huolto tapahtunut. |
al_remainingtime_for_service_due_is_less_than_24_hours | Huoltoon alle 24 tuntia. |
al_grace_period_started_after_expiry_of_service_date | Huoltopäivän jälkeinen lisäaika alkanut. |
al_service_date_including_grace_period_expired | Huoltopäivä lisäaikoineen umpeutunut. |
al_hs_cb_connected_with_new_setting_values | Käsi- ja ohjausyksikkö yhdistetty uusilla asetuksilla. |
al_service_date_reset_by_new_timestamp | Huoltopäivä nollattu uudella aikaleimalla. |
al_calibration_done_with_new_timestamp | Kalibrointi tehty uudella aikaleimalla. |
al_serialnumber_of_hs_changed_with_new_pair | Käsiyksikön sarjanumero muuttunut uuden parituksen yhteydessä. |
al_serialnumber_of_cb_changed_with_new_pair | Ohjausyksikön sarjanumero muuttunut uuden parituksen yhteydessä. |
al_log_data_deleted | Lokitiedot poistettu. |
al_forced_override_activated | Pakotettu override aktivoitu. |
al_forced_override_expired | Pakotettu override päättynyt. |
al_handset_disconnected_during_engine_run_movement | Käsiyksikkö irrotettu moottorin käydessä ja ajoneuvon liikkuessa. |
al_handset_disconnected_during_engine_run_acc | Käsiyksikkö irrotettu moottorin käydessä ja ACC:n ollessa päällä. |
al_engine_unblocked | Moottorin esto poistettu. |
al_engine_blocked | Moottorin esto aktivoitu. |
al_temporary_override_activated | Tilapäinen override aktivoitu. |
al_temporary_override_ended | Tilapä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.
| Vastaanotettu notification.type | Kuvaus |
|---|---|
deviceOfflinedeviceSleepOn | Offline tai lepotila. |
deviceOnline | Online tai herännyt. |
vibration | Liike tai tärinä. |
lowBattery | Sisäisen akun varaustaso alhainen. |
powerOnpowerOffdeviceChargeOndeviceChargeOff | Ulkoinen virta tai lataus päälle/pois. |
geofenceEntergeofenceExit | Geofence-alueelle saapuminen tai sieltä poistuminen. |
deviceOverspeed | Ylinopeus. |
alco_test_failed | Hylätty testi joissakin muissa malleissa. |
alco_physical_bypass | Fyysinen 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.
