express-bus-booking

name	express-bus-booking
description	Search and assist Korean 고속버스/KOBUS bookings using official HTTP/API-first flows; use for 고속버스 예매, 시간표, 좌석 조회, 임시 선점, and official checkout-entry handoff.
license	MIT
metadata	{"category":"travel","locale":"ko-KR","phase":"v1"}

Express Bus Booking (KOBUS)

Overview

Use this skill for Korean 고속버스 / KOBUS timetable lookup and reservation assistance. The preferred workflow is HTTP/API-first: resolve routes, query timetables, inspect remaining seats and fares, and only use browser automation when endpoint discovery or an official web-only step blocks progress.

This skill is intentionally separate from 시외버스. KOBUS terminal codes, route structures, and checkout pages differ from Tmoney 시외버스. Use intercity-bus-booking for 시외버스/Tmoney flows.

When to Use

• The user asks for 고속버스 예매, 고속버스 시간표, 고속버스 예약, 프리미엄 고속버스, or 우등 고속버스.
• The route is clearly a KOBUS 고속버스 route or the user names KOBUS/코버스/고속버스통합예매.
• The user wants assisted reservation up to seat selection, temporary hold, or a payment-entry link.

Do not use this for:

• 시외버스/Tmoney routes — use intercity-bus-booking.
• Final card submission or payment without explicit, narrowly scoped confirmation.
• Blind browser automation before trying the official HTTP flow.

Core Principles

• Use official KOBUS surfaces: https://www.kobus.co.kr.
• Keep a cookie jar and reuse referers. Stateless one-off POSTs are less reliable.
• Prefer desktop User-Agent and HTTP/1.1 during probing if the server behaves differently under HTTP/2.
• Default scope is assisted manual checkout: lookup, candidate presentation, seat-stage readiness, temporary seat hold, and official payment-entry page handoff.
• Do not submit card fields, agree to terms, or complete payment unless the user explicitly confirms that exact action.

Known HTTP Flow

See references/kobus-http-flow.md for session-proven endpoint details and parameter examples.

1. Start a Session

Fetch either the main page or route/search page with cookies enabled:

GET https://www.kobus.co.kr/main.do
GET https://www.kobus.co.kr/mrs/rotinf.do

Use a realistic desktop User-Agent and a cookie jar.

2. Resolve Route / Terminal Candidates

POST /mrs/readRotLinInf.ajax

The response is JSON and can include rotInfList, tfrInfList, len, and codeYn. Prefer code-confirmed routes over display-name matching because terminal names are not always unique.

3. Query Timetable

POST /mrs/alcnSrch.do

Typical fields include:

deprCd=010
arvlCd=700
pathDvs=sngl
pathStep=1
deprDtm=YYYYMMDD
busClsCd=0
rtrpChc=1
timeLinkMin=00
timeLinkMax=23

Parse the returned HTML for schedule rows/cards and fnSatsChc(...) onclick arguments. Respect mrsPsbYn=N or any equivalent booking-disabled marker.

4. Enter Seat / Fare Stage

POST /mrs/satschc.do

Send the original search form fields plus selected values from fnSatsChc(...), commonly including:

deprTime
alcnDeprTime
alcnDeprTrmlNo
alcnArvlTrmlNo
indVBusClsCd
cacmCd
dcDvsCd
prvtBbizEmpAcmtRt
chldSftySatsYn
dsprSatsYn

The response should include form#satsChcFrm and hidden fare/seat values such as adltFee, rmnSatsNum, totSatsNum, and terminal/time fields.

5. Temporary Seat Hold

POST /mrs/setPcpy.ajax

Submit the satsChcFrm hidden fields plus selected seat/count fields. A successful response includes:

MSG_CD=S0000
pcpyNoAll
satsNoAll
ESTM_AMT
DC_AMT
TISSU_AMT

Treat the hold as short-lived. If testing, if the user does not proceed, or if a new seat is chosen, release it explicitly.

6. Release Temporary Hold

POST /mrs/cancPcpy.ajax

Use the same relevant form fields plus the returned pcpyNoAll and satsNoAll. A successful response returns MSG_CD=S0000.

Helper Script

Use the bundled helper for KOBUS lookup and optional temporary holds:

python3 express-bus-booking/scripts/kobus_express_booking.py \
  --depart-code 021 \
  --arrive-code 500 \
  --date 20260520 \
  --select-index 1 \
  --hold-first-seat \
  --output-dir /tmp/kobus-hold

For Seoul to Gwangju, the verified KOBUS route is 센트럴시티(서울) code 021 to 광주(유·스퀘어) code 500. A successful hold returns MSG_CD=S0000, pcpyNoAll, satsNoAll, fare amounts, and saves a local auto-submit helper for the official KOBUS payment-information page. Final card entry and payment remain manual. Cancel abandoned holds with /mrs/cancPcpy.ajax using the saved cancel fields.

Checkout-Entry Link Helper

A plain official checkout URL is not enough because KOBUS expects a POST body containing the selected schedule, seat, fare, and hold identifiers. The practical user-facing pattern is:

1. Create the temporary hold server-side via setPcpy.ajax.
2. Generate a short helper page that auto-submits a POST form to the official KOBUS checkout endpoint.
3. Send the helper link to the user.
4. The user completes card/payment fields manually on the official KOBUS page.

Desktop action:

https://www.kobus.co.kr/mrs/stplcfmpym.do

Mobile-friendly action:

https://www.kobus.co.kr/mrs/stplcfmpym.do?keep=/mrs/pay

The POST body should include the original seat form fields plus returned hold values such as pcpyNoAll, satsNoAll, estmAmt, dcAmt, tissuAmt, and nonMbrsYn=Y when using a non-member checkout flow.

Mobile Redirect Caveat

KOBUS common JavaScript can redirect narrow/mobile screens to /mblIdx.do unless location.href contains a mobile-allowed path fragment such as /mrs/pay. In testing, posting to:

/mrs/stplcfmpym.do?keep=/mrs/pay

preserved the same checkout POST body while making the final browser URL contain /mrs/pay, avoiding the client-side mobile-main redirect condition. Use this variant for Discord/mobile users, but still verify with the user because in-app browsers may add their own quirks.

If mobile still lands on the homepage, recommend opening the helper link in a normal external browser or desktop browser. Do not keep retrying holds indefinitely; cancel stale holds.

Suggested Output Format

Keep candidate lists concise and actionable:

고속버스 서울경부 → 부산 / 2026-05-09
1. 00:30 심야우등 / 천일고속 / 잔여 10석 / 성인 47,600원
2. 13:50 우등 / ...

When a hold/checkout helper is created, state that the next step opens the official KOBUS payment page and that payment remains manual.

For Discord/mobile, provide links as normal text links, not fenced code blocks, so the user can tap them directly.

Common Pitfalls

1. Mixing KOBUS and Tmoney codes. KOBUS terminal codes are not Tmoney 시외버스 terminal codes.
2. Assuming a cart exists. KOBUS does not expose a shopping-cart style hold list in the tested web flow. The realistic UX is temporary seat hold plus checkout-entry handoff.
3. Ignoring hold cleanup. Always cancel test holds or abandoned holds with cancPcpy.ajax.
4. Treating lookup success as payment permission. Lookup, seat-stage entry, and temporary hold are not authorization to submit payment.
5. Mobile homepage redirects. Use the ?keep=/mrs/pay helper action for mobile; otherwise KOBUS JS may send the user to /mblIdx.do.
6. Browser automation too early. Try direct HTTP first. Use browser tooling only to discover changed endpoints or verify final user-facing behavior.

Verification Checklist

• Route/terminal codes were resolved from KOBUS, not guessed.
• Timetable was queried with cookies and a realistic User-Agent.
• Candidate output includes date, departure/arrival terminals, time, class/operator when available, fare, and remaining seats.
• Seat-stage response contains expected hidden fields before attempting a hold.
• Temporary hold success was confirmed with MSG_CD=S0000 before sending a checkout helper link.
• Stale/test holds were cancelled with cancPcpy.ajax.
• Payment/card fields were left for the user unless they explicitly confirmed otherwise.
• Mobile helper links use the /mrs/pay marker variant when sent to mobile-heavy platforms.