API Aplikasi Karyawan

Acuan lengkap bagi pengembang aplikasi seluler CompanyBrain. Seluruh bentuk data di halaman ini dibaca langsung dari kode backend yang sedang berjalan, bukan disusun dari ingatan.

Versi API v1 Diperbarui 25 Agustus 2026

Mulai dari sini

Alur terpendek dari layar kosong sampai daftar kehadiran:

# 1. Ambil identitas perusahaan (tanpa token, menentukan nama dan warna layar masuk)
curl https://os.perusahaan-contoh.id/api/v1/public/branding

# 2. Masuk dengan kode karyawan dan PIN
curl -X POST https://os.perusahaan-contoh.id/api/v1/auth/employee-login \
  -H 'Content-Type: application/json' \
  -d '{"employee_code":"EMP-0010","pin":"735291"}'

# 3. Pakai access_token pada seluruh permintaan berikutnya
curl https://os.perusahaan-contoh.id/api/v1/attendance?from=2026-08-01&to=2026-08-31 \
  -H 'Authorization: Bearer eyJ0eXAiOi...'

Alamat dan perusahaan

Akar seluruh alamat adalah https://<host-perusahaan>/api/v1.

Perusahaan ditentukan backend dari header Host. Tidak ada parameter tenant, tidak ada header tambahan, dan tidak ada pengenal perusahaan di dalam badan permintaan. Yang menentukan "aplikasi ini milik siapa" hanyalah alamat yang dihubungi.

Akibatnya bagi aplikasi seluler: simpan origin perusahaan, bukan pengenal tenant. Token yang diterbitkan sudah terikat pada satu perusahaan, sehingga menyimpan pengenalnya di sisi klien hanya menciptakan sumber kebenaran kedua yang dapat bertentangan dengan token.

Autentikasi

Bearer JWT. Access token berlaku 30 menit, refresh token 14 hari.

// Permintaan
{ "employee_code": "EMP-0010", "pin": "735291" }

// Balasan 200
{
  "tokens": {
    "access_token":  "eyJ0eXAiOi...",
    "refresh_token": "eyJ0eXAiOi...",
    "token_type":    "Bearer"
  },
  "tenant_id":       "a2e77511-fa3c-4527-9dda-84eaf9fb2ebe",
  "employee_id":     "6f1c...",
  "must_change_pin": false
}

must_change_pin bernilai benar ketika PIN baru saja disetel bagian SDM. Aplikasi wajib memaksa layar ganti PIN sebelum menampilkan apa pun yang lain.

Penguncian. Lima kali salah berturut-turut mengunci akses selama 15 menit. Balasannya tetap 400, dengan pesan yang menyebutkan sisa waktunya. Perlakukan sebagai pesan untuk ditampilkan apa adanya, bukan sebagai kondisi yang perlu dikenali secara khusus.

// Permintaan
{ "email": "budi@contoh.id", "password": "...", "totp_code": "123456" }  // totp_code opsional

// Balasan 200 ketika verifikasi dua langkah masih diperlukan
{ "requires_2fa": true }

// Permintaan
{ "refresh_token": "eyJ0eXAiOi..." }

// Balasan 200. Perhatikan: tidak dibungkus "tokens"
{ "access_token": "...", "refresh_token": "...", "token_type": "Bearer" }

Konvensi balasan

Pembungkus daftar

Endpoint daftar membungkus isinya dalam data. Sebagian menyertakan halaman, sebagian tidak.

// Berhalaman: /attendance, /leave-requests, /reimbursements, /announcements, /briefings
{ "data": [ ... ], "page": 1, "per_page": 20, "total": 137 }

// Tanpa halaman: /attendance/shifts, /leave-types, /leave-balances,
//                /reimbursement-types, /hr/loans, /tasks/{id}/checklist,
//                /tasks/{id}/comments
{ "data": [ ... ] }

// Khusus /me/tasks dan /me/payslips
{ "data": [ ... ], "punya_data_karyawan": true }

punya_data_karyawan bernilai salah ketika akun yang masuk tidak tertaut ke data karyawan mana pun. Itu bukan galat: sebagian akun memang milik pengelola. Tampilkan keadaan kosong yang menjelaskan, bukan pesan gagal.

Galat

Seluruh galat memakai satu bentuk yang sama:

{ "error": { "code": "bad_request", "message": "Kode karyawan atau PIN tidak cocok." } }

Tipe data

Izin dan cakupan

Bagian ini menjelaskan mengapa endpoint yang sama menjawab berbeda bagi dua orang di perusahaan yang sama.

Setiap izin terdiri atas sumber daya, tindakan, dan cakupan. Cakupan berjenjang dari yang paling sempit: own hanya dirinya sendiri, lalu team, dept, branch, dan all untuk seisi perusahaan. Backend memakai cakupan terluas yang dimiliki, lalu menyaring baris menurut cakupan itu.

Setiap peran memiliki izin dasar sebagai karyawan. Hampir seluruhnya bercakupan own, sehingga tidak satu baris pun membuka data orang lain:

Aplikasi dapat membaca izin efektifnya sendiri dari GET /me, pada larik permissions dan denials. Periksa denials lebih dahulu: penolakan eksplisit mengalahkan izin apa pun.

Profil dan PIN

// Ditemukan
{ "found": true, "name": "Perusahaan Contoh", "slug": "perusahaan-contoh-1234",
  "branding": { "logo_url": "...", "brand_color": "#4f46e5", "tagline": "..." } }

// Host portal bersama atau domain generik
{ "found": false, "portal": true }

Identitas visual adalah hiasan. Kegagalan mengambilnya tidak boleh menghalangi siapa pun masuk.

{
  "user": { "id": "...", "email": "...", "name": "Operator Satu",
            "avatar_url": null, "totp_enabled": false, "preferences": {} },
  "employee_id": "...",
  "employee": { "id": "...", "code": "EMP-0010", "name": "Operator Satu",
                "email": "...", "phone": "..." },
  "tenant":  { "id": "...", "name": "Perusahaan Contoh", "slug": "perusahaan-contoh-1234",
               "logo_url": "...", "white_label": false,
               "hidden_nav": [], "connected_providers": ["ginee"] },
  "roles":       [ { "key": "production_operator", "name": "Operator Produksi" } ],
  "permissions": [ { "resource": "attendance", "action": "read", "scope": "own" } ],
  "denials":     [ { "resource": "payroll", "action": "read" } ],
  "modules":     [ { "module_key": "hr", "enabled": true } ],
  "is_platform_admin": false
}

employee bernilai null bila akunnya tidak tertaut ke data karyawan.

{ "punya_data_karyawan": true, "employee_code": "EMP-0010", "punya_pin": true }

{ "pin_lama": "735291", "pin_baru": "486207" }

pin_lama boleh dihilangkan hanya ketika PIN sedang dalam keadaan wajib ganti karena baru disetel bagian SDM. Dalam keadaan itu pemiliknya baru saja membuktikan dirinya saat masuk, sehingga memintanya mengetik ulang PIN sementara hanya menambah langkah tanpa menambah bukti.

Aturan PIN: tepat enam angka, dan ditolak bila seluruh angkanya sama atau berurutan naik maupun turun. Kedua pola itu menyumbang bagian terbesar dari PIN yang dipakai orang, sehingga melarangnya menaikkan ketahanan jauh lebih banyak daripada menambah panjangnya. Terapkan pemeriksaan yang sama di sisi aplikasi agar pemakai tahu sebelum mengirim.

Kehadiran

Parameter: from, to (tanggal), employee_id, page, per_page (baku 20, batas 100).

Tidak perlu mengirim employee_id. Backend sudah menyaring menurut cakupan izin pemanggil, sehingga karyawan biasa hanya menerima barisnya sendiri.

{ "data": [ {
    "id": "...", "employee_id": "...", "employee_name": "Operator Satu",
    "work_date": "2026-08-25",
    "check_in":  "2026-08-25T01:02:11Z",
    "check_out": "2026-08-25T10:04:52Z",
    "status": "present", "latitude": -6.21, "longitude": 106.84,
    "note": null, "shift_id": "...", "method": "mobile",
    "photo_file_id": null, "out_of_geofence": false
  } ], "page": 1, "per_page": 20, "total": 107 }

status bernilai present atau late. Terlambat ditentukan dari jam mulai shift ditambah toleransi.

{ "data": [ { "id": "...", "name": "Pagi",
              "start_time": "08:00:00", "end_time": "17:00:00",
              "grace_minutes": 15 } ] }

{ "latitude": -6.21, "longitude": 106.84,
  "shift_id": "...",        // opsional; tanpa ini status selalu "present"
  "note": "...",            // opsional
  "method": "mobile",       // wajib cocok dengan metode yang diaktifkan perusahaan
  "photo_file_id": "..." }  // wajib bila perusahaan mensyaratkan foto

Balasannya satu baris kehadiran, bentuknya sama dengan di atas tanpa employee_name.

Perusahaan juga dapat membatasi metode yang boleh dipakai. Bila mobile tidak diaktifkan, balasannya 400 dengan pesan yang menyebut metodenya.

Keadaan absen yang perlu ditangani terpisah:

Pengajuan

Empat jenis pengajuan memakai pola yang sama: kirim, lalu tunggu keputusannya. Bacalah approval_status untuk cuti, lembur, dan reimbursement, serta status untuk kasbon.

Cuti

{ "data": [ { "id": "...", "name": "Cuti Tahunan", "quota_days": 12, "is_paid": true } ] }

{ "data": [ { "id": "...", "employee_id": "...", "leave_type_id": "...",
              "year": 2026, "entitled_days": 12, "used_days": 3 } ] }

Sisa cuti dihitung di sisi aplikasi: entitled_days - used_days. Tidak ada bidang remaining maupun balance.

// Permintaan. employee_id dihilangkan berarti "atas nama saya"
{ "leave_type_id": "...", "start_date": "2026-09-01",
  "end_date": "2026-09-03", "reason": "Keperluan keluarga" }

// Balasan
{ "id": "...", "employee_id": "...", "employee_name": "Operator Satu",
  "leave_type_id": "...", "leave_type_name": "Cuti Tahunan",
  "start_date": "2026-09-01", "end_date": "2026-09-03", "days": 3,
  "reason": "...", "approval_request_id": "...", "approval_status": "pending" }

Lembur

// Permintaan
{ "work_date": "2026-08-24", "minutes": 120, "reason": "Menyelesaikan pesanan" }

// Balasan
{ "id": "...", "employee_id": "...", "work_date": "2026-08-24",
  "minutes": 120, "reason": "...",
  "approval_request_id": "...", "approval_status": "pending" }

minutes wajib lebih dari nol.

Reimbursement

{ "data": [ { "id": "...", "name": "Transportasi", "created_at": "..." } ] }

// Permintaan
{ "type_id": "...", "amount": 150000, "description": "Ongkos kirim sampel",
  "receipt_url": "..." }   // opsional

// Balasan
{ "id": "...", "employee_id": "...", "type_id": "...", "amount": 150000,
  "description": "...", "receipt_url": null,
  "approval_request_id": "...", "approval_status": "pending",
  "current_step": 1, "created_at": "2026-08-25T02:10:00Z" }

Kasbon

{ "data": [ { "id": "...", "employee_id": "...", "employee_name": "Operator Satu",
              "principal": 500000, "installments": 5,
              "installment_amount": 100000, "remaining": 300000,
              "start_period": "2026-09", "reason": "...",
              "status": "active", "paid_count": 2 } ] }

// Seluruh bidang berikut WAJIB, termasuk employee_id dan start_period
{ "employee_id": "...", "principal": 500000, "installments": 5,
  "start_period": "2026-09", "reason": "Biaya sekolah anak" }

Tugas

Parameter: selesai (boolean, baku salah), per_page (baku 50, batas 200).

{ "data": [ { "id": "...", "project_id": "...", "project_name": "Produksi Agustus",
              "title": "Cek mesin lini 2", "description": "...",
              "status_name": "Berjalan", "due_date": "2026-08-26",
              "priority": "high", "selesai": false } ],
  "punya_data_karyawan": true }

Pakai endpoint ini, bukan /projects/{id}/tasks. Yang kedua menuntut pemanggilnya mengetahui proyeknya lebih dahulu, sehingga menyusun satu layar berarti belasan permintaan pada sambungan seluler.

{ "data": [ { "id": "...", "task_id": "...", "label": "Periksa oli",
              "is_done": false, "position": 0 } ] }

Judul butir ada pada label, bukan title.

{ "data": [ { "id": "...", "task_id": "...",
              "author_membership_id": "...", "body": "Sudah dikerjakan",
              "created_at": "2026-08-25T03:00:00Z" } ] }

Yang dikirim adalah author_membership_id, bukan nama penulis. Nama harus dipetakan sendiri di sisi aplikasi.

{ "body": "Sudah dikerjakan", "mentions": ["membership-id-1"] }  // mentions opsional

Pengumuman dan briefing

Parameter: is_active (boolean), page, per_page.

{ "data": [ { "id": "...", "title": "Libur bersama", "content": "...",
              "target_type": "all", "is_active": true,
              "author_membership_id": "...", "created_at": "..." } ],
  "page": 1, "per_page": 20, "total": 4 }

Slip gaji

{ "data": [ { "id": "...", "run_id": "...", "period": "2026-08",
              "base": 5000000, "allowances": 750000, "deductions": 250000,
              "gross": 5750000, "net": 5500000, "tax": 120000 } ],
  "punya_data_karyawan": true }

Hanya periode penggajian yang sudah difinalisasi yang muncul, terbaru lebih dahulu.

Notifikasi

{ "token": "fcm-token", "platform": "android" }

Pendaftaran bersifat idempoten pada token: mengirim ulang token yang sama akan memperbarui barisnya, bukan menggandakannya. Token terikat pada perusahaan, pemakai, dan data karyawan yang sedang aktif, sehingga token wajib didaftarkan ulang setiap kali berpindah perusahaan dan dicabut saat keluar.

Bekerja tanpa sinyal

Aplikasi ini dipakai di gudang, di jalan, dan di lokasi produksi. Sinyal hilang adalah keadaan biasa, bukan pengecualian.

Bedakan tiga jenis kegagalan, dan perlakukan berbeda:

Untuk permintaan yang diantre, sertakan kunci idempoten agar pengiriman ulang tidak menghasilkan pengajuan berganda. Endpoint baca dapat disimpan dengan kunci yang memuat parameternya, misalnya rentang tanggal, supaya permintaan dengan rentang berbeda tidak saling menimpa.

Masalah yang diketahui

Enam ketidakcocokan antara aplikasi karyawan yang berjalan sekarang dan backend, per 25 Agustus 2026. Nomor 1 dan 2 diuji langsung ke server; sisanya dibaca dari kode.

Berkas OpenAPI

Dua berkas OpenAPI 3.1, keduanya dapat diimpor ke Postman, Insomnia, atau pembangkit kode.

# Contoh membangkitkan klien Dart dari berkas lengkap
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.sikaryawan.com/openapi-lengkap.yaml \
  -g dart-dio -o ./klien

Ganti {host} pada variabel server dengan host perusahaan yang dituju.