간편 API와 기기 프로파일¶

Korail¶

Korail ¶

Korail(
    config: KorailConfig | None = None,
    *,
    transport: BaseTransport | None = None,
    validate_stations: bool = True,
)

일상적인 네 리소스를 제공하는 선택적 간편 클라이언트입니다.

client 속성에서 전체 KorailClient API에 접근할 수 있습니다. 컨텍스트 종료는 연결만 닫으며 서버 로그아웃은 별도로 호출해야 합니다.

logged_in ¶

logged_in(
    member_no: str,
    password: str,
    *,
    config: KorailConfig | None = None,
    transport: BaseTransport | None = None,
    validate_stations: bool = True,
) -> Korail

로그인 실패 시 연결을 닫고 원래 예외를 다시 발생시킵니다.

StationResource¶

StationResource ¶

StationResource(client: KorailClient)

역 목록을 클라이언트 수명 동안 캐시하고 이름을 검증합니다.

TrainResource¶

TrainResource ¶

TrainResource(
    client: KorailClient,
    stations: StationResource,
    *,
    validate_stations: bool,
)

KST datetime을 기존 열차 조회 조건으로 바꿉니다.

search ¶

search(
    departure: str,
    arrival: str,
    *,
    depart_after: datetime | None = None,
    passengers: KorailPassengerCounts | None = None,
    train_group_code: str = "109",
    include_srt: bool = False,
    include_nearby_stations: bool = False,
    peak_season: bool = False,
    continuation: TrainSearchContinuation | None = None,
) -> TrainSearchResult

직통 열차 한 페이지를 조회합니다. 결과의 next_page로 계속 조회하세요.

시간대가 없는 시각은 KST로 읽고, 시간대가 있으면 KST로 변환합니다. 과거 시각은 요청 전에 거절합니다. passengers는 기존 예약 입력 모델을 사용하며 생략하면 성인 한 명입니다.

ReservationResource¶

ReservationResource ¶

ReservationResource(client: KorailClient)

기존 예약 API의 결과와 안전 검사를 유지하는 짧은 진입점입니다.

create ¶

create(
    train: TrainSummary,
    *,
    passengers: KorailPassengerCounts | None = None,
    seat_class: KorailSeatClass = GENERAL,
    job_type: KorailReservationJobType = IMMEDIATE,
) -> ReservationHoldResponse

실제 미결제 홀드를 만듭니다. 결제 또는 취소는 호출자 책임입니다.

detail ¶

detail(
    hold: ReservationHoldResponse | str,
) -> TicketReservationDetailResponse

이미 생성된 예약을 별도 조회합니다. 생성 직후 자동 재조회하지 않습니다.

all ¶

all() -> ReservationHistoryResponse

기존 예약 이력 응답을 보존합니다.

cancel ¶

cancel(hold: ReservationHoldResponse) -> BaseKorailResponse

미결제 홀드의 가능 여부를 확인한 뒤 취소합니다.

pay ¶

pay(
    hold: ReservationHoldResponse, card: CardPayment
) -> ReservationPaymentResponse

카드를 실제 청구합니다. 서버 거절은 결과의 str_result로 확인하세요.

TicketResource¶

TicketResource ¶

TicketResource(client: KorailClient)

승차권 조회·환불의 기존 사전 확인 절차를 노출합니다.

refund_fee ¶

refund_fee(
    ticket: OriginalTicketReference,
) -> RefundCommissionResponse

실제 환불 없이 수수료를 조회합니다.

refund ¶

refund(
    ticket: PaidTicket,
    *,
    commission: RefundCommissionResponse,
) -> RefundTicketResponse

수수료 성공 응답을 받은 뒤 승차권 한 장을 실제 환불합니다.

KorailDeviceProfile¶

KorailDeviceProfile ¶

KorailDeviceProfile(
    device_id: str,
    model: str,
    android_release: str,
    build_id: str,
    android_sdk_int: int = KORAIL_DEFAULT_ANDROID_SDK_INT,
    width: int = KORAIL_DEFAULT_DEVICE_WIDTH,
    height: int = KORAIL_DEFAULT_DEVICE_HEIGHT,
)

호출자가 보유한 기기값입니다. device_id는 출력 표현에서 숨깁니다.

같은 계정으로 반복 실행한다면 같은 프로파일을 보관해 사용하세요. 이 객체는 자격 증명이나 세션을 담지 않으며, 실제 기기 여부를 검증하지 않습니다.

build_config_from_profile¶

build_config_from_profile ¶

build_config_from_profile(
    profile: KorailDeviceProfile,
    *,
    base: KorailConfig | None = None,
) -> KorailConfig

기기값을 DynaPath·대기열 UA·OS/화면 정보에 일관되게 적용합니다.

API User-Agent는 앱 관측값인 korailtalk를 유지합니다. 직접 지정한 토큰 공급자나 DynaPath 비활성화 설정은 덮어쓰지 않습니다.