Integraatio-opas

Versio 1.0 · 1. lokakuuta 2026

Vastaanota hälytykset omiin järjestelmiinne

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

Sopikaa vastaanottajan URL-osoitteesta, tunnuksesta ja vastaanotettavista tapahtumista Dignitan kanssa.

HTTP-pyyntö

POST /dignita/alarms HTTP/1.1
Host: receiver.example.com
Content-Type: application/json
Authorization: Bearer <TOKEN>

Esimerkkiarvot. Dignita toimittaa oikean URL-osoitteen ja tunnuksen erikseen.

Yhteys ja päätepiste

Yhteyden muodostaminen

Toimittakaa Dignitalle täydellinen vastaanottajan URL, esimerkiksi https://receiver.example.com/dignita/alarms. Sopikaa vastaanotettavista tapahtumista. Dignita toimittaa tunnuksen erikseen. Tehkää yhteinen yhteystesti Dignitan kanssa ennen integraation aktivointia.

Osoitteen vaatimukset

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: Bearer <TOKEN>. Tarkista tunnus jokaisesta pyynnöstä. Hylkää puuttuva tai virheellinen tunnus esimerkiksi 401-vastauksella käynnistämättä liiketoimintatoimintoa. Säilytä tunnus salaisessa määrityksessä ja peitä se lokitiedoista.

Dignita toimittaa tunnuksen erikseen. Tarkista koko sovittu arvo jokaisesta pyynnöstä.

Määrityksen ja tunnuksen muutokset

Ota yhteyttä Dignitaan tunnuksen vaihtamiseksi. Vaihto on sovitettava yhteen vastaanottimenne kanssa.

Pyynnöissä ei ole HMAC-allekirjoitusta tai erillistä allekirjoitusotsaketta.

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. Taulukko määrittää validoinnin vähimmäisvaatimukset; valinnaisia kenttiä ei saa vaatia vastaanottimessa.

Tulkitse tapahtuma notification.type-kentän perusteella. Liitä kukin asiakasmääritys 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.

AL-100 · hylätty testi

{
  "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
    }
  }
}

Esimerkkiarvot. Dignita toimittaa oikean URL-osoitteen ja tunnuksen erikseen.

Ajat, sijainti ja alkoholiarvot

Aikamuodot

notification.serverTime ilmaisee välitysajan Unix-aikana millisekunteina. notification.eventTime ilmaisee tapahtuma-ajan ja notification.position.time sijainnin mittausajan. Tapahtuma- ja sijaintiajat voivat puuttua tai käyttää eri muotoja. Esimerkkien ISO 8601 UTC/Z ei takaa samaa muotoa tuotannossa. Tarkista todelliset muodot yhteystestissä ja säilytä alkuperäiset arvot. Käsittele puuttuvat tai tulkitsemattomat ajat, äläkä tulkitse aikavyöhykkeettömiä aikoja paikallisajaksi ilman sopimusta.

Puuttuvat sijainnit

Sijainti voi olla tapahtumaa vanhempi; tarkista notification.position.time. 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.

Päättele testitulos notification.type-kentästä, älä itse lasketusta raja-arvosta. Alkoholiarvo nolla ei anna erillistä laatutakuuta. Puuttuva additionalInfo tarkoittaa, ettei alkoholiarvoa toimitettu. Tämä koskee myös alco_test_failed-tyyppiä.

Hälytys ilman sijaintia

{
  "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
    }
  }
}

Esimerkkiarvot. Dignita toimittaa oikean URL-osoitteen ja tunnuksen erikseen.

Kuittaus ja toimitusvirheet

Tallenna ennen kuittausta

Tallenna alkuperäinen viesti ja vastaanottoaika pysyvään jonoon tai tietokantaan ennen 204 No Content -vastausta. Suorita liiketoimintalogiikka taustalla vastauksen jälkeen. Jo tallennettu, varmistettu kaksoiskappale voidaan myös kuitata 204:llä. Tallennuksen epäonnistuessa vastaa 500 tai 503, älä 2xx.

Vastaanota POST sovittuun polkuun ja tarkista ensin tunnus. Validoi sitten JSON: device ja notification ovat objekteja, device.uniqueId ja notification.type ovat ei-tyhjiä merkkijonoja ja notification.serverTime äärellinen luku. Virheellinen JSON tai ydinkenttä hylätään yleensä 400-vastauksella. Älä vaadi sijaintia, alkoholiarvoa, nimeä, lähdetunnusta tai lähdeaikaa.

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.

Hae AL-100-tapahtumia

46 / 46 tapahtumatyyppiä

AL-100-tapahtumat
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 vaativat aktivoidun seurannan. 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.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.

Testaa vastaanotin

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

Esimerkkiarvot. Dignita toimittaa oikean URL-osoitteen ja tunnuksen erikseen.

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.