Kunjungan Klien

Lihat Markdown

Daftar klien, check-in dan check-out kunjungan lapangan (tim sales, teknisi, kurir), pembatalan, dan riwayat. Kunjungan bukan presensi kerja: tidak memengaruhi rekap presensi, tetapi check-out yang berhasil menambah aktivitas otomatis ke timesheet. Konvensi umum ada di README.md.

Atribut Nilai
Endpoint GET /clients, GET /client-visits, GET /client-visits/open, POST /client-visits/check-in, GET /client-visits/{clientVisit}, POST /client-visits/{clientVisit}/check-out, POST /client-visits/{clientVisit}/cancel
Sumber kode ClientVisitController, StoreClientVisitRequest, StoreClientVisitCheckOutRequest, ClientResource, ClientVisitResource, ClientVisitService, TimesheetService
Contoh direkam 2026-11-10, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, APP_LOCALE=id
Data uji Citra Satu. Klien PT Sinar Jaya Abadi (aktif, radius 300 m, pemilik akun Citra), CV Maju Bersama (calon pelanggan, radius kosong), PT Lama Tidak Aktif. Pengaturan bawaan: foto wajib maks. 500 KB, radius bawaan 300 m, durasi minimal 5 menit, kunjungan terbuka maks. 12 jam, toleransi kirim 24 jam

Enum

ClientVisitPurpose (purpose)

Nilai purpose_label
SALES_CALL Kunjungan Penjualan
PRESENTATION Presentasi Produk
NEGOTIATION Negosiasi
DELIVERY Pengiriman Barang
MAINTENANCE Perawatan & Perbaikan
COLLECTION Penagihan
SURVEY Survei Lokasi
OTHER Lainnya

ClientVisitStatus (status)

Nilai status_label Dapat check-out / dibatalkan
ONGOING Sedang Berlangsung ya
COMPLETED Selesai tidak
CANCELLED Dibatalkan tidak

ClientVisitOutcome (outcome)

Nilai outcome_label
SUCCESSFUL Berhasil
FOLLOW_UP Perlu Tindak Lanjut
POSTPONED Ditunda Klien
FAILED Tidak Berhasil

ClientStatus (clients[].status)

Nilai status_label Muncul di GET /clients
PROSPECT Calon Pelanggan ya
ACTIVE Pelanggan Aktif ya
INACTIVE Tidak Aktif tidak; check-in dengan client_id klien ini ditolak

Daftar klien

GET /clients

Deskripsi: klien perusahaan yang dapat dikunjungi (PROSPECT dan ACTIVE), urut nama, maksimal 200. Tanpa pagination.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.clients.index

Parameter

Nama Lokasi Tipe Wajib Aturan
search query string tidak mencocokkan sebagian nama atau kode klien. Tanpa validasi

Contoh Request

GET /api/v1/clients?search=sinar HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200, tanpa search)

{
  "success": true,
  "message": "Daftar klien berhasil diambil.",
  "data": [
    {
      "id": 2,
      "code": "CL-0002",
      "name": "CV Maju Bersama",
      "status": "PROSPECT",
      "status_label": "Calon Pelanggan",
      "industry": "Ritel",
      "contact_person": "Lina Kartika",
      "contact_phone": "0218880456",
      "address": "Jl. Pemuda No. 102",
      "city": "Jakarta Timur",
      "latitude": -6.193441,
      "longitude": 106.8907722,
      "radius_meters": null,
      "is_account_owner": false
    },
    {
      "id": 1,
      "code": "CL-0001",
      "name": "PT Sinar Jaya Abadi",
      "status": "ACTIVE",
      "status_label": "Pelanggan Aktif",
      "industry": "Distribusi Bahan Bangunan",
      "contact_person": "Hendra Wijaya",
      "contact_phone": "0215550123",
      "address": "Jl. Gunung Sahari Raya No. 21",
      "city": "Jakarta Pusat",
      "latitude": -6.1612301,
      "longitude": 106.8394562,
      "radius_meters": 300,
      "is_account_owner": true
    }
  ]
}

Field data[]

Field Tipe Null Keterangan
id integer tidak dipakai sebagai client_id saat check-in
code string ya kode klien
name string tidak nama klien
status string (enum) tidak ClientStatus
status_label string tidak label tampilan
industry string ya bidang usaha
contact_person string ya nama kontak
contact_phone string ya telepon kontak
address string ya alamat
city string ya kota
latitude number ya lintang lokasi klien; null bila belum dipetakan
longitude number ya bujur lokasi klien
radius_meters integer ya radius klien; null → server memakai policy.client_visit.radius_meters
is_account_owner boolean tidak true bila karyawan login pemegang akun klien ini

Objek client_visit

Sumber: ClientVisitResource. Dipakai seluruh endpoint kunjungan.

Field Tipe Null Keterangan
id integer tidak ID kunjungan, dipakai untuk check-out dan pembatalan
uuid string tidak UUID dari client saat check-in
work_date string (YYYY-MM-DD) tidak tanggal kerja (tanggal mulai shift, ikut lembur lintas tengah malam)
client_id integer ya klien terdaftar; null untuk klien teks bebas
client_name string tidak nama klien terdaftar atau teks bebas
purpose string (enum) tidak ClientVisitPurpose
purpose_label string tidak label tampilan
status string (enum) tidak ClientVisitStatus
status_label string tidak label tampilan
checked_in_at string (ISO 8601 UTC) tidak captured_at check-in
checked_out_at string (ISO 8601 UTC) ya captured_at check-out
duration_minutes integer ya menit kunjungan; null selama berlangsung, 0 bila dibatalkan
distance_meters integer ya jarak check-in ke koordinat klien; null bila klien tanpa koordinat atau teks bebas
is_within_radius boolean tidak true bila distance_meters - accuracy_meters <= radius; selalu true bila jarak tidak diukur
outcome string (enum) ya ClientVisitOutcome, diisi saat check-out
outcome_label string ya label tampilan
notes string ya catatan check-in; diganti catatan check-out bila dikirim
follow_up_date string (YYYY-MM-DD) ya tanggal tindak lanjut
is_suspect boolean tidak ditandai untuk ditinjau Admin HR, lihat tabel penanda di check-in
cancel_reason string ya alasan pembatalan

Foto kunjungan dan koordinat check-out tidak dikembalikan.


Riwayat kunjungan

GET /client-visits

Deskripsi: kunjungan milik karyawan login, 50 terbaru urut checked_in_at terbaru di atas.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.client-visits.index

Contoh Request

GET /api/v1/client-visits HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200, 2026-11-10 16:00 WIB)

{
  "success": true,
  "message": "Riwayat kunjungan klien berhasil diambil.",
  "data": [
    {
      "id": 3,
      "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30003",
      "work_date": "2026-11-10",
      "client_id": null,
      "client_name": "Toko Bangunan Sentosa",
      "purpose": "SURVEY",
      "purpose_label": "Survei Lokasi",
      "status": "ONGOING",
      "status_label": "Sedang Berlangsung",
      "checked_in_at": "2026-11-10T08:20:00+00:00",
      "checked_out_at": null,
      "duration_minutes": 0,
      "distance_meters": null,
      "is_within_radius": true,
      "outcome": null,
      "outcome_label": null,
      "notes": "Calon pelanggan baru, survei kebutuhan.",
      "follow_up_date": null,
      "is_suspect": true,
      "cancel_reason": null
    },
    {
      "id": 2,
      "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30002",
      "work_date": "2026-11-10",
      "client_id": 1,
      "client_name": "PT Sinar Jaya Abadi",
      "purpose": "DELIVERY",
      "purpose_label": "Pengiriman Barang",
      "status": "CANCELLED",
      "status_label": "Dibatalkan",
      "checked_in_at": "2026-11-10T07:40:05+00:00",
      "checked_out_at": null,
      "duration_minutes": 0,
      "distance_meters": 3224,
      "is_within_radius": false,
      "outcome": null,
      "outcome_label": null,
      "notes": null,
      "follow_up_date": null,
      "is_suspect": true,
      "cancel_reason": "Salah pilih klien, kunjungan sebenarnya ke gudang sendiri."
    },
    {
      "id": 1,
      "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
      "work_date": "2026-11-10",
      "client_id": 1,
      "client_name": "PT Sinar Jaya Abadi",
      "purpose": "SALES_CALL",
      "purpose_label": "Kunjungan Penjualan",
      "status": "COMPLETED",
      "status_label": "Selesai",
      "checked_in_at": "2026-11-10T06:02:15+00:00",
      "checked_out_at": "2026-11-10T07:12:25+00:00",
      "duration_minutes": 70,
      "distance_meters": 10,
      "is_within_radius": true,
      "outcome": "FOLLOW_UP",
      "outcome_label": "Perlu Tindak Lanjut",
      "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
      "follow_up_date": "2026-11-13",
      "is_suspect": false,
      "cancel_reason": null
    }
  ]
}

Kunjungan yang masih terbuka

GET /client-visits/open

Deskripsi: kunjungan ONGOING terbaru milik karyawan login, atau null. Panggil saat aplikasi dibuka untuk melanjutkan layar check-out. Ringkasannya juga ada di GET /me/config → open_client_visit.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.client-visits.open

Contoh Request

GET /api/v1/client-visits/open HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200, ada kunjungan terbuka)

{
  "success": true,
  "message": "Masih ada kunjungan yang belum di-check-out.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "ONGOING",
    "status_label": "Sedang Berlangsung",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": null,
    "duration_minutes": 0,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": null,
    "outcome_label": null,
    "notes": "Presentasi harga semen untuk proyek ruko.",
    "follow_up_date": null,
    "is_suspect": false,
    "cancel_reason": null
  }
}

Tidak ada kunjungan terbuka (200, data null):

{
  "success": true,
  "message": "Tidak ada kunjungan yang sedang berlangsung.",
  "data": {}
}

Check-in kunjungan

POST /client-visits/check-in

Deskripsi: memulai kunjungan dengan koordinat mentah, foto, dan klien terdaftar atau nama klien teks bebas. Server mengukur jarak ke klien dan menandai kecurigaan; check-in di luar radius tetap diterima.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive, throttle:attendance
Route name api.v1.client-visits.check-in

Header: Accept: application/json, Authorization: Bearer <token>, Content-Type: multipart/form-data

Parameter (StoreClientVisitRequest)

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
uuid body (part teks) string (UUID) ya required, uuid. Dibuat client sekali per kunjungan; kunci idempotency
client_id body (part teks) integer salah satu dengan client_name nullable, integer, min:1. Dari GET /clients
client_name body (part teks) string bila tanpa client_id required_without:client_id, nullable, string, max:150. Diabaikan bila client_id dikirim
purpose body (part teks) string (enum) ya required, salah satu ClientVisitPurpose
latitude body (part teks) number ya required, numeric, between:-90,90
longitude body (part teks) number ya required, numeric, between:-180,180
accuracy_meters body (part teks) number ya required, numeric, min:0, max:10000
captured_at body (part teks) string (ISO 8601) ya required, date. Wajib dengan offset (2026-11-10T13:02:15+07:00)
device_time body (part teks) string (ISO 8601) tidak nullable, date. Jam perangkat saat kirim
mock_location body (part teks) boolean tidak nullable, boolean. Kirim 1/0; true/false ditolak di multipart
notes body (part teks) string tidak nullable, string, max:1000
photo body (part berkas) berkas gambar bila policy.client_visit.photo_required required/nullable mengikuti pengaturan, image, max:{policy.client_visit.photo_max_kilobytes} KB (bawaan 500)

Contoh Request (2026-11-10 13:02 WIB)

POST /api/v1/client-visits/check-in HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova

--absenova
Content-Disposition: form-data; name="uuid"

7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001
--absenova
Content-Disposition: form-data; name="latitude"

-6.161312
--absenova
Content-Disposition: form-data; name="longitude"

106.8395011
--absenova
Content-Disposition: form-data; name="accuracy_meters"

8
--absenova
Content-Disposition: form-data; name="captured_at"

2026-11-10T13:02:15+07:00
--absenova
Content-Disposition: form-data; name="device_time"

2026-11-10T13:02:15+07:00
--absenova
Content-Disposition: form-data; name="mock_location"

0
--absenova
Content-Disposition: form-data; name="client_id"

1
--absenova
Content-Disposition: form-data; name="purpose"

SALES_CALL
--absenova
Content-Disposition: form-data; name="notes"

Presentasi harga semen untuk proyek ruko.
--absenova
Content-Disposition: form-data; name="photo"; filename="kunjungan.jpg"
Content-Type: image/jpeg

(berkas JPEG 480×640, 260 KB)
--absenova--

Contoh Response Sukses (201)

{
  "success": true,
  "message": "Kunjungan dimulai. Jangan lupa check-out setelah selesai.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "ONGOING",
    "status_label": "Sedang Berlangsung",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": null,
    "duration_minutes": null,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": null,
    "outcome_label": null,
    "notes": "Presentasi harga semen untuk proyek ruko.",
    "follow_up_date": null,
    "is_suspect": false,
    "cancel_reason": null
  }
}

Kirim ulang uuid yang sama (200, data asli, tanpa data ganda):

"message": "Kunjungan ini sudah pernah terkirim sebelumnya.",
"data": {
  "id": 1,
  "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
  "work_date": "2026-11-10",
  "client_id": 1,
  "client_name": "PT Sinar Jaya Abadi",
  "purpose": "SALES_CALL",
  "purpose_label": "Kunjungan Penjualan",
  "status": "ONGOING",
  "status_label": "Sedang Berlangsung",
  "checked_in_at": "2026-11-10T06:02:15+00:00",
  "checked_out_at": null,
  "duration_minutes": 0,
  "distance_meters": 10,
  "is_within_radius": true,
  "outcome": null,
  "outcome_label": null,
  "notes": "Presentasi harga semen untuk proyek ruko.",
  "follow_up_date": null,
  "is_suspect": false,
  "cancel_reason": null
}

Di luar radius klien 300 m (201, ditandai is_suspect):

"message": "Kunjungan dimulai, tetapi lokasi Anda jauh dari koordinat klien sehingga ditandai untuk ditinjau Admin HR.",
"data": {
  "id": 2,
  "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30002",
  "work_date": "2026-11-10",
  "client_id": 1,
  "client_name": "PT Sinar Jaya Abadi",
  "purpose": "DELIVERY",
  "purpose_label": "Pengiriman Barang",
  "status": "ONGOING",
  "status_label": "Sedang Berlangsung",
  "checked_in_at": "2026-11-10T07:40:05+00:00",
  "checked_out_at": null,
  "duration_minutes": null,
  "distance_meters": 3224,
  "is_within_radius": false,
  "outcome": null,
  "outcome_label": null,
  "notes": null,
  "follow_up_date": null,
  "is_suspect": true,
  "cancel_reason": null
}

Klien teks bebas dengan mock_location: 1 (201, jarak tidak diukur, ditandai is_suspect):

"message": "Kunjungan dimulai. Jangan lupa check-out setelah selesai.",
"data": {
  "id": 3,
  "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30003",
  "work_date": "2026-11-10",
  "client_id": null,
  "client_name": "Toko Bangunan Sentosa",
  "purpose": "SURVEY",
  "purpose_label": "Survei Lokasi",
  "status": "ONGOING",
  "status_label": "Sedang Berlangsung",
  "checked_in_at": "2026-11-10T08:20:00+00:00",
  "checked_out_at": null,
  "duration_minutes": null,
  "distance_meters": null,
  "is_within_radius": true,
  "outcome": null,
  "outcome_label": null,
  "notes": "Calon pelanggan baru, survei kebutuhan.",
  "follow_up_date": null,
  "is_suspect": true,
  "cancel_reason": null
}

Penanda is_suspect (kunjungan tetap diterima)

Pemicu Kondisi
Lokasi palsu mock_location = 1
Akurasi nol accuracy_meters = 0
Akurasi rendah accuracy_meters melebihi policy.gps_accuracy_threshold_meters
Jauh dari klien jarak diukur dan di luar radius klien
Jam perangkat menyimpang selisih device_time dengan jam server lebih dari 10 menit

Penolakan dan urutan pemeriksaan (422, errors.client_visit)

# HTTP message (direkam bila bertanda ✓)
1 429 Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi. (kuota bersama presensi)
2 422 ✓ Data yang dikirim tidak lolos pemeriksaan. (validasi FormRequest, termasuk foto wajib)
3 200 ✓ uuid sudah pernah diterima: bukan penolakan, data asli dikembalikan
4 422 ✓ Klien yang dipilih tidak ditemukan atau sedang tidak aktif.
5 422 Nama klien wajib diisi bila kunjungan tidak dikaitkan ke klien terdaftar.
6 422 ✓ Waktu yang dikirim berada di masa depan menurut jam server. (captured_at lebih dari 10 menit di depan jam server)
7 422 ✓ Kunjungan hanya dapat dikirim paling lama 24 jam setelah waktu perekaman. Waktu perekaman: 2026-11-09 09:00 WIB. (angka mengikuti policy.offline_sync_tolerance_hours)
8 422 ✓ Masih ada kunjungan yang belum di-check-out. Selesaikan kunjungan tersebut lebih dahulu.
9 422 Foto wajib disertakan pada setiap check-in kunjungan klien. (praktis tertangkap validasi nomor 2)

Validasi (uuid tidak sah, tanpa client_id/client_name, purpose: "JUALAN", mock_location: "true", tanpa foto):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "uuid": [
      "Kolom pengenal kunjungan harus berupa UUID yang sah."
    ],
    "client_name": [
      "Kolom nama klien wajib diisi bila tidak terdapat klien terdaftar."
    ],
    "purpose": [
      "Pilihan pada kolom tujuan kunjungan tidak sah."
    ],
    "longitude": [
      "Kolom bujur wajib diisi."
    ],
    "accuracy_meters": [
      "Kolom akurasi GPS wajib diisi."
    ],
    "mock_location": [
      "Kolom mock location harus bernilai benar atau salah."
    ],
    "photo": [
      "Kolom foto kunjungan wajib diisi."
    ]
  }
}

Catatan

  • Idempotency: uuid per kunjungan. Simpan bersama antrean offline dan pakai ulang saat kirim ulang; jawaban 200 berisi data asli.
  • Satu kunjungan terbuka. Check-in baru ditolak selama masih ada ONGOING; selesaikan dengan check-out atau batalkan. Kunjungan yang terbuka lebih dari policy.client_visit.max_open_hours tidak dapat di-check-out lagi (ditolak ...melewati batas wajar...); batalkan atau minta Admin HR menutupnya.
  • Waktu: checked_in_at = captured_at. Kirim dengan offset; sebelum 2026-10-22 server menyimpan jam lokal sebagai UTC (lihat CHANGELOG).
  • Rate limit: attendance, 12 per menit per karyawan, kuota bersama dengan POST /attendance/check-in dan POST /attendance/check-out. Respons membawa X-RateLimit-Limit dan X-RateLimit-Remaining; 429 membawa Retry-After dan X-RateLimit-Reset.
  • FeatureGate / modul: module_client_visit (server tidak memblokir). Status langganan: terkunci → 402.

Check-out kunjungan

POST /client-visits/{clientVisit}/check-out

Deskripsi: menyelesaikan kunjungan ONGOING, mencatat hasil, dan (bila diizinkan perusahaan) membuat aktivitas timesheet CLIENT_VISIT otomatis.

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.client-visits.check-out

Header: Accept: application/json, Authorization: Bearer <token>, Content-Type: application/json

Parameter (StoreClientVisitCheckOutRequest)

Nama Lokasi Tipe Wajib Aturan validasi (FormRequest)
clientVisit path integer ya ID kunjungan
outcome body string (enum) ya required, salah satu ClientVisitOutcome
captured_at body string (ISO 8601) ya required, date. Wajib dengan offset
latitude body number tidak nullable, numeric, between:-90,90
longitude body number tidak nullable, numeric, between:-180,180
accuracy_meters body number tidak nullable, numeric, min:0, max:10000
notes body string tidak nullable, string, max:1000
follow_up_date body string (YYYY-MM-DD) tidak nullable, date, after_or_equal:today

Contoh Request (2026-11-10 14:12 WIB)

POST /api/v1/client-visits/1/check-out HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "outcome": "FOLLOW_UP",
  "captured_at": "2026-11-10T14:12:25+07:00",
  "latitude": -6.1612877,
  "longitude": 106.839498,
  "accuracy_meters": 7.5,
  "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
  "follow_up_date": "2026-11-13"
}

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Kunjungan selesai dan durasinya tercatat.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "COMPLETED",
    "status_label": "Selesai",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": "2026-11-10T07:12:25+00:00",
    "duration_minutes": 70,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": "FOLLOW_UP",
    "outcome_label": "Perlu Tindak Lanjut",
    "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
    "follow_up_date": "2026-11-13",
    "is_suspect": false,
    "cancel_reason": null
  }
}

Bila aktivitas timesheet tidak dapat dibuat (mis. timesheet tanggal itu sudah dikirim), check-out tetap berhasil dengan message Kunjungan selesai dan durasinya tercatat, tetapi aktivitas timesheet tidak dibuat otomatis karena {alasan}.

Penolakan (422, errors.client_visit)

Kondisi message (direkam bila bertanda ✓)
Validasi ✓ Data yang dikirim tidak lolos pemeriksaan.
Bukan ONGOING ✓ Kunjungan ini sudah berstatus Selesai.
captured_at di masa depan / lewat toleransi sama dengan check-in nomor 6–7
captured_at tidak lebih akhir dari check-in Waktu check-out harus lebih besar daripada waktu check-in.
Durasi kurang dari policy.client_visit.minimum_duration_minutes ✓ Durasi kunjungan minimal 5 menit, sedangkan kunjungan ini baru 2 menit.
Durasi lebih dari max_open_hours Durasi kunjungan melewati batas wajar. Hubungi Admin HR untuk menutup kunjungan ini.
Milik karyawan lain (403) Kunjungan ini bukan milik Anda.

Validasi (outcome: "SELESAI", captured_at: "nanti", follow_up_date sebelum hari ini):

{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "outcome": [
      "Pilihan pada kolom hasil kunjungan tidak sah."
    ],
    "captured_at": [
      "Kolom waktu perekaman bukan tanggal yang sah."
    ],
    "follow_up_date": [
      "Kolom tanggal tindak lanjut harus berisi tanggal today atau setelahnya."
    ]
  }
}

Catatan

  • Idempotency: tidak ada kunci. Check-out kedua dijawab 422 Kunjungan ini sudah berstatus Selesai.; anggap sukses bila status lokal sudah COMPLETED.
  • Rate limit: tidak ada (check-out tidak memakai limiter attendance).
  • FeatureGate: module_client_visit. Status langganan: terkunci → 402.

Batalkan kunjungan

POST /client-visits/{clientVisit}/cancel

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.client-visits.cancel

Parameter

Nama Lokasi Tipe Wajib Aturan
clientVisit path integer ya ID kunjungan
reason body string tidak alasan pembatalan. Tanpa FormRequest: tidak divalidasi; batasi di client maksimal 255 karakter

Status yang dapat dibatalkan: hanya ONGOING.

Contoh Request

POST /api/v1/client-visits/2/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "Salah pilih klien, kunjungan sebenarnya ke gudang sendiri."
}

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Kunjungan dibatalkan.",
  "data": {
    "id": 2,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30002",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "DELIVERY",
    "purpose_label": "Pengiriman Barang",
    "status": "CANCELLED",
    "status_label": "Dibatalkan",
    "checked_in_at": "2026-11-10T07:40:05+00:00",
    "checked_out_at": null,
    "duration_minutes": 0,
    "distance_meters": 3224,
    "is_within_radius": false,
    "outcome": null,
    "outcome_label": null,
    "notes": null,
    "follow_up_date": null,
    "is_suspect": true,
    "cancel_reason": "Salah pilih klien, kunjungan sebenarnya ke gudang sendiri."
  }
}

Contoh Response Error (422, errors.client_visit)

Kondisi message
Bukan ONGOING ✓ Hanya kunjungan yang sedang berlangsung yang dapat dibatalkan.
Milik karyawan lain (403) Kunjungan ini bukan milik Anda.

Detail kunjungan

GET /client-visits/{clientVisit}

Auth & Middleware
Token wajib
Middleware auth:sanctum, EnsureSubscriptionActive
Route name api.v1.client-visits.show

Contoh Request

GET /api/v1/client-visits/1 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Contoh Response Sukses (200)

{
  "success": true,
  "message": "Detail kunjungan klien berhasil diambil.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "COMPLETED",
    "status_label": "Selesai",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": "2026-11-10T07:12:25+00:00",
    "duration_minutes": 70,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": "FOLLOW_UP",
    "outcome_label": "Perlu Tindak Lanjut",
    "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
    "follow_up_date": "2026-11-13",
    "is_suspect": false,
    "cancel_reason": null
  }
}

Contoh Response Error

Kondisi HTTP message
Milik karyawan lain di perusahaan yang sama 403 Kunjungan ini bukan milik Anda.
ID tidak ada atau milik perusahaan lain 404 Sumber daya tidak ditemukan.