위택스 API 연동 방법 (CODEF 기준): 지방세 데이터 실전 가이드

최종 수정일: 2026년 07월 21일

지방세 업무를 다뤄본 분이라면, 법인 차량 자동차세나 재산세 고지 내역을 매번 위택스 사이트에 접속해 하나씩 확인하던 번거로움을 아실 겁니다. 이런 반복 업무를 우리 서비스나 사내 시스템 안에서 자동으로 처리할 수 있게 해주는 것이 바로 위택스 지방세 데이터 연동 API입니다.

 다만 시작하기 전에 용어를 정확히 짚어야 합니다. 개발자들이 실무에서 ‘위택스 API‘라고 부르며 연동하는 것은, 대개 데이터 연동 전문 기업이 위택스의 지방세 데이터를 조회할 수 있도록 제공하는 API입니다. 이 글에서는 그중 CODEF가 제공하는 지방세 부과내역 조회 API를 기준으로, 연동의 개념과 흐름을 실전 관점에서 정리해 드립니다.

위택스 API 개요

위택스 API란 무엇인가요?

먼저 용어를 정리하겠습니다. 위택스(Wetax)는 행정안전부가 운영하는 대한민국 지방세 통합 시스템으로, 전국 지방자치단체의 지방세 조회·납부를 하나의 창구에서 처리하는 실제 공공 서비스입니다. 여기서 오해하기 쉬운 지점이 있습니다. 위택스가 납세자별 부과내역을 조회하는 공개 Open API를 제공하는 것은 아닙니다. 공공데이터 포털에 지방세와 관련된 통계성 공개 API가 일부 존재하기는 하지만, 특정 납세자의 부과내역을 인증을 거쳐 조회하는 API는 그와 다른 성격이며, 이 글이 다루는 것은 후자입니다.

그래서 실무에서 ‘위택스 API’라고 하면, 위택스에 있는 지방세 데이터를 외부 서비스에서 가져올 수 있도록 데이터 연동 전문 플랫폼이 제공하는 API를 가리키는 경우가 많습니다. 대표적인 것이 CODEF(헥토데이터)의 지방세 관련 API입니다. 개발자는 CODEF API라는 창구를 통해 “이 사용자의 지방세 부과내역을 조회해 줘”라고 요청하고, 그 결과를 JSON 형태로 받아 자신의 앱이나 회계 시스템에 통합할 수 있습니다.

이 구분이 중요한 이유는 인증 방식과 연동 구조가 일반적인 공공 오픈 API와 전혀 다르기 때문입니다. API 키만으로 익명 데이터를 받아오는 방식이 아니라, 실제 납세자 본인 인증(공동인증서 또는 간편인증)을 거쳐 그 사람의 지방세 정보를 가져오는 방식입니다. 이 개념을 먼저 이해하고 가야 이후 연동에서 헤매지 않습니다.

위택스 API의 주요 기능은 무엇인가요?

CODEF가 제공하는 지방세 관련 API 중 가장 기본이 되는 것이 지방세 부과내역 조회 기능입니다. 개인이나 법인에게 부과된 지방세 내역을 인증을 거쳐 조회하고, 세목·납세자명·납부기한·전자납부번호·납부금액·가상계좌 정보까지 구조화된 데이터로 받아볼 수 있습니다.

호출 주소(Endpoint)는 개발·테스트용 데모 환경과 실제 서비스용 정식 환경으로 나뉩니다. 데모 환경에서 인증 흐름을 충분히 검증한 뒤 정식 환경으로 전환하는 것이 일반적인 개발 순서입니다.

 다만 엔드포인트 주소와 경로는 버전에 따라 달라질 수 있으므로, 실제 연동 시에는 CODEF 공식 개발 문서의 ‘지방세 부과내역 API’ 페이지에서 최신 엔드포인트 값을 반드시 다시 확인해야 합니다. 이 글에 나오는 주소·경로·코드값은 모두 작성 시점 기준의 예시로만 참고하시기 바랍니다.

이 API가 반환하는 주요 데이터는 다음과 같습니다.

여기서 실무적으로 중요한 개념 하나는, 단건 조회는 객체 형태로, 다건 조회는 리스트 형태로 반환된다는 점입니다. 응답을 파싱하는 로직을 짤 때 이 두 경우를 모두 처리하도록 설계해야 예외가 생기지 않습니다. 이런 반환 형태의 차이는 잘 바뀌지 않는 구조적 특성이라 미리 알아두면 유용합니다. 구체적인 필드명과 필수·옵션 여부는 버전에 따라 조정될 수 있으니 공식 문서의 필드 정의를 기준으로 최종 확정하세요.

위택스 API 활용 및 연동

위택스 API 연동 절차는 어떻게 되나요?

이 API 연동의 핵심 개념은 납세자 본인 인증입니다. 지방세 정보는 민감한 개인·금융 정보이므로, API 키만으로 아무 데이터나 받아오는 것이 아니라 실제 그 납세자의 인증을 거쳐야 조회가 됩니다. 인증 방식은 크게 두 갈래로 나뉩니다.
첫째는 인증서 방식입니다. 공동인증서(기존 공인인증서)를 이용하는 방식으로, 인증서 파일과 암호화된 인증서 비밀번호를 함께 전달합니다.
둘째는 간편인증 방식입니다. 카카오톡, 통신사 PASS, 네이버, 신한인증서 등 사용자가 스마트폰으로 승인하는 방식으로, 사용자 이름·주민번호·전화번호 등을 함께 전달합니다.
각 인증 수단을 지정하는 구체적인 코드값(로그인 구분, 간편인증 종류 등)은 버전에 따라 갱신될 수 있으므로, CODEF 개발 문서의 코드 테이블을 참고해 구현해야 합니다. 개념적으로는 “인증서로 갈지, 간편인증으로 갈지를 먼저 정하고, 그에 맞는 입력값 세트를 구성한다”는 흐름만 잡으면 됩니다. 입력부의 대략적인 구조는 다음과 같은 형태입니다(주요 필드 구조를 보여주는 예시이며, 실제 필수·옵션 여부와 정확한 필드명은 CODEF 개발 문서의 필드 정의를 기준으로 최종 확정해야 합니다).

{
  "organization": "기관코드",
  "loginType": "인증 방식 구분",
  "certFile": "인증서 파일 문자열 (인증서 방식)",
  "keyFile": "인증서 key 파일 문자열 (인증서 방식)",
  "certPassword": "암호화된 인증서 비밀번호",
  "userName": "사용자 이름 (간편인증)",
  "identity": "주민등록번호",
  "startDate": "조회 시작일",
  "endDate": "조회 종료일"
}

주민등록번호는 암호화 여부에 따라 입력 방식이 달라집니다. 다만 주민번호·생년월일의 암호화 방식과 RSA 키 사용 방법은 보안에 직결되는 부분이라 임의로 구현하면 안 되고, CODEF 암호화 가이드와 해당 API 명세서의 ‘암호화 규칙’ 섹션을 그대로 따라야 합니다. 이 부분은 문서를 정확히 따르는 것이 곧 보안이므로, 예시를 참고하되 실제 값은 반드시 공식 규칙대로 처리하세요.

위택스 API 개발 가이드 활용하기

이 API에서 개발자가 가장 많이 막히는 지점이자, 이 글에서 꼭 이해하고 넘어가야 할 개념이 2-way 추가인증 흐름입니다. 공식 명세서만 봐서는 “왜 요청을 두 번 보내야 하는지” 감이 안 오는 경우가 많은데, 원리를 알면 간단합니다. 간편인증처럼 사용자의 추가 행동(스마트폰 앱에서 인증 승인)이 필요한 경우, 요청 한 번으로 데이터가 바로 오지 않습니다. 흐름은 이렇습니다. 먼저 1차 요청을 보내면, 서버는 “사용자가 아직 인증을 승인하지 않았으니 기다리라”는 의미의 응답을 돌려줍니다. 이때 추가 인증이 필요하다는 신호와 함께, 2차 요청에 필요한 식별값들(작업 인덱스, 트랜잭션 아이디, 타임스탬프 등)이 내려옵니다. 사용자가 스마트폰에서 인증을 승인한 뒤, 이 식별값들을 그대로 담아 2차 요청을 보내면 그제서야 실제 지방세 부과내역이 반환됩니다.

즉 “1차 요청 → 사용자 인증 대기 → 식별값 보관 → 사용자 승인 → 2차 요청 → 최종 데이터”의 두 단계 구조입니다. 이 흐름을 놓치면 “간편인증을 걸었는데 데이터가 안 온다”는 문제로 시간을 많이 쓰게 되므로, 연동 초기에 이 2-way 구조를 먼저 이해하고 1차 응답의 식별값을 저장·전달하는 로직부터 설계하는 것을 강력히 권합니다. 이 개념적 흐름은 잘 바뀌지 않지만, 실제 응답코드와 필드명·값은 버전 업데이트로 변경될 수 있으므로, 연동 시에는 CODEF 최신 개발 문서와 샌드박스 응답 값을 로그로 직접 확인해 구현해야 합니다.

위택스 API 활용 사례는 무엇인가요?

이 API의 실질적인 가치는 반복적인 지방세 확인·정리 업무를 자동화하는 데 있습니다. 예를 들어 여러 법인 차량이나 부동산을 관리하는 회계 담당자라면, 매번 위택스에 접속해 고지 내역을 눈으로 확인하는 대신, 인증을 거쳐 부과내역을 한 번에 불러와 사내 시스템에 정리하도록 만들 수 있습니다.

핀테크·회계 SaaS 관점에서는 사용자가 자신의 지방세 부과내역을 앱 안에서 바로 확인하도록 하는 기능에 활용할 수 있습니다. 반환 데이터에 세목·납부기한·전자납부번호·납부금액·가상계좌가 포함되므로, 이를 가공해 “납부 예정 세금 목록”이나 “납기 임박 알림” 같은 기능으로 구성할 수 있습니다. 다만 실제 납부 처리나 증명서 발급 등 다른 지방세 기능이 필요하다면, 부과내역 조회와는 별도의 API가 제공되는지 CODEF 공식 개발 문서에서 각각 확인해야 합니다. 이 글에서 다룬 것은 ‘지방세 부과내역 조회’ 기능을 기준으로 한 내용입니다.

위택스 API를 활용한 지방세 조회

정리하는 의미에서 지방세 부과내역 조회의 전체 흐름을 개념 중심으로 다시 짚어보겠습니다. 먼저 조회할 사용자의 인증 방식을 정하고(인증서 또는 간편인증), 그에 맞는 입력값을 구성합니다. 조회 기간을 지정해 요청을 보낸 뒤, 추가 인증이 필요하다는 신호가 오면 2-way 절차를 밟고, 사용자가 인증을 승인하면 2차 요청으로 최종 데이터를 받습니다. 반환된 데이터에서는 세목별 과세·가산·합계금액과 가상계좌 정보를 함께 받을 수 있습니다. 앞서 강조한 대로 단건이면 객체, 다건이면 리스트로 오므로 이 형태를 구분해 처리해야 합니다. 인증을 거쳐 조회하는 구조이기 때문에, 조회 결과는 저장된 과거 값이 아니라 인증 시점을 기준으로 한 데이터가 반환됩니다.

이처럼 위택스 지방세 데이터를 API로 연동하면, 사람이 하나하나 확인하던 지방세 업무를 시스템이 대신 처리하도록 만들 수 있습니다. 처음 연동할 때는 인증 방식 선택과 2-way 추가인증 흐름에서 막히는 경우가 많으므로, 데모 환경에서 인증 플로우부터 충분히 검증한 뒤 정식 환경으로 넘어가시길 권합니다.

이 글은 2026년 7월 기준으로 작성되었으며, 개념과 흐름 위주로 정리했습니다. 엔드포인트·코드값·필드 정의·응답코드 등 구체 사양은 이후 CODEF 명세가 업데이트되면 달라질 수 있으니, 실제 개발 시에는 정확한 파라미터와 최신 사양을 반드시 CODEF 공식 개발 문서에서 다시 확인하시기 바랍니다.

FAQ

Q1: 위택스 API는 행정안전부가 직접 제공하는 공식 오픈 API인가요?
아닙니다. 위택스는 행정안전부가 운영하는 지방세 시스템이 맞지만, 위택스가 납세자별 부과내역을 조회하는 공개 Open API를 제공하는 것은 아닙니다. 공공데이터포털에 지방세 관련 통계성 공개 API가 일부 있긴 하나 납세자별 조회 API는 아니며, 실무에서 ‘위택스 API’로 연동하는 것은 대체로 CODEF 같은 데이터 연동 전문 기업이 제공하는 API입니다. 이 글도 CODEF의 지방세 부과내역 조회 API를 기준으로 설명합니다.

Q2: 이 API를 쓰려면 어떤 인증이 필요한가요?
납세자 본인 인증이 필요합니다. 크게 공동인증서 방식과 간편인증 방식(카카오톡·통신사 PASS·네이버·신한인증서 등)으로 나뉩니다. API 키만으로 익명 조회가 되는 방식이 아닙니다. 각 인증 수단의 구체적인 코드값은 CODEF 개발 문서의 코드 테이블을 참고해 구현합니다.

Q3: 간편인증을 걸었는데 데이터가 한 번에 오지 않습니다.
정상입니다. 간편인증처럼 사용자의 추가 승인이 필요한 경우, 1차 요청 후 사용자가 인증을 승인한 뒤 2차 요청을 보내야 최종 데이터가 반환되는 2-way 구조입니다. 1차 응답에서 내려온 식별값(작업 인덱스·트랜잭션 아이디·타임스탬프 등)을 2차 요청에 그대로 넣어야 합니다. 정확한 응답코드와 필드명은 최신 문서와 샌드박스 응답으로 확인하세요.

Q4: 조회할 수 있는 데이터에는 어떤 것이 있나요?
지방세 부과내역 조회 API 기준으로 세목, 납세자명, 납부기한, 관할 자치단체, 전자납부번호, 납부금액, 세목별 과세·가산·합계금액, 가상계좌(은행·계좌번호) 정보 등이 반환됩니다. 단건은 객체, 다건은 리스트 형태입니다.

Q5: 개발과 실제 서비스에서 호출 주소가 다른가요?
네. 개발·테스트용 데모 환경과 실제 운영용 정식 환경의 호출 주소가 구분됩니다. 개발·테스트는 데모 환경에서 진행한 뒤, 검증이 끝나면 정식 환경으로 전환하는 것이 일반적입니다. 정확한 엔드포인트 주소는 버전에 따라 달라질 수 있으니 CODEF 공식 개발 문서에서 최신 값을 확인하세요.

한 지석

테크백과 운영자 · 데이터 엔지니어 한지석입니다. 11년간 금융·공공 데이터 파이프라인을 구축하고 API 문서화를 담당해왔습니다. 흩어져 있는 API 정보를 한 항목씩 검증해 레퍼런스로 정리합니다.