k-gov-skill(5) transport-receipt-collector: 교통비 증빙 수집

먼저 결론

transport-receipt-collector는 출장·여비·교통비 정산에 필요한 영수증을 한곳에 모으고, 제출하기 좋은 파일명과 형식으로 정리하는 스킬입니다.

현재 기준으로는 하이패스, SRT, KTX/Korail 3종 provider를 다룹니다.

핵심은 단순 캡처가 아닙니다.

• 어떤 거래의 영수증인지 나중에 바로 알 수 있어야 합니다.
• PDF, PNG, JSON 같은 산출물이 거래 기준으로 묶여야 합니다.
• 실패한 항목은 왜 실패했는지 남아야 합니다.
• 계정정보, 카드번호 원문, 인증정보는 로그나 저장소에 남지 않아야 합니다.
• 공개 저장소에는 민감한 내부 구현 정보를 남기지 않아야 합니다.

해결하는 문제

출장 정산에서 영수증을 모으는 일은 작지만 반복적으로 시간을 잡아먹습니다.

하이패스는 별도 사이트에서 찾아야 하고, SRT와 KTX/Korail은 각각 다른 흐름으로 영수증을 확인해야 합니다. 제출처에 따라 PDF가 필요할 때도 있고, 이미지 첨부만 가능한 경우도 있습니다.

파일명까지 제각각이면 나중에 다시 찾을 때 또 시간이 듭니다.

이 스킬은 이 과정을 provider별로 나누고, 결과물은 같은 규칙으로 정리합니다.

outputs/receipts/YYYY-MM/
  YYYY-MM-DD_provider_route_or_train_amount.pdf
  YYYY-MM-DD_provider_route_or_train_amount.png
  YYYY-MM-DD_provider_route_or_train_amount.json

지원 provider

하이패스

하이패스는 사용내역 조회와 영수증 저장을 지원합니다.

• 사용내역 조회
• 영수증 출력 화면 진입
• PDF 저장
• 제출용 PNG 저장
• headless 모드 지원
• 실패 항목과 실패 사유 요약

SRT

SRT는 이용내역 조회 후 영수증 화면을 저장하는 흐름을 지원합니다.

• 이용내역 조회
• 선택 행 영수증 저장
• PNG 산출물 저장
• 추가 본인확인 발생 시 중단

KTX/Korail

KTX/Korail은 공개 저장소에 세부 구현을 두지 않고, 로컬/private 커넥터를 통해 처리합니다.

공개 스킬이 맡는 것은 경계와 산출물 규칙입니다.

• 로컬 커넥터 호출
• 코레일톡 스타일 PNG 산출물 저장
• redacted JSON 저장
• 공개 문서에서 내부 호출 구조와 파라미터 비공개

이렇게 나눈 이유는 명확합니다. 영수증 스킬은 공개할 수 있지만, 내부 호출 세부사항까지 공개할 필요는 없기 때문입니다.

이 기능으로 할 수 있는 일

• 하이패스 사용내역 조회
• 하이패스 영수증 PDF/PNG 저장
• SRT 영수증 PNG 저장
• KTX/Korail 영수증 PNG/redacted JSON 저장
• provider별 월별 폴더 정리
• 파일명에 날짜, provider, 구간, 금액 반영
• 성공·실패 요약
• 실패 항목의 사유 기록

먼저 알아둘 점

이 스킬은 모든 인증을 자동으로 통과하려는 도구가 아닙니다.

다음 상황에서는 자동화를 멈추는 것이 맞습니다.

• CAPTCHA
• 추가 본인확인
• OTP
• 공동인증서 조작
• 휴대전화 인증
• 결제, 취소, 환불
• 계정 변경

공공기관 실무용 스킬에서는 “어디까지 자동화할 것인가”만큼 “어디서 멈출 것인가”가 중요합니다.

입력

기본 입력은 다음입니다.

• provider: hipass, srt, korail
• 시작일과 종료일
• 저장 폴더
• 선택 항목 또는 row index
• 실행 옵션: --headless, --auth-mode session, --list-only, --no-render-local

KTX/Korail을 사용할 때는 공개 저장소에 포함되지 않은 로컬/private 커넥터가 필요합니다.

출력

provider별 대표 산출물은 다음과 같습니다.

하이패스: PDF + PNG
SRT: PNG
KTX/Korail: PNG + redacted JSON

예시 출력 구조는 다음과 같습니다.

outputs/receipts/2026-05/
  2026-05-03_hipass_서울TG-동대구TG_12800.pdf
  2026-05-03_hipass_서울TG-동대구TG_12800.png
  2026-04-21_korail_오송-동대구_24800.png
  2026-04-21_korail_오송-동대구_24800.json

기본 흐름

1. provider와 기간을 확인합니다.
2. provider별 인증 조건을 확인합니다.
3. 추가 본인확인이 나오면 자동화를 중단합니다.
4. 사용내역 또는 승차권 구입이력을 조회합니다.
5. 대상 건의 영수증 데이터를 확인합니다.
6. 제출 가능한 산출물을 저장합니다.
7. 저장된 파일과 실패 항목을 요약합니다.

결과 확인 포인트

작업 후에는 아래를 확인합니다.

• 같은 거래 기준으로 파일이 묶였는가
• 파일명에 날짜, provider, 구간, 금액이 들어갔는가
• 조회 기간이 요청한 기간과 맞는가
• PNG가 제출 가능한 영수증 형태인가
• 실패 항목의 사유가 남았는가
• 계정정보, 카드번호 원문, 인증정보가 로그에 남지 않았는가
• KTX/Korail 내부 구현 세부사항이 공개 문서에 남지 않았는가

주의할 점

정산 증빙은 “비슷하게 만든 이미지”만으로 충분하지 않을 수 있습니다.

가능하면 공식 사이트나 앱에서 확인 가능한 데이터와 실제 저장본 형식에 가깝게 맞춰야 합니다. 제출처가 엄격한 경우에는 공식 앱 또는 사이트에서 직접 저장한 원본 이미지를 우선해야 합니다.

KTX/Korail은 특히 공개 저장소와 로컬 구현의 경계를 나눕니다. 공개 문서에는 기능과 안전 경계만 남기고, 내부 호출 구조나 파라미터는 남기지 않습니다.

관련 파일

skills/transport-receipt-collector/
  SKILL.md
  references/hipass.md
  references/korail-srt.md
  scripts/collect_transport_receipts.cjs
docs/features/transport-receipt-collector.md

저장소

https://github.com/mouseco/k-gov-skills/tree/main/skills/transport-receipt-collector

정리

transport-receipt-collector의 가치는 큰 기능 하나가 아니라, 작고 귀찮은 정산 반복 업무를 안전한 절차로 고정하는 데 있습니다.

하이패스, SRT, KTX/Korail 영수증을 provider별로 처리하되, 산출물은 같은 기준으로 정리합니다. 그리고 자동화하지 말아야 할 인증·결제·민감정보 영역은 명확히 제외합니다.

이 스킬의 목표는 영수증을 멋지게 보여주는 것이 아니라, 나중에 다시 찾고 제출할 수 있는 증빙 묶음을 안정적으로 남기는 것입니다.