korail-mobile-api 2.6.1

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

코레일+ 안드로이드 앱의 요청·응답 형식을 바탕으로 만든 비공식 동기 Python 클라이언트입니다. 열차 조회, 예약·결제·환불과 승차권·계정 조회를 지원합니다.

KORAIL과는 관계없는 개인 프로젝트입니다. 공식 API가 아니라서 KORAIL이 서버나 앱을 바꾸면 언제든 깨질 수 있습니다. 쓰기 전에 법적 고지는 꼭 읽어 주세요.

• 타입이 붙은 응답 — 서버 응답을 dataclass로 읽고, 원문은 .raw에 남깁니다. .raw의 개인정보는 자동으로 가리지 않습니다.
• 실수하기 어렵게 — 결제 금액은 홀드의 received_amount를 쓰며, 0원·예약대기 홀드의 카드 결제를 차단합니다. 2.6.0부터 환불은 성공한 수수료 조회와 대상 승차권의 연결도 확인합니다.
• 변경 요청 재전송 없음 — 예약·결제·환불 결과가 불명확해도 자동으로 같은 요청을 다시 보내지 않습니다.
• 오프라인 검증 — CI에서 Python 3.11~3.14와 최소 의존성 조합, 타입·포맷·문서, checkout 밖에 설치한 wheel까지 검사합니다.

버전과 호환 범위

PyPI 배포본과 main의 미배포 변경은 구분하세요. 패키지 버전 문자열이 같아도 포함된 변경이 다를 수 있습니다.

2.6.0에는 사전 갱신, 요청 필드 순서 정정, 환불 대상 연결 검증과 초장문 마일리지 숫자 처리 보완이 포함됩니다. 2.6.1에는 운임 입력 팩토리, 선택적 검색 이어보기와 멤버십·공항버스 간편 조회가 있습니다. 사용법은 간편 API 가이드를 참고하세요. 새 간편 흐름은 오프라인 검증만 완료했으며 실서버 확인 범위와 구분합니다. 2.5.0에서 수수료 응답을 직접 생성·파싱해 환불하던 호출은 변경해야 합니다. 실제 수수료 조회 반환값과 원표 반환일·동반자 정보를 맞추세요. 사전의 앱 버전을 요청 기본값이나 전체 호환 인증으로 간주하지 않습니다. KorailConfig(app_version="7.0.10")으로 명시한 제한적 실서버 확인과 정적 검토의 범위는 7.0.10 검증 기록에 구분돼 있습니다.

설치

Python 3.11 이상이 필요합니다.

pip install korail-mobile-api

검색 필터·객실 우선 선택·메시지 사전과 신규 오류 분류는 2.5.0부터 제공합니다. 환불 대상 연결 검증과 7.0.10 메시지 사전은 2.6.0부터 제공합니다. 운임 입력 팩토리·검색 이어보기·멤버십·공항버스 간편 조회는 2.6.1부터 제공합니다. 이전 버전은 pip install --upgrade korail-mobile-api로 갱신하세요.

개발 버전 설치: main의 Unreleased 변경이 필요하면 GitHub에서 바로 설치할 수 있습니다.

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

필수 런타임 의존성은 httpx>=0.24.1과 cryptography>=42.0.8입니다. SOCKS 프록시를 쓰려면 pip install "korail-mobile-api[socks]"로 설치하세요.

기존 예약을 가져오는 get_reservation_hold는 2.3.0부터 제공합니다. 이전 버전은 pip install --upgrade korail-mobile-api로 갱신하세요.

빠르게 써보기

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

자주 쓰는 조회는 with와 KST datetime을 받는 간편 API로 시작할 수 있습니다.

from datetime import datetime, timedelta, timezone

from korail_mobile_api import Korail

with Korail() as korail:
    result = korail.trains.search(
        "서울", "부산", depart_after=datetime.now(timezone(timedelta(hours=9))) + timedelta(days=1)
    )
    for train in result.trains:
        print(train.train_no, train.departure_time)

간편 API는 처음 검색할 때 역 목록을 받아 입력을 확인합니다. 전체 요청 옵션과 모든 메서드는 아래의 KorailClient로 사용할 수 있습니다. 자세한 내용은 간편 API 가이드에 있습니다.

from datetime import datetime, timedelta, timezone

from korail_mobile_api import KorailClient, TrainSearchQuery

departure_date = (datetime.now(timezone(timedelta(hours=9))) + timedelta(days=1)).strftime("%Y%m%d")

client = KorailClient()
try:
    query = TrainSearchQuery(
        departure_station_code="서울",
        arrival_station_code="부산",
        departure_date=departure_date,
        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()로 먼저 확인하세요.

2.6.0부터 환불은 대상 연결을 확인할 수 없으면 거절하는 fail-closed 정책입니다. PaidTicket.from_refund_detail() 사용을 권하며, 수동 생성 시 현재 sale_date와 별도로 return_sale_date를 명시하세요. 수수료 조회 연결은 금액의 유효기간이나 서버 승인을 보장하지 않습니다. 환불 가이드를 참고하세요.

앱이나 다른 패키지에서 예약한 표는 로그인 후 hold = client.get_reservation_hold(pnr_no)로 가져와 금액을 확인하고 client.pay_with_card(hold, card)로 결제할 수 있습니다. 창구번호와 금액을 임의로 채우지 않으며, 유효한 여정·좌석·정산액이 필요합니다. 결제 플래그는 상세에서 생략될 수 있고, 명시된 경우에만 Y를 요구합니다. 2026년 9월 29일 실서버에서 기존 예약 가져오기를 확인했습니다. 실제 카드 결제와 N카드 예약 복원은 별도 검증하지 않았습니다. 기존 예약 결제 예제를 참고하세요.

지원 범위

현재 공개 메서드는 85개입니다. 메서드 제공, 오프라인 테스트 통과, 실서버 성공은 서로 다른 확인 범위입니다.

2026년 10월 19일에는 개발 소스의 AppVersion=7.0.10을 명시해 64개 메서드(로컬 전용 2개 포함)를 실행한 기록이 있습니다. 일부 조회·인증과 직통·환승 임시 예약 후 취소를 확인했지만 실제 카드 결제·환불은 하지 않았습니다. 유효한 수수료 응답과 환불 대상 연결의 정상 실서버 흐름도 미검증입니다. 전체 내역과 미실행 21개의 한계는 7.0.10 제한적 실서버 확인을 참고하세요.

아래 표는 별도의 과거 기록입니다. 당시의 84개 메서드를 2026년 9월 28일 코레일+ 7.0.8 설정으로 확인했고, 이후 추가한 get_reservation_hold의 실서버 조회는 9월 29일 확인했습니다. 새 기록을 아래 집계에 합산하지 않습니다. 메서드별 결과는 7.0.8 검증표와 실서버 확인 현황에 있습니다.

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

메서드는 있지만 정상 실서버 흐름을 확인하지 못한 주요 경로입니다.

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

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

동작 방식

• 폼은 확인한 앱 직렬화 순서를 따릅니다. 환불·수수료 조회는 공통 필드를 먼저, 은행 직접 필드는 Device, Version, Key, AppVersion 순서로 만듭니다. 순서에 따른 서버 영향은 미확인입니다.
• 좌석배정 조회의 *2 이상 번호 그룹은 앱 DTO와 동일한 형식으로 확인된 것이 아니라 기존 SDK 확장입니다.
• 열차 조회, 일부 예약(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은 데이터센터·VPN IP 대역에서 오는 요청을 막습니다. Oracle Cloud나 Vercel 같은 곳에서 KorailDynaPathError(HTTP 403, -8202 등)가 나고, 같은 코드가 집 네트워크에서는 되는 사례가 보고됐습니다. 라이브러리의 요청 형식 문제가 아니라 요청이 나가는 네트워크의 문제입니다. 2.4.0부터는 KorailConfig(proxy="socks5://...")로 KORAIL 요청만 본인이 관리하는 다른 네트워크로 보낼 수 있습니다. 자세한 내용은 설정 가이드의 프록시를 보세요.

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

문서와 링크

• 문서 사이트 — 시작하기, 가이드, 메서드 85개 전체의 API 레퍼런스
• 동작 규칙 (checks/BEHAVIOR.md) — 요청을 만드는 규칙, 응답을 읽는 규칙, 앱과 다르게 한 부분
• 변경 이력 (CHANGELOG.md)
• 오프라인 검사 기준 (checks/ACCEPTANCE.md)
• AI 에이전트 작업 가이드 (AGENTS.md) — 작업별 코드 위치, 안전 경계, 테스트와 완료 기준
• 배포 절차 — 버전, 검증, 패키지 빌드, PyPI와 문서 배포
• 한국철도공사 공식 홈페이지 — https://www.korail.com
• 코레일+ 앱 — Google Play · App Store
• 이전 SRT 클라이언트 — srt-mobile-api

개발

저장소 루트 기준 macOS·Linux 예시입니다. 에이전트로 작업한다면 먼저 AGENTS.md를 읽어 주세요.

git clone https://github.com/yakisoba0728/korail-mobile-api
cd korail-mobile-api
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]' -r docs/requirements.txt

.venv/bin/python -m pytest tests/ --cov=korail_mobile_api --cov-branch --cov-report=term-missing:skip-covered --cov-fail-under=90
.venv/bin/python -m ruff check src checks tests
.venv/bin/python -m ruff format --check src checks tests
.venv/bin/python -m mypy
.venv/bin/python -m pyright
.venv/bin/actionlint -shellcheck= -pyflakes=
.venv/bin/python -m mkdocs build --strict
git diff --check

전체 테스트는 합성 응답과 소켓 차단을 사용하며, 두 기존 오프라인 검사·문서 예제·실제 wheel/sdist 내용 검사도 포함합니다. CI는 새 가상환경에 wheel을 설치하고 checkout 밖에서 공개 호출·7.0.10 독립 계약·환불 연결을 다시 확인합니다. 신규 간편 조회도 설치된 wheel에서 검사합니다. 주간 CI와 Dependabot으로 갱신을 확인하고, actionlint와 Trivy로 워크플로·해석된 런타임 의존성·비밀·설정을 검사합니다. 스캔은 실서버 호환 검사나 모든 취약점의 부재를 보장하지 않습니다. 패키지·문서 배포는 계속 수동입니다. 이는 전체 wire 계약이나 실서버 수용을 증명하지 않습니다. README의 사용 예제는 테스트 밖에서 실행하면 실제 서버에 접속합니다. 검사별 한계는 오프라인 검사 기준, 배포 검증은 배포 절차에 있습니다. 버그나 앱 업데이트로 달라진 부분을 찾으면 이슈로 알려 주세요.

법적 고지

• 이 프로젝트는 한국철도공사(KORAIL)와 관계없는 개인의 비공식 프로젝트이며, 후원·승인·지원을 받지 않았습니다. 통합 전의 (주)에스알(SR)과도 관계없습니다.
• KORAIL, 코레일, 코레일+, 코레일톡, KTX, SRT 등의 이름과 상표는 각 권리자의 것입니다. 이 저장소는 무엇과 호환되는지 설명하려고 이름만 씁니다. 저장소의 이미지는 직접 만들었고 공식 로고는 쓰지 않았습니다.
• 저장소에는 앱 설치 파일(APK)이나 디컴파일한 앱 소스를 넣지 않았습니다. 라이브러리는 앱과 호환되도록 요청 형식만 재현합니다.
• 이 라이브러리로 하는 예약·결제·환불은 전부 실제 거래입니다. 그 결과와 비용은 사용자 책임입니다.
• KORAIL 서비스를 쓸 때는 KORAIL의 이용약관과 여객운송약관을 따라야 합니다. 자동화된 방식으로 쓰는 것이 약관에 맞는지는 사용자가 직접 확인해야 합니다.
• KORAIL은 매크로 탐지 시스템을 운영하고 있습니다. 자동 프로그램 사용이 의심되면 로그인·조회 단계부터 접속을 막고, 대량 구매·취소에 쓰인 카드는 1년 동안 승차권 결제를 제한한다고 밝혔습니다(2025년 10월 보도).
• 승차권을 상습적으로 또는 영업으로 산 값보다 비싸게 되팔거나 이를 알선하는 행위는 철도사업법 제10조의2로 금지돼 있고, 최대 1천만 원의 과태료가 부과될 수 있습니다. 이 라이브러리를 암표, 좌석 선점, 대량 예매에 쓰지 마세요.
• 계정과 카드 정보 관리는 사용자 몫입니다. 라이브러리는 로그나 .raw의 개인정보를 가리지 않습니다.
• 이 소프트웨어는 Apache License 2.0에 따라 "있는 그대로" 제공되며 어떤 보증도 하지 않습니다. 사용하다 생긴 손해에 대해 저작자는 책임지지 않습니다.
• 어떤 용도로 쓰든 막지는 않습니다. 다만 되도록 개인 용도로만 쓰고, 상업적이거나 불법적인 용도로는 쓰지 말아 주세요. 라이선스 조건이 아니라 부탁입니다.

라이선스

Apache License 2.0