경정청구 세무자료 자동수취

세무사무소가 경정청구(과오납 세금 환급 청구) 업무를 수행하려면 고객사의 최근 5개년 신고 이력이 반드시 필요합니다. 이 솔루션은 고객 인증 1회만으로 홈택스에서 부가가치세 · 법인세 · 종합소득세 신고서와 부속서식, 근로자 고용정보를 자동 수집해 클라우드에 보관하는 웹 서비스입니다. 직원용 웹(수취 실행 · 진행 확인)과 관리자 웹(문서 열람 · 이력 · 권한 관리)으로 분리해, 영업 직원은 수취만 수행하고 고객 자료 파일에는 접근할 수 없도록 권한을 설계했습니다.

경정청구는 5년치 신고자료 확보가 전제인데, 담당자가 고객사마다 홈택스에 직접 로그인해 수십 개 서식을 연도별로 하나씩 조회 · 출력해야 했습니다. 고객 1곳당 수백 번의 반복 작업이 발생하고, 서식이 누락돼도 확인할 방법이 없어 재인증을 요청하는 일이 반복됐습니다. 상용 API 도입은 건당 비용이 사업성에 맞지 않아 자체 구현을 택했습니다.

Next.js 16 · React 19 · TypeScript · Tailwind · Python 3.12 · FastAPI · Playwright · curl_cffi · pypinksign · Firebase · GCP Cloud Run · Cloud Tasks · Cloudflare Worker · pytest

1. 01

   외부 시스템 연동의 신뢰성 확보

   공식 API · 에러 규격이 제공되지 않는 환경에서 인증부터 자료 수집까지 전 과정을 안정적으로 동작시키는 것이 가장 큰 과제였습니다.

2. 02

   다중 인증 경로 설계

   법인 · 개인, 인증서 · 간편인증에 따라 로그인 방식과 조회 권한 범위가 달라, 경로별로 분리된 인증 · 조회 구조를 설계했습니다.

3. 03

   장기 실행 작업의 상태 관리

   건당 20분 이상 걸리는 작업을 다건 동시 처리하기 위해, 진행 상태 · 중단 감지 · 부분 완료를 표현하는 상태 모델과 큐 기반 실행 구조를 구축했습니다.

4. 04

   데이터 정합성 검증

   세무자료는 누락이 곧 업무 리스크이므로, "자료 없음"과 "확인 실패"를 구분하고 불완전한 결과를 성공으로 처리하지 않는 검증 체계를 설계했습니다.

5. 05

   회귀 방지 체계

   외부 사이트 변경에 따른 동작 변화를 조기에 감지하기 위해, 실제 장애 사례를 테스트로 축적해 운영 안정성을 유지했습니다.

2026.05 – 2026.07
홈택스 자동화 · 클라우드 문서 보관