Kerja di Staffy, dari awal sampai rekap.

Sebelum absen pertama: checklist admin

1. Buat akun karyawan. Buka Organisasi, buat akun langsung atau selesaikan undangan. Pastikan orang tersebut sudah tercatat di perusahaan yang benar. Mendaftarkan orang di mesin tidak otomatis membuat akun Staffy.
2. Daftarkan orang di mesin. Catat Employee ID/PIN yang benar. Simpan ID sebagai teks: 001 dan 1 dapat dianggap berbeda. Nama yang sama tidak digunakan untuk mencocokkan dua akun secara otomatis.
3. Siapkan jadwal. Di Jadwal Kerja, buat jadwal utama perusahaan. Jika sebagian karyawan bekerja sampai Sabtu, buat jadwal lain lalu pilih mereka di Penugasan Karyawan. Tentukan tanggal mulai berlaku; karyawan tanpa jadwal khusus mengikuti jadwal utama.
4. Tambahkan sumber. Buka Sumber Data Presensi, klik Tambah Sumber Presensi, lalu pilih Hikvision, REST API, Webhook, atau impor file sesuai cara perangkat menyediakan log.
5. Hubungkan ID ke akun. Di Pemetaan Karyawan, pilih sumber, isi ID mesin, lalu pilih pengguna dan simpan. Gunakan sumber tertentu bila beberapa mesin memiliki PIN yang sama untuk orang berbeda.
6. Lakukan absensi dan terima log. Lakukan percobaan masuk serta keluar. Tarik log untuk API, jalankan pengirim untuk webhook, atau impor file. Baca jumlah log baru, duplikat, dan yang perlu mapping.
7. Periksa hasil. Buka Rekap Kehadiran; pilih tanggal percobaan, semua status, dan departemen yang sesuai. Cocokkan orang, jam masuk, jam keluar, dan jadwal.

Hikvision HTTP Listening: event langsung ke server

1. Di Sumber Data Presensi, tambahkan sumber dengan metode Hikvision — kirim event via HTTP Listening, lalu simpan. Sumber ISAPI yang sudah ada tetap dapat dipakai untuk tarik log.
2. Isi alamat server yang dapat dijangkau perangkat. Untuk hosting gunakan domain HTTPS; untuk localhost gunakan IP LAN komputer beserta port aplikasi, bukan localhost atau IP mesin fingerprint.
3. Salin empat nilai dari form ke menu HTTP Listening di Hikvision: Event Alarm IP/Domain Name, URL, Port, dan Protocol. URL mengandung token rahasia; jangan bagikan. Ganti URL rahasia di aplikasi jika bocor, lalu perbarui perangkat.
4. Simpan di perangkat, lakukan absen, lalu klik Cek penerimaan. Heartbeat atau alarm pintu hanya membuktikan adanya kiriman, belum menjadi log presensi. Format yang diterima adalah EventNotificationAlert JSON/XML atau metadata multipart. Foto tidak disimpan; nonaktifkan pengiriman foto jika ukuran kiriman melebihi 4 MB.
5. Di Pemetaan Karyawan pilih sumber HTTP Listening yang baru dan hubungkan Employee ID. Pemetaan khusus sumber ISAPI tidak otomatis berlaku pada sumber baru. Log tanpa pemetaan disimpan sampai ID dihubungkan.
6. Pengiriman ulang saat internet terputus bergantung pada firmware perangkat. Tarik riwayat melalui ISAPI hanya dapat dilakukan jika server masih bisa menjangkau perangkat. HTTP Listening tidak memberi bukti kelengkapan tarikan, sehingga sumber ini belum menghasilkan Alpa otomatis dari ketiadaan log.

Contoh: menghubungkan dua karyawan

Misalnya sumber bernama Kantor Utama memiliki Andi dengan Employee ID 1 dan Budi dengan ID 2. Buat kedua akun di Organisasi, lalu pasangkan Kantor Utama + 1 ke Andi dan Kantor Utama + 2 ke Budi. Jika hanya Andi yang melakukan absen, keberadaan mapping Budi tidak membuat log absensi Budi.

Sumber dan akun harus berada pada tenant/perusahaan yang sama. ID 1 dari perusahaan lain tidak ikut dipasangkan. Saat mapping disimpan, sistem mencoba memproses ulang log berstatus UNMAPPED yang sesuai; muat ulang rekap sesudahnya.

Memahami jam dan hasil rekap

• Untuk log bertipe masuk/keluar, sistem mengambil masuk paling awal dan keluar paling akhir pada hari tersebut. Untuk log tanpa jenis yang dikenali, kejadian pertama dipakai sebagai masuk dan kejadian berikutnya sebagai keluar.
• Satu kali scan belum cukup untuk menghitung durasi masuk–keluar. Periksa log pulang sebelum menganggap durasi kosong sebagai error.
• Tanpa aturan Terlambat aktif, keterlambatan mengikuti jadwal dan toleransi. Contoh: mulai 07.30, toleransi 15 menit, masuk 08.00 → terlambat 30 menit. Bila ada aturan Terlambat aktif, aturan itu menggantikan batas bawaan: masuk setelah 09.00 → masuk 09.20 dihitung telat 20 menit.
• Durasi dihitung dari selisih keluar–masuk. Hanya bagian waktu yang benar-benar beririsan dengan istirahat yang dikurangi. Dua log berselisih 21 menit di luar jam istirahat menghasilkan durasi 21 menit.
• Waktu yang sudah membawa offset, misalnya 2026-10-09T08:00:00+07:00, mengikuti offset itu. Mengganti zona pada form tidak menulis ulang timestamp log lama.
• Jadwal kerja menggunakan WIB (Asia/Jakarta), dengan toleransi yang dapat diatur per jadwal. Jam pulang harus setelah jam masuk; shift lintas tengah malam belum didukung.

Aturan otomatis dan perubahan rekap

Atur kondisi masuk/keluar, sebelum/setelah/tepat jam, atau tidak ada presensi masuk/keluar. Semua kondisi dalam satu aturan harus terpenuhi. Aturan aktif diperiksa dari atas ke bawah; aturan pertama yang cocok menentukan status. Status cuti/izin/dinas yang sudah ditentukan, hari libur, dan koreksi yang disetujui tetap dilindungi.

Uji Aturan memakai evaluator dan jadwal yang sama dengan proses log, tanpa menyimpan rekap. Setelah aturan disimpan, log berikutnya memakai aturan baru. Rekap lama tidak langsung berubah: untuk log API Hikvision gunakan Proses Ulang Data pada tanggal akhir filter yang sesuai. Simulator belum memuat cuti atau koreksi milik karyawan tertentu.

Jadwal karyawan dan Alpa otomatis

1. Buka Jadwal Kerja → Penugasan Karyawan. Cari nama atau filter departemen, centang karyawan, lalu Atur karyawan. Pilih jadwal dan tanggal mulai berlaku. Pilihan “Utama” mengembalikan karyawan ke jadwal perusahaan.
2. Untuk mengganti penugasan mendatang, pilih karyawan dan tanggal yang sama. Penugasan pada tanggal lain tetap tersimpan. Penugasan mulai hari ini memperbarui rekap hari ini yang sudah ada; rekap sebelumnya tidak dipindahkan ke jadwal baru.
3. Di Edit jadwal, aktifkan Evaluasi Alpa otomatis bila diperlukan. Jadwal lama tetap nonaktif sampai admin mengaktifkannya. Hanya karyawan aktif yang sudah memiliki Pemetaan Karyawan yang dievaluasi; akun lain tidak dibuatkan Alpa.
4. Setelah jam pulang ditambah jeda (bawaan 30 menit), satu presensi menjadi Tidak Lengkap. Selama hari masih berjalan, tampil Sedang berjalan atau Terlambat. Log masuk/keluar yang datang kemudian menghitung ulang rekap.
5. Alpa tanpa log hanya dibuat jika semua sumber API karyawan berhasil menarik rentang dari awal hari sampai batas evaluasi. Sinkronisasi gagal atau belum lengkap menunda Alpa. CSV dan webhook/bridge tidak memiliki bukti kelengkapan tarikan, sehingga tidak menyimpulkan Alpa otomatis dari ketiadaan log.
6. Hari di luar jadwal dan tanggal libur khusus tidak dinilai Alpa. Tambahkan libur nasional/perusahaan secara manual pada jadwal; kalender libur nasional belum diisi otomatis. Cuti, izin, dinas yang disetujui dan koreksi admin tetap dilindungi.

Evaluasi berjalan bertahap sekitar 5 menit melalui penjadwal server dan memeriksa 7 hari terakhir, paling awal sejak fitur diaktifkan serta karyawan dipetakan. Server harus tetap menyala; deployment serverless memerlukan cron. Perubahan isi jadwal dipakai saat rekap diproses ulang. Aturan Terlambat dengan jam tertentu masih didahulukan dari batas jadwal.

Koreksi, izin, dan cuti

1. Di Presensi Saya, pilih catatan yang ingin dikoreksi, isi perubahan jam/status dan alasan, lalu ajukan. Koreksi memerlukan catatan presensi yang sudah ada; bila belum ada log, selesaikan pengambilan dan mapping terlebih dahulu.
2. Untuk cuti/izin, pilih jenis, tanggal mulai–selesai, dan lengkapi form pengajuan. Pisahkan pengajuan yang melewati pergantian tahun.
3. HR/Admin menyiapkan jenis cuti dan kuota untuk karyawan, jenis cuti, serta tahun yang sesuai melalui Manajemen Cuti. Cuti tahunan, cuti besar, dan jenis berkuota memerlukan alokasi terlebih dahulu.
4. Pihak peninjau memproses pengajuan sesuai alur persetujuan. Menyimpan konfigurasi alur staff atau manager memerlukan minimal satu peninjau pada masing-masing alur.

Saldo tersedia = alokasi − terpakai − pending. Contoh: alokasi 12 hari, terpakai 3, pending 2 → tersedia 7 hari. Pengajuan yang masih menunggu sudah mengurangi saldo tersedia; cek pengajuan sebelumnya bila saldo terlihat kurang.

Hikvision / REST: tes, simpan, lalu tarik

1. Isi nama sumber dan URL lengkap dengan http:// atau https://. Hikvision memakai alamat dasar mesin; REST memakai endpoint JSON log, bukan halaman login perangkat.
2. Isi akun perangkat pada kolom terpisah. Untuk REST, pilih autentikasi yang diminta penyedia API. Akun web Staffy tidak otomatis menjadi akun mesin.
3. Klik Tes koneksi nyata. Tes membaca sampel dalam 24 jam terakhir, tanpa menyimpan log dan tanpa memeriksa mapping karyawan. Hasil tanpa event tetap dapat berarti koneksi berhasil.
4. Setelah tes konfigurasi baru berhasil, bagian Tarik log muncul dalam modal yang sama. Pilih rentang maksimal 7 hari. Rentang pada form tarik log diberi label UTC; WIB = UTC+7. Pukul 08.00 WIB setara 01.00 UTC.
5. Klik Tarik log. Untuk sumber baru, konfigurasi disimpan sebelum pengambilan. Membuat sumber saja tidak mengaktifkan polling berkala; pengambilan API langsung berjalan saat tombol ditekan.

REST harus menyediakan array objek log atau jalur array yang dikonfigurasi. Jika respons berupa { data: { events: [...] } }, jalur arraynya data.events. Cocokkan field ID karyawan, waktu, dan jenis event. Pagination generik saat ini memakai nextCursor; API dengan format berbeda memerlukan penyesuaian/penghubung.

Webhook / penghubung lokal

1. Pilih Webhook lalu simpan sumber untuk mendapatkan URL dan token. Salin token saat ditampilkan; token tidak diperlihatkan lagi setelah modal ditutup.
2. Untuk Hikvision di jaringan kantor, unduh paket penghubung dari modal, ekstrak pada komputer kantor, lalu jalankan Mulai-Penghubung.cmd. Komputer memerlukan Node.js 22.18+.
3. Isi IP serta akun perangkat, URL webhook, dan token di penghubung. Komputer harus dapat menjangkau mesin dan internet, serta tetap menyala bersama jendela penghubung.
4. Klik Perbarui status untuk melihat kabar terakhir penghubung. Status aktif menunjukkan penghubung menghubungi server; tetap periksa bahwa log dan rekap benar-benar bertambah.

Pengirim khusus mengirim JSON ke URL webhook dengan header Authorization: Bearer TOKEN. Gunakan satu objek atau { events: [...] } berisi maksimal 100 log. Contoh satu kejadian:

{
  "employeeIdentifier": "001",
  "timestamp": "2026-10-09T08:00:00+07:00",
  "eventType": "CHECK_IN",
  "externalEventId": "kantor-utama-00001"
}

Gunakan CHECK_OUT untuk keluar dan ID kejadian yang stabil agar kiriman ulang dikenali sebagai duplikat. Bila token diganti, perbarui token pada pengirim juga. Dukungan webhook tidak berarti protokol bawaan setiap merek, seperti ADMS/PUSH, otomatis kompatibel; pengirim harus mengikuti format yang diterima.

Impor file: siapkan log per kejadian

Gunakan CSV, TSV, TXT, atau XLSX, maksimal 5 MB dan 1.000 baris data per impor. XLS lama perlu disimpan ulang menjadi XLSX/CSV. Untuk XLSX, sistem membaca sheet pertama. Header kolom harus terisi dan unik.

employeeIdentifier,timestamp,eventType
001,2026-10-09T08:00:00+07:00,CHECK_IN
001,2026-10-09T17:00:00+07:00,CHECK_OUT

Cocokkan kolom pada form, periksa pratinjau, lalu simpan dan impor. Ekspor ringkasan mesin seperti “total hari hadir, terlambat, jam kerja” bukan pengganti log per kejadian. Simpan PIN sebagai teks di spreadsheet agar nol di depan tidak hilang.

Arti hasil tarik log

Log baru

Event baru berhasil disimpan. Lihat juga jumlah yang perlu mapping; tersimpan belum selalu berarti sudah menjadi rekap karyawan.

Duplikat

Event sudah pernah diterima dari sumber yang sama. Mengulang rentang pengambilan dapat menghasilkan duplikat; sistem melewatinya.

Perlu mapping karyawan

Log diterima, tetapi ID mesin belum terhubung. Buat akun bila belum ada, lalu simpan Pemetaan Karyawan untuk sumber dan ID tersebut.

Event non-presensi dilewati

Event perangkat tidak memenuhi kriteria log presensi. Contoh hasil 0 baru, 0 duplikat, 0 perlu mapping, 2 dilewati berarti dua event dilewati sebelum tahap mapping.