Perjalanan Bisnis

Lihat Markdown

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. message sukses menyebut penyetuju Tahap 1, atau Admin HR bila karyawan tidak memiliki penyetuju berjenjang.
  • Sesudah disetujui, pada hari perjalanan: GET /me/config mengirim blok business_trip, presensi tidak memeriksa geofence kantor, jendela jam diperlebar policy.business_trip_window_extra_minutes, dan presensi yang jauh dari koordinat tujuan ditandai is_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.