{"openapi":"3.0.3","info":{"title":"API Dokumentasi Modul Perhitungan Tunjangan Transport","description":"Dokumentasi RESTful API untuk Sistem Perhitungan Tunjangan Transport Pegawai - JMC IT Consultant. Menjelaskan endpoint, request payload, response schema, dan otentikasi JWT.","version":"1.0.0","contact":{"name":"Tim Pengembang JMC IT Consultant","email":"support@jmc.co.id"}},"servers":[{"url":"http://localhost:3000/api","description":"Local Development Server"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Masukkan token JWT autentikasi (diperoleh setelah verifikasi OTP login)."}},"schemas":{"SettingTunjangan":{"type":"object","properties":{"id":{"type":"integer","example":1},"tarif_per_km":{"type":"number","format":"float","example":5000},"berlaku_mulai":{"type":"string","format":"date","example":"2026-01-01"},"min_kilometer":{"type":"integer","example":5},"max_kilometer":{"type":"integer","example":25}}},"SettingTunjanganRequest":{"type":"object","required":["tarif_per_km","berlaku_mulai","min_kilometer","max_kilometer"],"properties":{"tarif_per_km":{"type":"number","description":"Tarif base fare rupiah per kilometer","example":5000},"berlaku_mulai":{"type":"string","format":"date","description":"Tanggal mulai berlaku pengaturan tarif","example":"2026-01-01"},"min_kilometer":{"type":"integer","description":"Batas minimum jarak kilometer (jarak <= min tidak dihitung)","example":5},"max_kilometer":{"type":"integer","description":"Batas maksimum jarak kilometer yang ditanggung (capped)","example":25}}},"TunjanganPeriode":{"type":"object","properties":{"id":{"type":"integer","example":7},"bulan":{"type":"integer","example":7},"nama_bulan":{"type":"string","example":"Juli"},"tahun":{"type":"integer","example":2026},"total_penerima":{"type":"integer","example":3},"total_tunjangan":{"type":"number","format":"float","example":5630000},"is_calculated":{"type":"integer","example":1},"calculated_at":{"type":"string","format":"date-time","example":"2026-07-31 23:59:59"}}},"TunjanganDetailItem":{"type":"object","properties":{"id":{"type":"integer","example":1},"periode_id":{"type":"integer","example":7},"pegawai_id":{"type":"integer","example":1},"nip":{"type":"string","example":"198801152015031001"},"nama_penerima":{"type":"string","example":"Ahmad Hermawan"},"status_kontrak":{"type":"string","example":"PKWTT"},"jarak_km_asli":{"type":"integer","example":12},"jarak_km":{"type":"integer","example":12},"jumlah_hari":{"type":"integer","example":22},"base_fare":{"type":"number","example":5000},"nominal":{"type":"number","example":1320000},"status_eligible":{"type":"integer","example":1},"keterangan":{"type":"string","example":"Pegawai Tetap (PKWTT), Jarak 12km (5-25km), Masuk 22 hari (>=19 hari)"}}},"CalculateRequest":{"type":"object","required":["bulan","tahun"],"properties":{"bulan":{"type":"integer","description":"Bulan perhitungan (1-12)","example":7},"tahun":{"type":"integer","description":"Tahun perhitungan (e.g. 2026)","example":2026}}},"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Operasi berhasil"}}}}},"security":[{"BearerAuth":[]}],"paths":{"/tunjangan/setting":{"get":{"summary":"Mendapatkan Konfigurasi Setting Tunjangan Transport","description":"Mengambil konfigurasi tarif per km, tanggal berlaku, batas minimum jarak, dan batas maksimum jarak kilometer.","tags":["Setting Tunjangan Transport"],"responses":{"200":{"description":"Berhasil mendapatkan konfigurasi","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/SettingTunjangan"}}}}}},"401":{"description":"Unauthorized: Token tidak valid atau sesi berakhir"}}},"post":{"summary":"Menyimpan / Memperbarui Setting Tunjangan Transport","description":"Admin HRD memperbarui tarif dasar per km, batas jarak min-max, dan tanggal berlaku.","tags":["Setting Tunjangan Transport"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingTunjanganRequest"}}}},"responses":{"200":{"description":"Pengaturan berhasil disimpan","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Setting tunjangan transport berhasil disimpan"},"data":{"$ref":"#/components/schemas/SettingTunjangan"}}}}}},"400":{"description":"Validasi gagal (tarif <= 0 atau batas jarak tidak valid)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden: Role tidak memiliki hak akses CRUD setting tunjangan"}}}},"/tunjangan/transport":{"get":{"summary":"Mendapatkan Daftar Rekap Bulan Tunjangan Transport","description":"Mengambil ringkasan tunjangan transport per bulan untuk tahun tertentu dengan informasi total penerima dan total nominal.","tags":["Modul Tunjangan Transport"],"parameters":[{"name":"tahun","in":"query","required":false,"schema":{"type":"integer","default":2026},"description":"Tahun periode (contoh: 2026)"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Pencarian nama bulan"}],"responses":{"200":{"description":"Berhasil mendapatkan daftar bulan","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/TunjanganPeriode"}}}}}}},"401":{"description":"Unauthorized"}}}},"/tunjangan/transport/{id}":{"get":{"summary":"Mendapatkan Detail Penerima Tunjangan per Bulan","description":"Mengambil rincian perhitungan setiap pegawai pada bulan terpilih (Nama, Jarak KM, Jumlah Hari Masuk, Nominal).","tags":["Modul Tunjangan Transport"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"ID Periode atau Angka Bulan (1-12)"},{"name":"tahun","in":"query","required":false,"schema":{"type":"integer","default":2026},"description":"Tahun periode"}],"responses":{"200":{"description":"Berhasil mendapatkan detail tunjangan","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"periode":{"$ref":"#/components/schemas/TunjanganPeriode"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TunjanganDetailItem"}}}}}}},"401":{"description":"Unauthorized"}}}},"/tunjangan/transport/calculate":{"post":{"summary":"Mengeksekusi Kalkulasi Tunjangan Transport","description":"Menjalankan kalkulasi tunjangan transport otomatis berdasarkan seluruh aturan: (1) Hanya Pegawai Tetap PKWTT, (2) Minimal 19 hari kerja, (3) Jarak > 5 km dan <= 25 km capped, (4) Rumus = base_fare * round(km) * hari_kerja.","tags":["Modul Tunjangan Transport"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"}}}},"responses":{"200":{"description":"Kalkulasi berhasil dieksekusi","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Perhitungan tunjangan transport Juli 2026 berhasil dieksekusi."},"summary":{"type":"object","properties":{"totalRecipients":{"type":"integer","example":3},"totalNominal":{"type":"number","example":5630000},"baseFare":{"type":"number","example":5000}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/TunjanganDetailItem"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}}