დროის აღრიცხვის გზამკვლევი

1. მიანიჭეთ თანამშრომლებს ბარათის ნომერი

ჩანაწერი თანამშრომელს ან HourSquare-ის იდენტიფიკატორით ამოიცნობს, ან გარე იდენტიფიკატორით: იმ მნიშვნელობით, რომელიც თქვენმა მოწყობილობამ უკვე იცის — ბარათის ნომერი, PIN კოდი ან ბარათის UID. დააყენეთ ერთხელ თითოეული თანამშრომლისთვის.

curl -s -X PUT https://api.hoursquare.com/api/public/v1/employees/0f8fad5b-d9cb-469f-a165-70867728950e/external-id \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"B-1042"}'

გარე იდენტიფიკატორები კომპანიის ფარგლებში უნიკალურია. თუ სხვა თანამშრომელს უკვე აქვს B-1042, მიიღებთ 409 already_exists პასუხს, დეტალებში კი მითითებულია, ვის ეკუთვნის. გასასუფთავებლად გააგზავნეთ null. თანამშრომლების იდენტიფიკატორების საპოვნელად ჯერ ჩამოთვალეთ ისინი (საჭიროა employees.read):

curl -s "https://api.hoursquare.com/api/public/v1/employees?limit=100&status=active" \
  -H "Authorization: Bearer $TOKEN"

2. ჩაწერეთ შემოსვლა ან გასვლა

POST /api/public/v1/time-clock/events ერთ მოვლენას იღებს. type არის clock_in, clock_out ან toggle; toggle გასვლას აფიქსირებს, თუ თანამშრომელს ღია სესია აქვს, და შემოსვლას — თუ არა. სწორედ ეს სჭირდება ერთღილაკიან მოწყობილობას.

curl -s -i -X POST https://api.hoursquare.com/api/public/v1/time-clock/events \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "employee": { "externalId": "B-1042" },
    "type": "toggle",
    "occurredAt": "2026-09-14T17:31:05+02:00",
    "deviceId": "front-door-1"
  }'

HTTP/1.1 201 Created
Content-Type: application/json
RateLimit-Policy: apikey;q=300;w=60
RateLimit: limit=300, remaining=298, reset=60

{
  "timeEntryId": "c1a4e0b2-5f7d-4a1e-9b3c-2d6f8e0a1b2c",
  "employee": { "id": "0f8fad5b-d9cb-469f-a165-70867728950e", "externalId": "B-1042" },
  "type": "clock_out",
  "workDate": "2026-09-14",
  "time": "17:31:05",
  "timeZone": "Europe/Berlin",
  "occurredAt": "2026-09-14T17:31:05+02:00",
  "endsNextDay": false,
  "status": "pending_approval",
  "dryRun": false,
  "startTime": "08:59:12",
  "endTime": "17:31:05",
  "totalHours": 8.53
}

employee იღებს id-ს ან externalId-ს; ერთი საკმარისია, ორივეს გაგზავნისას კი ერთსა და იმავე ადამიანზე უნდა მიუთითებდეს. occurredAt არის RFC 3339 დროის ნიშნული და აუცილებლად UTC-სთან სხვაობა უნდა ჰქონდეს; ნიშნული სხვაობის გარეშე 422 კოდით უარიყოფა. deviceId (64 სიმბოლომდე) და note (500 სიმბოლომდე) არასავალდებულოა და ჩანაწერს ინახება.

დროის სარტყელები

სერვერი occurredAt-ს თანამშრომლის სარტყელში ათავსებს: სამუშაო ადგილის დროის სარტყელში, თუ თანამშრომელს ასეთი აქვს, თუ არა — კომპანიისაში, თუ არც ეს — ზუსტად იმ საათობრივ დროში, როგორც გამოაგზავნეთ. პასუხი აბრუნებს გადაწყვეტილ workDate, time, timeZone და occurredAt მნიშვნელობებს, ამიტომ ხედავთ, რა ჩაიწერა. გააგზავნეთ რეალური მომენტი თავისი სხვაობით და განთავსება სერვერს მიანდეთ.

პასუხი

ყველა ველი ყოველთვის არსებობს; სადაც არ გამოიყენება, იქ null წერია.

3. დასრულებული და ღამის ცვლები

როცა თქვენმა სისტემამ ცვლის ორივე ბოლო უკვე იცის, გააგზავნეთ ის ერთი მოთხოვნით POST /api/public/v1/time-entries მისამართზე. ღამის ცვლები ნორმალურად მუშაობს: ჩანაწერი შემოსვლის დღით თარიღდება და endsNextDay დაყენებულია.

curl -s -X POST https://api.hoursquare.com/api/public/v1/time-entries \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "employee": { "externalId": "B-1042" },
    "clockIn": "2026-09-13T22:00:00+02:00",
    "clockOut": "2026-09-14T06:00:00+02:00",
    "note": "night shift"
  }'

breakMinutes ცვლის შუაში ერთ აუნაზღაურებელ შესვენებას აფიქსირებს; ღამის ცვლასთან ერთად მისი გამოყენება არ შეიძლება. 24 საათი ან მეტი ხანგრძლივობის ცვლა უარიყოფა, წმინდა სამუშაო დრო კი მინიმუმ 15 წუთი უნდა იყოს.

4. წარსული თარიღით ჩაწერის ლიმიტები

• occurredAt მომავალში მაქსიმუმ 5 წუთით შეიძლება იყოს, რათა თქვენი მოწყობილობისა და ჩვენი სერვერების საათებს შორის სხვაობა დაიფაროს.
• წარსულში მაქსიმუმ 30 დღით შეიძლება იყოს. უფრო ძველი შესწორებები Hub-ის გავლით კეთდება.
• დღე, რომელიც თანამშრომელმა უკვე დაადასტურა, დაბლოკილია: 409 day_locked.
• ჩანაწერი, რომელიც არსებულ ჩანაწერში ხვდება, უარიყოფა: 409 overlaps_existing_entry.

5. შედარება

attendance.read არეთი ჩამოთვალეთ, რა ჩაიწერა თანამშრომლისთვის, და შეადარეთ თქვენი მოწყობილობის ლოგს.

curl -s "https://api.hoursquare.com/api/public/v1/time-entries?externalId=B-1042&from=2026-09-01&to=2026-09-14&limit=50" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    {
      "id": "c1a4e0b2-5f7d-4a1e-9b3c-2d6f8e0a1b2c",
      "employee": { "id": "0f8fad5b-d9cb-469f-a165-70867728950e", "externalId": "B-1042" },
      "workDate": "2026-09-14",
      "startTime": "08:59:12",
      "endTime": "17:31:05",
      "endsNextDay": false,
      "totalHours": 8.53,
      "breakMinutes": 0,
      "status": "pending_approval",
      "source": "api",
      "approvedAt": null,
      "createdAt": "2026-09-14T06:59:14+00:00"
    }
  ],
  "nextCursor": "MjAyNi0wOS0xNHxjMWE0ZTBiMg",
  "hasMore": true
}

from და to თარიღებია; დიაპაზონი მაქსიმუმ 92 დღეს მოიცავს და ნაგულისხმევად ბოლო 30 დღეა. გვერდზე limit ჩანაწერია (1-დან 100-მდე, ნაგულისხმევად 25); მიჰყევით nextCursor-ს, სანამ hasMore false არ გახდება. თითოეულ ჩანაწერს აქვს id, employee, workDate, startTime, endTime, endsNextDay, totalHours, breakMinutes, status, source, approvedAt და createdAt.

ამ ენდპოინტების შეცდომის კოდები

ყველა შეცდომა application/problem+json ფორმატშია; შეადარეთ error სტრიქონი და არასდროს — ტექსტი.