API v1

API & Webhook

Hubungkan KelolaGaji dengan sistem akuntansi, ERP, atau mesin absensi, supaya angka yang sama tidak diketik dua kali. Tersedia di paket Pro.

10 endpoint8 peristiwa webhookJSONAlamat dasar https://kelolagaji.id/api/v1

Autentikasi

Setiap permintaan membawa kunci API pada header Authorization: Bearer kg_live_…. Kunci dibuat di portal, pada halaman Integrasi → Kunci API, dan hanya ditampilkan sekali. Izinnya mengikuti peran yang dipilih saat kunci dibuat, sama dengan peran pengguna.

Batas laju

Setiap perusahaan boleh mengirim 120 permintaan per menit dan 10.000 per hari. Bila terlampaui, jawabannya 429 dengan header Retry-After.

Idempotensi

3 endpoint menulis data, dan semuanya mewajibkan header Idempotency-Key. Jaringan bisa putus setelah kami menerima permintaan tetapi sebelum jawabannya sampai; tanpa kunci itu, percobaan ulang Anda akan membuat data ganda. Permintaan ulang dengan kunci yang sama mengembalikan jawaban pertama, disertai header Idempotency-Replayed: true. Kunci yang sama dengan isi berbeda dijawab 409.

Halaman & kursor

Daftar memakai kursor, bukan nomor halaman: data bertambah saat Anda membaca, dan nomor halaman akan melewatkan baris tanpa ada yang tahu. Teruskan nilai berikutnya sebagai parameter kursor sampai nilainya null.

Galat

Setiap galat punya kode yang tetap dan pesan berbahasa Indonesia. Buat percabangan berdasarkan kode: pesannya bisa kami perbaiki kapan saja, kodenya tidak pernah berubah.

Tanggal & zona waktu

Satu tanggal di produk ini bisa punya tiga acuan: batas hari absensi mengikuti zona lokasi kerja, periode payroll mengikuti zona perusahaan, dan tanggal transaksi pajak selalu Asia/Jakarta. Karena itu setiap waktu dikirim sebagai ISO-8601 berzona, dan setiap tanggal yang batas harinya bergantung zona, seperti tanggal kerja absensi dan periode payroll, dikirim bersama zonaWaktu-nya. Tanggal kalender biasa seperti tanggal masuk karyawan dikirim apa adanya dan tidak pernah digeser.

Endpoint

Semua jalur di bawah diawali https://kelolagaji.id/api/v1.

MetodeJalurIzin peran
Karyawan
GET/karyawankursor

Daftar karyawan beserta jabatan, lokasi kerja, dan zona waktunya.

penyaring: aktif, lokasiKerjaId, limit, kursor

karyawan.lihat
GET/karyawan/{id}

Satu karyawan beserta jabatan, tanggal masuk, dan tanggal keluarnya.

karyawan.lihat
POST/karyawanidempoten

Menambah karyawan dari sistem HR yang sudah ada. Wajib: nomorKaryawan, nama, tanggalMasuk (YYYY-MM-DD), lokasiKerja (nama atau id).

karyawan.kelola
Absensi
GET/absensikursor

Catatan absensi per tanggal. Batas harinya mengikuti zona LOKASI KERJA (aturan 3).

penyaring: dari, sampai, employeeId, limit, kursor

absensi.lihat
POST/absensi/imporidempoten

Tap mesin fingerprint dari middleware di jaringan perusahaan (#5). Jalur yang sama dengan impor mesin di halaman Impor absensi. Wajib: sumber, lokasiKerja (nama atau id), tap[] berisi pin dan waktu ISO-8601 berzona; tipe MASUK/KELUAR opsional. PIN dipetakan sekali di halaman Impor absensi.

absensi.impor
Cuti
GET/cutikursor

Pengajuan cuti beserta keputusannya.

penyaring: dari, sampai, status, limit, kursor

cuti.lihat
Lembur
GET/lemburkursor

Lembur yang diajukan dan disetujui.

penyaring: dari, sampai, status, limit, kursor

lembur.lihat
Payroll
GET/payroll/runkursor

Periode penggajian. Periodenya mengikuti zona PERUSAHAAN (aturan 3).

penyaring: status, limit, kursor

payroll.run
GET/payroll/slipkursor

Slip gaji yang sudah dibekukan. Tidak pernah dihitung ulang.

penyaring: runId, employeeId, limit, kursor

payroll.run
Komponen variabel
POST/komponen-variabelidempoten

Menyetor komponen gaji variabel satu periode — bonus, tunjangan, potongan.

payroll.input.tinjau

Peristiwa webhook

KelolaGaji mengirim permintaan POST ke alamat https milik Anda setiap kali peristiwa yang dipilih terjadi. Setiap kiriman ditandatangani HMAC-SHA256.

karyawan.masukKaryawan baru aktif
karyawan.berubahJabatan atau upahnya berganti
karyawan.keluarHubungan kerja berakhir
cuti.disetujuiCuti disetujui di tingkat terakhir
lembur.disetujuiLembur disahkan
payroll.finalPeriode payroll dikunci
slip.terbitSlip gaji siap dibagikan
absensi.ditandaiAbsensi perlu ditinjau HR

Memeriksa tanda tangan

Hitung tanda tangannya sendiri: HMAC-SHA256(rahasia, "{waktu}.{badan mentah}"), awali dengan v1=, lalu bandingkan dengan header X-KelolaGaji-Signature. Nilai waktu ada di header X-KelolaGaji-Waktu.

Cap waktu ikut ditandatangani. Tanpa itu, muatan yang pernah sah bisa dikirim ulang orang lain bertahun-tahun kemudian dan tetap lolos. Tolak kiriman yang capnya berselisih lebih dari lima menit.

Pengiriman ulang

Kiriman yang gagal dicoba ulang dengan jeda 1 menit, 5 menit, 30 menit, 2 jam, 6 jam, lalu berhenti dengan catatan. Kiriman yang berhenti bisa dikirim ulang dari portal.

Yang belum ada

OAuth dan aplikasi pihak ketiga, GraphQL, SDK resmi, dan webhook masuk dari sistem lain. Kalau salah satunya menghalangi integrasi Anda, beri tahu kami. Urutan pengerjaan berikutnya ditentukan oleh yang paling banyak diminta.