Reimbursement

Lihat Markdown

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. message sukses menyebut penyetuju Tahap 1, atau Admin HR bila 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.