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:
uuidper kunjungan. Simpan bersama antrean offline dan pakai ulang saat kirim ulang; jawaban200berisi data asli. - Satu kunjungan terbuka. Check-in baru ditolak selama masih ada
ONGOING; selesaikan dengan check-out atau batalkan. Kunjungan yang terbuka lebih daripolicy.client_visit.max_open_hourstidak 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 denganPOST /attendance/check-indanPOST /attendance/check-out. Respons membawaX-RateLimit-LimitdanX-RateLimit-Remaining; 429 membawaRetry-AfterdanX-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 sudahCOMPLETED. - 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. |