Riwayat, detail, pengajuan, dan pembatalan perjalanan bisnis (dinas luar). Selama perjalanan bisnis
yang disetujui, presensi tetap wajib pada hari kerja, tetapi geofence lokasi kantor diabaikan dan
jendela jam presensi diperlebar. Konvensi umum ada di README.md; dampaknya pada presensi
ada di attendance.md dan blok business_trip di me.md.
| Atribut | Nilai |
|---|---|
| Endpoint | GET /business-trips, POST /business-trips, GET /business-trips/{businessTrip}, POST /business-trips/{businessTrip}/cancel |
| Sumber kode | BusinessTripController, StoreBusinessTripRequest, BusinessTripResource, BusinessTripService, BusinessTripDayCalculator, BusinessTripLookup |
| Contoh direkam | 2026-10-22 dan 2026-11-04, 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, jam tetap Senin–Jumat, Cuti Sakit 2026-10-21 disetujui. Alur persetujuan Citra: Tahap 1 Anton Satu (atasan langsung) → Tahap 2 Budi Satu (Kepala Departemen unit Anton, karena Anton tanpa atasan langsung) |
Enum
ApprovalStatus (status)
| Nilai | status_label |
Dapat dibatalkan karyawan |
|---|---|---|
PENDING |
Menunggu Persetujuan | ya |
APPROVED |
Disetujui | ya, hanya bila start_date masih setelah hari ini (zona perusahaan) |
REJECTED |
Ditolak | tidak |
CANCELLED |
Dibatalkan | tidak |
days[].schedule_status memakai ScheduleStatus dari attendance.md.
Objek business_trip
Sumber: BusinessTripResource. days hanya ada pada detail dan respons pengajuan.
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | ID perjalanan |
letter_number |
string | ya | nomor surat tugas/referensi |
purpose |
string | tidak | maksud perjalanan |
destination_name |
string | tidak | nama lokasi tujuan |
destination_address |
string | ya | alamat tujuan |
destination_latitude |
number | ya | lintang tujuan; dipakai menandai presensi yang jauh dari tujuan |
destination_longitude |
number | ya | bujur tujuan |
start_date |
string (YYYY-MM-DD) |
tidak | tanggal berangkat |
end_date |
string (YYYY-MM-DD) |
tidak | tanggal kembali |
total_days |
integer | tidak | jumlah hari kalender dalam rentang, termasuk hari libur |
status |
string (enum) | tidak | ApprovalStatus |
status_label |
string | tidak | label tampilan |
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 |
days |
array objek | — | hanya detail/pengajuan, lihat tabel di bawah |
approvals |
array objek | tidak | tahap persetujuan, lihat koreksi presensi |
days[]
| Field | Tipe | Keterangan |
|---|---|---|
work_date |
string (YYYY-MM-DD) |
satu tanggal dalam rentang |
is_counted |
boolean | selalu true |
requires_attendance |
boolean | true bila tanggal itu hari kerja; presensi tetap wajib dan tercatat BUSINESS_TRIP |
schedule_status |
string (enum) | ScheduleStatus tanggal itu |
schedule_status_label |
string | label tampilan |
Lampiran tidak dikembalikan.
Riwayat perjalanan bisnis
GET /business-trips
Deskripsi: perjalanan bisnis milik karyawan login, 50 terbaru urut start_date terbaru di atas,
tanpa days. Tanpa pagination dan tanpa filter.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.business-trips.index |
Contoh Request
GET /api/v1/business-trips HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-11-04 08:00 WIB)
{
"success": true,
"message": "Riwayat perjalanan bisnis berhasil diambil.",
"data": [
{
"id": 2,
"letter_number": null,
"purpose": "Mengantar dokumen tender ke kantor pelanggan.",
"destination_name": "PT Karya Mandiri Bekasi",
"destination_address": null,
"destination_latitude": null,
"destination_longitude": null,
"start_date": "2026-11-12",
"end_date": "2026-11-12",
"total_days": 1,
"status": "CANCELLED",
"status_label": "Dibatalkan",
"submitted_at": "2026-10-22T06:05:00+00:00",
"decided_at": null,
"cancelled_at": "2026-10-22T06:05: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
}
]
},
{
"id": 1,
"letter_number": "PB/2026/10/021",
"purpose": "Audit stok gudang mitra dan pelatihan staf penerimaan barang.",
"destination_name": "Gudang Mitra Surabaya",
"destination_address": "Jl. Margomulyo No. 44, Surabaya",
"destination_latitude": -7.241387,
"destination_longitude": 112.678269,
"start_date": "2026-11-03",
"end_date": "2026-11-06",
"total_days": 4,
"status": "APPROVED",
"status_label": "Disetujui",
"submitted_at": "2026-10-22T06:00:00+00:00",
"decided_at": "2026-10-22T06:05:00+00:00",
"cancelled_at": null,
"decision_notes": "Disetujui.",
"approvals": [
{
"sequence": 1,
"stage_name": "Tahap 1",
"approver": "Anton Satu",
"status": "APPROVED",
"status_label": "Disetujui",
"decided_at": "2026-10-22T06:05:00+00:00",
"decided_by": "Anton Satu",
"notes": "Disetujui, sesuai kebutuhan operasional."
},
{
"sequence": 2,
"stage_name": "Tahap 2",
"approver": "Budi Satu",
"status": "APPROVED",
"status_label": "Disetujui",
"decided_at": "2026-10-22T06:05:00+00:00",
"decided_by": "Budi Satu",
"notes": "Disetujui."
}
]
}
]
}
Field data[]: objek business_trip tanpa days.
Detail perjalanan bisnis
GET /business-trips/{businessTrip}
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.business-trips.show |
Parameter: businessTrip (path, integer).
Contoh Request
GET /api/v1/business-trips/1 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-10-22 13:05 WIB)
{
"success": true,
"message": "Detail perjalanan bisnis berhasil diambil.",
"data": {
"id": 1,
"letter_number": "PB/2026/10/021",
"purpose": "Audit stok gudang mitra dan pelatihan staf penerimaan barang.",
"destination_name": "Gudang Mitra Surabaya",
"destination_address": "Jl. Margomulyo No. 44, Surabaya",
"destination_latitude": -7.241387,
"destination_longitude": 112.678269,
"start_date": "2026-11-03",
"end_date": "2026-11-06",
"total_days": 4,
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"submitted_at": "2026-10-22T06:00:00+00:00",
"decided_at": null,
"cancelled_at": null,
"decision_notes": null,
"days": [
{
"work_date": "2026-11-03",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
},
{
"work_date": "2026-11-04",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
},
{
"work_date": "2026-11-05",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
},
{
"work_date": "2026-11-06",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
}
],
"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
}
]
}
}
Contoh Response Error
| Kondisi | HTTP | message |
|---|---|---|
| Milik karyawan lain di perusahaan yang sama | 403 | Perjalanan bisnis ini bukan milik Anda. |
| ID tidak ada atau milik perusahaan lain | 404 | Sumber daya tidak ditemukan. |
Ajukan perjalanan bisnis
POST /business-trips
Deskripsi: mengajukan perjalanan bisnis untuk rentang tanggal. Server menyusun days dari Jadwal
Kerja dan menyusun penyetuju sesuai alur persetujuan.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.business-trips.store |
Header: Accept: application/json, Authorization: Bearer <token>, Content-Type: application/json atau multipart/form-data (wajib multipart bila mengirim attachment)
Parameter (StoreBusinessTripRequest)
| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
start_date |
body | string (YYYY-MM-DD) |
ya | required, date |
end_date |
body | string (YYYY-MM-DD) |
ya | required, date, after_or_equal:start_date |
purpose |
body | string | ya | required, string, min:10, max:1000 |
destination_name |
body | string | ya | required, string, max:255 |
destination_address |
body | string | tidak | nullable, string, max:255 |
destination_latitude |
body | number | bila ada destination_longitude |
nullable, required_with:destination_longitude, numeric, between:-90,90 |
destination_longitude |
body | number | bila ada destination_latitude |
nullable, required_with:destination_latitude, numeric, between:-180,180 |
letter_number |
body | string | tidak | nullable, string, max:100 |
attachment |
body (part berkas) | berkas | tidak | nullable, file, mimes:jpg,jpeg,png,pdf, max:2048 KB (pengaturan perusahaan) |
Contoh Request (multipart dengan surat tugas, 2026-10-22 13:00 WIB)
POST /api/v1/business-trips HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova
--absenova
Content-Disposition: form-data; name="start_date"
2026-11-03
--absenova
Content-Disposition: form-data; name="end_date"
2026-11-06
--absenova
Content-Disposition: form-data; name="purpose"
Audit stok gudang mitra dan pelatihan staf penerimaan barang.
--absenova
Content-Disposition: form-data; name="destination_name"
Gudang Mitra Surabaya
--absenova
Content-Disposition: form-data; name="destination_address"
Jl. Margomulyo No. 44, Surabaya
--absenova
Content-Disposition: form-data; name="destination_latitude"
-7.2413870
--absenova
Content-Disposition: form-data; name="destination_longitude"
112.6782690
--absenova
Content-Disposition: form-data; name="letter_number"
PB/2026/10/021
--absenova
Content-Disposition: form-data; name="attachment"; filename="surat-tugas.pdf"
Content-Type: application/pdf
(berkas PDF, 185 KB)
--absenova--
Contoh Response Sukses (201)
{
"success": true,
"message": "Pengajuan perjalanan bisnis terkirim dan menunggu persetujuan Anton Satu.",
"data": {
"id": 1,
"letter_number": "PB/2026/10/021",
"purpose": "Audit stok gudang mitra dan pelatihan staf penerimaan barang.",
"destination_name": "Gudang Mitra Surabaya",
"destination_address": "Jl. Margomulyo No. 44, Surabaya",
"destination_latitude": -7.241387,
"destination_longitude": 112.678269,
"start_date": "2026-11-03",
"end_date": "2026-11-06",
"total_days": 4,
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"submitted_at": "2026-10-22T06:00:00+00:00",
"decided_at": null,
"cancelled_at": null,
"decision_notes": null,
"days": [
{
"work_date": "2026-11-03",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
},
{
"work_date": "2026-11-04",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
},
{
"work_date": "2026-11-05",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
},
{
"work_date": "2026-11-06",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
}
],
"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 koordinat dan lampiran (JSON):
POST /api/v1/business-trips HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json
{
"start_date": "2026-11-12",
"end_date": "2026-11-12",
"purpose": "Mengantar dokumen tender ke kantor pelanggan.",
"destination_name": "PT Karya Mandiri Bekasi"
}
"message": "Pengajuan perjalanan bisnis terkirim dan menunggu persetujuan Anton Satu.",
"data": {
"id": 2,
"letter_number": null,
"purpose": "Mengantar dokumen tender ke kantor pelanggan.",
"destination_name": "PT Karya Mandiri Bekasi",
"destination_address": null,
"destination_latitude": null,
"destination_longitude": null,
"start_date": "2026-11-12",
"end_date": "2026-11-12",
"total_days": 1,
"status": "PENDING",
"status_label": "Menunggu Persetujuan",
"submitted_at": "2026-10-22T06:05:00+00:00",
"decided_at": null,
"cancelled_at": null,
"decision_notes": null,
"days": [
{
"work_date": "2026-11-12",
"is_counted": true,
"requires_attendance": true,
"schedule_status": "ON_DUTY",
"schedule_status_label": "Masuk kerja"
}
],
"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 business_trip dengan days.
Penolakan dan urutan pemeriksaan (422, errors.business_trip)
| # | HTTP | message (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 422 | ✓ Data yang dikirim tidak lolos pemeriksaan. (validasi FormRequest) |
| 2 | 422 | ✓ Periode rekap untuk tanggal mulai tersebut sudah dikunci sehingga tidak dapat diajukan lagi. |
| 3 | 422 | ✓ Sudah ada perjalanan bisnis lain yang beririsan tanggalnya dan belum dibatalkan. |
| 4 | 422 | ✓ Tanggal tersebut beririsan dengan pengajuan cuti yang masih berlaku. |
| 5 | 422 | Jadwal kerja pada {tanggal} belum lengkap: {status}. Hubungi Admin HR. |
Tidak ada batas tanggal mundur maupun minimal hari sebelum berangkat.
Validasi (end_date sebelum start_date, purpose: "Audit", tanpa destination_name, hanya
destination_latitude):
{
"success": false,
"message": "Data yang dikirim tidak lolos pemeriksaan.",
"errors": {
"end_date": [
"Kolom tanggal selesai harus berisi tanggal tanggal mulai atau setelahnya."
],
"purpose": [
"Kolom maksud perjalanan minimal 10 karakter."
],
"destination_name": [
"Kolom nama lokasi tujuan wajib diisi."
],
"destination_longitude": [
"Kolom bujur tujuan wajib diisi bila terdapat lintang tujuan."
]
}
}
Catatan
- Idempotency: tidak ada kunci. Pengajuan kedua untuk tanggal yang beririsan ditolak (nomor 3).
- Penyetuju disusun server saat pengajuan dibuat dan disimpan pada
approvals; lihat alur persetujuan.messagesukses menyebut penyetuju Tahap 1, atauAdmin HRbila karyawan tidak memiliki penyetuju berjenjang. - Sesudah disetujui, pada hari perjalanan:
GET /me/configmengirim blokbusiness_trip, presensi tidak memeriksa geofence kantor, jendela jam diperlebarpolicy.business_trip_window_extra_minutes, dan presensi yang jauh dari koordinat tujuan ditandaiis_suspect. - Klaim biaya perjalanan diajukan lewat reimbursements.md dengan
business_trip_id. - Rate limit: tidak ada. FeatureGate / modul:
module_business_trip(server tidak memblokir). Status langganan: terkunci → 402.
Batalkan perjalanan bisnis
POST /business-trips/{businessTrip}/cancel
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.business-trips.cancel |
Parameter: businessTrip (path, integer). Tanpa body.
Status yang dapat dibatalkan: PENDING kapan saja; APPROVED hanya bila start_date masih
setelah hari ini. REJECTED dan CANCELLED tidak.
Contoh Request
POST /api/v1/business-trips/2/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200). Respons pembatalan tidak memuat days:
{
"success": true,
"message": "Pengajuan perjalanan bisnis dibatalkan.",
"data": {
"id": 2,
"letter_number": null,
"purpose": "Mengantar dokumen tender ke kantor pelanggan.",
"destination_name": "PT Karya Mandiri Bekasi",
"destination_address": null,
"destination_latitude": null,
"destination_longitude": null,
"start_date": "2026-11-12",
"end_date": "2026-11-12",
"total_days": 1,
"status": "CANCELLED",
"status_label": "Dibatalkan",
"submitted_at": "2026-10-22T06:05:00+00:00",
"decided_at": null,
"cancelled_at": "2026-10-22T06:05: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.business_trip)
| Kondisi | message |
|---|---|
Sudah CANCELLED/REJECTED |
✓ Pengajuan perjalanan bisnis ini sudah berstatus Dibatalkan. |
APPROVED dan sudah berjalan (2026-11-04 08:00 WIB, perjalanan 3–6 Nov) |
✓ Perjalanan bisnis yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Ajukan koreksi presensi atau hubungi Admin HR. |
| Milik karyawan lain (403) | Perjalanan bisnis ini bukan milik Anda. |
{
"success": false,
"message": "Perjalanan bisnis yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Ajukan koreksi presensi atau hubungi Admin HR.",
"errors": {
"business_trip": [
"Perjalanan bisnis yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Ajukan koreksi presensi atau hubungi Admin HR."
]
}
}
Catatan: rate limit tidak ada; FeatureGate module_business_trip; langganan terkunci → 402.