Rajapinta ja webhookit

1. Luo API-avain

Pääkäyttäjä luo avaimen sovelluksessa: Asetukset → Rajapinta ja webhookit → Luo avain. Avain näytetään vain kerran. Lähetä se jokaisessa pyynnössä otsakkeessa Authorization: Bearer <avain>.

curl -H "Authorization: Bearer llk_..." \
  "https://leimauslaite.fi/app/api/v1/entries?from=2026-11-01&to=2026-11-30"

2. Resurssit

Ajat ovat UTC-muodossa (ISO 8601), päivämäärät Suomen aikaa. Ilman parametreja entries ja expenses palauttavat viimeiset 30 päivää. Enintään 600 pyyntöä minuutissa avainta kohden.

{
  "from": "2026-11-01",
  "to": "2026-11-30",
  "data": [
    {
      "id": "kA1b2C3d4E5f6",
      "employeeId": "uX9y8Z7w6V5u4",
      "siteId": "sQ1w2E3r4T5y6",
      "projectId": null,
      "start": "2026-11-03T05:30:00.000Z",
      "end": "2026-11-03T14:00:00.000Z",
      "breakMin": 30,
      "minutes": 480,
      "source": "device",
      "note": ""
    }
  ]
}

3. Webhookit

Lisää osoite kohdassa Asetukset → Rajapinta ja webhookit → Lisää webhook ja valitse tapahtumat. Osoitteen pitää olla https. Vastaa koodilla 2xx viiden sekunnin kuluessa.

POST https://esimerkki.fi/leimauslaite-webhook
Content-Type: application/json
Leimauslaite-Event: entry.started
Leimauslaite-Signature: t=1794500000,v1=5f2c…

{"id":"evt…","type":"entry.started","created":"2026-11-03T05:30:01.120Z","data":{ …kirjaus kuten yllä… }}

Allekirjoituksen tarkistus

Laske HMAC-SHA256 webhookin salaisuudella merkkijonosta <t>.<pyynnön runko> ja vertaa arvoon v1. Hylkää yli viisi minuuttia vanhat pyynnöt.

// Node.js
const crypto = require("crypto");
function verify(rawBody, header, secret) {
  const [, t, v1] = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header) || [];
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;   // enintään 5 min vanha
  const mac = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Virhekoodit

401 avain puuttuu tai on poistettu · 402 paketti ei sisällä rajapintaa · 404 tuntematon resurssi · 422 virheellinen parametri · 429 liian monta pyyntöä. Virheen kuvaus on kentässä error.