API berbayar · Langganan

Referensi API pengembang (berbayar)

Integrasikan API produksi untuk pengiriman jadwal dengan kunci API yang terikat ke langganan berbayar Anda. Default penyewa dapat disimpan dengan PATCH /v1/schedule-defaults; harian mingguan per staf dibaca atau diganti penuh dengan GET/PUT /v1/staff/{staffId}/weekly-shift-wish. Penagihan mengikuti paket dan kontrak Anda (bukan bayar per panggilan API). Halaman ini mendokumentasikan hak, aturan validasi, dan kode error — gunakan bilah sisi untuk melompat ke setiap field.

Halaman ini mendokumentasikan API REST produk untuk integrasi eksternal (API Gateway {stage}/v1/*, autentikasi x-api-key).

Webhook penyelesaian hasil jadwal adalah notifikasi HTTPS keluar yang dikonfigurasi di manajemen API (bukan CRUD REST). Lihat Completion webhooks di halaman ini.

Rute browser internal (mis. callback pembayaran atau analitik) bukan pengganti API produk ini. Untuk sistem eksternal, gunakan /v1/* dan webhook penyelesaian.

API HTTP ini merupakan bagian produk berbayar: akses memerlukan perjanjian komersial aktif dan kunci diterbitkan ke organisasi Anda setelah onboarding.

Penagihan berdasarkan langganan dan kontrak. Untuk paket berbayar, biaya biasanya mengikuti halaman harga (mis. per staf terdaftar per bulan).

Batas playground / tingkat gratis tidak berlaku untuk kunci API berbayar. Batas efektif seperti rentang jadwal, jumlah staf, dan granularitas 15 menit ditentukan oleh hak berbayar Anda. Lihat Batas & default di halaman ini.

Permintaan harus menyertakan kunci API yang valid yang diterbitkan untuk langganan berbayar Anda. Buat, putar, dan cabut kunci dari area akun setelah masuk.

Kirim kunci di header x-api-key. Kunci terikat ke organisasi Anda untuk identifikasi penyewa dan batas akses berdasarkan paket.

Kelola kunci: Manajemen API

Kirim kondisi jadwal sebagai JSON. Ini adalah permukaan integrasi berbayar; URL dasar pasti diberikan per lingkungan setelah akses API disediakan.

POST {baseUrl}/v1/schedule

Gunakan URL dasar yang diberikan saat akses API disediakan atau oleh kontak operasi Anda.

Ganti **BASE_URL** dengan URL dasar API (awalan jalur) yang diberikan saat akses Anda disediakan.

Kirim kunci API di header **x-api-key**. Organisasi (penyewa) Anda diidentifikasi dari kunci — Anda tidak perlu mengirim ID penyewa terpisah di query string.

Fitur berbayar (emergency shift, detail ketenagakerjaan, beberapa default jadwal) memerlukan langganan berbayar yang aktif. Anda dapat menerima **503** (mis. kode **STRIPE_NOT_CONFIGURED**) bila penagihan belum dikonfigurasi. Profil perusahaan, log audit, dan pengelolaan pengguna (akun) dilakukan di aplikasi web dan bukan bagian dari API publik.

Contoh curl (bash / macOS / Linux / WSL)

Windows PowerShell: `\` di akhir baris **bukan** kelanjutan baris. Tulis satu baris, atau akhiri setiap baris dengan backtick (`) untuk melanjutkan.

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/schedule-results?limit=10"

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/staff"

URL dasar dan kunci API yang sama seperti POST /v1/schedule. Query opsional: limit (1–100, bawaan 50), cursor (token buram dari field nextCursor respons sebelumnya).

GET{baseUrl}/v1/schedule-results
Mendaftar baris induk SCHEDULE_RESULT: conditionId, status, candidateCount, createdAt/updatedAt, dll. Paginasi baris induk DynamoDB.
GET{baseUrl}/v1/schedule-results/history
Pencarian riwayat hasil jadwal (sama seperti browser). from / to (ISO 8601, default awal layanan hingga sekarang), keyword, eventName (INSERT,MODIFY,REMOVE dipisah koma), limit, cursor. Menggabungkan data terbaru dan arsip otomatis; hanya items / nextCursor.
GET{baseUrl}/v1/schedule-results/{conditionId}
Mengambil satu baris induk SCHEDULE_RESULT menurut conditionId (atribut JSON; PK/SK dihilangkan).
GET{baseUrl}/v1/schedule-results/{conditionId}/resolution
Output optimasi terselesaikan: status, candidates, confirmedAssignments jika ada. Jika status completed dan belum dikonfirmasi, rank-1 dapat dikonfirmasi otomatis pada GET ini (efek samping). Gunakan POST …/confirm-assignments untuk konfirmasi manual.
GET{baseUrl}/v1/schedule-results/{conditionId}/review
Payload tinjauan untuk konfirmasi manual (kandidat, requiredByCellKey, allowedCellKeys staf, dll.).
GET{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context
Konteks shift darurat (tanggal kalender, staf, slot). Langganan berbayar diperlukan; null jika kondisi tidak ada.
GET{baseUrl}/v1/schedule-conditions
Daftar baris induk SCHEDULE_CONDITION (conditionId, tanggal, publicApiCancelledAt opsional).
GET{baseUrl}/v1/schedule-conditions/{conditionId}
Baris induk kondisi plus reqDays dan staffSnapshots (tanpa PK/SK).
GET{baseUrl}/v1/schedule-defaults
Baris default jadwal penyewa (SCHEDULE_DEFAULTS) atau null jika belum disimpan.
GET{baseUrl}/v1/schedule-actual/{conditionId}
Baris SCHEDULE_ACTUAL penugasan aktual, atau null jika tidak ada.
GET{baseUrl}/v1/staff/{staffId}/weekly-shift-wish
Baris keinginan shift mingguan staf, atau null jika tidak ada.
GET{baseUrl}/v1/staff
Mendaftar staf aktif penyewa (diurut menurut nama tampilan).
GET{baseUrl}/v1/staff/{staffId}
Mengambil satu anggota staf menurut staffId termasuk detail ketenagakerjaan (laborLawCompliance, laborFlsaExempt, batas pribadi, laborConstraintMask). Soft delete → 404.

Metode	Jalur	Deskripsi
GET	{baseUrl}/v1/schedule-results	Mendaftar baris induk SCHEDULE_RESULT: conditionId, status, candidateCount, createdAt/updatedAt, dll. Paginasi baris induk DynamoDB.
GET	{baseUrl}/v1/schedule-results/history	Pencarian riwayat hasil jadwal (sama seperti browser). from / to (ISO 8601, default awal layanan hingga sekarang), keyword, eventName (INSERT,MODIFY,REMOVE dipisah koma), limit, cursor. Menggabungkan data terbaru dan arsip otomatis; hanya items / nextCursor.
GET	{baseUrl}/v1/schedule-results/{conditionId}	Mengambil satu baris induk SCHEDULE_RESULT menurut conditionId (atribut JSON; PK/SK dihilangkan).
GET	{baseUrl}/v1/schedule-results/{conditionId}/resolution	Output optimasi terselesaikan: status, candidates, confirmedAssignments jika ada. Jika status completed dan belum dikonfirmasi, rank-1 dapat dikonfirmasi otomatis pada GET ini (efek samping). Gunakan POST …/confirm-assignments untuk konfirmasi manual.
GET	{baseUrl}/v1/schedule-results/{conditionId}/review	Payload tinjauan untuk konfirmasi manual (kandidat, requiredByCellKey, allowedCellKeys staf, dll.).
GET	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context	Konteks shift darurat (tanggal kalender, staf, slot). Langganan berbayar diperlukan; null jika kondisi tidak ada.
GET	{baseUrl}/v1/schedule-conditions	Daftar baris induk SCHEDULE_CONDITION (conditionId, tanggal, publicApiCancelledAt opsional).
GET	{baseUrl}/v1/schedule-conditions/{conditionId}	Baris induk kondisi plus reqDays dan staffSnapshots (tanpa PK/SK).
GET	{baseUrl}/v1/schedule-defaults	Baris default jadwal penyewa (SCHEDULE_DEFAULTS) atau null jika belum disimpan.
GET	{baseUrl}/v1/schedule-actual/{conditionId}	Baris SCHEDULE_ACTUAL penugasan aktual, atau null jika tidak ada.
GET	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Baris keinginan shift mingguan staf, atau null jika tidak ada.
GET	{baseUrl}/v1/staff	Mendaftar staf aktif penyewa (diurut menurut nama tampilan).
GET	{baseUrl}/v1/staff/{staffId}	Mengambil satu anggota staf menurut staffId termasuk detail ketenagakerjaan (laborLawCompliance, laborFlsaExempt, batas pribadi, laborConstraintMask). Soft delete → 404.

Gunakan kunci API yang sama dengan body JSON. PATCH /v1/schedule-defaults menyimpan default penyewa (requirementsByCellKey, horizon perencanaan, dll.); field berbayar mengikuti langganan Anda. PUT /v1/staff/{staffId}/weekly-shift-wish mengganti seluruh grid keinginan mingguan staf tersebut (lihat catatan validasi). POST /v1/staff mengembalikan 409 STAFF_LIMIT jika daftar melebihi batas kontrak. Pengelolaan pengguna (akun), profil perusahaan, dan log audit dilakukan di aplikasi web dan bukan bagian dari API publik.

POST /v1/staff: JSON { "displayName": "..." } saja. PATCH /v1/staff/{staffId}: displayName, laborLawCompliance, laborFlsaExempt, personalMaxWeeklyMinutes / personalMaxMonthlyMinutes / personalMaxThreeMonthMinutes (bilangan bulat atau null), laborConstraintMask (objek atau null jika laborLawCompliance true) — field ketenagakerjaan berbayar. POST /v1/schedule-results/{conditionId}/emergency-shift: absentStaffIds, absentDatesYmd dan/atau absentSlots (berbayar, jadwal sumber selesai). POST …/confirm-assignments: array assignments dan relaxAvailability opsional. PATCH /v1/schedule-defaults: PUBLIC_API_SCHEDULE_REQUEST_BODY.md §12. PUT /v1/staff/{staffId}/weekly-shift-wish: scheduleStartDate, scheduleEndDate, timeRangeStart, timeRangeEnd, wishByCellKey.

PATCH{baseUrl}/v1/schedule-defaults
Menyimpan default jadwal penyewa (body selaras saveSchema di schedule-defaults-actions). Field berbayar mengikuti langganan Anda.
POST{baseUrl}/v1/staff
Membuat anggota staf (displayName). Mengembalikan 201 dengan JSON staff.
POST{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift
Mengkloning jadwal sumber yang selesai dengan absensi diterapkan; mengembalikan 201 dengan conditionId. Langganan berbayar diperlukan.
POST{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments
Memvalidasi dan menyimpan penugasan yang diedit manual (200 dengan { ok: true }).
PATCH{baseUrl}/v1/staff/{staffId}
Memperbarui displayName dan detail ketenagakerjaan (laborLawCompliance, laborFlsaExempt, batas pribadi, laborConstraintMask).
DELETE{baseUrl}/v1/staff/{staffId}
Soft delete anggota staf (mengatur deletedAt).
DELETE{baseUrl}/v1/schedule-conditions/{conditionId}
Menandai kondisi dibatalkan (publicApiCancelledAt); tidak menghapus baris anak.
PUT{baseUrl}/v1/schedule-actual/{conditionId}
Menyimpan penugasan aktual JSON { "assignments": [ ... ] } (divalidasi terhadap grid kondisi).
PUT{baseUrl}/v1/staff/{staffId}/weekly-shift-wish
Mengganti keinginan mingguan: grid penuh (1–7 hari), wishByCellKey per sel (NONE|LOW|HIGH); granularitas dari default penyewa.

Metode	Jalur	Deskripsi
PATCH	{baseUrl}/v1/schedule-defaults	Menyimpan default jadwal penyewa (body selaras saveSchema di schedule-defaults-actions). Field berbayar mengikuti langganan Anda.
POST	{baseUrl}/v1/staff	Membuat anggota staf (displayName). Mengembalikan 201 dengan JSON staff.
POST	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift	Mengkloning jadwal sumber yang selesai dengan absensi diterapkan; mengembalikan 201 dengan conditionId. Langganan berbayar diperlukan.
POST	{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments	Memvalidasi dan menyimpan penugasan yang diedit manual (200 dengan { ok: true }).
PATCH	{baseUrl}/v1/staff/{staffId}	Memperbarui displayName dan detail ketenagakerjaan (laborLawCompliance, laborFlsaExempt, batas pribadi, laborConstraintMask).
DELETE	{baseUrl}/v1/staff/{staffId}	Soft delete anggota staf (mengatur deletedAt).
DELETE	{baseUrl}/v1/schedule-conditions/{conditionId}	Menandai kondisi dibatalkan (publicApiCancelledAt); tidak menghapus baris anak.
PUT	{baseUrl}/v1/schedule-actual/{conditionId}	Menyimpan penugasan aktual JSON { "assignments": [ ... ] } (divalidasi terhadap grid kondisi).
PUT	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Mengganti keinginan mingguan: grid penuh (1–7 hari), wishByCellKey per sel (NONE\|LOW\|HIGH); granularitas dari default penyewa.

When a schedule result reaches a terminal status, we POST a signed JSON notification to your HTTPS URL. The body does not include the full result; fetch details with GET /v1/schedule-results/{conditionId}.

Playground results are not delivered. If the webhook is disabled or no URL is saved, nothing is sent.

Setup

After sign-in, open API management and save an HTTPS notification URL.
Turn on Enable notifications.
Copy the signing secret shown once (it cannot be revealed again; regenerate if lost).
Verify the signature on your receiver, then GET links.result with your API key if needed.

Events

Event type and when it is sent.

schedule.result.terminal
Schedule result status becomes completed, no_solution, failed, error, or canceled

type	When
schedule.result.terminal	Schedule result status becomes completed, no_solution, failed, error, or canceled

Request body

status is terminal only. customerId is omitted from the body.

{
  "type": "schedule.result.terminal",
  "conditionId": "019ee481-e855-7000-abd8-977cbfd64ffc",
  "status": "completed",
  "occurredAt": "2026-07-16T13:00:54.694Z",
  "links": {
    "result": "{baseUrl}/v1/schedule-results/019ee481-e855-7000-abd8-977cbfd64ffc"
  }
}

Request headers

Content-Type
application/json
User-Agent
AutoScheduler-Webhook/1.0
X-AutoScheduler-Timestamp
Unix seconds as a string
X-AutoScheduler-Signature
v1=<hex> (see verification below)

Header	Description
Content-Type	application/json
User-Agent	AutoScheduler-Webhook/1.0
X-AutoScheduler-Timestamp	Unix seconds as a string
X-AutoScheduler-Signature	v1=<hex> (see verification below)

Signature verification

Compute a digest from the raw body (before JSON parse) and the Timestamp, then compare to Signature. Reject requests when |now − timestamp| exceeds 300 seconds (5 minutes) unless you intentionally allow wider clock skew.

HMAC-SHA256(signingSecret, `${timestamp}.${rawBody}`) → hex; header value is v1=<hex>

Retries

On 5xx or timeout we retry automatically. Persistent failures go to a dead-letter queue. Browser push notifications use a separate path.

x-api-key
Kunci API terikat ke langganan berbayar Anda (mengidentifikasi penyewa dan batas paket).
Content-Type
application/json

Header	Deskripsi
x-api-key	Kunci API terikat ke langganan berbayar Anda (mengidentifikasi penyewa dan batas paket).
Content-Type	application/json

Header respons

Beberapa header respons (seperti ID permintaan) adalah metadata pelacakan, bukan kunci API Anda. Anggap **body** JSON bersifat rahasia bila berisi data perusahaan atau pengguna.

Batas validasi tipikal untuk kontrak Anda (granularitas 15 menit, rentang jadwal, jumlah staf terdaftar, dan batas terkait).

Model penagihan
Langganan Stripe; biaya produk biasanya mengikuti jumlah kursi staf terdaftar sesuai halaman harga (bukan tagihan per panggilan API).
maxScheduleDays
Hingga 14 hari kalender per pengiriman untuk perencanaan detail dua minggu standar (rentang lebih lebar hanya jika kontrak mengizinkan).
maxStaffPerSchedule
Hingga 500 baris staff per POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; staffId inline di body).
maxRosterStaff
Hingga 30 staf aktif via POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT jika terlampaui.
allowedGranularities
[60, 15] — slot 15 menit adalah fitur berbayar; 60 menit juga didukung.
maxPayloadBytes
524288 (512 KiB) UTF-8 kecuali batas lebih tinggi diberikan.
strictUnknownRootKeys
true — kunci tingkat atas atau di staff yang tidak dikenal ditolak

Pengaturan	API berbayar (tipikal)
Model penagihan	Langganan Stripe; biaya produk biasanya mengikuti jumlah kursi staf terdaftar sesuai halaman harga (bukan tagihan per panggilan API).
maxScheduleDays	Hingga 14 hari kalender per pengiriman untuk perencanaan detail dua minggu standar (rentang lebih lebar hanya jika kontrak mengizinkan).
maxStaffPerSchedule	Hingga 500 baris staff per POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; staffId inline di body).
maxRosterStaff	Hingga 30 staf aktif via POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT jika terlampaui.
allowedGranularities	[60, 15] — slot 15 menit adalah fitur berbayar; 60 menit juga didukung.
maxPayloadBytes	524288 (512 KiB) UTF-8 kecuali batas lebih tinggi diberikan.
strictUnknownRootKeys	true — kunci tingkat atas atau di staff yang tidak dikenal ditolak

Kebutuhan kepala per sel tetap bilangan bulat 0 hingga 15. Melebihi batas frekuensi permintaan dapat mengembalikan respons error.

Saat mode ketat aktif, hanya kunci tingkat atas berikut yang diterima. Kunci lain mengembalikan UNKNOWN_FIELD.

apiVersion
timeZone
scheduleStartDate
scheduleEndDate
timeRangeStart
timeRangeEnd
slotGranularityMinutes
requirementsByCell
staff

Payload mengikuti model permintaan jadwal publik berbayar: tanggal kalender, zona waktu, grid slot (60 atau 15 menit di API berbayar), kebutuhan per sel, dan ketersediaan staf. Yurisdiksi hukum kerja, flag optimasi berbayar, dan field hukum kerja tingkat staf bukan bagian JSON — server menulis default pada baris induk SCHEDULE_CONDITION saat menyimpan (lihat «Hukum kerja & flag berbayar»). Jangan sertakan kunci DynamoDB atau tipe entitas internal di body.

apiVersion — Opsional. Jika ada, hanya string versi skema yang didukung.
Format cellKey — Kunci di requirementsByCell dan availableCells harus cocok dengan `${date}__${slotId}` dengan date YYYY-MM-DD dalam rentang dan slotId dari slot yang dihitung untuk rentang waktu dan granularitas Anda (sama seperti `cellKey` di helper playground).

timeZone
Tipe
string
Wajib
Ya
Zona waktu IANA untuk menafsirkan tanggal dan slot.
scheduleStartDate / scheduleEndDate
Tipe
string (YYYY-MM-DD)
Wajib
Ya
Rentang kalender inklusif; mulai ≤ akhir.
timeRangeStart / timeRangeEnd
Tipe
string (HH:mm)
Wajib
Ya
Rentang jam dinding yang mendefinisikan kolom slot; harus menghasilkan setidaknya satu slot.
slotGranularityMinutes
Tipe
60 | 15
Wajib
Ya
API berbayar: 60 (per jam) atau 15 (15 menit). Harus ada di allowedGranularities.
requirementsByCell
Tipe
object
Wajib
Ya
Kunci = cellKey di grid yang dihitung; nilai = bilangan bulat 0–15.
staff
Tipe
array
Wajib
Ya
Tidak kosong; ukuran maks. sesuai batas; setiap item: staffId, displayName, availableCells opsional.

Field	Tipe	Wajib	Catatan
timeZone	string	Ya	Zona waktu IANA untuk menafsirkan tanggal dan slot.
scheduleStartDate / scheduleEndDate	string (YYYY-MM-DD)	Ya	Rentang kalender inklusif; mulai ≤ akhir.
timeRangeStart / timeRangeEnd	string (HH:mm)	Ya	Rentang jam dinding yang mendefinisikan kolom slot; harus menghasilkan setidaknya satu slot.
slotGranularityMinutes	60 \| 15	Ya	API berbayar: 60 (per jam) atau 15 (15 menit). Harus ada di allowedGranularities.
requirementsByCell	object	Ya	Kunci = cellKey di grid yang dihitung; nilai = bilangan bulat 0–15.
staff	array	Ya	Tidak kosong; ukuran maks. sesuai batas; setiap item: staffId, displayName, availableCells opsional.

Referensi field (nilai yang diizinkan)

Bagian berikut mencerminkan validator di `app/lib/public-schedule-api/validate.ts` dan sanitiser di `sanitize.ts`, dengan default berbayar dari `PUBLIC_SCHEDULE_SUBMIT_DEFAULTS` kecuali opsi diberikan. Kirim angka JSON sebagai angka sebenarnya (bukan string). Setelah validasi, `build-schedule-transact-items.ts` menambahkan field baris induk (salinan optimasi berbayar, yurisdiksi hukum kerja, versi model) yang bukan kunci permintaan — lihat «Hukum kerja & flag berbayar».

Nilai yang diizinkan

Dihilangkan: diterima (perilaku terbaru).
Jika ada, harus tepat "2026-04-01" (PUBLIC_SCHEDULE_API_VERSION).
String lain ditolak (TYPE_ERROR).

Perilaku

Dibandingkan setelah penanganan setara trim di sanitizeApiVersion.

Error umum

TYPE_ERRORNilai apiVersion tidak didukung.

Nilai yang diizinkan

Format satu string. API TIDAK menerbitkan enum tertutup semua zona: server memvalidasi secara dinamis.
Validasi cocok dengan `isValidIanaTimeZone`: Luxon `DateTime.now().setZone(zone).isValid` harus true.
Gunakan pengidentifikasi IANA kanonik, mis. `Asia/Tokyo`, `America/New_York`, `Europe/Berlin`, `UTC`.
Jangan mengandalkan hanya singkatan (`EST`, `JST`, `GMT`) — bukan ID zona IANA yang stabil dan mungkin ditolak.
Daftar referensi: distribusi IANA (https://www.iana.org/time-zones) atau API zona waktu platform Anda.

Perilaku

Digunakan dengan tanggal dan waktu slot dalam normalisasi hilir.
Jika perlu daftar tetap di klien, turunkan dari aturan yang sama (ID IANA), jangan mengharapkan enum server di skema JSON.

Error umum

INVALID_TIME_ZONEHilang, kosong, atau zona IANA tidak valid.

Nilai yang diizinkan

Harus cocok /^\d{4}-\d{2}-\d{2}$/ (setelah trim).
Tanggal kalender nyata; rentang inklusif harus menghasilkan setidaknya satu hari melalui enumerateDates.
Jumlah hari dalam rentang tidak boleh melebihi maxScheduleDays (API berbayar biasanya hingga 14 hari; batas pasti = hak penyewa).

Perilaku

scheduleStartDate harus pada atau sebelum scheduleEndDate.

Error umum

INVALID_DATE_RANGEFormat buruk, tanggal tidak valid, atau rentang kosong.
SCHEDULE_SPAN_TOO_LONGLebih dari maxScheduleDays hari.

Nilai yang diizinkan

String tidak kosong (trim) diinterpretasikan dengan enumerasi slot yang sama seperti UI (`enumerateSlotsByGranularity`).
Pasangan harus menghasilkan setidaknya satu slot; jika tidak, validasi gagal.

Perilaku

Bersama slotGranularityMinutes, mendefinisikan nilai slotId untuk cellKey.

Error umum

INVALID_TIME_RANGENilai hilang atau nol slot untuk rentang.

Nilai yang diizinkan

Harus tepat 60 atau 15 (bukan string).
Juga harus muncul di allowedGranularities. Di API berbayar keduanya biasanya diaktifkan; jika 15 dinonaktifkan untuk penyewa Anda, INVALID_GRANULARITY.

Perilaku

Mendefinisikan jumlah slot bersama rentang waktu.

Error umum

INVALID_GRANULARITYBukan 60/15, atau tidak diizinkan untuk paket.

Nilai yang diizinkan

Harus objek JSON biasa (bukan array).
Setiap kunci harus cellKey di grid yang diharapkan (tanggal × slotIds). Kunci tidak dikenal → UNKNOWN_CELL_KEY.
Setiap nilai harus angka JSON, bilangan bulat, antara 0 dan 15 inklusif.
Sel yang dihilangkan diperlakukan sebagai kebutuhan 0 (hanya sel dengan kebutuhan ≥ 1 ikut SHORTFALL).

Perilaku

Kunci dibandingkan setelah trim melalui sanitizeCellKey.

Error umum

INVALID_REQUIREMENTSBukan objek atau nilai numerik tidak valid untuk kunci.
UNKNOWN_CELL_KEYKunci tidak dalam grid tanggal × slot yang dihitung.

Nilai yang diizinkan

Panjang antara 1 dan maxStaffPerSchedule (default 500 untuk POST /v1/schedule; terpisah dari batas roster POST /v1/staff).
Setiap elemen harus objek biasa dengan kunci yang diizinkan saja: staffId, displayName, availableCells (mode ketat).
staffId dan displayName harus lulus sanitasi (lihat bagian Sanitasi).
staffId harus unik di array (DUPLICATE_STAFF_ID).

Perilaku

Urutan dipertahankan untuk penghitungan ketersediaan.

Error umum

INVALID_STAFFArray kosong, terlalu banyak baris, objek buruk, atau sanitasi gagal.
UNKNOWN_FIELDKunci ekstra pada objek staff dalam mode ketat.
DUPLICATE_STAFF_IDstaffId yang sama dua kali.

Nilai yang diizinkan

Jika dihilangkan: staf dianggap tersedia di semua sel grid (implementasi memakai null «semua sel»).
Jika ada: harus array JSON string; setiap string tidak kosong harus cellKey di grid yang diharapkan.
String kosong dalam array tidak valid (INVALID_AVAILABLE_CELL).

Pemeriksaan SHORTFALL

Untuk setiap sel dengan kebutuhan ≥ 1, jumlah staf yang dihitung tersedia harus ≥ kebutuhan, jika tidak SHORTFALL_CELLS.

Error umum

INVALID_AVAILABLE_CELLKunci sel tidak dikenal atau entri kosong.
SHORTFALL_CELLSStaf tidak cukup untuk kebutuhan sel.

Yang disimpan API pada baris induk

API publik hanya menerima ROOT_KEYS di tingkat atas dan STAFF_KEYS pada setiap objek staf. Jangan kirim laborLawJurisdiction, usLaborStateCode, laborModelVersion, atau paidOptimization.
Saat mengirim, server mengatur SCHEDULE_CONDITION induk dari default bersama: paidOptimization = DEFAULT_PAID_OPTIMIZATION — laborLawCompliance false; balanceStaffLoad, honorShiftWishes, dan preferConsecutiveShifts true (lihat schedule-defaults-shared.ts dan build-schedule-transact-items.ts). laborLawJurisdiction JP, usLaborStateCode GENERIC, laborModelVersion v1.
Kendala hukum kerja bergaya undang-undang di optimizer memerlukan flag kepatuhan induk dan per staf aktif; jalur ini mematikannya — jangan harap batas undang-undang hanya dari JSON ini.
Model hukum kerja adalah perkiraan untuk penjadwalan, bukan nasihat hukum. Katalog: optimizer/config/labor_models.json.

Dokumentasi

Detail lengkap: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §2.1.1 dan §3.1.

Jika mengirim kunci yang dilarang

UNKNOWN_FIELDMode ketat menolak properti root atau staff yang tidak dikenal.

Diterapkan sebelum atau selama validasi seperti di `sanitize.ts`. Menjelaskan penolakan INVALID_STAFF.

staffId

Trim; panjang 1–128.
Karakter harus cocok /^[a-zA-Z0-9._-]+$/ (tanpa garis miring atau backslash).

displayName

Hapus karakter kontrol dan zero-width; rapatkan spasi; trim.
Kurung sudut < dan > tidak diizinkan.
Maks. 128 karakter setelah sanitasi; tidak boleh kosong.

Kunci sel (requirements / availableCells)

Kunci di-trim; harus cocok persis dengan string cellKey di grid yang dihitung.

202 Accepted

Body lolos validasi dan kondisi ditulis; optimasi dapat berlanjut secara asinkron. Handler dapat mengembalikan JSON dengan conditionId dan field terkait.

Error validasi mengembalikan informasi terstruktur dengan `code` yang stabil. Parsing sebelum validasi (INVALID_JSON, PAYLOAD_TOO_LARGE). Kegagalan persistensi dapat muncul sebagai DYNAMODB_ERROR. PATCH /v1/schedule-defaults dapat mengembalikan SCHEDULE_DEFAULTS_SAVE_FAILED (HTTP 400) dengan detail.

INVALID_JSON
Body bukan JSON yang valid.
PAYLOAD_TOO_LARGE
Panjang byte UTF-8 melebihi maxPayloadBytes (default 512 KiB).
TYPE_ERROR
Tipe JSON salah atau string apiVersion tidak didukung.
UNKNOWN_FIELD
Mode ketat: properti tidak diizinkan pada root atau objek staff.
INVALID_TIME_ZONE
timeZone hilang atau bukan nama IANA yang valid.
INVALID_DATE_RANGE
Tanggal bukan YYYY-MM-DD, rentang tidak valid, atau enumerasi kosong.
SCHEDULE_SPAN_TOO_LONG
Terlalu banyak hari antara mulai dan akhir (lihat maxScheduleDays).
INVALID_TIME_RANGE
Rentang waktu hilang atau menghasilkan nol slot.
INVALID_GRANULARITY
slotGranularityMinutes bukan 60/15 atau tidak diizinkan paket.
INVALID_REQUIREMENTS
requirementsByCell bukan objek atau hitungan bukan bilangan bulat 0–15.
UNKNOWN_CELL_KEY
Kunci tidak dalam grid jadwal yang dihitung.
INVALID_STAFF
staff kosong, terlalu besar, baris buruk, atau sanitasi gagal.
DUPLICATE_STAFF_ID
Nilai staffId duplikat.
INVALID_AVAILABLE_CELL
Entri kosong atau tidak dikenal di availableCells.
SHORTFALL_CELLS
Ketersediaan staf tidak cukup vs kebutuhan.
DYNAMODB_ERROR
Error sementara atau persistensi setelah validasi (tergantung handler).
SCHEDULE_DEFAULTS_SAVE_FAILED
PATCH /v1/schedule-defaults: validasi atau aturan bisnis gagal (lihat error.details).
LABOR_COMPLIANCE_REQUIRED
PATCH /v1/staff/{staffId}: laborConstraintMask dikirim saat laborLawCompliance false.

Kode	Arti
INVALID_JSON	Body bukan JSON yang valid.
PAYLOAD_TOO_LARGE	Panjang byte UTF-8 melebihi maxPayloadBytes (default 512 KiB).
TYPE_ERROR	Tipe JSON salah atau string apiVersion tidak didukung.
UNKNOWN_FIELD	Mode ketat: properti tidak diizinkan pada root atau objek staff.
INVALID_TIME_ZONE	timeZone hilang atau bukan nama IANA yang valid.
INVALID_DATE_RANGE	Tanggal bukan YYYY-MM-DD, rentang tidak valid, atau enumerasi kosong.
SCHEDULE_SPAN_TOO_LONG	Terlalu banyak hari antara mulai dan akhir (lihat maxScheduleDays).
INVALID_TIME_RANGE	Rentang waktu hilang atau menghasilkan nol slot.
INVALID_GRANULARITY	slotGranularityMinutes bukan 60/15 atau tidak diizinkan paket.
INVALID_REQUIREMENTS	requirementsByCell bukan objek atau hitungan bukan bilangan bulat 0–15.
UNKNOWN_CELL_KEY	Kunci tidak dalam grid jadwal yang dihitung.
INVALID_STAFF	staff kosong, terlalu besar, baris buruk, atau sanitasi gagal.
DUPLICATE_STAFF_ID	Nilai staffId duplikat.
INVALID_AVAILABLE_CELL	Entri kosong atau tidak dikenal di availableCells.
SHORTFALL_CELLS	Ketersediaan staf tidak cukup vs kebutuhan.
DYNAMODB_ERROR	Error sementara atau persistensi setelah validasi (tergantung handler).
SCHEDULE_DEFAULTS_SAVE_FAILED	PATCH /v1/schedule-defaults: validasi atau aturan bisnis gagal (lihat error.details).
LABOR_COMPLIANCE_REQUIRED	PATCH /v1/staff/{staffId}: laborConstraintMask dikirim saat laborLawCompliance false.

{
  "apiVersion": "2026-04-01",
  "timeZone": "Asia/Tokyo",
  "scheduleStartDate": "2026-04-07",
  "scheduleEndDate": "2026-04-13",
  "timeRangeStart": "08:00",
  "timeRangeEnd": "20:00",
  "slotGranularityMinutes": 60,
  "requirementsByCell": {
    "2026-04-07__slot-0": 2
  },
  "staff": [
    {
      "staffId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Example",
      "availableCells": ["2026-04-07__slot-0"]
    }
  ]
}

Bacaan lanjutan. Paket & fitur berbayar: docs/architecture/NURSE_SCHEDULING_SERVICE_SPECIFICATION.md. Isi permintaan POST /v1/schedule: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §1–§11. Isi permintaan PATCH default penyewa: berkas yang sama §12. Kode: app/lib/public-schedule-api/, app/features/schedule-settings/schedule-defaults-actions.ts, app/lib/public-api-write/weekly-shift-wish-tenant.ts. Penerapan: docs/aws/CDK_DEPLOY.md.

Referensi API pengembang (berbayar)

Metode

Jalur

Deskripsi

GET

{baseUrl}/v1/schedule-results

Mendaftar baris induk SCHEDULE_RESULT: conditionId, status, candidateCount, createdAt/updatedAt, dll. Paginasi baris induk DynamoDB.

GET

{baseUrl}/v1/schedule-results/history

Pencarian riwayat hasil jadwal (sama seperti browser). from / to (ISO 8601, default awal layanan hingga sekarang), keyword, eventName (INSERT,MODIFY,REMOVE dipisah koma), limit, cursor. Menggabungkan data terbaru dan arsip otomatis; hanya items / nextCursor.

GET

{baseUrl}/v1/schedule-results/{conditionId}

Mengambil satu baris induk SCHEDULE_RESULT menurut conditionId (atribut JSON; PK/SK dihilangkan).

GET

{baseUrl}/v1/schedule-results/{conditionId}/resolution

Output optimasi terselesaikan: status, candidates, confirmedAssignments jika ada. Jika status completed dan belum dikonfirmasi, rank-1 dapat dikonfirmasi otomatis pada GET ini (efek samping). Gunakan POST …/confirm-assignments untuk konfirmasi manual.

GET

{baseUrl}/v1/schedule-results/{conditionId}/review

Payload tinjauan untuk konfirmasi manual (kandidat, requiredByCellKey, allowedCellKeys staf, dll.).

GET

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context

Konteks shift darurat (tanggal kalender, staf, slot). Langganan berbayar diperlukan; null jika kondisi tidak ada.

GET

{baseUrl}/v1/schedule-conditions

Daftar baris induk SCHEDULE_CONDITION (conditionId, tanggal, publicApiCancelledAt opsional).

GET

{baseUrl}/v1/schedule-conditions/{conditionId}

Baris induk kondisi plus reqDays dan staffSnapshots (tanpa PK/SK).

GET

{baseUrl}/v1/schedule-defaults

Baris default jadwal penyewa (SCHEDULE_DEFAULTS) atau null jika belum disimpan.

GET

{baseUrl}/v1/schedule-actual/{conditionId}

Baris SCHEDULE_ACTUAL penugasan aktual, atau null jika tidak ada.

GET

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Baris keinginan shift mingguan staf, atau null jika tidak ada.

GET

{baseUrl}/v1/staff

Mendaftar staf aktif penyewa (diurut menurut nama tampilan).

GET

{baseUrl}/v1/staff/{staffId}

Mengambil satu anggota staf menurut staffId termasuk detail ketenagakerjaan (laborLawCompliance, laborFlsaExempt, batas pribadi, laborConstraintMask). Soft delete → 404.

Metode

Jalur

Deskripsi

PATCH

{baseUrl}/v1/schedule-defaults

Menyimpan default jadwal penyewa (body selaras saveSchema di schedule-defaults-actions). Field berbayar mengikuti langganan Anda.

POST

{baseUrl}/v1/staff

Membuat anggota staf (displayName). Mengembalikan 201 dengan JSON staff.

POST

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift

Mengkloning jadwal sumber yang selesai dengan absensi diterapkan; mengembalikan 201 dengan conditionId. Langganan berbayar diperlukan.

POST

{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments

Memvalidasi dan menyimpan penugasan yang diedit manual (200 dengan { ok: true }).

PATCH

{baseUrl}/v1/staff/{staffId}

Memperbarui displayName dan detail ketenagakerjaan (laborLawCompliance, laborFlsaExempt, batas pribadi, laborConstraintMask).

DELETE

{baseUrl}/v1/staff/{staffId}

Soft delete anggota staf (mengatur deletedAt).

DELETE

{baseUrl}/v1/schedule-conditions/{conditionId}

Menandai kondisi dibatalkan (publicApiCancelledAt); tidak menghapus baris anak.

PUT

{baseUrl}/v1/schedule-actual/{conditionId}

Menyimpan penugasan aktual JSON { "assignments": [ ... ] } (divalidasi terhadap grid kondisi).

PUT

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Mengganti keinginan mingguan: grid penuh (1–7 hari), wishByCellKey per sel (NONE|LOW|HIGH); granularitas dari default penyewa.

type

When

schedule.result.terminal

Schedule result status becomes completed, no_solution, failed, error, or canceled

{ "type": "schedule.result.terminal", "conditionId": "019ee481-e855-7000-abd8-977cbfd64ffc", "status": "completed", "occurredAt": "2026-07-16T13:00:54.694Z", "links": { "result": "{baseUrl}/v1/schedule-results/019ee481-e855-7000-abd8-977cbfd64ffc" } }

Header

Description

Content-Type

application/json

User-Agent

AutoScheduler-Webhook/1.0

X-AutoScheduler-Timestamp

Unix seconds as a string

X-AutoScheduler-Signature

v1=<hex> (see verification below)

Header

Deskripsi

x-api-key

Kunci API terikat ke langganan berbayar Anda (mengidentifikasi penyewa dan batas paket).

Content-Type

application/json

Pengaturan

API berbayar (tipikal)

Model penagihan

Langganan Stripe; biaya produk biasanya mengikuti jumlah kursi staf terdaftar sesuai halaman harga (bukan tagihan per panggilan API).

maxScheduleDays

Hingga 14 hari kalender per pengiriman untuk perencanaan detail dua minggu standar (rentang lebih lebar hanya jika kontrak mengizinkan).

maxStaffPerSchedule

Hingga 500 baris staff per POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; staffId inline di body).

maxRosterStaff

Hingga 30 staf aktif via POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT jika terlampaui.

allowedGranularities

[60, 15] — slot 15 menit adalah fitur berbayar; 60 menit juga didukung.

maxPayloadBytes

524288 (512 KiB) UTF-8 kecuali batas lebih tinggi diberikan.

strictUnknownRootKeys

true — kunci tingkat atas atau di staff yang tidak dikenal ditolak

Field

Tipe

Wajib

Catatan

timeZone

string

Zona waktu IANA untuk menafsirkan tanggal dan slot.

scheduleStartDate / scheduleEndDate

string (YYYY-MM-DD)

Rentang kalender inklusif; mulai ≤ akhir.

timeRangeStart / timeRangeEnd

string (HH:mm)

Rentang jam dinding yang mendefinisikan kolom slot; harus menghasilkan setidaknya satu slot.

slotGranularityMinutes

60 | 15

API berbayar: 60 (per jam) atau 15 (15 menit). Harus ada di allowedGranularities.

requirementsByCell

object

Kunci = cellKey di grid yang dihitung; nilai = bilangan bulat 0–15.

staff

array

Tidak kosong; ukuran maks. sesuai batas; setiap item: staffId, displayName, availableCells opsional.

Referensi field (nilai yang diizinkan)

Kode

Arti

INVALID_JSON

Body bukan JSON yang valid.

PAYLOAD_TOO_LARGE

Panjang byte UTF-8 melebihi maxPayloadBytes (default 512 KiB).

TYPE_ERROR

Tipe JSON salah atau string apiVersion tidak didukung.

UNKNOWN_FIELD

Mode ketat: properti tidak diizinkan pada root atau objek staff.

INVALID_TIME_ZONE

timeZone hilang atau bukan nama IANA yang valid.

INVALID_DATE_RANGE

Tanggal bukan YYYY-MM-DD, rentang tidak valid, atau enumerasi kosong.

SCHEDULE_SPAN_TOO_LONG

Terlalu banyak hari antara mulai dan akhir (lihat maxScheduleDays).

INVALID_TIME_RANGE

Rentang waktu hilang atau menghasilkan nol slot.

INVALID_GRANULARITY

slotGranularityMinutes bukan 60/15 atau tidak diizinkan paket.

INVALID_REQUIREMENTS

requirementsByCell bukan objek atau hitungan bukan bilangan bulat 0–15.

UNKNOWN_CELL_KEY

Kunci tidak dalam grid jadwal yang dihitung.

INVALID_STAFF

staff kosong, terlalu besar, baris buruk, atau sanitasi gagal.

DUPLICATE_STAFF_ID

Nilai staffId duplikat.

INVALID_AVAILABLE_CELL

Entri kosong atau tidak dikenal di availableCells.

SHORTFALL_CELLS

Ketersediaan staf tidak cukup vs kebutuhan.

DYNAMODB_ERROR

Error sementara atau persistensi setelah validasi (tergantung handler).

SCHEDULE_DEFAULTS_SAVE_FAILED

PATCH /v1/schedule-defaults: validasi atau aturan bisnis gagal (lihat error.details).

LABOR_COMPLIANCE_REQUIRED

PATCH /v1/staff/{staffId}: laborConstraintMask dikirim saat laborLawCompliance false.

{ "apiVersion": "2026-04-01", "timeZone": "Asia/Tokyo", "scheduleStartDate": "2026-04-07", "scheduleEndDate": "2026-04-13", "timeRangeStart": "08:00", "timeRangeEnd": "20:00", "slotGranularityMinutes": 60, "requirementsByCell": { "2026-04-07__slot-0": 2 }, "staff": [ { "staffId": "550e8400-e29b-41d4-a716-446655440000", "displayName": "Example", "availableCells": ["2026-04-07__slot-0"] } ] }

Referensi API pengembang (berbayar)

Cakupan dokumentasi ini

Langganan & akses

Autentikasi

Endpoint

Cara memanggil (mulai cepat)

Contoh curl (bash / macOS / Linux / WSL)

API baca (GET)

API tulis (PATCH / POST / PUT / DELETE)

Completion webhooks

Setup

Events

Request body

Request headers

Signature verification

Retries

Header

Header respons

Batas tingkat berbayar (hak)

Kunci root yang diizinkan (mode ketat)

Body permintaan (ringkasan)

Tabel referensi cepat

Referensi field (nilai yang diizinkan)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Hukum kerja & optimasi berbayar (tidak di body JSON)

Aturan sanitasi

Respons sukses

Daftar kode error (lengkap)

Contoh JSON minimal

Referensi API pengembang (berbayar)

Cakupan dokumentasi ini

Langganan & akses

Autentikasi

Endpoint

Cara memanggil (mulai cepat)

Contoh curl (bash / macOS / Linux / WSL)

API baca (GET)

API tulis (PATCH / POST / PUT / DELETE)

Completion webhooks

Setup

Events

Request body

Request headers

Signature verification

Retries

Header

Header respons

Batas tingkat berbayar (hak)

Kunci root yang diizinkan (mode ketat)

Body permintaan (ringkasan)

Tabel referensi cepat

Referensi field (nilai yang diizinkan)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Hukum kerja & optimasi berbayar (tidak di body JSON)

Aturan sanitasi

Respons sukses

Daftar kode error (lengkap)

Contoh JSON minimal