Timesheet

Lihat Markdown

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.