Catatan aktivitas harian karyawan: satu timesheet per tanggal kerja berisi beberapa aktivitas
(entri), lalu dikirim untuk ditinjau atasan. Aktivitas CLIENT_VISIT dibuat otomatis dari check-out
kunjungan klien. Konvensi umum ada di README.md.
| Atribut | Nilai |
|---|---|
| Endpoint | GET /timesheets, GET /timesheets/today, GET /timesheets/{timesheet}, POST /timesheets/{timesheet}/submit, POST /timesheet-entries, PUT /timesheet-entries/{timesheetEntry}, DELETE /timesheet-entries/{timesheetEntry} |
| Sumber kode | TimesheetController, StoreTimesheetEntryRequest, TimesheetResource, TimesheetEntryResource, TimesheetService, TimesheetCalculator |
| Contoh direkam | 2026-11-10 dan 2026-11-11, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, APP_LOCALE=id |
| Data uji | Citra Satu, kunjungan klien 13:02–14:12 WIB sudah di-check-out. Pengaturan bawaan (policy.timesheet): entri 15–720 menit, total 960 menit per hari, mundur maks. 7 hari, aktivitas otomatis dari kunjungan aktif |
Enum
TimesheetStatus (status)
| Nilai | status_label |
is_editable |
Arti |
|---|---|---|---|
DRAFT |
Rancangan | true |
sedang diisi karyawan |
SUBMITTED |
Menunggu Tinjauan | false |
sudah dikirim, menunggu atasan |
APPROVED |
Disetujui | false |
disetujui atasan |
REJECTED |
Dikembalikan | true |
dikembalikan untuk diperbaiki; boleh diubah dan dikirim ulang |
Tidak ada pembatalan pengiriman dari aplikasi; atasan atau Admin HR dapat membuka kembali timesheet
menjadi DRAFT.
TimesheetActivityType (activity_type)
| Nilai | activity_label |
|---|---|
CLIENT_VISIT |
Kunjungan Klien |
MEETING |
Rapat |
FIELD_WORK |
Pekerjaan Lapangan |
ADMINISTRATION |
Administrasi |
TRAINING |
Pelatihan |
SUPPORT |
Dukungan Teknis |
OTHER |
Lainnya |
Objek timesheet
Sumber: TimesheetResource. Seluruh endpoint mengembalikan timesheet lengkap dengan entries,
termasuk endpoint entri.
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | ID timesheet, dipakai untuk detail dan pengiriman |
work_date |
string (YYYY-MM-DD) |
tidak | tanggal kerja |
status |
string (enum) | tidak | TimesheetStatus |
status_label |
string | tidak | label tampilan |
total_minutes |
integer | tidak | jumlah duration_minutes seluruh entri |
total_hours |
number | tidak | total_minutes / 60, dibulatkan 2 desimal (informasi tampilan) |
entry_count |
integer | tidak | jumlah entri |
is_editable |
boolean | tidak | true bila entri boleh ditambah, diubah, dihapus, dan timesheet boleh dikirim |
submitted_at |
string (ISO 8601 UTC) | ya | waktu dikirim |
reviewed_at |
string (ISO 8601 UTC) | ya | waktu ditinjau |
reviewer |
string | ya | nama peninjau |
review_notes |
string | ya | catatan peninjau |
entries |
array objek | tidak | entri urut started_at naik |
entries[] (TimesheetEntryResource)
| Field | Tipe | Null | Keterangan |
|---|---|---|---|
id |
integer | tidak | ID entri, dipakai untuk ubah/hapus |
activity_type |
string (enum) | tidak | TimesheetActivityType |
activity_label |
string | tidak | label tampilan |
started_at |
string (ISO 8601 UTC) | tidak | jam mulai |
ended_at |
string (ISO 8601 UTC) | tidak | jam selesai |
duration_minutes |
integer | tidak | durasi menit |
title |
string | tidak | judul aktivitas |
description |
string | ya | rincian |
reference |
string | ya | nomor rujukan; entri otomatis berisi kode klien |
client_visit_id |
integer | ya | kunjungan terkait |
business_trip_id |
integer | ya | perjalanan bisnis terkait |
is_generated |
boolean | tidak | true bila dibuat otomatis dari kunjungan klien; tidak dapat diubah, tetapi boleh dihapus |
Timesheet hari ini
GET /timesheets/today
Deskripsi: timesheet untuk tanggal kerja saat ini (mengikuti jadwal, termasuk shift malam lintas
tengah malam). Bila belum ada, server membuatnya sebagai DRAFT kosong.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheets.today |
Contoh Request
GET /api/v1/timesheets/today HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-11-10 16:10 WIB, sudah berisi aktivitas otomatis dari kunjungan
klien)
{
"success": true,
"message": "Timesheet hari ini berhasil diambil.",
"data": {
"id": 1,
"work_date": "2026-11-10",
"status": "DRAFT",
"status_label": "Rancangan",
"total_minutes": 70,
"total_hours": 1.17,
"entry_count": 1,
"is_editable": true,
"submitted_at": null,
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": [
{
"id": 1,
"activity_type": "CLIENT_VISIT",
"activity_label": "Kunjungan Klien",
"started_at": "2026-11-10T06:02:15+00:00",
"ended_at": "2026-11-10T07:12:25+00:00",
"duration_minutes": 70,
"title": "Kunjungan PT Sinar Jaya Abadi",
"description": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
"reference": "CL-0001",
"client_visit_id": 1,
"business_trip_id": null,
"is_generated": true
}
]
}
}
Hari baru tanpa aktivitas (2026-11-11 08:05 WIB):
{
"id": 2,
"work_date": "2026-11-11",
"status": "DRAFT",
"status_label": "Rancangan",
"total_minutes": 0,
"total_hours": 0,
"entry_count": 0,
"is_editable": true,
"submitted_at": null,
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": []
}
Riwayat timesheet
GET /timesheets
Deskripsi: timesheet milik karyawan login, 31 terbaru urut work_date terbaru di atas, lengkap
dengan entries. Tanpa pagination dan tanpa filter. Timesheet kosong yang terbentuk oleh
GET /timesheets/today ikut tampil.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheets.index |
Contoh Request
GET /api/v1/timesheets HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, 2026-11-11 08:05 WIB)
{
"success": true,
"message": "Riwayat timesheet berhasil diambil.",
"data": [
{
"id": 2,
"work_date": "2026-11-11",
"status": "DRAFT",
"status_label": "Rancangan",
"total_minutes": 0,
"total_hours": 0,
"entry_count": 0,
"is_editable": true,
"submitted_at": null,
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": []
},
{
"id": 1,
"work_date": "2026-11-10",
"status": "SUBMITTED",
"status_label": "Menunggu Tinjauan",
"total_minutes": 235,
"total_hours": 3.92,
"entry_count": 3,
"is_editable": false,
"submitted_at": "2026-11-10T10:05:00+00:00",
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": [
{
"id": 2,
"activity_type": "MEETING",
"activity_label": "Rapat",
"started_at": "2026-11-10T01:30:00+00:00",
"ended_at": "2026-11-10T02:45:00+00:00",
"duration_minutes": 75,
"title": "Rapat koordinasi pengiriman",
"description": "Pembagian rute armada minggu kedua November.",
"reference": "MOM-2026-11-10",
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 3,
"activity_type": "ADMINISTRATION",
"activity_label": "Administrasi",
"started_at": "2026-11-10T03:00:00+00:00",
"ended_at": "2026-11-10T04:30:00+00:00",
"duration_minutes": 90,
"title": "Input surat jalan dan faktur ke sistem",
"description": null,
"reference": null,
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 1,
"activity_type": "CLIENT_VISIT",
"activity_label": "Kunjungan Klien",
"started_at": "2026-11-10T06:02:15+00:00",
"ended_at": "2026-11-10T07:12:25+00:00",
"duration_minutes": 70,
"title": "Kunjungan PT Sinar Jaya Abadi",
"description": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
"reference": "CL-0001",
"client_visit_id": 1,
"business_trip_id": null,
"is_generated": true
}
]
}
]
}
Detail timesheet
GET /timesheets/{timesheet}
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheets.show |
Contoh Request
GET /api/v1/timesheets/1 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200): sama dengan objek timesheet di riwayat.
Contoh Response Error
| Kondisi | HTTP | message |
|---|---|---|
| Milik karyawan lain di perusahaan yang sama | 403 | Timesheet ini bukan milik Anda. |
| ID tidak ada atau milik perusahaan lain | 404 | Sumber daya tidak ditemukan. |
Tambah aktivitas
POST /timesheet-entries
Deskripsi: menambah satu aktivitas. Tanggal kerja (dan timesheet tujuan) ditentukan server dari
started_at dan jadwal karyawan; timesheet dibuat bila belum ada.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheet-entries.store |
Header: Accept: application/json, Authorization: Bearer <token>, Content-Type: application/json
Parameter (StoreTimesheetEntryRequest, sama untuk PUT)
| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
activity_type |
body | string (enum) | ya | required, salah satu TimesheetActivityType |
started_at |
body | string (ISO 8601) | ya | required, date. Wajib dengan offset (2026-11-10T08:30:00+07:00) |
ended_at |
body | string (ISO 8601) | ya | required, date, after:started_at |
title |
body | string | ya | required, string, min:3, max:150 |
description |
body | string | tidak | nullable, string, max:1000 |
reference |
body | string | tidak | nullable, string, max:100 |
client_visit_id |
body | integer | tidak | nullable, integer, min:1. ID milik orang lain diabaikan (tersimpan null) |
business_trip_id |
body | integer | tidak | nullable, integer, min:1. ID milik orang lain diabaikan |
Contoh Request (2026-11-10 16:10 WIB)
POST /api/v1/timesheet-entries HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json
{
"activity_type": "MEETING",
"started_at": "2026-11-10T08:30:00+07:00",
"ended_at": "2026-11-10T09:45:00+07:00",
"title": "Rapat koordinasi pengiriman",
"description": "Pembagian rute armada minggu kedua November.",
"reference": "MOM-2026-11-10"
}
Contoh Response Sukses (201). Respons berisi timesheet lengkap, bukan entri saja:
{
"success": true,
"message": "Aktivitas tercatat pada timesheet.",
"data": {
"id": 1,
"work_date": "2026-11-10",
"status": "DRAFT",
"status_label": "Rancangan",
"total_minutes": 145,
"total_hours": 2.42,
"entry_count": 2,
"is_editable": true,
"submitted_at": null,
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": [
{
"id": 2,
"activity_type": "MEETING",
"activity_label": "Rapat",
"started_at": "2026-11-10T01:30:00+00:00",
"ended_at": "2026-11-10T02:45:00+00:00",
"duration_minutes": 75,
"title": "Rapat koordinasi pengiriman",
"description": "Pembagian rute armada minggu kedua November.",
"reference": "MOM-2026-11-10",
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 1,
"activity_type": "CLIENT_VISIT",
"activity_label": "Kunjungan Klien",
"started_at": "2026-11-10T06:02:15+00:00",
"ended_at": "2026-11-10T07:12:25+00:00",
"duration_minutes": 70,
"title": "Kunjungan PT Sinar Jaya Abadi",
"description": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
"reference": "CL-0001",
"client_visit_id": 1,
"business_trip_id": null,
"is_generated": true
}
]
}
}
Penolakan dan urutan pemeriksaan (422, errors.timesheet)
| # | HTTP | message (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 422 | ✓ Data yang dikirim tidak lolos pemeriksaan. (validasi FormRequest) |
| 2 | 422 | ✓ Durasi aktivitas minimal 15 menit, sedangkan aktivitas ini 10 menit. |
| 3 | 422 | Durasi satu aktivitas paling lama 720 menit, sedangkan aktivitas ini {n} menit. |
| 4 | 422 | ✓ Aktivitas tidak dapat dicatat untuk tanggal kerja yang belum berjalan. |
| 5 | 422 | ✓ Timesheet hanya dapat diisi paling lama 7 hari ke belakang. |
| 6 | 422 | Periode rekap yang memuat tanggal {tanggal} sudah dikunci. |
| 7 | 422 | ✓ Timesheet tanggal 2026-11-10 berstatus Menunggu Tinjauan sehingga tidak dapat diubah. |
| 8 | 422 | ✓ Jam aktivitas beririsan dengan Input surat jalan ke sistem (10:00 WIB–12:00 WIB). |
| 9 | 422 | Total aktivitas pada tanggal kerja ini menjadi {terpakai}+{baru} menit, melewati batas 960 menit per hari. |
Angka mengikuti policy.timesheet di me/config. Irisan diperiksa terhadap seluruh entri tanggal
kerja yang sama, termasuk entri otomatis.
Validasi (activity_type: "RAPAT", ended_at sebelum started_at, title: "R"):
{
"success": false,
"message": "Data yang dikirim tidak lolos pemeriksaan.",
"errors": {
"activity_type": [
"Pilihan pada kolom jenis aktivitas tidak sah."
],
"ended_at": [
"Kolom jam selesai harus berisi tanggal setelah jam mulai."
],
"title": [
"Kolom judul aktivitas minimal 3 karakter."
]
}
}
Catatan
- Idempotency: tidak ada kunci. Entri kedua dengan jam sama ditolak aturan irisan (nomor 8).
- Rate limit: tidak ada. FeatureGate / modul:
module_timesheet(server tidak memblokir). Status langganan: terkunci → 402.
Ubah aktivitas
PUT /timesheet-entries/{timesheetEntry}
Deskripsi: mengganti seluruh isi satu entri. Kirim semua field seperti saat menambah (bukan pembaruan sebagian).
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheet-entries.update |
Parameter: timesheetEntry (path, integer) dan body sama dengan tambah aktivitas.
Contoh Request
PUT /api/v1/timesheet-entries/3 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json
{
"activity_type": "ADMINISTRATION",
"started_at": "2026-11-10T10:00:00+07:00",
"ended_at": "2026-11-10T11:30:00+07:00",
"title": "Input surat jalan dan faktur ke sistem"
}
Contoh Response Sukses (200, isi message dan data)
"message": "Aktivitas diperbarui.",
"data": {
"id": 1,
"work_date": "2026-11-10",
"status": "DRAFT",
"status_label": "Rancangan",
"total_minutes": 235,
"total_hours": 3.92,
"entry_count": 3,
"is_editable": true,
"submitted_at": null,
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": [
{
"id": 2,
"activity_type": "MEETING",
"activity_label": "Rapat",
"started_at": "2026-11-10T01:30:00+00:00",
"ended_at": "2026-11-10T02:45:00+00:00",
"duration_minutes": 75,
"title": "Rapat koordinasi pengiriman",
"description": "Pembagian rute armada minggu kedua November.",
"reference": "MOM-2026-11-10",
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 3,
"activity_type": "ADMINISTRATION",
"activity_label": "Administrasi",
"started_at": "2026-11-10T03:00:00+00:00",
"ended_at": "2026-11-10T04:30:00+00:00",
"duration_minutes": 90,
"title": "Input surat jalan dan faktur ke sistem",
"description": null,
"reference": null,
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 1,
"activity_type": "CLIENT_VISIT",
"activity_label": "Kunjungan Klien",
"started_at": "2026-11-10T06:02:15+00:00",
"ended_at": "2026-11-10T07:12:25+00:00",
"duration_minutes": 70,
"title": "Kunjungan PT Sinar Jaya Abadi",
"description": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
"reference": "CL-0001",
"client_visit_id": 1,
"business_trip_id": null,
"is_generated": true
}
]
}
Penolakan (422, errors.timesheet): seluruh aturan tambah aktivitas, ditambah:
| Kondisi | message (direkam bila bertanda ✓) |
|---|---|
| Entri otomatis dari kunjungan | ✓ Aktivitas yang dibuat otomatis dari kunjungan klien tidak dapat diubah manual. |
| Jam baru jatuh pada tanggal kerja lain | Jam aktivitas yang baru jatuh pada tanggal kerja lain. Hapus aktivitas ini lalu catat ulang. |
| Milik karyawan lain (403) | ✓ Aktivitas ini bukan milik Anda. |
Hapus aktivitas
DELETE /timesheet-entries/{timesheetEntry}
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheet-entries.destroy |
Parameter: timesheetEntry (path, integer). Tanpa body.
Contoh Request
DELETE /api/v1/timesheet-entries/4 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200, timesheet sesudah entri dihapus; isi message dan data)
"message": "Aktivitas dihapus dari timesheet.",
"data": {
"id": 1,
"work_date": "2026-11-10",
"status": "DRAFT",
"status_label": "Rancangan",
"total_minutes": 235,
"total_hours": 3.92,
"entry_count": 3,
"is_editable": true,
"submitted_at": null,
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": [
{
"id": 2,
"activity_type": "MEETING",
"activity_label": "Rapat",
"started_at": "2026-11-10T01:30:00+00:00",
"ended_at": "2026-11-10T02:45:00+00:00",
"duration_minutes": 75,
"title": "Rapat koordinasi pengiriman",
"description": "Pembagian rute armada minggu kedua November.",
"reference": "MOM-2026-11-10",
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 3,
"activity_type": "ADMINISTRATION",
"activity_label": "Administrasi",
"started_at": "2026-11-10T03:00:00+00:00",
"ended_at": "2026-11-10T04:30:00+00:00",
"duration_minutes": 90,
"title": "Input surat jalan dan faktur ke sistem",
"description": null,
"reference": null,
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 1,
"activity_type": "CLIENT_VISIT",
"activity_label": "Kunjungan Klien",
"started_at": "2026-11-10T06:02:15+00:00",
"ended_at": "2026-11-10T07:12:25+00:00",
"duration_minutes": 70,
"title": "Kunjungan PT Sinar Jaya Abadi",
"description": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
"reference": "CL-0001",
"client_visit_id": 1,
"business_trip_id": null,
"is_generated": true
}
]
}
Penolakan: timesheet tidak dapat diubah (SUBMITTED/APPROVED) → 422 dengan message seperti
nomor 7 tambah aktivitas; milik karyawan lain → 403 Aktivitas ini bukan milik Anda.
Kirim timesheet
POST /timesheets/{timesheet}/submit
Deskripsi: mengirim timesheet DRAFT atau REJECTED untuk ditinjau. Sesudah dikirim, entri tidak
dapat diubah.
| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | auth:sanctum, EnsureSubscriptionActive |
| Route name | api.v1.timesheets.submit |
Parameter: timesheet (path, integer). Tanpa body.
Contoh Request
POST /api/v1/timesheets/1/submit HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Contoh Response Sukses (200)
{
"success": true,
"message": "Timesheet dikirim dan menunggu tinjauan atasan langsung.",
"data": {
"id": 1,
"work_date": "2026-11-10",
"status": "SUBMITTED",
"status_label": "Menunggu Tinjauan",
"total_minutes": 235,
"total_hours": 3.92,
"entry_count": 3,
"is_editable": false,
"submitted_at": "2026-11-10T10:05:00+00:00",
"reviewed_at": null,
"reviewer": null,
"review_notes": null,
"entries": [
{
"id": 2,
"activity_type": "MEETING",
"activity_label": "Rapat",
"started_at": "2026-11-10T01:30:00+00:00",
"ended_at": "2026-11-10T02:45:00+00:00",
"duration_minutes": 75,
"title": "Rapat koordinasi pengiriman",
"description": "Pembagian rute armada minggu kedua November.",
"reference": "MOM-2026-11-10",
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 3,
"activity_type": "ADMINISTRATION",
"activity_label": "Administrasi",
"started_at": "2026-11-10T03:00:00+00:00",
"ended_at": "2026-11-10T04:30:00+00:00",
"duration_minutes": 90,
"title": "Input surat jalan dan faktur ke sistem",
"description": null,
"reference": null,
"client_visit_id": null,
"business_trip_id": null,
"is_generated": false
},
{
"id": 1,
"activity_type": "CLIENT_VISIT",
"activity_label": "Kunjungan Klien",
"started_at": "2026-11-10T06:02:15+00:00",
"ended_at": "2026-11-10T07:12:25+00:00",
"duration_minutes": 70,
"title": "Kunjungan PT Sinar Jaya Abadi",
"description": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
"reference": "CL-0001",
"client_visit_id": 1,
"business_trip_id": null,
"is_generated": true
}
]
}
}
Penolakan (422, errors.timesheet)
| Kondisi | message |
|---|---|
Sudah SUBMITTED/APPROVED |
✓ Timesheet tanggal 2026-11-10 berstatus Menunggu Tinjauan sehingga tidak dapat diubah. |
| Tanpa entri | ✓ Timesheet kosong tidak dapat dikirim. Catat aktivitas terlebih dahulu. |
| Milik karyawan lain (403) | Timesheet ini bukan milik Anda. |
Catatan
- Idempotency: pengiriman kedua dijawab 422; anggap sukses bila status lokal sudah
SUBMITTED. - Rate limit: tidak ada. FeatureGate:
module_timesheet. Status langganan: terkunci → 402.