Bookings›Confirm a booking on behalf of the customer
Confirm a booking on behalf of the customer
Fires the customer-actor `confirm_booking` action from the BUSINESS surface (audited as business_on_behalf). Two uses: (1) LIVE — staff confirm a slot for a customer who booked by phone; (2) SANDBOX — the customer magic-token surface is live-only (a sandbox job's link can never reach a real customer), so this is the ONLY way to drive a sandbox test job past booking (book → quote → confirm → assign → complete). Body carries the customer-chosen scheduled_at (business-local naive datetime).
DECISION TABLE — every 409 this endpoint returns, and the correct NEXT STEP (branch on error_code, never on the HTTP status):
• JOB_REQUEST_STAGE_CONFLICT — the job changed since you read it (NOTE: every FAILED confirm attempt also bumps status_version by design). Next: re-GET the job, retry with the fresh status_version.
• JOB_REQUEST_ACTION_NOT_PENDING — the job is no longer at the confirm step (usually: already confirmed). Next: re-GET and show current status; do not retry.
• JOB_REQUEST_NO_TECHNICIAN_AVAILABLE — the TIME is infeasible for everyone (outside working hours / the customer window, or nobody qualifies). Next: pick another time via booking-windows / time-segments. NOT an emergency case — displacement cannot conjure capacity.
• JOB_REQUEST_TECH_INFEASIBLE — the FORCED technician can never take the job then; `data.reason` says why: cannot_arrive_in_time (commute/shift-start — `data.earliest_feasible_at` (RFC3339 UTC) is the first same-day time they CAN be on site → offer it) | missing_required_skills | not_available_today | not_lead_tier. Next: keep the tech and reschedule to earliest_feasible_at+, OR keep the time and drop technician_id (auto-pick) / choose another tech from time-segments. NOT an emergency case.
• JOB_REQUEST_P0_REQUIRES_DISPLACEMENT — the ONLY code that routes to the EMERGENCY flow: the job is P0, the tech qualifies, but the lane is genuinely occupied. Next: POST emergency/candidates → preview → commit (the commit auto-confirms). Caveat: if the occupying jobs are themselves P0 the preview will reject with EMERGENCY_RESCHEDULE_SLOT_OCCUPIED (P0 never displaces P0) — then pick another tech/time.
Arguments
idstringpathrequired
Job request ID
Idempotency-Keystringheaderoptional
Unique key making retries safe: a repeat send with the same key replays the original response (header Idempotent-Replayed: true) instead of re-running the operation. Reusing a key with a different body returns 422 IDEMPOTENCY_KEY_REUSE.
arrival_window_minutesintegerbodyoptional
ArrivalWindowMinutes = width (phút) của arrival-window ô khách bấm ở
slot-picker (chính là time_slot_step_minutes, mặc định 30). Persist để
post-confirm detail render lại đúng window. Optional; bounds ([5, 240],
khớp slot-picker step) validate ở usecase — single authority, một error
code (JOB_REQUEST_INVALID_INPUT).
scheduled_atstringbodyoptional
Chosen start time — business-local naive datetime, no offset (the business_time.datetime value from the time-segments picker). The server converts to UTC using the job's business timezone.
status_versionintegerbodyoptional
Optimistic-lock fence: the status_version from your last read. Omitted/0 = fence on the row's current version (no race protection).
technician_idstringbodyoptional
TechnicianID (BUSINESS confirm only — ignored on the customer surface):
force-assign the job to this technician instead of the ranked auto-pick.
Ranking is bypassed; feasibility (hours/time-off/geo/skills), the
TierLead rule and the double-booking guard still apply — an infeasible
forced tech rejects the confirm (P0 gets the displacement hint).
