Forritaskil

API og vefhooks

Tengdu Tímabox við launakerfi, BI, Zapier/Make eða eigin hugbúnað. Lestu gögn með REST API og fáðu rauntímatilkynningar með undirrituðum vefhooks.

Búa til API-lykil Hafa samband

Endapunktar

Vefhooks

Sannprófun undirritunar

Yfirlit

Tímabox býður upp á opið, lesandi REST API og útgangandi vefhooks. API-ið er fyrirtækjaskorið — lykillinn sér aðeins gögn þess fyrirtækis sem bjó til hann.

REST API (JSON) — aðeins GET, engar breytingar í gegnum API
Bearer-auðkenning með `tb_live_…` lykli
Vefhooks með HMAC-SHA256 undirritun
Lyklar og vefhooks eru stilltir undir Stillingar → Forritaskil

Allir endapunktar eru undir:

base URL

https://timabox.is

Auðkenning

Allar API-kallanir þurfa `Authorization: Bearer` haus með gildum API-lykli. Lykillinn er sýndur aðeins einu sinni við stofnun — vistaðu hann örugglega.

Skráðu þig inn sem stjórnandi
Farðu í Stillingar → Forritaskil
Búðu til API-lykil og afritaðu hann strax
Sendu lykilinn í Authorization haus á hverri beiðni

header

Authorization: Bearer tb_live_…

Ef lykill er ógiltur eða vantar færðu `401` með `{ "error": "Invalid or missing API key" }`.

Endapunktar

Allir endapunktar eru lesandi (GET) og skila JSON. Blöðrun notar `limit` (hámark 500, sjálfgefið 100) og `offset` þar sem það á við.

GET/api/v1/time-entries

Tímaskráningar

Sækir stimplanir fyrirtækisins, nýjustu fyrst.

Query-breytur

from	ISO dagsetning eða tími — frá og með (valfrjálst)
to	ISO dagsetning eða tími — til og með (valfrjálst)
employee_id	Sía eftir starfsmanni (UUID)
limit	Fjöldi færslna (sjálfgefið 100, hámark 500)
offset	Hliðrun fyrir blöðrun (sjálfgefið 0)

Dæmi

bash

curl "https://timabox.is/api/v1/time-entries?from=2026-07-01&to=2026-07-31&limit=50" \
  -H "Authorization: Bearer tb_live_YOUR_KEY"

Svar

json

{
  "data": [
    {
      "id": "…",
      "user_id": "…",
      "project_id": "…",
      "clock_in": "2026-07-15T08:02:11.000Z",
      "clock_out": "2026-07-15T16:11:04.000Z",
      "break_minutes": 30,
      "status": "approved",
      "clock_in_notes": null,
      "clock_out_notes": null
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 128 }
}

GET/api/v1/employees

Starfsmenn

Listar starfsmenn fyrirtækisins, raðað eftir nafni.

Dæmi

bash

curl "https://timabox.is/api/v1/employees" \
  -H "Authorization: Bearer tb_live_YOUR_KEY"

Svar

json

{
  "data": [
    {
      "id": "…",
      "full_name": "Anna Jónsdóttir",
      "email": "anna@example.is",
      "role": "employee",
      "is_active": true,
      "created_at": "2026-01-10T12:00:00.000Z"
    }
  ]
}

GET/api/v1/projects

Verkefni

Listar verkefni fyrirtækisins.

Dæmi

bash

curl "https://timabox.is/api/v1/projects" \
  -H "Authorization: Bearer tb_live_YOUR_KEY"

Svar

json

{
  "data": [
    {
      "id": "…",
      "name": "Viðgerð — Austurstræti",
      "color": "#15B8A6",
      "is_active": true,
      "client_id": "…",
      "created_at": "2026-03-01T09:00:00.000Z"
    }
  ]
}

GET/api/v1/absences

Fjarvera

Listar fjarverubeiðnir, nýjustu fyrst.

Query-breytur

status	Sía eftir stöðu (t.d. pending, approved, rejected)
employee_id	Sía eftir starfsmanni (UUID)
limit	Fjöldi færslna (sjálfgefið 100, hámark 500)
offset	Hliðrun fyrir blöðrun (sjálfgefið 0)

Dæmi

bash

curl "https://timabox.is/api/v1/absences?status=pending" \
  -H "Authorization: Bearer tb_live_YOUR_KEY"

Svar

json

{
  "data": [
    {
      "id": "…",
      "user_id": "…",
      "type": "vacation",
      "status": "pending",
      "start_date": "2026-08-10",
      "end_date": "2026-08-14",
      "is_half_day": false,
      "reason": null,
      "requested_at": "2026-07-20T10:15:00.000Z",
      "reviewed_at": null
    }
  ],
  "pagination": { "limit": 100, "offset": 0, "total": 3 }
}

Vefhooks

Þegar atburður gerist sendir Tímabox `POST` á skráða vefslóð með JSON-bol og undirritunarhaus. Sendingartími er takmarkaður við 8 sekúndur. Þú getur séð árangur/mistök undir Stillingar → Forritaskil.

Atburðir

time_entry.clocked_in	Starfsmaður stimplar sig inn
time_entry.clocked_out	Starfsmaður stimplar sig út
absence.requested	Fjarverubeiðni send inn
absence.approved	Fjarverubeiðni samþykkt
absence.rejected	Fjarverubeiðni hafnað

Hausar

headers

Content-Type: application/json
X-Timabox-Event: time_entry.clocked_in
X-Timabox-Signature: sha256=<hmac_sha256(secret, raw_body)>

Bolur (body)

json

{
  "event": "time_entry.clocked_in",
  "created_at": "2026-07-15T08:02:11.000Z",
  "data": {
    "time_entry_id": "…",
    "user_id": "…",
    "project_id": "…",
    "clock_in": "2026-07-15T08:02:11.000Z"
  }
}

Nýlegar sendingar (HTTP-staða, villa) eru sýndar í stillingum svo þú þurfir ekki að greina eigin netþjónsloga til að sjá hvort sendingar nái í gegn.

Sannprófun undirritunar

Hver sending er undirrituð með HMAC-SHA256 yfir hráa JSON-bolinn og leyndarmálinu (`whsec_…`) sem þú fékkst við stofnun. Berðu saman við `X-Timabox-Signature` hausinn á forminu `sha256=<hex>`.

Node.js dæmi

javascript

import crypto from "crypto";

function verifyTimaboxSignature(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Python dæmi

python

import hmac, hashlib

def verify_timabox_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"
    return hmac.compare_digest(expected, signature_header)

Villur

401	Vantar eða ógildur API-lykill
500	Villa á þjóni — skoðaðu `error` í svarinu

Algengar spurningar

Undir Stillingar → Forritaskil. Aðeins stjórnendur fyrirtækisins hafa aðgang.

Nei. API-ið er lesandi (GET) til að byrja með — þú sækir gögn til samþættingar. Skráningar gerast í appinu eða á vefnum.

Notaðu HTTP Request / Webhooks einingar: API-lykil fyrir að sækja gögn, eða vefhook-URL hjá Zapier/Make til að taka á móti atburðum frá Tímabox.

Venjuleg notkun fyrir samþættingar er í lagi. Ef þú keyrir mjög tíðar kannanir skaltu frekar nota vefhooks fyrir atburði og sækja lista með blöðrun.

Tilbúinn að tengja?

Búðu til API-lykil í stillingum, eða hafðu samband ef þú þarft aðstoð við samþættingu.

Opna Forritaskil Hafa samband