Kategori klaim, riwayat, detail, pengajuan, dan pembatalan klaim biaya (reimbursement). Seluruh nominal dalam rupiah bilangan bulat tanpa desimal. Konvensi umum ada di README.md.
| Atribut | Nilai |
|---|---|
| Endpoint | GET /reimbursement-categories, GET /reimbursements, POST /reimbursements, GET /reimbursements/{reimbursement}, POST /reimbursements/{reimbursement}/cancel |
| Sumber kode | ReimbursementController, StoreReimbursementRequest, ReimbursementCategoryResource, ReimbursementResource, ReimbursementService |
| Contoh direkam | 2026-11-07 sampai 2026-11-09, direkam ulang 2026-10-23 setelah perubahan alur persetujuan, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, APP_LOCALE=id |
| Data uji | Citra Satu dengan perjalanan bisnis Surabaya 3–6 Nov 2026 (id 1). Kategori bawaan perusahaan baru. Pengaturan bawaan: nominal minimal Rp10.000, klaim paling lama 30 hari setelah tanggal pengeluaran, bukti maks. 2048 KB. Alur persetujuan Citra: Tahap 1 Anton Satu (atasan langsung) → Tahap 2 Budi Satu (Kepala Departemen unit Anton, karena Anton tanpa atasan langsung) |
Enum
ReimbursementCategoryType (category_type)
| Nilai | category_type_label |
|---|---|
TRANSPORT |
Transportasi |
MEAL |
Makan |
ACCOMMODATION |
Penginapan |
MEDICAL |
Kesehatan |
COMMUNICATION |
Komunikasi |
OPERATIONAL |
Operasional |
OTHER |
Lainnya |
ApprovalStatus (status)
| Nilai | status_label |
Dapat dibatalkan karyawan |
|---|---|---|
PENDING |
Menunggu Persetujuan | ya |
APPROVED |
Disetujui | tidak (pencabutan hanya oleh Admin HR) |
REJECTED |
Ditolak | tidak |
CANCELLED |
Dibatalkan | tidak |
Status pembayaran bukan bagian enum: lihat is_paid.
Kategori klaim
GET /reimbursement-categories
Deskripsi: kategori klaim aktif milik perusahaan, urut sort_order lalu nama, tanpa batas jumlah.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.reimbursement-categories.index |
Parameter: tidak ada.
Contoh Request
GET /api/v1/reimbursement-categories HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200)
{
"success": true,
"message": "Kategori klaim berhasil diambil.",
"data": [
{
"id": 1,
"code": "TRP",
"name": "Transportasi",
"category_type": "TRANSPORT",
"category_type_label": "Transportasi",
"max_amount_per_claim": 500000,
"monthly_limit_amount": 2000000,
"requires_receipt": true,
"description": "Ongkos perjalanan bisnis dalam kota dan antar kota."
},
{
"id": 2,
"code": "MKN",
"name": "Makan",
"category_type": "MEAL",
"category_type_label": "Makan",
"max_amount_per_claim": 150000,
"monthly_limit_amount": 1500000,
"requires_receipt": true,
"description": "Konsumsi saat lembur, rapat, dan tugas luar kantor."
},
{
"id": 3,
"code": "INP",
"name": "Penginapan",
"category_type": "ACCOMMODATION",
"category_type_label": "Penginapan",
"max_amount_per_claim": 1000000,
"monthly_limit_amount": null,
"requires_receipt": true,
"description": "Biaya menginap selama perjalanan bisnis."
},
{
"id": 4,
"code": "KSH",
"name": "Kesehatan",
"category_type": "MEDICAL",
"category_type_label": "Kesehatan",
"max_amount_per_claim": null,
"monthly_limit_amount": null,
"requires_receipt": true,
"description": "Pengobatan yang tidak tertanggung jaminan kesehatan."
},
{
"id": 5,
"code": "KOM",
"name": "Komunikasi",
"category_type": "COMMUNICATION",
"category_type_label": "Komunikasi",
"max_amount_per_claim": 300000,
"monthly_limit_amount": 300000,
"requires_receipt": false,
"description": "Pulsa dan paket data untuk keperluan pekerjaan."
},
{
"id": 6,
"code": "OPR",
"name": "Operasional",
"category_type": "OPERATIONAL",
"category_type_label": "Operasional",
"max_amount_per_claim": null,
"monthly_limit_amount": null,
"requires_receipt": true,
"description": "Pembelian keperluan kerja yang dibayar lebih dahulu oleh karyawan."
}
]
}
Field data[]
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | dipakai sebagai reimbursement_category_id |
code |
string | tidak | kode singkat |
name |
string | tidak | nama tampilan |
category_type |
string (enum) | tidak | ReimbursementCategoryType |
category_type_label |
string | tidak | label tampilan |
max_amount_per_claim |
integer | ya | batas rupiah per klaim; null tanpa batas |
monthly_limit_amount |
integer | ya | batas rupiah per bulan kalender expense_date, menjumlahkan klaim PENDING dan APPROVED; null tanpa batas |
requires_receipt |
boolean | tidak | true: receipt wajib |
description |
string | ya | keterangan dari perusahaan |
Objek reimbursement
Sumber: ReimbursementResource.
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | ID klaim |
number |
string | tidak | nomor klaim dari server, mis. RMB-202611-0001; perlakukan sebagai teks utuh |
category |
objek | tidak | id, name, category_type |
business_trip_id |
integer | ya | perjalanan bisnis terkait; null bila tidak dikaitkan atau ID yang dikirim bukan milik karyawan |
expense_date |
string (YYYY-MM-DD) |
tidak | tanggal pengeluaran |
amount |
integer | tidak | nominal yang diajukan, rupiah |
approved_amount |
integer | tidak | nominal yang disetujui, rupiah; 0 selama belum disetujui. Penyetuju boleh menyetujui lebih kecil dari amount |
description |
string | tidak | rincian pengeluaran |
status |
string (enum) | tidak | ApprovalStatus |
status_label |
string | tidak | label tampilan |
is_paid |
boolean | tidak | true bila Admin HR sudah menandai dibayarkan |
paid_at |
string (ISO 8601 UTC) | ya | waktu ditandai dibayarkan |
payment_reference |
string | ya | nomor referensi pembayaran |
submitted_at |
string (ISO 8601 UTC) | tidak | waktu pengajuan |
decided_at |
string (ISO 8601 UTC) | ya | waktu keputusan akhir |
cancelled_at |
string (ISO 8601 UTC) | ya | waktu pembatalan |
decision_notes |
string | ya | catatan keputusan akhir |
approvals |
array objek | tidak | tahap persetujuan, lihat koreksi presensi |
Bukti pengeluaran tidak dikembalikan (tidak ada URL berkas).
Riwayat klaim
GET /reimbursements
Deskripsi: klaim milik karyawan login, 50 terbaru urut expense_date terbaru di atas. Tanpa
pagination dan tanpa filter.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.reimbursements.index |
Contoh Request
GET /api/v1/reimbursements HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-11-09 08:00 WIB)
{
"success": true,
"message": "Riwayat klaim reimbursement berhasil diambil.",
"data": [
{
"id": 1,
"number": "RMB-202611-0001",
"category": {
"id": 1,
"name": "Transportasi",
"category_type": "TRANSPORT"
},
"business_trip_id": 1,
"expense_date": "2026-11-06",
"amount": 185000,
"approved_amount": 175000,
"description": "Taksi bandara Juanda ke hotel dan kembali ke bandara.",
"status": "APPROVED",
"status_label": "Disetujui",
"is_paid": true,
"paid_at": "2026-11-07T03:00:00+00:00",
"payment_reference": "TRF-20261109-0042",
"submitted_at": "2026-11-07T02:00:00+00:00",
"decided_at": "2026-11-07T03:00:00+00:00",
"cancelled_at": null,
"decision_notes": "Disetujui Rp175.000, biaya tol di luar nota tidak diganti.",
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "APPROVED",
"status_label": "Disetujui",
"decided_at": "2026-11-07T03:00:00+00:00",
"decided_by": "Anton Satu",
"notes": "Sesuai nota."
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "APPROVED",
"status_label": "Disetujui",
"decided_at": "2026-11-07T03:00:00+00:00",
"decided_by": "Budi Satu",
"notes": "Disetujui Rp175.000, biaya tol di luar nota tidak diganti."
}
]
},
{
"id": 2,
"number": "RMB-202611-0002",
"category": {
"id": 5,
"name": "Komunikasi",
"category_type": "COMMUNICATION"
},
"business_trip_id": null,
"expense_date": "2026-11-02",
"amount": 150000,
"approved_amount": 0,
"description": "Paket data seluler bulan November untuk koordinasi lapangan.",
"status": "CANCELLED",
"status_label": "Dibatalkan",
"is_paid": false,
"paid_at": null,
"payment_reference": null,
"submitted_at": "2026-11-07T02:02:00+00:00",
"decided_at": null,
"cancelled_at": "2026-11-09T01:00:00+00:00",
"decision_notes": null,
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "CANCELLED",
"status_label": "Dibatalkan",
"decided_at": null,
"decided_by": null,
"notes": null
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "CANCELLED",
"status_label": "Dibatalkan",
"decided_at": null,
"decided_by": null,
"notes": null
}
]
}
]
}
Field data[]: objek reimbursement.
Detail klaim
GET /reimbursements/{reimbursement}
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.reimbursements.show |
Parameter: reimbursement (path, integer).
Contoh Request
GET /api/v1/reimbursements/1 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200). Klaim Rp185.000 disetujui Rp175.000 dan sudah dibayarkan:
{
"success": true,
"message": "Detail klaim reimbursement berhasil diambil.",
"data": {
"id": 1,
"number": "RMB-202611-0001",
"category": {
"id": 1,
"name": "Transportasi",
"category_type": "TRANSPORT"
},
"business_trip_id": 1,
"expense_date": "2026-11-06",
"amount": 185000,
"approved_amount": 175000,
"description": "Taksi bandara Juanda ke hotel dan kembali ke bandara.",
"status": "APPROVED",
"status_label": "Disetujui",
"is_paid": true,
"paid_at": "2026-11-07T03:00:00+00:00",
"payment_reference": "TRF-20261109-0042",
"submitted_at": "2026-11-07T02:00:00+00:00",
"decided_at": "2026-11-07T03:00:00+00:00",
"cancelled_at": null,
"decision_notes": "Disetujui Rp175.000, biaya tol di luar nota tidak diganti.",
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "APPROVED",
"status_label": "Disetujui",
"decided_at": "2026-11-07T03:00:00+00:00",
"decided_by": "Anton Satu",
"notes": "Sesuai nota."
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "APPROVED",
"status_label": "Disetujui",
"decided_at": "2026-11-07T03:00:00+00:00",
"decided_by": "Budi Satu",
"notes": "Disetujui Rp175.000, biaya tol di luar nota tidak diganti."
}
]
}
}
Contoh Response Error
| Kondisi | HTTP | message |
|---|---|---|
| Milik karyawan lain di perusahaan yang sama | 403 | Klaim reimbursement ini bukan milik Anda. |
| ID tidak ada atau milik perusahaan lain | 404 | Sumber daya tidak ditemukan. |
Ajukan klaim
POST /reimbursements
Deskripsi: mengajukan satu klaim biaya. Nomor klaim dibuat server.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.reimbursements.store |
Header: Accept: application/json, Authorization: Bearer <token>, Content-Type: application/json atau multipart/form-data (wajib multipart bila mengirim receipt)
Parameter (StoreReimbursementRequest)
| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
reimbursement_category_id |
body | integer | ya | required, integer, min:1. Kategori tidak ada atau milik perusahaan lain → 422 Kategori klaim tidak ditemukan. |
expense_date |
body | string (YYYY-MM-DD) |
ya | required, date |
amount |
body | integer | ya | required, integer, min:1. Rupiah tanpa titik ribuan dan tanpa desimal (185000, bukan 185.000). Di multipart dikirim sebagai teks angka |
description |
body | string | ya | required, string, min:10, max:1000 |
business_trip_id |
body | integer | tidak | nullable, integer, min:1. ID perjalanan bisnis milik karyawan; ID milik orang lain diabaikan (tersimpan null) tanpa penolakan |
receipt |
body (part berkas) | berkas | bila requires_receipt |
nullable, file, mimes:jpg,jpeg,png,pdf, max:2048 KB (pengaturan perusahaan). Kewajiban per kategori diperiksa aturan bisnis |
Contoh Request (multipart dengan bukti, 2026-11-07 09:00 WIB)
POST /api/v1/reimbursements HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova
--absenova
Content-Disposition: form-data; name="reimbursement_category_id"
1
--absenova
Content-Disposition: form-data; name="expense_date"
2026-11-06
--absenova
Content-Disposition: form-data; name="amount"
185000
--absenova
Content-Disposition: form-data; name="description"
Taksi bandara Juanda ke hotel dan kembali ke bandara.
--absenova
Content-Disposition: form-data; name="business_trip_id"
1
--absenova
Content-Disposition: form-data; name="receipt"; filename="nota-taksi.jpg"
Content-Type: image/jpeg
(berkas JPEG 480×640, 210 KB)
--absenova--
Contoh Response Sukses (201)
{
"success": true,
"message": "Klaim reimbursement terkirim dan menunggu persetujuan Anton Satu.",
"data": {
"id": 1,
"number": "RMB-202611-0001",
"category": {
"id": 1,
"name": "Transportasi",
"category_type": "TRANSPORT"
},
"business_trip_id": 1,
"expense_date": "2026-11-06",
"amount": 185000,
"approved_amount": 0,
"description": "Taksi bandara Juanda ke hotel dan kembali ke bandara.",
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"is_paid": false,
"paid_at": null,
"payment_reference": null,
"submitted_at": "2026-11-07T02:00:00+00:00",
"decided_at": null,
"cancelled_at": null,
"decision_notes": null,
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"decided_at": null,
"decided_by": null,
"notes": null
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"decided_at": null,
"decided_by": null,
"notes": null
}
]
}
}
Tanpa bukti untuk kategori yang tidak mewajibkan bukti (JSON):
POST /api/v1/reimbursements HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json
{
"reimbursement_category_id": 5,
"expense_date": "2026-11-02",
"amount": 150000,
"description": "Paket data seluler bulan November untuk koordinasi lapangan."
}
"message": "Klaim reimbursement terkirim dan menunggu persetujuan Anton Satu.",
"data": {
"id": 2,
"number": "RMB-202611-0002",
"category": {
"id": 5,
"name": "Komunikasi",
"category_type": "COMMUNICATION"
},
"business_trip_id": null,
"expense_date": "2026-11-02",
"amount": 150000,
"approved_amount": 0,
"description": "Paket data seluler bulan November untuk koordinasi lapangan.",
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"is_paid": false,
"paid_at": null,
"payment_reference": null,
"submitted_at": "2026-11-07T02:02:00+00:00",
"decided_at": null,
"cancelled_at": null,
"decision_notes": null,
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"decided_at": null,
"decided_by": null,
"notes": null
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"decided_at": null,
"decided_by": null,
"notes": null
}
]
}
Field data: objek reimbursement.
Penolakan dan urutan pemeriksaan (422, errors.reimbursement kecuali disebut lain)
| # | HTTP | message (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 422 | ✓ Data yang dikirim tidak lolos pemeriksaan. (validasi FormRequest) |
| 2 | 422 | ✓ Kategori klaim tidak ditemukan. (errors.reimbursement_category_id) |
| 3 | 422 | Kategori klaim {nama} sedang tidak aktif. |
| 4 | 422 | ✓ Kategori klaim Makan wajib melampirkan bukti pengeluaran. |
| 5 | 422 | ✓ Nominal klaim minimal Rp10.000, sedangkan klaim ini Rp5.000. |
| 6 | 422 | ✓ Kategori Transportasi dibatasi Rp500.000 per klaim, sedangkan klaim ini Rp650.000. |
| 7 | 422 | ✓ Tanggal pengeluaran tidak boleh melewati hari ini. |
| 8 | 422 | ✓ Klaim hanya dapat diajukan paling lama 30 hari setelah tanggal pengeluaran. |
| 9 | 422 | ✓ Batas bulanan kategori Komunikasi sebesar Rp300.000 terlampaui. Bulan tersebut sudah terpakai Rp150.000. |
Validasi (reimbursement_category_id kosong, amount: "125.000", description: "Taksi", bukti
.docx):
{
"success": false,
"message": "Data yang dikirim tidak lolos pemeriksaan.",
"errors": {
"reimbursement_category_id": [
"Kolom kategori klaim wajib diisi."
],
"amount": [
"Kolom nominal klaim harus berupa bilangan bulat."
],
"description": [
"Kolom rincian pengeluaran minimal 10 karakter."
],
"receipt": [
"Kolom bukti pengeluaran harus berupa berkas berjenis: jpg, jpeg, png, pdf."
]
}
}
Penolakan aturan bisnis:
{
"success": false,
"message": "Batas bulanan kategori Komunikasi sebesar Rp300.000 terlampaui. Bulan tersebut sudah terpakai Rp150.000.",
"errors": {
"reimbursement": [
"Batas bulanan kategori Komunikasi sebesar Rp300.000 terlampaui. Bulan tersebut sudah terpakai Rp150.000."
]
}
}
Catatan
- Idempotency: tidak ada kunci dan tidak ada pemeriksaan klaim ganda. Mengirim ulang membuat klaim
kedua dengan nomor baru; client wajib menonaktifkan tombol kirim selama request berjalan dan tidak
mengulang otomatis setelah timeout tanpa memeriksa
GET /reimbursements. - Penyetuju disusun server saat klaim dibuat dan disimpan pada
approvals; lihat alur persetujuan.messagesukses menyebut penyetuju Tahap 1, atauAdmin HRbila karyawan tidak memiliki penyetuju berjenjang. - Rate limit: tidak ada. FeatureGate / modul:
module_reimbursement(server tidak memblokir). Status langganan: terkunci → 402.
Batalkan klaim
POST /reimbursements/{reimbursement}/cancel
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.reimbursements.cancel |
Parameter: reimbursement (path, integer). Tanpa body.
Status yang dapat dibatalkan: hanya PENDING.
Contoh Request
POST /api/v1/reimbursements/2/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200)
{
"success": true,
"message": "Klaim reimbursement dibatalkan.",
"data": {
"id": 2,
"number": "RMB-202611-0002",
"category": {
"id": 5,
"name": "Komunikasi",
"category_type": "COMMUNICATION"
},
"business_trip_id": null,
"expense_date": "2026-11-02",
"amount": 150000,
"approved_amount": 0,
"description": "Paket data seluler bulan November untuk koordinasi lapangan.",
"status": "CANCELLED",
"status_label": "Dibatalkan",
"is_paid": false,
"paid_at": null,
"payment_reference": null,
"submitted_at": "2026-11-07T02:02:00+00:00",
"decided_at": null,
"cancelled_at": "2026-11-09T01:00:00+00:00",
"decision_notes": null,
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "CANCELLED",
"status_label": "Dibatalkan",
"decided_at": null,
"decided_by": null,
"notes": null
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "CANCELLED",
"status_label": "Dibatalkan",
"decided_at": null,
"decided_by": null,
"notes": null
}
]
}
}
Contoh Response Error (422, errors.reimbursement)
| Kondisi | message |
|---|---|
Sudah CANCELLED |
✓ Klaim yang sudah berstatus Dibatalkan tidak dapat dibatalkan karyawan. |
Sudah APPROVED (dibayar atau belum) |
✓ Klaim yang sudah berstatus Disetujui tidak dapat dibatalkan karyawan. |
| Milik karyawan lain (403) | Klaim reimbursement ini bukan milik Anda. |
{
"success": false,
"message": "Klaim yang sudah berstatus Disetujui tidak dapat dibatalkan karyawan.",
"errors": {
"reimbursement": [
"Klaim yang sudah berstatus Disetujui tidak dapat dibatalkan karyawan."
]
}
}
Catatan: rate limit tidak ada; FeatureGate module_reimbursement; langganan terkunci → 402.