korail-mobile-api 2.0.1__tar.gz

korail_mobile_api-2.0.1/CHANGELOG.md

@@ -0,0 +1,103 @@
+# 변경 이력
+
+## [2.0.1] - 2026-09-27
+
+코드는 2.0.0 과 같습니다.
+
+- PyPI 에 올립니다. `pip install korail-mobile-api` 로 설치할 수 있습니다.
+- README 의 이미지와 링크를 절대 주소로 바꿔 PyPI 페이지에서도 보이게 했습니다.
+- 오류 처리 문서에 로그인의 `-2000` 차단이 접속한 네트워크의 IP 대역 때문에도 생길 수 있다는 안내를 더했습니다.
+
+## [2.0.0] - 2026-09-26
+
+v1.1.1 이후의 변경입니다. 코레일+ 안드로이드 앱 7.0.6 기준이며, GitHub 릴리스로 공개하고 PyPI 에는 올리지 않습니다.
+v1.0.0~v1.1.1 의 기록은
+[v1.1.1 태그의 CHANGELOG](https://github.com/yakisoba0728/korail-mobile-api/blob/v1.1.1/CHANGELOG.md)에 있습니다.
+
+### 달라진 요청과 동작
+
+- 요청 필드를 앱 DTO 의 선언 순서로 보냅니다(`NetworkService.java:15335–15392`). 로그인, 예약 5종, 환불·수수료 조회
+  (공통 필드를 맨 뒤), 호차 조회, 승차권 목록, 병합 조회가 해당하고, 요금 재계산은 Retrofit 목록 순서입니다. `lang` 은 `Key` 뒤에 옵니다.
+- API 요청은 `User-Agent: korailtalk` 과 앱 OkHttp 기본 헤더(`Connection: Keep-Alive`, `Accept-Encoding: gzip`)를 보내고
+  `Accept` 는 보내지 않습니다.
+- 대기열 요청은 빈 본문 POST 에 안드로이드 기본 Dalvik User-Agent(`Build/…` 포함)를 싣고, 응답 코드와 TTL·대기 인원은
+  Java `Integer.parseInt` 처럼 읽습니다. 허용 범위 밖 노드는 무시하고 정문으로 진행·반납합니다.
+- DynaPath 토큰의 `rt` 에 요청 간 시간차(최근 5개)를 싣습니다. v1.1.1 은 `rt=0` 고정이었습니다.
+- 운임 조회는 상품번호가 없어도 `gdNo` 칸을 보냅니다.
+- 요청 전에 거절합니다: 카드 입력 형식, 0원·예약대기 홀드의 카드 결제, 수수료 조회 응답 없는 환불, 마일리지가 수수료보다 적은
+  마일리지 정산, 탑승 순서가 아닌 환승 구간, 운행일이 다른 병합 행, 공항버스 좌석 중복.
+- 좌석·호차·역의 선택 필드 18개가 빠지면 앱 기본값으로 읽습니다. 봉투와 String 필드의 JSON 정수는 문자열로 읽습니다.
+  파싱에 실패하면 예외 `.raw` 에 전체 응답, `.parser_raw` 에 부분 원문이 남습니다.
+
+### 수정
+
+- `refund`는 `commission`이 `get_refund_commission`의 응답이 아니면(`None` 포함) 요청 전에 `KorailProtocolError`로 거절합니다.
+  전에는 `commission=None`을 명시하면 수수료 값 없이 환불 요청을 보냈습니다.
+- 로그인 폼에서 `txtInputFlg`를 회원번호 앞, `custId`를 `checkValidPw` 앞에 둡니다
+  (`LoginIn.java:57–80,141–164`). 경로·필드·값·헤더는 유지합니다.
+- 봉투와 `PriceRecalculationRequest.for_hold` 좌석의 과도하게 큰 JSON 정수도 원문을 보존한
+  `KorailProtocolError`로 거절합니다. 재계산 실패에는 좌석 원문도 `parser_raw`로 남깁니다.
+- `BaseKorailResponse.from_raw`는 봉투의 JSON 정수를 문자열로 읽고 잘못된 타입은 원문과 함께 거절합니다.
+  성공·실패 판정은 하지 않습니다.
+- 지연확인증의 선택 `runDt`는 다른 선택 문자열처럼 잘못된 타입이면 `None`입니다.
+- 대기열 TTL·대기 인원은 부호·BMP 십진 숫자·긴 선행 0을 Java int32처럼 읽습니다.
+  잘못된 값은 기존의 0 기본값을 유지하며 큰 정수 변환의 `ValueError`가 새어 나오지 않습니다.
+- 공통 파싱·요청·재시도 정책은 [동작 계약](https://github.com/yakisoba0728/korail-mobile-api/blob/main/checks/BEHAVIOR.md)에 모았습니다.
+
+### 타입
+
+- `KorailLoginInputFlag`와 `KorailRoomClassCode` 입력 타입 별칭을 공개합니다.
+  로그인 종류·비밀번호 확인 여부·객실 종류를 타입으로 좁히며 런타임 검증은 추가하지 않습니다.
+- 공개 응답 모델의 `raw`는 `Mapping[str, object]`입니다. 실제 원문 객체를 복사·동결하거나 마스킹하지 않습니다.
+- `BaseKorailResponse.from_raw`와 `TrainSummary.from_raw`의 반환형은 `Self`입니다.
+  서버 응답 코드 필드는 `str`/`str | None`을 유지합니다.
+
+### 공개 API 추가
+
+- 상품 예약 취소, 공항버스 예약, 역 발권 승차권 환불 검증·실행을 제공합니다:
+  `cancel_product_reservation`, `reserve_limousine`, `verify_station_ticket_refund`, `execute_station_ticket_refund`.
+- 지연확인증·지연료 반환 영수증, 셀프 체크인 정보·좌석 확인·등록·취소, 전달 승차권 회수를 제공합니다:
+  `get_delay_certificate`, `get_delay_return_receipt`, `get_self_checkin_info`, `check_self_checkin_seat`,
+  `register_self_checkin`, `cancel_self_checkin`, `retrieve_delivered_ticket`.
+- `PriceRecalculationRequest.for_hold`는 첫 여정 좌석별 재계산 행을 만듭니다.
+  `recalculate_price(add_to_cart=True)`는 재계산 성공 뒤 장바구니 추가를 요청하고 `cart_addition`에 결과를 남깁니다.
+- `TrainSearchQuery`는 청소년·유아·안내견 인원도 받습니다. 조회 폼에서는 각각 어른·어린이·어른 인원에 합칩니다.
+- `ReservationHoldResponse.payable`은 예약대기 결제를 막는 값입니다. 병합 첫 홀드는 결제할 수 있습니다.
+
+### v1.1.1 과 호환되지 않는 변경
+
+모델은 키워드 인자로 생성하십시오. 변경 메서드는 별도 사전 동의 없이 즉시 요청합니다.
+
+- 제거 메서드: `get_gift_ticket_list`, `get_limousine_schedule_view`, `get_platform_numbers`, `pay_with_fake_card`.
+- 제거 인자·이름: `consent=`, `MutationPreview`, `SELF_SEAT_CHANGE_ROOM_CLASS_CODES`, `inquiry_action`.
+  제거 모듈: `consent`, `redaction`, `safety`.
+  `live_enabled`, `read_credentials_from_env`, `run_live_smoke_from_env`도 제거했습니다.
+- `get_crew_request_list`는 `query_division_code` 대신 키워드 `timestamp_ms`를 받습니다.
+  `get_station_info`의 `device`, `refund`의 `return_times_division_code`는 제거했습니다.
+- `refund`의 `commission`은 필수 키워드입니다. `reserve_merge`의 두 번째 인자 이름은 `merge_rows`입니다.
+  `get_ticket_receipt`의 식별값은 키워드 전용이며 `get_ticket_list`의 `page_no` 기본값은 `1`입니다.
+- `get_ticket_list`, `refund`, `add_to_cart`는 각각 전용 `BaseKorailResponse` 하위 모델을 반환합니다.
+- `KorailConfig.enable_dynapath`·`live_env_var`는 제거했습니다. DynaPath를 끄려면 `disable_dynapath=True`를 씁니다.
+  API의 `user_agent`와 대기열의 `netfunnel_user_agent`는 별도 설정입니다.
+  `build_dalvik_user_agent`는 키워드 `build_id`가 필요합니다.
+- 제거 모델 필드: `AppDataResponse.for_seat_intg`·`airport_bus_msg`, `DelayDiscountTicket.usable_until_date`,
+  `DiscountCardScheduleTrain.station_string_info`, `DiscountCardSection.section_sequence`, `DiscountCoupon.discount_values`,
+  `MileageHistoryResponse.rail_now_saved_point_1`, `PriceFareLeg.standing_train_classification_code`,
+  `RefundTicketDetailResponse.mileage_save_flag`, `TrainSearchContinuation.page_count`,
+  `TrainSearchMetadata.merge_reservation_available_flag`, `TripChangeDateResponse.trip_change_date`,
+  `TripMenuContent.content_type`, `KorailAuthContinuationRequired.post_data`.
+- `DiscountCoupon.discount_values` 대신 할인 구분·평일/주말 운임·요금 할인 속성을 사용합니다.
+  `StationInfoResponse.count`, `SeatInventoryResponse.layout_type`, `CartItem.ticket_count`,
+  `TicketDuplicationCheckResponse.reservation_count`, `KorailStation.popup_type`, `PassMenuItem.after_day`,
+  `TrainScheduleStop.actual_arrival_delay_count`는 문자열입니다.
+- `PbpAcceptanceJourney.member_card_no`, `PriceFareLeg.train_class_code`, `TicketReceipt.printed_discount_kind_code`·
+  `ticket_kind_name`·`train_group_code`는 필수입니다. 선택 수량·좌석 비율은 `None`일 수 있습니다.
+- 닫힌 클라이언트와 잘못된 도메인 입력은 `KorailProtocolError`로 거절합니다.
+  `cancel_unpaid_hold`는 기본으로 확인과 취소를 순서대로 요청합니다.
+
+### 검증 범위
+
+오프라인 검사는 운영 서버의 수용을 보장하지 않습니다. 보호된 리터럴과 미관측 응답은 검증 못 함입니다.
+셀프 체크인 변경·전달 승차권 회수·N카드의 실서버 검증 상태를 새로 확인하지 않습니다.
+기록용 `_*_unsupported.py` 세 파일은 유지하며 보호된 값을 추측해 기능을 추가하지 않습니다.
+버전 변경·태그 생성·배포는 하지 않습니다.

korail_mobile_api-2.0.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

korail_mobile_api-2.0.1/MANIFEST.in

@@ -0,0 +1,15 @@
+global-exclude *
+include pyproject.toml MANIFEST.in LICENSE README.md CHANGELOG.md
+recursive-include src/korail_mobile_api *.py
+include src/korail_mobile_api/py.typed
+recursive-include checks *.py *.md
+recursive-include tests *.py
+prune analysis
+prune .git
+prune .github
+prune build
+prune dist
+global-exclude *.apk *.apks *.aab *.dex *.so *.dll *.dylib
+global-exclude *.pem *.key *.p12 *.pfx *.jks *.keystore
+global-exclude .env .env.* *.env .pypirc *credentials* *credential* *secrets*
+global-exclude *.pyc *.pyo .DS_Store

korail_mobile_api-2.0.1/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: korail-mobile-api
+Version: 2.0.1
+Summary: Unofficial synchronous Python client for the KORAIL mobile API
+Author: yakisoba0728
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/yakisoba0728/korail-mobile-api
+Project-URL: Documentation, https://yaki.kr/korail-mobile-api/
+Project-URL: Repository, https://github.com/yakisoba0728/korail-mobile-api
+Project-URL: Issues, https://github.com/yakisoba0728/korail-mobile-api/issues
+Project-URL: Changelog, https://github.com/yakisoba0728/korail-mobile-api/blob/main/CHANGELOG.md
+Keywords: korail,ktx,railway,train,reservation,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.1
+Requires-Dist: cryptography>=42.0.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: mypy>=1.15; extra == "dev"
+Requires-Dist: pyright>=1.1.400; extra == "dev"
+Requires-Dist: setuptools>=78.1.1; extra == "dev"
+Requires-Dist: packaging>=24.2; extra == "dev"
+Dynamic: license-file
+
+> [!IMPORTANT]
+> ## 🚆 The Journey Begins Again
+>
+> ### **여기서, 여정이 다시 시작됩니다.**
+>
+> 2026년 9월 1일, KORAIL과 SR이 통합되면서 SRT 열차는 KTX로 합쳐졌고, 코레일톡도 코레일+로 바뀌었습니다.
+> 두 갈래로 이어져 오던 서비스가 하나의 선로 위에서 만난 것처럼,
+> **[`srt-mobile-api`](https://github.com/yakisoba0728/srt-mobile-api)의 개발과 기록도
+> 이제 `korail-mobile-api`로 이어집니다.**
+>
+> `srt-mobile-api`는 여기서 멈췄지만, 그 안에서 확인한 수많은 요청과 응답,
+> 시행착오와 검증의 기록까지 사라지는 것은 아닙니다.
+> 그 경험은 이 프로젝트의 다음 장을 이루는 기반으로 남습니다.
+>
+> **우리는 SRT를 기억할 것입니다.**  
+> 하나의 프로젝트는 종착역에 도착했지만, 그 여정은 이곳에서 다시 출발합니다.
+>
+> **One journey ended. Another begins here.**
+>
+> → [`srt-mobile-api` — Final Stop](https://github.com/yakisoba0728/srt-mobile-api)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/main/docs/assets/banner-dark.svg">
+    <img src="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/main/docs/assets/banner-light.svg" alt="korail-mobile-api" width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://github.com/yakisoba0728/korail-mobile-api/actions/workflows/ci.yml"><img src="https://github.com/yakisoba0728/korail-mobile-api/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://pypi.org/project/korail-mobile-api/"><img src="https://img.shields.io/pypi/v/korail-mobile-api" alt="PyPI"></a>
+  <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&amp;logoColor=white" alt="Python 3.11 | 3.12 | 3.13 | 3.14">
+  <img src="https://img.shields.io/badge/typing-mypy%20strict-2A6DB2" alt="mypy strict">
+  <img src="https://img.shields.io/badge/%EC%BD%94%EB%A0%88%EC%9D%BC%2B-7.0.6%20%EA%B8%B0%EC%A4%80-0b7a75" alt="코레일+ 7.0.6 기준">
+  <a href="https://github.com/yakisoba0728/korail-mobile-api/blob/main/LICENSE"><img src="https://img.shields.io/github/license/yakisoba0728/korail-mobile-api" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://yaki.kr/korail-mobile-api/">문서</a> ·
+  <a href="#설치">설치</a> ·
+  <a href="#빠르게-써보기">빠르게 써보기</a> ·
+  <a href="#예약결제환불">예약·결제·환불</a> ·
+  <a href="#지원-범위">지원 범위</a> ·
+  <a href="#동작-방식">동작 방식</a> ·
+  <a href="#법적-고지">법적 고지</a>
+</p>
+
+코레일+ 안드로이드 앱이 서버에 보내는 요청을 그대로 따라 하는 비공식 Python 클라이언트입니다.
+2026년 9월 KORAIL과 SR이 통합되면서 SRT는 KTX로 합쳐졌고, 코레일톡도 코레일+로 이름이 바뀌었습니다.
+
+KORAIL과는 관계없는 개인 프로젝트입니다. 공식 API가 아니라서 KORAIL이 서버나 앱을 바꾸면 언제든 깨질 수 있습니다.
+쓰기 전에 [법적 고지](#법적-고지)는 꼭 읽어 주세요.
+
+- **타입이 붙은 응답** — 응답은 전부 dataclass로 돌려주고, 서버가 준 원본은 `.raw`에 남겨 둡니다.
+- **실수하기 어렵게** — 결제 금액은 홀드의 `received_amount`를 그대로 쓰고, 0원·예약대기 홀드를 카드로 결제하려는 건 아닌지, 환불 전에 수수료를 조회했는지 요청 전에 확인합니다.
+- **네트워크 없이 도는 테스트 2,100여 개** — CI에서 Python 3.11~3.14로 `pytest`, `mypy --strict`, `pyright`, `ruff`를 돌립니다.
+
+## 설치
+
+Python 3.11 이상이 필요합니다.
+
+```sh
+pip install korail-mobile-api
+```
+
+아직 릴리스되지 않은 최신 코드는 GitHub에서 바로 설치할 수 있습니다.
+
+```sh
+pip install "git+https://github.com/yakisoba0728/korail-mobile-api"
+```
+
+의존성은 `httpx`와 `cryptography` 두 개뿐입니다.
+
+## 빠르게 써보기
+
+열차 조회는 로그인 없이 됩니다.
+
+```python
+from korail_mobile_api import KorailClient, TrainSearchQuery
+
+client = KorailClient()
+try:
+    query = TrainSearchQuery(
+        departure_station_code="서울",
+        arrival_station_code="부산",
+        departure_date="20261002",
+        departure_time="090000",
+    )
+    result = client.search_trains(query)
+    for t in result.trains:
+        print(t.train_class_name, t.train_no, t.departure_time, t.arrival_time)
+finally:
+    client.close()
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/main/docs/assets/demo.svg" alt="열차 조회 실행 예시" width="100%">
+</p>
+
+역은 이름이나 역 코드 어느 쪽으로 넣어도 됩니다. 날짜는 `YYYYMMDD`, 시각은 `HHMMSS`입니다.
+결과는 한 페이지씩 옵니다. `result.next_page()`가 `None`이 아니면 `client.search_trains(query, continuation=result.next_page())`로 다음 페이지를 받습니다.
+`None`이면 `result.next_query_from_last_departure(query)`로 마지막 열차의 출발일·출발 시각부터 조회할 조건을 만들어 다시 조회할 수 있습니다. 마지막 열차가 다시 포함될 수 있으니 열차 번호로 중복을 거르세요.
+
+로그인하면 내 승차권과 예약 내역도 볼 수 있습니다.
+
+```python
+from getpass import getpass
+
+from korail_mobile_api import KorailClient
+
+client = KorailClient()
+try:
+    client.login(input("회원번호·전화번호·이메일: "), getpass("비밀번호: "))
+    tickets = client.get_ticket_list()
+    print(sum(len(r.tickets) for r in tickets.reservations), "장")
+finally:
+    try:
+        client.logout()
+    finally:
+        client.close()
+```
+
+로그인 ID는 하이픈 없는 회원번호·전화번호나 이메일입니다. 로그인에 실패하면 계정 잠금 횟수에 들어갈 수 있으니 조심하세요.
+
+## 예약·결제·환불
+
+**이 메서드들은 부르는 순간 실제로 처리됩니다.** 확인 창이나 미리보기 같은 건 없습니다.
+예약하면 좌석이 잡히고, 결제하면 카드가 실제로 청구되고, 환불에는 수수료가 붙을 수 있습니다.
+
+| 하려는 것 | 메서드 | 알아둘 점 |
+|---|---|---|
+| 좌석 잡기 (결제 전) | `reserve`, `reserve_transfer`, `reserve_merge`, `reserve_limousine` | 승객 구성은 조회할 때와 같게 넣습니다. |
+| 결제 전 취소 | `cancel_unpaid_hold` | 결제한 표에는 쓰지 않습니다. |
+| 카드 결제 | `pay_with_card` | 카드 거절은 예외가 아니라 FAIL 응답으로 돌아옵니다. |
+| 환불 | `get_refund_commission` → `refund(..., commission=...)` | 승차권 한 장씩이고, 수수료 조회가 먼저입니다. `commission`이 수수료 조회의 성공 응답이 아니면(`None` 포함) 요청 전에 거절합니다. |
+| 할인 재계산 | `PriceRecalculationRequest.for_hold` → `recalculate_price` | 결제는 재계산된 홀드로 합니다. |
+
+변경 요청은 자동으로 다시 보내지 않습니다. 응답을 못 읽어서 예외가 나도 서버에서는 이미 처리됐을 수 있습니다.
+그럴 땐 다시 보내지 말고 예외의 `.raw`를 보고, 예약은 `get_reservation_history()`, 결제·환불은 `get_ticket_list()`로 먼저 확인하세요.
+
+## 지원 범위
+
+공개 메서드는 84개이고, 2026년 9월 24~26일에 실서버로 하나씩 확인했습니다.
+
+| 영역 | 메서드 | 실서버 확인 | 예 |
+|---|---:|---:|---|
+| 로그인·세션 | 4 | 2 | `login`, `logout` (나머지 둘은 네트워크를 쓰지 않음) |
+| 공통 정보 | 9 | 9 | 역 목록, 운행 달력, 공지 |
+| 열차 조회·좌석 | 12 | 11 | `search_trains`, 환승 조회, 호차·좌석 배치, 운임 |
+| 공항버스·부가서비스 | 6 | 6 | 공항버스 스케줄·좌석, 부가서비스 메뉴 |
+| 정기권·패스 | 6 | 6 | 패스 사용 가능일, 정기권 조건 |
+| 내 승차권·계정 | 28 | 21 | 승차권 목록, 예약 내역, 영수증, 마일리지, 지연확인증 |
+| 예약·결제·환불 | 19 | 11 | `reserve`, `pay_with_card`, `refund` |
+
+확인 못 한 것 중 4개는 요청은 서버까지 갔지만 이 계정에 해당 자료나 자격이 없어서 실패 응답만 봤습니다.
+나머지 12개는 필요한 카드나 승차권이 없어서 성공 응답을 보지 못했습니다. 이 중 3개는 요청을 보내 실패 응답만 받았습니다. 코드는 앱과 똑같이 짰습니다.
+
+- N카드: 구매, 기간 연장, N카드로 예약, 사용 내역, 이용 가능 열차, 2인 승차권 수령자 조회
+- 셀프 체크인: 좌석 확인, 등록, 취소
+- 역에서 산 승차권 환불: 확인, 실행
+- 다른 회원에게 전달한 승차권 회수
+
+간편 로그인(카카오·네이버 등), 여행상품 검색·예약·결제, 부가서비스 구매·결제·환불은 지원하지 않습니다.
+앱에서 필요한 값이 암호화돼 있거나 외부 SDK를 거쳐야 해서입니다.
+정기권·패스 구매, 다른 회원에게 승차권 전달, 승차권 변경도 지원하지 않습니다. 관련 정보를 조회하는 메서드는 있지만 실행하는 메서드는 없습니다.
+
+## 동작 방식
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/main/docs/assets/flow-dark.svg">
+    <img src="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/main/docs/assets/flow-light.svg" alt="요청 흐름" width="100%">
+  </picture>
+</p>
+
+- 폼은 앱의 요청 DTO에 선언된 순서대로 만듭니다. 앱이 그 순서로 보내기 때문입니다.
+- 열차 조회, 일부 예약(`reserve`, `reserve_transfer`, `reserve_with_discount_card`), 카드 결제, 예약 내역 조회 전에는 앱처럼 NetFunnel 대기열을 거칩니다. 기본으로 켜져 있습니다.
+- 로그인 비밀번호는 앱처럼 AES로 암호화해서 보냅니다.
+- 응답을 못 읽으면 받은 원문 전체를 예외의 `.raw`에 담아 던집니다.
+
+더 자세한 규칙과 앱과 다르게 처리한 부분은 [checks/BEHAVIOR.md](https://github.com/yakisoba0728/korail-mobile-api/blob/main/checks/BEHAVIOR.md)에 정리해 뒀습니다.
+
+## 자주 묻는 질문
+
+**SRT는요?**
+SRT는 2026년 9월 통합 때 KTX로 합쳐져서 이제 따로 없습니다. 예매는 코레일+ 앱 하나로 하고, 이 라이브러리도 그 앱의 요청을 씁니다.
+SRT 앱용으로 만들었던 [srt-mobile-api](https://github.com/yakisoba0728/srt-mobile-api)는 개발을 멈추고 이 저장소로 이어졌습니다.
+
+**대기열을 끄면 빨라지나요?**
+`KorailConfig(netfunnel_enabled=False)`로 끌 수는 있습니다. 하지만 앱과 다르게 동작하게 되고 KORAIL의 혼잡 제어를 건너뛰는 셈이라 권하지 않습니다.
+
+**비밀번호나 카드 번호는 어디에 저장되나요?**
+어디에도 저장하지 않습니다. KORAIL 서버로만 보내고 파일로 쓰지 않습니다.
+다만 응답 모델과 예외의 `.raw`에는 개인정보가 그대로 들어 있으니 로그에 그대로 찍지 않도록 조심하세요.
+
+## 문서와 링크
+
+- [문서 사이트](https://yaki.kr/korail-mobile-api/) — 시작하기, 가이드, 메서드 84개 전체의 API 레퍼런스
+- [동작 규칙 (checks/BEHAVIOR.md)](https://github.com/yakisoba0728/korail-mobile-api/blob/main/checks/BEHAVIOR.md) — 요청을 만드는 규칙, 응답을 읽는 규칙, 앱과 다르게 한 부분
+- [변경 이력 (CHANGELOG.md)](https://github.com/yakisoba0728/korail-mobile-api/blob/main/CHANGELOG.md)
+- [오프라인 검사 기준 (checks/ACCEPTANCE.md)](https://github.com/yakisoba0728/korail-mobile-api/blob/main/checks/ACCEPTANCE.md)
+- 한국철도공사 공식 홈페이지 — <https://www.korail.com>
+- 코레일+ 앱 — [Google Play](https://play.google.com/store/apps/details?id=com.korail.talk) · [App Store](https://apps.apple.com/kr/app/id1000558562)
+- 이전 SRT 클라이언트 — [srt-mobile-api](https://github.com/yakisoba0728/srt-mobile-api)
+
+## 개발
+
+```sh
+git clone https://github.com/yakisoba0728/korail-mobile-api
+cd korail-mobile-api
+pip install -e ".[dev]"
+
+pytest
+ruff check src checks tests && ruff format --check src checks tests
+mypy && pyright
+python checks/contract_api.py && python checks/netfunnel_offline.py
+```
+
+테스트는 전부 가짜 응답으로 돌고 소켓을 막아 둬서 실수로 실서버에 요청이 나가지 않습니다.
+버그나 앱 업데이트로 달라진 부분을 찾으면 이슈로 알려 주세요.
+
+## 법적 고지
+
+- 이 프로젝트는 한국철도공사(KORAIL)와 관계없는 개인의 비공식 프로젝트이며, 후원·승인·지원을 받지 않았습니다. 통합 전의 (주)에스알(SR)과도 관계없습니다.
+- KORAIL, 코레일, 코레일+, 코레일톡, KTX, SRT 등의 이름과 상표는 각 권리자의 것입니다. 이 저장소는 무엇과 호환되는지 설명하려고 이름만 씁니다. 저장소의 이미지는 직접 만들었고 공식 로고는 쓰지 않았습니다.
+- 저장소에는 앱 설치 파일(APK)이나 디컴파일한 앱 소스를 넣지 않았습니다. 라이브러리는 앱과 호환되도록 요청 형식만 재현합니다.
+- 이 라이브러리로 하는 예약·결제·환불은 전부 실제 거래입니다. 그 결과와 비용은 사용자 책임입니다.
+- KORAIL 서비스를 쓸 때는 KORAIL의 이용약관과 여객운송약관을 따라야 합니다. 자동화된 방식으로 쓰는 것이 약관에 맞는지는 사용자가 직접 확인해야 합니다.
+- KORAIL은 매크로 탐지 시스템을 운영하고 있습니다. 자동 프로그램 사용이 의심되면 로그인·조회 단계부터 접속을 막고, 대량 구매·취소에 쓰인 카드는 1년 동안 승차권 결제를 제한한다고 밝혔습니다([2025년 10월 보도](https://www.paxetv.com/news/articleView.html?idxno=248146)).
+- 승차권을 상습적으로 또는 영업으로 산 값보다 비싸게 되팔거나 이를 알선하는 행위는 [철도사업법 제10조의2](https://www.law.go.kr/%EB%B2%95%EB%A0%B9/%EC%B2%A0%EB%8F%84%EC%82%AC%EC%97%85%EB%B2%95)로 금지돼 있고, 최대 1천만 원의 과태료가 부과될 수 있습니다. 이 라이브러리를 암표, 좌석 선점, 대량 예매에 쓰지 마세요.
+- 계정과 카드 정보 관리는 사용자 몫입니다. 라이브러리는 로그나 `.raw`의 개인정보를 가리지 않습니다.
+- 이 소프트웨어는 Apache License 2.0에 따라 "있는 그대로" 제공되며 어떤 보증도 하지 않습니다. 사용하다 생긴 손해에 대해 저작자는 책임지지 않습니다.
+- 어떤 용도로 쓰든 막지는 않습니다. 다만 되도록 개인 용도로만 쓰고, 상업적이거나 불법적인 용도로는 쓰지 말아 주세요. 라이선스 조건이 아니라 부탁입니다.
+
+## 라이선스
+
+[Apache License 2.0](https://github.com/yakisoba0728/korail-mobile-api/blob/main/LICENSE)