korail-mobile-api 2.1.0

문서 · 설치 · 빠르게 써보기 · 예약·결제·환불 · 지원 범위 · 동작 방식 · 법적 고지

코레일+ 안드로이드 앱이 서버에 보내는 요청을 그대로 따라 하는 비공식 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 이상이 필요합니다.

pip install korail-mobile-api

개발 중인 코드는 GitHub에서 바로 설치할 수 있습니다.

pip install "git+https://github.com/yakisoba0728/korail-mobile-api"

의존성은 httpx와 cryptography 두 개뿐입니다.

빠르게 써보기

열차 조회는 로그인 없이 됩니다.

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()

역은 이름이나 역 코드 어느 쪽으로 넣어도 됩니다. 날짜는 YYYYMMDD, 시각은 HHMMSS입니다. 결과는 한 페이지씩 옵니다. result.next_page()가 None이 아니면 client.search_trains(query, continuation=result.next_page())로 다음 페이지를 받습니다. None이면 result.next_query_from_last_departure(query)로 마지막 열차의 출발일·출발 시각부터 조회할 조건을 만들어 다시 조회할 수 있습니다. 마지막 열차가 다시 포함될 수 있으니 열차 번호로 중복을 거르세요.

로그인하면 내 승차권과 예약 내역도 볼 수 있습니다.

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는 하이픈 없는 회원번호·전화번호나 이메일입니다. 로그인에 실패하면 계정 잠금 횟수에 들어갈 수 있으니 조심하세요.

예약·결제·환불

이 메서드들은 부르는 순간 실제로 처리됩니다. 확인 창이나 미리보기 같은 건 없습니다. 예약하면 좌석이 잡히고, 결제하면 카드가 실제로 청구되고, 환불에는 수수료가 붙을 수 있습니다.

변경 요청은 자동으로 다시 보내지 않습니다. 응답을 못 읽어서 예외가 나도 서버에서는 이미 처리됐을 수 있습니다. 그럴 땐 다시 보내지 말고 예외의 .raw를 보고, 예약은 get_reservation_history(), 결제·환불은 get_ticket_list()로 먼저 확인하세요.

지원 범위

공개 메서드 84개를 2026년 9월 28일 코레일+ 7.0.8 설정으로 다시 확인했습니다. 메서드별 결과 코드와 남은 전제 조건은 7.0.8 검증표에 있습니다.

2026년 9월 24~26일의 7.0.6 시기 검증 기록에는 카드 결제와 환불 성공 사례가 있습니다. 이는 7.0.8에서 결제·환불을 재실행했다는 뜻이 아닙니다.

• N카드: 구매, 기간 연장, N카드로 예약, 사용 내역, 이용 가능 열차의 정상 조회, 2인 승차권 수령자 조회
• 셀프 체크인: 좌석 확인, 등록, 취소
• 역에서 산 승차권 환불: 확인, 실행
• 다른 회원에게 전달한 승차권 회수

간편 로그인(카카오·네이버 등), 여행상품 검색·예약·결제, 부가서비스 구매·결제·환불은 지원하지 않습니다. 앱에서 필요한 값이 암호화돼 있거나 외부 SDK를 거쳐야 해서입니다. 정기권·패스 구매, 다른 회원에게 승차권 전달, 승차권 변경도 지원하지 않습니다. 관련 정보를 조회하는 메서드는 있지만 실행하는 메서드는 없습니다.

동작 방식

• 폼은 앱의 요청 DTO에 선언된 순서대로 만듭니다. 앱이 그 순서로 보내기 때문입니다.
• 열차 조회, 일부 예약(reserve, reserve_transfer, reserve_with_discount_card), 카드 결제, 예약 내역 조회 전에는 앱처럼 NetFunnel 대기열을 거칩니다. 기본으로 켜져 있습니다.
• 로그인 비밀번호는 앱처럼 AES로 암호화해서 보냅니다.
• 응답을 못 읽으면 받은 원문 전체를 예외의 .raw에 담아 던집니다.

더 자세한 규칙과 앱과 다르게 처리한 부분은 checks/BEHAVIOR.md에 정리해 뒀습니다.

자주 묻는 질문

SRT는요? SRT는 2026년 9월 통합 때 KTX로 합쳐져서 이제 따로 없습니다. 예매는 코레일+ 앱 하나로 하고, 이 라이브러리도 그 앱의 요청을 씁니다. SRT 앱용으로 만들었던 srt-mobile-api는 개발을 멈추고 이 저장소로 이어졌습니다.

대기열을 끄면 빨라지나요? KorailConfig(netfunnel_enabled=False)로 끌 수는 있습니다. 하지만 앱과 다르게 동작하게 되고 KORAIL의 혼잡 제어를 건너뛰는 셈이라 권하지 않습니다.

비밀번호나 카드 번호는 어디에 저장되나요? 어디에도 저장하지 않습니다. KORAIL 서버로만 보내고 파일로 쓰지 않습니다. 다만 응답 모델과 예외의 .raw에는 개인정보가 그대로 들어 있으니 로그에 그대로 찍지 않도록 조심하세요.

문서와 링크

• 문서 사이트 — 시작하기, 가이드, 메서드 84개 전체의 API 레퍼런스
• 동작 규칙 (checks/BEHAVIOR.md) — 요청을 만드는 규칙, 응답을 읽는 규칙, 앱과 다르게 한 부분
• 변경 이력 (CHANGELOG.md)
• 오프라인 검사 기준 (checks/ACCEPTANCE.md)
• 한국철도공사 공식 홈페이지 — https://www.korail.com
• 코레일+ 앱 — Google Play · App Store
• 이전 SRT 클라이언트 — srt-mobile-api

개발

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월 보도).
• 승차권을 상습적으로 또는 영업으로 산 값보다 비싸게 되팔거나 이를 알선하는 행위는 철도사업법 제10조의2로 금지돼 있고, 최대 1천만 원의 과태료가 부과될 수 있습니다. 이 라이브러리를 암표, 좌석 선점, 대량 예매에 쓰지 마세요.
• 계정과 카드 정보 관리는 사용자 몫입니다. 라이브러리는 로그나 .raw의 개인정보를 가리지 않습니다.
• 이 소프트웨어는 Apache License 2.0에 따라 "있는 그대로" 제공되며 어떤 보증도 하지 않습니다. 사용하다 생긴 손해에 대해 저작자는 책임지지 않습니다.
• 어떤 용도로 쓰든 막지는 않습니다. 다만 되도록 개인 용도로만 쓰고, 상업적이거나 불법적인 용도로는 쓰지 말아 주세요. 라이선스 조건이 아니라 부탁입니다.

라이선스

Apache License 2.0