Integrationsguide

Version 1.0 · 1 oktober 2026

Ta emot larm i era egna system

Dignita skickar valda larm och händelser som webhooks till er HTTPS-endpoint. Varje POST-anrop innehåller ett JSON-objekt, kodat i UTF-8.

Stäm av er mottagar-URL, token och vilka händelser ni vill ta emot med Dignita.

HTTP-anrop

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

Exempelvärden. Er riktiga URL och token lämnas separat av Dignita.

Anslutning och endpoint

Så ansluter ni

Lämna en fullständig mottagar-URL till Dignita, till exempel https://receiver.example.com/dignita/alarms. Kom överens om vilka händelser ni vill ta emot. Dignita lämnar er token separat. Genomför ett gemensamt anslutningstest med Dignita innan integrationen aktiveras.

Krav på adressen

Adressen måste använda HTTPS med ett giltigt certifikat, korrekt värdnamn och en betrodd certifikatkedja. Självsignerade certifikat accepteras inte som standard. URL:en får vara högst 500 UTF-8-byte och får inte innehålla användarnamn, lösenord eller ett fragment (#).

Endpointen ska vara publikt nåbar. DNS kontrolleras vid varje leverans och måste ge tillåtna publika IP-adresser. Privata, lokala, reserverade adresser och loopback avvisas. Endpointen ska svara direkt; omdirigeringar följs inte.

Autentisering

Kontrollera token

Varje anrop innehåller Authorization: Bearer <TOKEN>. Kontrollera token på varje begäran. Avvisa saknad eller felaktig token, exempelvis med 401, utan att starta någon verksamhetsåtgärd. Förvara token i hemlig konfiguration och maskera den i loggar.

Dignita lämnar er token separat. Kontrollera hela det överenskomna värdet vid varje anrop.

Ändringar och tokenbyte

Kontakta Dignita för byte av token. Bytet behöver samordnas med er mottagare.

Anropen har ingen HMAC-signatur eller separat signaturrubrik.

JSON och fält

Meddelandet innehåller objekten device och notification. Positionsinformation finns i notification.position. Exemplet visar ett underkänt AL-100-prov med position och alkoholvärde.

Händelse-ID, tider, namn och positionsvärden kan saknas eller vara null. Acceptera även nya JSON-fält för framtida utökningar. Tabellen anger minimikraven för validering; valfria fält får inte bli ett krav hos mottagaren.

Tolka händelsen utifrån notification.type. Knyt varje kundkonfiguration till den överenskomna endpointen och token.

Fält i meddelandet

device objectObligatoriskt: Information om enheten.
device.id number | stringValfritt / kan saknas: Enhets-ID. Behandla som identifierare.
device.uniqueId stringObligatoriskt: Icke-tom sträng, normalt IMEI. Bevara inledande nollor.
device.name string | nullValfritt / kan saknas: Enhetens aktuella namn; inte en unik identifierare. Kan vara null.
notification objectObligatoriskt: Information om händelsen.
notification.id number | stringValfritt / kan saknas: Källans händelse-ID. Inte globalt unikt; kan saknas eller vara null.
notification.type stringObligatoriskt: Icke-tom, exakt och skiftlägeskänslig händelsetyp.
notification.eventTime Format från källanValfritt / kan saknas: Tidpunkten för händelsen. Kan saknas eller vara null; formatet kan variera.
notification.serverTime numberObligatoriskt: Ändligt tal. Tidpunkten för vidarebefordran som Unix-tid i millisekunder.
notification.position objectValfritt / kan saknas: Positionsinformation för händelsen. Positionsfält kan saknas eller vara null.
notification.position.id number | stringValfritt / kan saknas: Källans positions-ID. Kan saknas eller vara null.
notification.position.time Format från källanValfritt / kan saknas: Tidpunkten för positionsmätningen. Kan saknas eller vara null; formatet kan variera.
notification.position.latitude numberValfritt / kan saknas: Latitud. Kan saknas eller vara null.
notification.position.longitude numberValfritt / kan saknas: Longitud. Kan saknas eller vara null.
notification.additionalInfo objectValfritt / kan saknas: Endast de fyra AL-100-provtyperna. Kan utelämnas.
notification.additionalInfo.bac numberValfritt / kan saknas: Numeriskt alkoholvärde. Använd perMille för promillehalten.
notification.additionalInfo.perMille numberValfritt / kan saknas: Promillevärde: bac × 10, högst fyra decimaler.

AL-100 · underkänt prov

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

Exempelvärden. Er riktiga URL och token lämnas separat av Dignita.

Tider, position och alkoholvärden

Tidsformat

notification.serverTime anger tidpunkten för vidarebefordran som Unix-tid i millisekunder. notification.eventTime anger tiden för händelsen och notification.position.time tiden för positionsmätningen. Händelse- och positionstider kan saknas eller ha varierande format. ISO 8601 med UTC/Z i exemplen är ingen formatgaranti. Kontrollera verkliga format i anslutningstestet och bevara originalvärden. Hantera saknade eller oläsbara tider och tolka inte tider utan tidszon som lokal tid utan överenskommelse.

När position saknas

Positionen kan vara äldre än händelsen; kontrollera notification.position.time. När position saknas är de fyra positionsfälten null. Enskilda positionsfält kan också utelämnas. En saknad position är inte koordinaten 0, 0.

Promille och provresultat

additionalInfo med numeriska bac och perMille förekommer endast för al_test_passed, al_test_failed, al_retest_passed och al_retest_failed. Använd perMille för promille: perMille = bac × 10, avrundat till högst fyra decimaler. bac 0.08 motsvarar perMille 0.8.

Avgör provresultatet från notification.type, inte från ett egenberäknat gränsvärde. Ett alkoholvärde på noll ger ingen separat kvalitetsgaranti. Saknad additionalInfo betyder att inget alkoholvärde följde med. Det gäller även typen alco_test_failed.

Larm utan position

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

Exempelvärden. Er riktiga URL och token lämnas separat av Dignita.

Kvittens och leveransfel

Spara före kvittens

Spara originalmeddelandet och mottagningstiden i en beständig kö eller databas innan ni svarar med 204 No Content. Kör verksamhetslogiken i bakgrunden efter svaret. En bekräftad dubblett som redan sparats kan också kvitteras med 204. Om lagringen misslyckas ska ni svara med 500 eller 503, inte 2xx.

Ta emot POST på överenskommen sökväg och kontrollera token först. Validera sedan JSON: device och notification ska vara objekt, device.uniqueId och notification.type ska vara icke-tomma strängar och notification.serverTime ett ändligt tal. Ogiltig JSON eller ogiltiga kärnfält avvisas normalt med 400. Kräv inte position, alkoholvärde, namn, käll-ID eller källtid.

Avsluta HTTP-svaret

Alla HTTP-svar med status 200–299 räknas som lyckade när hela svaret är färdigt, även om er bakgrundsbearbetning senare misslyckas. 204 rekommenderas; 200 och 202 fungerar också. Svarskroppen tolkas inte och behöver inget visst JSON-format. Avsluta svaret direkt: ett öppet eller strömmande svar kan nå timeout även efter 2xx-rubriker.

Tidsgränser och svarsstorlek

Gränsen är 10 sekunder för hela HTTPS-anropet: anslutning, TLS, sändning och fullständigt svar. DNS har en separat gräns på 5 sekunder. Svarskroppen får vara högst 64 KiB (65 536 byte). Sikta på att spara och kvittera inom ungefär en sekund vid normal drift. Detta är ingen garanti för tiden från händelsen i fordonet till mottagning.

Misslyckade leveranser

Nätverksfel, timeout och felstatus räknas som misslyckad leverans. Vid timeout kan meddelandet redan ha sparats hos er, trots att Dignita inte fick någon kvittens.

Dubbletter och ordning

Anrop kan ske samtidigt och ordningen är inte garanterad. En källhändelse kan komma flera gånger. notification.id är inte globalt unikt och något idempotency-key-header skickas inte.

Om tillräckliga källfält finns kan ni kombinera kundkonfiguration, device.uniqueId, notification.id, notification.type och notification.eventTime för dubblettkontroll. Verifiera nyckeln mot verklig data. Ta inte med serverTime; det kan ändras mellan försök. Om ID och tid inte räcker, bevara händelserna utan att automatiskt slå ihop liknande meddelanden.

Så tolkas ert HTTP-svar

2xx: Lyckad leverans när hela svaret avslutats. 204 rekommenderas.
3xx: Misslyckad leverans. Omdirigering följs inte.
4xx: Misslyckad leverans, även 400, 401 och 403. Ingen automatisk retry.
429: Misslyckad leverans. Retry-After leder inte till omsändning.
5xx: Misslyckad leverans. Ingen automatisk retry.

AL-100-händelser

Tabellen visar de exakta värdena i notification.type. Endast händelser som aktiverats för er integration skickas. Namnen är skiftlägeskänsliga.

Listan innehåller 46 händelsetyper. Vilka som förekommer beror på enhetens funktioner. HS betyder handenhet (handset) och CB styrenhet (control box). Använd det exakta mottagna namnet, till exempel al_engine_blocked eller al_engine_unblocked.

Spara och kvittera giltiga meddelanden med nya eller okända händelsetyper. Markera dem för komplettering av er verksamhetsmappning i stället för att tappa dem.

Sök bland AL-100-händelser

46 av 46 händelsetyper

AL-100-händelser
Mottagen notification.type	Beskrivning
`al_test_passed`	Utandningsprov godkänt.
`al_test_failed`	Utandningsprov underkänt.
`al_retest_passed`	Återtest godkänt.
`al_retest_failed`	Återtest underkänt.
`al_hs_connected_cb_after_calibration`	Handenheten ansluten efter kalibrering.
`al_memory_full`	Minnet fullt.
`al_handset_disconnected`	Handenheten frånkopplad.
`al_handset_reconnected`	Handenheten återansluten.
`al_invalid_breath_sample`	Ogiltigt utandningsprov.
`al_out_of_working_temperature_hs`	Handenhetens temperatur utanför arbetsområdet.
`al_out_of_working_temperature_cb`	Styrenhetens temperatur utanför arbetsområdet.
`al_main_power_on_cb_turned_on`	Strömmen till styrenheten påslagen.
`al_low_battery_detected`	Lågt batteri upptäckt.
`al_ignition_turned_off`	Tändningen avstängd.
`al_ignition_turned_on`	Tändningen påslagen.
`al_main_power_on_cb_turned_off`	Strömmen till styrenheten avstängd.
`al_start_of_engine`	Motorstart.
`al_starter_relay_opened`	Startrelä öppnat.
`al_starter_relay_closed`	Startrelä stängt.
`al_vehicle_movement_detected`	Fordonsrörelse upptäckt.
`al_hs_cb_connected_with_new_timestamp`	Handenhet och styrenhet anslutna med ny tidsstämpel.
`al_device_error`	Enhetsfel.
`al_hs_exchanged`	Handenheten utbytt.
`al_cb_connected_with_computer`	Styrenheten ansluten till dator.
`al_serialnumber_not_matched_between_cb_and_hs`	Serienumren för handenhet och styrenhet matchar inte.
`al_retest_requested`	Återtest begärt.
`al_retest_not_delivered`	Begärt återtest ej levererat.
`al_vehicle_movement_detected_without_breath_test`	Fordonsrörelse utan utandningsprov.
`al_early_service_is_occurred`	Tidig service har inträffat.
`al_remainingtime_for_service_due_is_less_than_24_hours`	Mindre än 24 timmar till service.
`al_grace_period_started_after_expiry_of_service_date`	Uppskovsperiod efter servicedatum har börjat.
`al_service_date_including_grace_period_expired`	Servicedatum inklusive uppskovsperiod har passerat.
`al_hs_cb_connected_with_new_setting_values`	Handenhet och styrenhet anslutna med nya inställningar.
`al_service_date_reset_by_new_timestamp`	Servicedatum återställt med ny tidsstämpel.
`al_calibration_done_with_new_timestamp`	Kalibrering utförd med ny tidsstämpel.
`al_serialnumber_of_hs_changed_with_new_pair`	Handenhetens serienummer ändrat vid ny parkoppling.
`al_serialnumber_of_cb_changed_with_new_pair`	Styrenhetens serienummer ändrat vid ny parkoppling.
`al_log_data_deleted`	Loggdata raderad.
`al_forced_override_activated`	Forcerad override aktiverad.
`al_forced_override_expired`	Forcerad override avslutad.
`al_handset_disconnected_during_engine_run_movement`	Handenheten frånkopplad vid motordrift och rörelse.
`al_handset_disconnected_during_engine_run_acc`	Handenheten frånkopplad vid motordrift och ACC på.
`al_engine_unblocked`	Motorblockering avaktiverad.
`al_engine_blocked`	Motorblockering aktiverad.
`al_temporary_override_activated`	Tillfällig override aktiverad.
`al_temporary_override_ended`	Tillfällig override avslutad.

Övriga larm och modeller

Vilka larm ni kan ta emot beror på enhetsmodellen och vad som aktiverats för er integration. De flesta kräver aktiverad tracking. Alla enheter stöder inte alla larm.

Vid ett underkänt prov skickar AL-100 al_test_failed. Vissa andra modeller skickar alco_test_failed, utan additionalInfo med alkoholvärden.

För AL-100 kan ni ta emot al_ignition_turned_on när tändningen slås på och al_ignition_turned_off när den slås av. Händelserna skickas när de aktiverats för er integration.

Geofence- och hastighetslarm innehåller händelsetyp och eventuell position. JSON innehåller inte geofence-ID, uppmätt hastighet eller gränsvärde.

Övriga larm och modeller
Mottagen notification.type	Beskrivning
`deviceOfflinedeviceSleepOn`	Offline eller viloläge.
`deviceOnline`	Online eller väckt.
`vibration`	Rörelse eller vibration.
`lowBattery`	Lågt internt batteri.
`powerOnpowerOffdeviceChargeOndeviceChargeOff`	Extern ström eller laddning på/av.
`geofenceEntergeofenceExit`	Inträde i eller utträde ur geofence.
`deviceOverspeed`	Överhastighet.
`alco_test_failed`	Underkänt prov på vissa andra modeller.
`alco_physical_bypass`	Fysisk bypass på modeller som stöder det.

Testa och driftsätt

Testa er mottagare

Spara JSON-exemplet som alarm-example.json. Sätt miljövariablerna ALARM_ENDPOINT till er testendpoint och ALARM_FORWARDING_TOKEN till rätt token. Lägg aldrig riktiga token i källkod eller dokumentation. Kommandot testar er mottagare; förväntat svar är 204 utan svarskropp.

Gemensamt anslutningsprov

Ett curl-test ersätter inte det gemensamma leveranstestet från Dignita, inklusive DNS och TLS. Testa med exakt URL, giltigt certifikat, rätt token, en verklig enhet kopplad till företaget och minst ett av de avsedda larmen. Bekräfta både att ni har sparat händelsen och att avsändaren fått ett fullständigt 2xx-svar inom 10 sekunder.

Välj bara de händelser ni behöver och kontrollera modellens stöd samt eventuella trackingkrav. En leverans som redan påbörjats kan använda tidigare inställningar.

Kontrollera före driftsättning

Giltig token och AL-100-prov: spara rätt typ, identifierare och alkoholvärden, svara 2xx.
Utan position: spara null, inte 0, 0.
Saknat ID, namn, källtid eller positionsfält: acceptera om kärnfälten är giltiga.
Felaktig eller saknad token: avvisa utan verksamhetsåtgärd.
Ogiltig JSON eller kärnfält: avvisa, normalt med 400.
Extra JSON-fält eller okänd typ: spara, kvittera och markera behov av verksamhetsmappning.
Samma källhändelse två gånger: undvik dubbla verksamhetsåtgärder när den säkert kan identifieras.
Samtidiga och fördröjda händelser: bevara alla utan antaganden om ordning.
Fel i beständig lagring: svara inte med lyckad 2xx och kontrollera att felet övervakas.

Testa er mottagare

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

Exempelvärden. Er riktiga URL och token lämnas separat av Dignita.

Drift och felsökning

Logga mottagningstid, device.uniqueId, notification.type, källans händelse-ID när det finns och resultatet av bearbetningen. Maskera token. Följ upp lagringsfel, HTTP-fel, svarstider och fel i bakgrundsbearbetningen.

Det finns ingen heartbeat. Frånvaro av händelser bevisar inte att anslutningen fungerar. Fel och timeout leder inte till automatisk omsändning.

Om ett larm saknas

Kontakta Dignita om ett larm saknas. Dignita kontrollerar att enheten ingår i er integration, vilka händelser som aktiverats och leveransens status. Hos mottagaren kontrollerar ni tillgänglighet, token, certifikat och beständig lagring.