API: údaje z Taktovky vo vašom programe

Oprávnenie

Netreba kľúč.

Odpoveď

data je jeden objekt s týmito poľami:

api"taktovka"

version"v1"

docsstring · uri

openapistring · uri

Príklad

curl https://api.taktovka.com/v1 \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": {
    "api": "taktovka",
    "version": "v1",
    "docs": "https://taktovka.com/integracie",
    "openapi": "https://api.taktovka.com/openapi.json"
  }
}

Oprávnenie

Stačí platný kľúč, oprávnenie netreba.

Odpoveď

data je jeden objekt s týmito poľami:

companyobject

idstring · uuid

namestring

countrystring

SKCZ

currencystring

EURCZK

localestring

tzstring

IANA time zone of the company

planstring

freekaviarenrestauraciasietenterprise

keyobject

idstring · uuid

namestring

scopesarray of string

company:readpeople:readpeople:contactschedules:readattendance:readabsences:readabsences:kindsleave:read

created_atstring · date-time

ISO 8601 instant

expires_atstring · date-time | null

ISO 8601 instant

rate_limitobject

per_secondinteger

burstinteger

Príklad

curl https://api.taktovka.com/v1/me \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": {
    "company": {
      "id": "5b0f2c1e-8d4a-4c7e-9a1b-2f3d4e5a6b7c",
      "name": "Kaviareň pri fontáne",
      "country": "SK",
      "currency": "EUR",
      "locale": "sk",
      "tz": "Europe/Bratislava",
      "plan": "kaviaren"
    },
    "key": {
      "id": "6e5d4c3b-2a19-4807-9f6e-5d4c3b2a1908",
      "name": "Účtovníčka",
      "scopes": [
        "company:read",
        "people:read",
        "schedules:read",
        "attendance:read"
      ],
      "created_at": "2026-09-24T09:30:00.000Z",
      "expires_at": null
    },
    "rate_limit": {
      "per_second": 10,
      "burst": 30
    }
  }
}

Oprávnenie

company:read

Parametre

limitv dotaze · integer

Rows per page, 1–500

Predvolená hodnota 200.

cursorv dotaze · string

The `next_cursor` of the previous page

Odpoveď

data je zoznam, každá položka má tieto polia:

idstring · uuid

namestring

tzstring

IANA time zone the location plans and counts in

addressstring | null

activeboolean

attendance_enabledboolean

The QR door scan is on here

work_timeobject | null

Uneven distribution of working time with an averaging period; null when the week is even

distributionstring

evenuneven

weekly_norm_minutesinteger

The standard week the average is held to, e.g. 2400 = 40 h

averaging_startstring · date | null

First day of the first averaging period

averaging_lengthinteger | null

Length of one averaging period: months in SK, weeks in CZ

Príklad

curl https://api.taktovka.com/v1/locations \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
      "name": "Kaviareň Hlavná",
      "tz": "Europe/Bratislava",
      "address": "Hlavná 12, Košice",
      "active": true,
      "attendance_enabled": true,
      "work_time": null
    }
  ],
  "next_cursor": null
}

Oprávnenie

company:read

Parametre

limitv dotaze · integer

Rows per page, 1–500

Predvolená hodnota 200.

cursorv dotaze · string

The `next_cursor` of the previous page

Odpoveď

data je zoznam, každá položka má tieto polia:

idstring · uuid

namestring

colorstring | null

sort_orderinteger

activeboolean

Príklad

curl https://api.taktovka.com/v1/positions \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "id": "9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f",
      "name": "Barista",
      "color": "#b45309",
      "sort_order": 0,
      "active": true
    }
  ],
  "next_cursor": null
}

Oprávnenie

people:read

S people:contact pribudnú polia email a phone.

Parametre

limitv dotaze · integer

Rows per page, 1–500

Predvolená hodnota 200.

cursorv dotaze · string

The `next_cursor` of the previous page

activev dotaze · string

Active cards (default), former ones, or all

Hodnoty: true, false, all , predvolená true

Odpoveď

data je zoznam, každá položka má tieto polia:

idstring · uuid

first_namestring

last_namestring

activeboolean

contract_typestring

SK: TPP, DoPC, DoBPS, DoVP, DoPCS; CZ: HPP, DPP, DPC

TPPDoPCDoBPSDoVPHPPDPPDPCDoPCS

max_hours_weekinteger | null

Agreed weekly hours

home_location_idstring · uuid | null

position_idsarray of string · uuid

emailstring | nullmôže chýbať

Only with the people:contact scope

phonestring | nullmôže chýbať

Only with the people:contact scope

created_atstring · date-time

ISO 8601 instant

updated_atstring · date-time

ISO 8601 instant

Príklad

curl https://api.taktovka.com/v1/employees \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "first_name": "Eva",
      "last_name": "Nováková",
      "active": true,
      "contract_type": "TPP",
      "max_hours_week": 40,
      "home_location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
      "position_ids": [
        "9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f"
      ],
      "created_at": "2026-03-02T08:15:00.000Z",
      "updated_at": "2026-09-01T10:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Oprávnenie

people:read

S people:contact pribudnú polia email a phone.

Parametre

idv ceste · string · uuidpovinný

Odpoveď

data je jeden objekt s týmito poľami:

idstring · uuid

first_namestring

last_namestring

activeboolean

contract_typestring

SK: TPP, DoPC, DoBPS, DoVP, DoPCS; CZ: HPP, DPP, DPC

TPPDoPCDoBPSDoVPHPPDPPDPCDoPCS

max_hours_weekinteger | null

Agreed weekly hours

home_location_idstring · uuid | null

position_idsarray of string · uuid

emailstring | nullmôže chýbať

Only with the people:contact scope

phonestring | nullmôže chýbať

Only with the people:contact scope

created_atstring · date-time

ISO 8601 instant

updated_atstring · date-time

ISO 8601 instant

Príklad

curl https://api.taktovka.com/v1/employees/{id} \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": {
    "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
    "first_name": "Eva",
    "last_name": "Nováková",
    "active": true,
    "contract_type": "TPP",
    "max_hours_week": 40,
    "home_location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
    "position_ids": [
      "9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f"
    ],
    "email": "eva.novakova@example.com",
    "phone": "+421 900 123 456",
    "created_at": "2026-03-02T08:15:00.000Z",
    "updated_at": "2026-09-01T10:00:00.000Z"
  }
}

Oprávnenie

schedules:read

Parametre

fromv dotaze · string · datepovinný

First day, YYYY-MM-DD, included; years 2000–2100

tov dotaze · string · datepovinný

Last day, YYYY-MM-DD, included; years 2000–2100

locationv dotaze · string · uuid

Only this location

Odpoveď

data je zoznam, každá položka má tieto polia:

schedule_idstring · uuid

location_idstring · uuid

period_startstring · date

Local date of the location, YYYY-MM-DD

period_endstring · date

Local date of the location, YYYY-MM-DD

versioninteger

published_atstring · date-time

ISO 8601 instant

sha256string | null

SHA-256 of the canonical snapshot; null for versions published before it was kept

Príklad

curl "https://api.taktovka.com/v1/schedules?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "schedule_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
      "period_start": "2026-10-19",
      "period_end": "2026-10-25",
      "version": 2,
      "published_at": "2026-10-09T14:12:05.000Z",
      "sha256": "4f1a0c7e9b2d3a6f8e5c1b0d9a7f6e4c3b2a1908f7e6d5c4b3a291807f6e5d4c"
    }
  ],
  "next_cursor": null
}

Oprávnenie

schedules:read

Parametre

schedule_idv ceste · string · uuidpovinný

versionv dotaze · integer

A past version; the latest published one when left out

Odpoveď

data je jeden objekt s týmito poľami:

schedule_idstring · uuid

location_idstring · uuid

period_startstring · date

Local date of the location, YYYY-MM-DD

period_endstring · date

Local date of the location, YYYY-MM-DD

versioninteger

published_atstring · date-time

ISO 8601 instant

sha256string | null

SHA-256 of the canonical snapshot; null for versions published before it was kept

shiftsarray of object

idstring · uuid

schedule_idstring · uuid

versioninteger

The published version the shift is read from

location_idstring · uuid

position_idstring · uuid | null

datestring · date

Local date the shift starts on

start_localstring

Wall-clock time at the location, HH:MM

end_localstring

Wall-clock end; not after start_local means the next day

tzstring

IANA time zone of the location when the version was published

starts_atstring · date-time

ISO 8601 instant with the location's offset at that moment

ends_atstring · date-time

ISO 8601 instant with the location's offset at that moment

break_mininteger

Unpaid break, minutes

minutesinteger

Elapsed minutes from start to end

paid_minutesinteger

Elapsed minutes less the break

headcountinteger

People the shift needs

assignmentsarray of object

employee_idstring · uuid

statestring

declined: the person gave the seat back and does not work it

assignedconfirmedswap_requesteddeclined

Príklad

curl https://api.taktovka.com/v1/schedules/{schedule_id} \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": {
    "schedule_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
    "period_start": "2026-10-19",
    "period_end": "2026-10-25",
    "version": 2,
    "published_at": "2026-10-09T14:12:05.000Z",
    "sha256": "4f1a0c7e9b2d3a6f8e5c1b0d9a7f6e4c3b2a1908f7e6d5c4b3a291807f6e5d4c",
    "shifts": [
      {
        "id": "7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a",
        "schedule_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "version": 2,
        "location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
        "position_id": "9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f",
        "date": "2026-10-24",
        "start_local": "22:00",
        "end_local": "06:00",
        "tz": "Europe/Bratislava",
        "starts_at": "2026-10-24T22:00:00+02:00",
        "ends_at": "2026-10-25T06:00:00+01:00",
        "break_min": 30,
        "minutes": 540,
        "paid_minutes": 510,
        "headcount": 1,
        "assignments": [
          {
            "employee_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
            "state": "confirmed"
          }
        ]
      }
    ]
  }
}

Oprávnenie

schedules:read

Parametre

fromv dotaze · string · datepovinný

First day, YYYY-MM-DD, included; years 2000–2100

tov dotaze · string · datepovinný

Last day, YYYY-MM-DD, included; years 2000–2100

locationv dotaze · string · uuid

Only this location

employeev dotaze · string · uuid

Only this person

Odpoveď

data je zoznam, každá položka má tieto polia:

idstring · uuid

schedule_idstring · uuid

versioninteger

The published version the shift is read from

location_idstring · uuid

position_idstring · uuid | null

datestring · date

Local date the shift starts on

start_localstring

Wall-clock time at the location, HH:MM

end_localstring

Wall-clock end; not after start_local means the next day

tzstring

IANA time zone of the location when the version was published

starts_atstring · date-time

ISO 8601 instant with the location's offset at that moment

ends_atstring · date-time

ISO 8601 instant with the location's offset at that moment

break_mininteger

Unpaid break, minutes

minutesinteger

Elapsed minutes from start to end

paid_minutesinteger

Elapsed minutes less the break

headcountinteger

People the shift needs

assignmentsarray of object

employee_idstring · uuid

statestring

declined: the person gave the seat back and does not work it

assignedconfirmedswap_requesteddeclined

Príklad

curl "https://api.taktovka.com/v1/shifts?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "id": "7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a",
      "schedule_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "version": 2,
      "location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
      "position_id": "9e1d2c3b-4a5f-4e6d-8c7b-1a2b3c4d5e6f",
      "date": "2026-10-24",
      "start_local": "22:00",
      "end_local": "06:00",
      "tz": "Europe/Bratislava",
      "starts_at": "2026-10-24T22:00:00+02:00",
      "ends_at": "2026-10-25T06:00:00+01:00",
      "break_min": 30,
      "minutes": 540,
      "paid_minutes": 510,
      "headcount": 1,
      "assignments": [
        {
          "employee_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
          "state": "confirmed"
        }
      ]
    }
  ],
  "next_cursor": null
}

Oprávnenie

schedules:readattendance:read (všetky)

S absences:read fond pracovného času započíta aj schválené neprítomnosti (fund.absence_minutes a fund.target_minutes).

Limit

Jedno volanie sa ráta ako 5 požiadaviek. Pre jednu firmu beží naraz len jedno. Druhé volanie počas neho dostane 429 s retry_after.

Parametre

monthv dotaze · stringpovinný

Calendar month, YYYY-MM, years 2000–2100

employeev dotaze · string · uuid

Only this person

locationv dotaze · string · uuid

Only the plan and the counted time of this location; the fund and the signature stay the person's whole month

Odpoveď

data je zoznam, každá položka má tieto polia:

employee_idstring · uuid

monthstring

Calendar month, YYYY-MM, years 2000–2100

planned_minutesinteger

Elapsed minutes of the published shifts starting in the month

paid_planned_minutesinteger

The same less the breaks

counted_minutesinteger | null

Counted time from the door scan and manual entries, matched to the roster the way the app counts it (rounding, the plan, the break the law requires, a minor's break); null when attendance is off at every place of the person and nothing was clocked

fundobject | null

Only for an employment contract (SK TPP, CZ HPP) with agreed weekly hours

weekly_hoursnumber

fund_minutesinteger

Weekdays of the month that are not a day-off holiday, times a fifth of the weekly hours

holiday_minutesinteger

Day-off holidays on weekdays of the month

absence_minutesinteger | null

Weekdays covered by an approved absence; only with absences:read, null without it

target_minutesinteger | null

The fund less approved absences: what the plan should reach; only with absences:read, null without it

confirmedobject | null

The person confirmed the month in the app

confirmed_atstring · date-time

ISO 8601 instant

counted_minutesinteger

Counted minutes at the moment of the signature

staleboolean

The month was corrected or counts differently since the signature

mealsobject | null

Meals of the month for the payroll accountant, who applies the amounts; null when the company has set no meal policy in the app or the person's contract is outside it

countinteger

Shifts that give a meal under the company's policy: more than 4 h of work in Slovakia, at least 3 h in Czechia, the break not counted

secondinteger

Second meals, on shifts longer than 11 h including the break, when the policy gives them

absence_daysinteger | null

Working days of approved absences that give a meal when the policy includes absences; only with absences:read and without `location`, null otherwise

sourcestring | null

Where the shifts were read: counted time where the person clocked in that day at that place, the published plan elsewhere; null without a meal from work

attendanceplanboth

formstring

How the company gives meals at the end of the month

kitchenvoucherallowancechoice

choicestring | null

With form `choice` (Slovakia): what the person picked, null until they pick

voucherallowance

Príklad

curl "https://api.taktovka.com/v1/hours?month=2026-09" \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "employee_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "month": "2026-10",
      "planned_minutes": 10620,
      "paid_planned_minutes": 9990,
      "counted_minutes": 9870,
      "fund": {
        "weekly_hours": 40,
        "fund_minutes": 10560,
        "holiday_minutes": 0,
        "absence_minutes": 960,
        "target_minutes": 9600
      },
      "confirmed": {
        "confirmed_at": "2026-11-02T07:41:10.000Z",
        "counted_minutes": 9870,
        "stale": false
      },
      "meals": {
        "count": 20,
        "second": 1,
        "absence_days": 2,
        "source": "both",
        "form": "choice",
        "choice": "allowance"
      }
    }
  ],
  "next_cursor": null
}

Oprávnenie

attendance:read

Parametre

fromv dotaze · string · datepovinný

First day, YYYY-MM-DD, included; years 2000–2100

tov dotaze · string · datepovinný

Last day, YYYY-MM-DD, included; years 2000–2100

employeev dotaze · string · uuid

Only this person

locationv dotaze · string · uuid

Only this location

Odpoveď

data je zoznam, každá položka má tieto polia:

idstring · uuid

employee_idstring · uuid

location_idstring · uuid

shift_idstring · uuid | null

The planned shift the entry belongs to; null for unplanned work

clock_instring · date-time

ISO 8601 instant with the location's offset at that moment

clock_outstring · date-time | null

null while the person is still in

sourcestring

qrmanualpos

offline_inboolean

The clock-in was read on a phone without signal and delivered later

offline_outboolean

correctedboolean

A manager entered or corrected the row

notestring | null

Reason of the manual entry or the last correction

Príklad

curl "https://api.taktovka.com/v1/time-entries?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
      "employee_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "location_id": "0c8e6a42-1f3b-4d5e-8a9b-7c6d5e4f3a2b",
      "shift_id": "7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a",
      "clock_in": "2026-10-24T21:56:00+02:00",
      "clock_out": "2026-10-25T06:04:00+01:00",
      "source": "qr",
      "offline_in": false,
      "offline_out": false,
      "corrected": false,
      "note": null
    }
  ],
  "next_cursor": null
}

Oprávnenie

absences:read

S absences:kinds pole kind ukáže skutočný druh (pn, ocr, other) namiesto absence a pribudne poznámka v note.

Parametre

fromv dotaze · string · datepovinný

First day, YYYY-MM-DD, included; years 2000–2100

tov dotaze · string · datepovinný

Last day, YYYY-MM-DD, included; years 2000–2100

employeev dotaze · string · uuid

Only this person

statusv dotaze · string

Only requests in this state

Hodnoty: requested, approved, rejected

Odpoveď

data je zoznam, každá položka má tieto polia:

idstring · uuid

employee_idstring · uuid

kindstring

dovolenka | absence without absences:kinds; dovolenka | pn | ocr | other with it

dovolenkapnocrotherabsence

date_fromstring · date

Local date of the location, YYYY-MM-DD

date_tostring · date

Local date of the location, YYYY-MM-DD

statusstring

requestedapprovedrejected

notestring | null

Only with absences:kinds

created_atstring · date-time

ISO 8601 instant

approved_atstring · date-time | null

When the request was approved; null unless status is approved

Príklad

curl "https://api.taktovka.com/v1/absences?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "id": "8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d",
      "employee_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "kind": "dovolenka",
      "date_from": "2026-10-28",
      "date_to": "2026-10-29",
      "status": "approved",
      "note": null,
      "created_at": "2026-10-01T12:00:00.000Z",
      "approved_at": "2026-10-01T16:20:00.000Z"
    }
  ],
  "next_cursor": null
}

Oprávnenie

leave:read

Parametre

yearv dotaze · integer

Calendar year; the company's current year when left out

employeev dotaze · string · uuid

Only this person

Odpoveď

data je zoznam, každá položka má tieto polia:

employee_idstring · uuid

yearinteger

unitstring

dayhour

entitlednumber

carried_overnumber

usednumber

Approved leave of the year, past and planned

pendingnumber

Requests of the year still waiting for a decision

remainingnumber

Entitled plus carried over less used; may be below zero

Príklad

curl https://api.taktovka.com/v1/leave-balances \
  -H "Authorization: Bearer $TAKTOVKA_API_KEY"

{
  "data": [
    {
      "employee_id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "year": 2026,
      "unit": "day",
      "entitled": 25,
      "carried_over": 3,
      "used": 12,
      "pending": 2,
      "remaining": 16
    }
  ],
  "next_cursor": null
}