예약·결제 모델¶
예약·결제·환불 메서드의 입력과 응답 모델입니다.
RefundTicketResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
settlement_method_codes: tuple[str, ...] = (),
settlement_list_is_null: bool = False,
)
Bases: BaseKorailResponse
승차권 환불 결과의 정산수단 코드를 담습니다.
응답의 정산 목록(stlList)이 null이면 settlement_method_codes는 빈 튜플이고 settlement_list_is_null이
True입니다. 정산 목록 키가 없으면 KorailProtocolError가 발생합니다.
StationRefundOriginalTicket(
pnr_no: str,
original_sale_date: str | None = None,
original_sale_window_no: str | None = None,
original_sale_sequence: str | None = None,
original_return_password: str | None = None,
ticket_kind_code: str | None = None,
refund_division_code: str | None = None,
refund_reason_code: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
)
역에서 발권한 승차권의 환불 확인 응답에 들어 있는 원표 한 행을 담습니다.
StationRefundVerificationRequest(
customer_name: str,
return_no_1: str,
return_no_2: str,
return_no_3: str,
return_no_4: str,
)
역에서 발권한 승차권의 환불 확인에 필요한 이름과 반환 식별자를 구성합니다.
return_no_1~return_no_4에는 반환번호 네 칸을 차례로 넣습니다. 모든 필드는 비어 있지 않은
문자열이어야 하며, 아니면 KorailProtocolError가 발생합니다.
StationRefundVerificationResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
received_amount: str | None = None,
refund_fee: str | None = None,
refund_amount: str | None = None,
popup_message: str | None = None,
result_message: str | None = None,
original_tickets: tuple[
StationRefundOriginalTicket, ...
] = (),
original_ticket_list_is_null: bool = False,
)
Bases: BaseKorailResponse
역에서 발권한 승차권의 환불 확인 결과(금액과 원표 목록)를 담습니다.
서버가 원표 목록을 null로 보내면 original_tickets는 빈 튜플이고 original_ticket_list_is_null이
True입니다.
StationRefundExecutionRequest(
pnr_no: str,
original_sale_date: str,
original_sale_window_no: str,
original_sale_sequence: str,
original_return_password: str,
refund_division_code: str,
refund_reason_code: str,
ticket_kind_code: str,
customer_phone: str,
refund_amount: str,
refund_fee: str,
customer_name: str,
)
역에서 발권한 승차권의 환불 실행 입력을 구성합니다.
보통 from_verification으로 환불 확인 결과에서 만듭니다. 만들기만 해서는 요청을 보내지 않으며, 실제 환불은
KorailClient.execute_station_ticket_refund를 호출해야 합니다. 모든 필드는 비어 있지 않은 문자열이어야 하며,
아니면 KorailProtocolError가 발생합니다.
from_verification(
verification: StationRefundVerificationResponse,
*,
customer_phone: str,
customer_name: str,
) -> StationRefundExecutionRequest
환불 확인 응답의 첫 원표와 확인된 환불액·수수료로 실행 입력을 만듭니다.
확인 응답이 성공("SUCC")이 아니거나 원표가 없거나 옮겨 담을 값이 비어 있으면 KorailProtocolError가
발생합니다.
KorailPassengerCounts(
adult: int = 1,
teenager: int = 0,
child: int = 0,
infant: int = 0,
senior: int = 0,
severe_disability: int = 0,
mild_disability: int = 0,
guide_dog: int = 0,
)
승객 종류별 예약 인원을 구성합니다.
인원이 0인 승객 종류는 요청에 싣지 않습니다. 유아·안내견을 포함한 전체 인원은 1~9명이어야 합니다. 인원에 음수나 정수가
아닌 값이 있거나 전체 인원이 이 범위를 벗어나면 KorailProtocolError가 발생합니다.
호차 번호와 좌석 식별자로 좌석 지정 입력을 구성합니다.
seat_no에는 좌석 재고 응답의 seat_no를 그대로 넣으세요. 보통 from_inventory로 만듭니다. car_no는 1
이상의 정수, seat_no는 비어 있지 않은 문자열이어야 하며, 아니면 KorailProtocolError가 발생합니다.
from_inventory(
inventory: SeatInventoryResponse, seat: PhysicalSeat
) -> KorailSeatAssignment
좌석 재고 응답과 그 응답의 판매 가능한 좌석으로 좌석 지정 입력을 만듭니다.
inventory.car_no가 없으면 이 메서드를 쓸 수 없으므로 KorailSeatAssignment(car_no=..., seat_no=...)로 직접
만드세요. 호차 번호가 없거나, seat이 inventory.seats에 없거나, seat.sale_possible이 "Y"가 아니면
KorailProtocolError가 발생합니다.
ReservationJourney(
journey_sequence: str | None = None,
reservation_change_no: str | None = None,
departure_date: str | None = None,
departure_time: str | None = None,
arrival_date: str | None = None,
arrival_time: str | None = None,
departure_station_code: str | None = None,
arrival_station_code: str | None = None,
train_no: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
)
ReservationHoldResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
pnr_no: str | None = None,
journey_count: str | None = None,
window_no: str | None = None,
temporary_job_sequence_1: str | None = None,
temporary_job_sequence_2: str | None = None,
payment_flag: str | None = None,
payment_message: str | None = None,
payment_deadline_message: str | None = None,
payment_deadline_notice: str | None = None,
payment_deadline_date: str | None = None,
payment_deadline_time: str | None = None,
total_fare: str | None = None,
total_price: str | None = None,
received_amount: str | None = None,
journeys: tuple[ReservationJourney, ...] = (),
total_discount_amount: str | None = None,
customer_management_no: str | None = None,
mandatory_message: str | None = None,
additional_service_flag: str | None = None,
disability_certificate_number: str | None = None,
pre_settlement_target_flag: str | None = None,
family_info_confirm_flag: str | None = None,
special_room_fare: str | None = None,
issue_possible_date: str | None = None,
issue_possible_time: str | None = None,
passengers: tuple[ReservationPassengerInfo, ...] = (),
payable: bool = True,
cart_addition: CartAddResponse | None = None,
)
Bases: BaseKorailResponse
홀드(결제 전 예약) 요청의 결과와 결제 기한·금액을 담습니다.
이 객체를 받았다는 것만으로 예약이 성공했다고 보장하지 않으므로 응답 상태(str_result)와 pnr_no를 확인하세요.
결제할 금액은 received_amount입니다.
h_pay_limit_msg 값입니다. 결제 기한은 이 필드가 아니라 payment_deadline_date와 payment_deadline_time에 있습니다.
결제 기한 날짜입니다. 앱은 이 값과 payment_deadline_time을 이어 붙여 결제 기한으로 표시합니다.
h_tot_fare 값입니다. 의미를 확인하지 못했습니다. 결제 금액으로는 received_amount를 쓰세요.
앱이 표시하는 합계 금액(h_tot_prc)입니다. 결제에는 received_amount를 쓰세요.
결제할 금액입니다. 좌석별 금액(h_rcvd_amt)의 합이며, 응답의 총액(h_tot_rcvd_amt)과 다르면 응답을 읽을 때 KorailProtocolError가 발생합니다. 좌석 행이 없으면 응답의 총액을 쓰고, 좌석 금액을 읽을 수 없으면 None입니다.
결제할 수 있는 홀드인지 나타냅니다. 예약대기(STANDBY)로 만든 홀드는 False이며, pay_with_card는 이런 홀드를 요청 전에 거절합니다.
cart_addition: CartAddResponse | None = None
recalculate_price(..., add_to_cart=True)로 받은 결과에만 장바구니 추가 결과가 들어갑니다. 장바구니 추가가 실패해도 예외 없이 이 필드에 담기므로 str_result를 확인하세요. 그 밖에는 None입니다.
ReservationPaymentCoupon(
certificate_password: str | None = None,
coupon_no: str | None = None,
management_close_date: str | None = None,
management_start_date: str | None = None,
ticket_return_no: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
)
결제 결과에 포함된 쿠폰 정보를 담습니다.
ReservationPaymentTicket(
ticket_sequence: str | None = None,
sale_date: str | None = None,
sale_sequence: str | None = None,
return_password: str | None = None,
return_no: str | None = None,
recipient_name: str | None = None,
discount_card_no: str | None = None,
ticket_price: str | None = None,
ticket_fare: str | None = None,
bz5_fare_discount_amount: str | None = None,
bz6_fare_discount_amount: str | None = None,
total_discount_amount: str | None = None,
total_received_amount: str | None = None,
standard_seat_price_fare: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
)
결제로 발권된 승차권 한 장의 식별자와 반환 식별자를 담습니다.
ReservationPaymentSettlement(
settlement_sequence: str | None = None,
settlement_type_code: str | None = None,
settlement_result: str | None = None,
transaction_division: str | None = None,
card_installment_count: str | None = None,
installment_months: str | None = None,
settlement_amount: str | None = None,
settlement_card_no: str | None = None,
card_company_code: str | None = None,
card_company_name: str | None = None,
approval_date: str | None = None,
approval_time: str | None = None,
approval_no: str | None = None,
point_division: str | None = None,
point_no: str | None = None,
point_approval_no: str | None = None,
remnant_amount: str | None = None,
remote_point: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
)
결제 결과의 정산수단 한 행을 담습니다.
카드번호·승인번호 같은 값이 들어 있을 수 있으므로 로그에 남길 때 주의하세요.
ReservationPaymentTableSeat(
room_class_name_1: str | None = None,
car_no_1: str | None = None,
seat_no_start_1: str | None = None,
seat_no_end_1: str | None = None,
seat_count_1: str | None = None,
group_name_1: str | None = None,
room_class_name_2: str | None = None,
car_no_2: str | None = None,
seat_no_start_2: str | None = None,
seat_no_end_2: str | None = None,
seat_count_2: str | None = None,
group_name_2: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
)
결제 결과에 포함된 두 구간 단체석 정보를 담습니다.
ReservationPaymentResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
image_ticket_flag: str | None = None,
reservation_no: str | None = None,
settlement_approval_no: str | None = None,
total_received_amount: str | None = None,
settlement_amount: str | None = None,
total_settlement_amount: str | None = None,
customer_no: str | None = None,
member_card_no: str | None = None,
buyer_name: str | None = None,
publication_start_no: str | None = None,
publication_end_no: str | None = None,
mixed_settlement_division: str | None = None,
cancellation_fee: str | None = None,
coupons: tuple[ReservationPaymentCoupon, ...] = (),
tickets: tuple[ReservationPaymentTicket, ...] = (),
settlements: tuple[
ReservationPaymentSettlement, ...
] = (),
table_seats: tuple[
ReservationPaymentTableSeat, ...
] = (),
window_no: str | None = None,
settlement_count: str | None = None,
discount_card_count: str | None = None,
total_price: str | None = None,
total_fare: str | None = None,
total_discount_amount: str | None = None,
adult_count: str | None = None,
child_count: str | None = None,
table_seat_count: str | None = None,
ticket_count: str | None = None,
settlement_type_code: str | None = None,
trade_division: str | None = None,
remark: str | None = None,
survey_flag: str | None = None,
survey_title: str | None = None,
survey_text: str | None = None,
survey_url: str | None = None,
)
Bases: BaseKorailResponse
카드 결제 시도의 발권·정산·좌석 결과를 담습니다.
PaidTicket(
pnr_no: str,
sale_date: str,
sale_window_no: str,
sale_sequence: str,
return_password: str,
train_no: str = "",
pbp_acceptance_target_flag: str | None = None,
)
환불할 발권 승차권 한 장의 PNR과 반환 식별자를 구성합니다.
보통 from_refund_detail로 승차권 상세 응답에서 만드세요. 환불 요청은 상세 응답의 판매일(sale_date)을 쓰고,
수수료 조회는 원표 반환일을 쓰므로 두 값을 섞어 쓰지 마세요. refund에는 이 값과 함께 get_refund_commission의
응답을 commission으로 넘겨야 합니다.
환불 요청의 판매일(h_orgtk_sale_dt)입니다. 재발행된 승차권은 원표의 판매일과 다를 수 있습니다. from_refund_detail로 만들면 상세 응답의 sale_date가 들어갑니다.
환불 요청에 함께 싣는 열차 번호입니다. 빈 문자열이면 보내지 않습니다. from_refund_detail은 따로 주지 않으면 첫 여정의 열차 번호를 넣습니다.
대리수령 대상 플래그입니다. refund의 pbp_acceptance_target_flag가 None일 때 이 값을 쓰며, 둘 다 None이면 보내지 않습니다.
from_refund_detail(
detail: RefundTicketDetailResponse,
*,
train_no: str = "",
) -> PaidTicket
승차권 상세 응답에서 환불 입력을 앱과 같은 방식으로 만듭니다.
train_no를 주지 않으면 첫 여정의 열차 번호를 씁니다. 상세 응답에 PNR, 판매일, 원표 창구번호·일련번호·반환
비밀번호 중 빈 값이 있으면 KorailProtocolError가 발생합니다.
DiscountCardSectionRequest(
run_date: str,
train_no: str,
departure_station_code: str,
arrival_station_code: str,
journey_type_code: str = "11",
)
구매할 N카드의 적용 구간을 구성합니다.
요청에는 구간마다 1부터 매긴 번호를 붙여 보냅니다.
2인용 N카드의 추가 사용자 정보를 구성합니다.
요청 키 이름은 앱 내부 값이 공개돼 있지 않아 확인하지 못했습니다.
DiscountCardPurchaseRequest(
card_kind_management_no: str,
customer_no: str,
validity_start_date: str = "",
usable_trip_count: str = "",
sections: tuple[DiscountCardSectionRequest, ...] = (),
additional_users: tuple[
DiscountCardAdditionalUser, ...
] = (),
)
N카드 구매에 필요한 구간·사용자·상품 정보를 구성합니다.
DiscountCardTicket(
sale_window_no: str,
sale_date: str,
sale_sequence: str,
return_password: str,
)
N카드 기간연장에 필요한 원표의 반환 식별자를 구성합니다.
DiscountCardPurchaseResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
lump_settlement_target_no: str | None = None,
discount_card_settlement_target_no: str | None = None,
received_amount: str | None = None,
stx_amount: str | None = None,
taxt_supply_amount: str | None = None,
usable_trip_count: str | None = None,
validity_start_date: str | None = None,
validity_end_date: str | None = None,
registered_card_kind_management_no: str | None = None,
)
Bases: BaseKorailResponse
N카드 구매의 결제 전 예약 결과를 담습니다.
응답에 담긴 카드 종류 관리번호입니다. 요청한 값은 DiscountCardPurchaseRequest.card_kind_management_no에 있습니다.
PriceRecalculationRow(
passenger_type_code: str,
room_class_code: str,
discount_kind_code: str,
requested_discount_code: str = "",
certificate_no: str = "",
family_sequence_no: str = "",
)
예약 할인 재계산에 사용할 승객 한 행을 구성합니다.
보통 PriceRecalculationRequest.for_hold가 홀드의 좌석마다 한 행씩 만듭니다. 값이 없는 칸은 None이 아니라
빈 문자열로 두세요. 모든 필드는 문자열이어야 하고 passenger_type_code, room_class_code,
discount_kind_code는 비어 있으면 안 됩니다. 이 검사는 요청을 보내기 전에 합니다.
홀드 좌석의 기존 할인 종류 코드(h_dcnt_knd_cd1)를 그대로 옮겨 담습니다. 새로 요청할 할인 코드(requested_discount_code)와 다른 값이므로 임의로 덮어쓰지 마세요.
PriceRecalculationRequest(
pnr_no: str,
rows: tuple[PriceRecalculationRow, ...] = (),
non_member_no: str | None = None,
cabin_class_code: str | None = None,
seat_attribute_code_2: str | None = None,
seat_attribute_code_4: str | None = None,
seat_attribute_code_5: str | None = None,
)
PNR 한 건의 할인 재계산 조건을 구성합니다.
보통 for_hold로 홀드에서 만듭니다. 비회원일 때만 non_member_no를 채우세요. 요청에 싣는 작업 구분 값과
비회원 구분 값은 앱 내부 값이 공개돼 있지 않아 확인하지 못했습니다.
비회원 고객번호입니다. 값이 있으면 비회원 구분과 함께 보내고, None이면 보내지 않습니다.
좌석 속성 코드 4번 칸(txtSeatAttCd4)입니다. 재계산 요청에서의 의미는 확인하지 못했습니다. None이면 보내지 않습니다.
for_hold(
hold: ReservationHoldResponse,
requested_discount_codes: Sequence[str],
) -> PriceRecalculationRequest
홀드의 첫 여정 좌석마다 한 행씩, 앱과 같은 방식으로 재계산 조건을 만듭니다.
좌석별 승객 유형·객실 등급·기존 할인 코드·증빙 번호를 옮겨 담으므로 requested_discount_codes는 첫 여정 좌석 수와
같은 개수여야 합니다. 홀드가 성공("SUCC")이 아니거나 PNR·좌석 행이 없거나 개수가 다르면 KorailProtocolError가
발생합니다.
CartDiscountAddition(
passenger_sequence_no: str | None = None,
duty_reference_recognition_division_code: str
| None = None,
raw: Mapping[str, object] = dict[str, object](),
)
장바구니 추가 결과의 승객별 할인 정보를 담습니다.
h_duty_ref_rcgn_ps_dv_cd 값입니다. 의미와 가능한 값을 확인하지 못했습니다.
CartAddResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
discount_additions: tuple[
CartDiscountAddition, ...
] = (),
)
홀드를 장바구니에 추가할 PNR 입력을 구성합니다.
PNR은 hidPnrNo로 보내며, 비어 있으면 요청을 보내기 전에 KorailProtocolError가 발생합니다.
SelfCheckInRegisterResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
message_id: str | None = None,
)
Bases: BaseKorailResponse
셀프 체크인 등록 결과를 담습니다.
message_id(msgId)는 null일 수 있으며 앱은 이 값을 쓰지 않습니다. 응답에 msgId 키가 없으면
KorailProtocolError가 발생합니다.
DeliveredTicketRetrievalResponse(
h_msg_cd: str | None = None,
h_msg_txt: str | None = None,
str_result: str | None = None,
raw: Mapping[str, object] = dict[str, object](),
process_flags: tuple[str, ...] = (),
)
Bases: BaseKorailResponse
대리수령으로 전달한 승차권을 회수한 결과를 담습니다.
process_flags에는 응답 행마다 처리 결과 플래그(prsFlg)가 들어 있습니다. 응답에 목록(prsList)이 없거나
행에 prsFlg가 없으면 KorailProtocolError가 발생합니다.