개발자 문서/지방세 납부·환급 결과조회

지방세 납부·환급 결과조회

명세 내보내기OpenAPI 3.0.3Postman 컬렉션Markdown

transactionId 로 처리 상태를 확인하고, 조회가 끝난 뒤에는 표준화된 결과를 반환합니다. 인증 대기·조회 중·실패 응답은 과금되지 않으며, 실제 결과가 최초로 반환될 때만 1회 과금됩니다.

POST/rest/get_local_tax_payment
요청 예제로 이동 ↓

기능·제공 범위

인증
Bearer 키
요청
form-data
응답
JSON
요금·이용 조건
기본 단가 240P · 건당
이용 전 결제 필요

빠른 시작

서버의 APICK_API_KEY를 준비하고 입력값을 바꾸세요. 아래에서 경로별 입력·응답·실행 환경을 함께 확인할 수 있습니다.

요청과 응답

API 요청
POST/rest/get_local_tax_payment

Bearer 인증 · multipart/form-data · JSON 응답

입력 항목
폼 항목·타입
필수
설명·예제
transactionIdstring
필수
/rest/req_local_tax_payment 가 반환한 트랜잭션 ID예: 9f2c4a7b1d8e35c60a4f7b2d1e9c803a
응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

추가 입력 조건·전송 규칙

요청 본문 형식

인증요청·결과조회 모두 POST + form-data 입니다. 입력은 모두 최상위 이름으로 보내며, 아래 형식 하나만 씁니다.

형식
Content-Type
보내는 값 예시
form-data (정본)
multipart/form-data
name=홍길동&birthDate=900101&phone=01012345678&authProvider=kakao
입력을 user·requestData·options 로 묶지 마세요. 조회 조건과 조회 기간도 docNo·customerNo·years 처럼 최상위 이름 그대로 보냅니다. 이름은 birthDate 대신 birthday, authProvider 대신 provider 로 보내도 같은 값으로 인정됩니다. 문서·코드·테스트는 birthDate·authProvider 로 통일합니다.
Header
이름
필수
설명
Authorization
O
Bearer 인증키
본문은 transactionId 하나입니다. 결과조회 엔드포인트는 인증요청과 짝이 되는 /rest/get_local_tax_payment 이며, 다른 항목의 엔드포인트로 조회하면 실패합니다. 조회 시각 기준 24시간이 지나면 RESULT_EXPIRED 가 반환됩니다. 이때는 인증요청부터 다시 시작해야 하며, 인증요청 단가(20P)가 다시 발생합니다.
요청 예시

form-data 전체 예제 보기

응답 상세

서비스 고유 응답·필드 상세 설명
처리 상태(status)
값
의미
과금
AUTH_REQUESTED
조회 인증 요청 (/rest/req_local_tax_payment 응답)
인증요청 시 과금
AUTH_WAITING
사용자 인증 대기중
무과금
AUTH_COMPLETED
승인 완료, 조회 시작 전
무과금
COLLECTING
조회 결과를 준비하는 중
무과금
SUCCESS
모든 항목 조회 완료
최초 1회만
PARTIAL_SUCCESS
일부 항목만 조회 완료 (sources 참고)
최초 1회만
AUTH_REJECTED
사용자가 인증을 거부
무과금
AUTH_EXPIRED
제한 시간 안에 승인하지 않음
무과금
FAILED
조회 실패
무과금
Body
이름
타입
설명
data
Object
상태·결과
schemaVersion
String
결과 스키마 버전 (고정값: "1.0")
transactionId
String
트랜잭션 ID
product
String
조회 항목 코드. 인증요청 응답과 같은 값입니다.
status
String
처리 상태 (위 표 참고)
resultAvailable
Boolean
실제 결과 포함 여부. 과금 여부도 이 값으로 결정됩니다.
charged
Boolean
이번 호출의 과금 발생 여부. 최초 결과 반환에서만 true 입니다.
sources
Array
항상 포함됩니다. 값이 없으면 빈 배열 [] 입니다. 항목이 여러 개인 상품에서 어느 것이 성공·실패했는지 알려줍니다. 각 항목은 source(제공 기관명), type(데이터 종류), status(SUCCESS/FAILED). 수집이 끝나기 전에는 아직 확정되지 않은 기관이 FAILED 로 보일 수 있습니다.
progress
Object
진행률(COLLECTING 일 때). total(전체 항목), completed(완료 항목)
checkedAt
String
실제 정보를 확인한 시각. 한국시간(UTC+09:00) ISO 8601 이며 재조회 유효기간의 기준입니다.
resultExpiresAt
String
결과 재조회 만료 시각. 한국시간(UTC+09:00) ISO 8601 입니다.
errorCode
String
오류 구분. RESULT_EXPIRED(재조회 기간 만료) / AUTH_EXPIRED / AUTH_REJECTED / COLLECT_FAILED
result
Object
조회된 결과 묶음. 실제 데이터가 있을 때만 포함됩니다.
localTaxPayment
Object
이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요.
message
String
상태 메시지
success
Integer
과금 여부
0: 결과 없음 또는 재조회(무과금)
1: 최초 결과 반환(과금)
api
Object
API 호출 공통 데이터
success
Boolean
API 서버 정상 응답 여부
cost
Integer
API 호출 요금
ms
Integer
API 응답 시간
pl_id
Integer
API 결제 로그 ID

결과 규격

result.localTaxPayment
경로
타입
값 존재
설명
예시
조회기간
Object
O
조회 구간.
시작
String(YYYY-MM-DD)
O
조회 구간 시작
2023-10-01
끝
String(YYYY-MM-DD)
O
조회 구간 끝
2025-09-30
합계
Object
O
납부·납부대상·통합납부·환급신청 전체 합계.
납부건수
Integer
O
지방세 납부 건수
12
납부금액
Integer
O
납부금액 합계(원)
1280000
납부대상건수
Integer
O
납부 대상 건수
1
납부대상금액
Integer
O
납부 대상 금액(원)
154000
통합납부건수
Integer
O
통합납부 건수
0
통합납부금액
Integer
O
통합납부 금액(원)
0
환급신청건수
Integer
O
환급 신청 건수
0
미수령환급금건수
Integer
O
미수령 환급금 건수
0
미수령환급금
Object
O
찾아가지 않은 환급금 건수를 종류별로 센다.
지방세
Integer
O
지방세 미수령 환급금 건수
0
국세
Integer
O
국세 미수령 환급금 건수
0
환경개선부담금
Integer
O
환경개선부담금 미수령 건수
0
납부내역
Array<Object>
O
지방세 납부 건별 내역. 자동납부는 "예"·"아니오" 문자열이다.
납부일
String(YYYY-MM-DD)
O
납부일
2025-03-14
세목
String
O
세목
재산세
구분
String
O
지방세 구분
지방세
자치단체
String
O
과세 자치단체
서울특별시 강남구
과세대상
String
O
과세 대상
자동차
납부금액
Integer
O
납부금액(원)
1280000
자동납부
String
O
자동납부 여부("예"/"아니오")
아니오
전자납부번호
String
O
전자납부번호
2025-0001234
납부대상
Array<Object>
O
아직 납부하지 않은 고지 건. 없으면 빈 배열이다.
납부기한
String(YYYY-MM-DD)
O
납부 기한
2025-03-14
세목
String
O
세목
재산세
자치단체
String
O
과세 자치단체
서울특별시 강남구
과세대상
String
O
과세 대상
자동차
고지금액
Integer
O
고지금액(원)
154000
납부금액
Integer
O
이미 납부한 금액(원)
0
귀속연도
String
O
귀속연도
2025
귀속월
String
O
귀속월 2자리
03
전자납부번호
String
O
전자납부번호
2025-0001234
통합납부내역
Array<Object>
O
여러 세목을 묶어 낸 통합납부 건. 없으면 빈 배열이다.
납부일
String(YYYY-MM-DD)
O
납부일
2025-03-14
세목
String
O
세목
재산세
구분
String
O
지방세 구분
지방세
납세자
String
O
납세자명
홍길동
자치단체
String
O
과세 자치단체
서울특별시 강남구
납부금액
Integer
O
납부금액(원)
1280000
환급신청내역
Array<Object>
O
환급 신청 건. 없으면 빈 배열이다.
신청일
String(YYYY-MM-DD)
O
신청일
2025-03-14
신청인
String
O
신청인명
홍길동
자치단체
String
O
신청 자치단체
서울특별시 강남구
환급구분
String
O
환급 구분 코드
01
전자납부번호
String
O
전자납부번호
2025-0001234
타입 읽는 법 — String 은 문자열, Integer 는 소수점 없는 정수(원 단위 금액 포함), Boolean 은 true/false, Object 는 이름이 있는 하위 항목 묶음, Array<Object> 는 같은 구조가 여러 건 오는 목록, Array<String> 은 문자열 목록입니다. String(YYYY-MM-DD) 처럼 괄호가 붙으면 그 형식의 문자열이라는 뜻이고 날짜 타입이 아닙니다. 값 존재 — O는 정상 결과에 있는 항목, 조건부는 해당 정보가 있을 때 제공하는 항목입니다. 누락·빈 문자열·빈 배열·0·null의 의미는 항목별 설명을 따릅니다. 부모 항목이 없으면 그 하위 항목도 없습니다. 예시 — 응답에 들어오는 형태 그대로의 값입니다. 실제 조회 결과가 아니며 개인을 특정할 수 없는 가상의 값입니다. 이 열이 비어 있으면 하위 항목이 있는 묶음이거나 값이 빠질 수 있는 항목입니다. 들여쓰기된 항목은 바로 위 부모 안에 들어 있는 하위 항목입니다. 경로 표기에서 . 는 하위 항목, [ ] 를 붙인 항목은 그 안에 여러 건이 오는 목록이라는 뜻입니다.

경로별 응답 예시와 필드 명세는 위 API 요청 설명에 붙어 있습니다. JSON을 파일로 저장하기 전에는 Content-Type과 오류를 확인하세요.

상태·오류·재시도

HTTP 상태 → API 처리 여부 → 업무 상태 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

서비스별 코드·조건 전체 보기

공통 오류 응답

아래 항목은 조회 항목과 무관하게 공통으로 발생합니다. 오류 응답은 과금되지 않습니다.

상황
확인할 값
대응
인증키 누락·오류
api.success=false
Header Authorization: Bearer 를 확인하세요. 과금되지 않습니다.
입력값 누락·형식 오류
오류 메시지에 어느 항목이 잘못됐는지 표시됩니다.
이름·생년월일·휴대전화번호·인증방식을 다시 확인하세요.
조회 항목에 필요한 추가 입력 누락
오류 메시지에 필요한 입력 이름이 표시됩니다.
아래 요청 표의 추가 입력 항목을 채우세요.
없는 transactionId · 만료된 요청
요청을 찾을 수 없다는 응답 또는 status AUTH_EXPIRED
인증요청부터 다시 하세요.
처리 중 재요청
HTTP 424 · 요청 처리 중 또는 처리 잠금 획득 실패 · api.cost=0
같은 사용자·같은 조회 항목의 접수는 서버가 한 건씩 처리합니다. 앞선 요청이 끝난 뒤 같은 transactionId 로 다시 조회하세요.
결과 재조회 기한 만료
errorCode=RESULT_EXPIRED
24시간이 지났습니다. 인증요청부터 다시 하세요.
사용자 인증 거부
errorCode=AUTH_REJECTED
사용자에게 다시 시도할지 안내하세요. 과금되지 않습니다.
정보 조회 실패
errorCode=COLLECT_FAILED · status FAILED
잠시 후 인증요청부터 다시 시도하세요. 결과 단가는 과금되지 않습니다.
보유 포인트 부족
HTTP 402 · data.error 에 사유 · api.cost=0
이 호출은 과금되지 않습니다. 요금과 포인트를 확인한 뒤 충전하고 다시 요청하세요.
처리 시간 초과
HTTP 408 · data.success=3
서버가 제한 시간 안에 끝내지 못했습니다. 과금되지 않습니다. 잠시 후 같은 요청을 다시 보내세요.
정상 응답은 HTTP 200 입니다. 상태가 인증 대기중·조회 중 이어도 200 이며, data.success 만 0 입니다. HTTP 코드로 성공을 판단하지 말고 data.status 와 data.resultAvailable 을 보세요. api.success 는 "APICK 서버가 요청을 정상 처리했는가"만 뜻합니다. 포인트가 모자라 HTTP 402 로 거절돼도 api.success=true 입니다. 과금 여부는 api.cost 와 data.charged 로 판단하세요.

상태와 성공 판정

필드가 여러 곳에 흩어져 있어 "무엇으로 성공을 판단해야 하는가" 가 가장 많이 나오는 질문입니다. 결론은 data.status 와 data.resultAvailable 두 개입니다.

필드
의미
판단 기준
HTTP 상태 코드
전송 계층의 결과
200 이 정상, 402 는 포인트 부족, 408 은 처리 시간 초과, 424 는 동일 요청 처리 중. 성공 판정에 쓰지 마세요.
api.success
APICK 서버가 요청을 정상 처리했는지
포인트 부족(402)이나 시간 초과(408)에도 true 입니다. 업무 성공 판정에 쓰지 마세요.
data.status
조회 진행 상태
AUTH_WAITING(승인 대기) · AUTH_COMPLETED · COLLECTING(조회 중) · SUCCESS(완료) · FAILED · AUTH_EXPIRED · AUTH_REJECTED · PARTIAL_SUCCESS. resultAvailable=true이면 결과를 사용하세요. RESULT_EXPIRED는 errorCode입니다.
data.resultAvailable
지금 응답에 쓸 수 있는 결과가 들어 있는지
true 이면 폴링을 멈추고 result 를 사용하세요. false는 대기 또는 종료 상태일 수 있으므로 status를 함께 확인하세요.
data.success
이 응답이 결과 제공 응답인지 (1/0)
새 유료 결과 제공에서는 1, 무료 재조회에서는 0일 수 있습니다. 결과 유무는 resultAvailable로 판단하세요. 처리 시간 초과(408)에서는 3 이 오므로 "1 인지"로 비교하세요.
data.charged · api.cost
이번 호출의 과금 여부·금액
과금 회계 확인용입니다. 성공 판정에 쓰지 마세요.
성공 판정 정본: data.resultAvailable === true이고 상태가 SUCCESS 또는 PARTIAL_SUCCESS 이면 성공입니다. resultAvailable=false인 경우 진행 중이거나 종료이며, 종료 상태는 사용자에게 다시 시도할지 물어보세요.
공통 폼 입력 오류

FORM_DATA_INVALID · HTTP 400: 필드 이름·타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.

FORM_DATA_FIELD_CONFLICT · HTTP 400: 같은 값과 중첩 경로를 동시에 지정하지 마세요.

MULTIPART_LIMIT_OR_PARSE_ERROR · HTTP 400/413: boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·제한·이용 조건

기능·제공 범위·요금·제한 전체 보기

한눈에 보는 진행 절차

조회는 인증요청 → 인증대기 → 사용자인증완료 → 정보조회 → 정보제공 5단계입니다. 과금은 1단계(인증요청 발송 성공) 와 5단계(결과 최초 제공) 두 번만 발생하고, 그 사이 조회는 몇 번을 호출해도 무과금입니다.

인증부터 정보조회까지 절차: 1 인증요청 API 호출, 2 인증대기중, 3 사용자인증완료, 4 정보조회, 5 정보제공
단계
무슨 일이 일어나는가
내 코드가 할 일 / 과금
1. 인증요청 API 호출
요청한 사용자에게 간편인증 요청이 발송되고, 결과 조회에 쓸 transactionId 가 즉시 반환됩니다. 인증요청은 1회만 발송됩니다.
반환된 transactionId 를 저장하세요. 발송에 성공하면 20P 과금, 실패하면 무과금으로 실패 응답이 옵니다.
2. 인증대기중
사용자가 아직 승인하지 않은 상태입니다. 조회하면 status AUTH_WAITING 과 "인증 대기중입니다." 메시지를 돌려줍니다.
결과조회 API 를 주기적으로 호출하세요. 이 구간은 무과금입니다.
3. 사용자인증완료
사용자가 간편인증을 승인하면 서버가 정보를 조회하기 시작합니다.
별도 호출이 필요 없습니다. 다음 조회에서 status 가 AUTH_COMPLETED → COLLECTING 으로 바뀝니다.
4. 정보조회
요청한 항목의 최종 정보를 조회해 결과를 만듭니다.
계속 조회하세요. 이 구간도 무과금입니다.
5. 정보제공
status SUCCESS 로 표준화된 결과가 result 에 담겨 반환됩니다.
새 결과 제공의 과금 여부는 charged와 api.cost로 확인합니다. 결과 보관 기준은 수집 시각(checkedAt)입니다. 응답의 resultExpiresAt을 확인하고 받은 자료를 즉시 보관하세요.
인증요청 5분 · 결과 재조회 24시간은 서로 다른 기한입니다. 5분(AUTH_WAITING 중 expiresAt)은 "사용자가 승인해야 하는 시간"이고, 24시간(resultExpiresAt)은 "받은 결과를 다시 꺼내볼 수 있는 시간"입니다. 5분 안에 승인하지 못하면 그 요청은 AUTH_EXPIRED 로 끝나고 결과 단가는 발생하지 않습니다. 인증요청 단가 20P 는 발송이 성공한 시점에 이미 발생하므로 승인 실패·거부와 무관하게 환불되지 않습니다. 결과 보관 만료는 errorCode=RESULT_EXPIRED로 구분합니다. 새 인증·조회에는 각 단계의 과금 조건이 다시 적용됩니다. 동일 APICK 계정·같은 상품의 진행 중 요청 또는 최근 30초 내 요청이 있으면 인증을 재발송하지 않고 기존 transactionId 를 그대로 반환합니다. 이때는 success=0, charged=false 로 돌아오며 과금되지 않습니다. 중복 판정은 조회 대상자의 이름·전화번호가 아닌 계정·상품 기준입니다. 다른 대상자의 인증을 동시에 요청하지 마세요.

모든 조회 상품에 공통인 계약

항목
내용
비고
엔드포인트
조회 항목마다 전용 2개입니다. /rest/req_<항목> 으로 인증요청, /rest/get_<항목> 으로 결과조회를 합니다.
조회 항목을 지정하는 product 파라미터가 없습니다. 엔드포인트 자체가 항목입니다.
HTTP Method
POST 만 지원합니다. GET·PUT·DELETE 는 동작하지 않습니다.
본문은 form-data(Content-Type: multipart/form-data)로 보냅니다. 기존 레거시 API와 같은 규격입니다. 요청 본문 형식을 참고하세요.
인증키
Header Authorization: Bearer 에 발급받은 키를 넣습니다.
키가 없거나 틀리면 인증 없이 거절되며 과금되지 않습니다.
회신 형식
모든 응답이 data(상태·결과)와 api(호출 공통 정보) 두 덩어리로 고정됩니다.
api.success 는 API 서버 정상 응답 여부이고, 과금 여부는 data.success(0/1)입니다.
입력값
성명·생년월일·휴대전화번호는 인증받는 본인의 정보여야 합니다. 타인 명의로는 승인되지 않습니다.
휴대전화번호는 숫자만 넣으세요(하이픈 없이). 주민등록번호는 받지 않습니다.
동시 호출
같은 사용자·같은 조회 항목의 동시 요청은 하나로 합쳐 처리됩니다. 두 번째 요청은 첫 요청의 transactionId 를 재사용하며 추가 과금되지 않습니다.
서버가 처리 중일 때는 잠시 후 다시 시도하라는 응답이 올 수 있습니다.
재시도
인증 대기·조회 중 구간은 무과금이므로 부담 없이 반복 호출할 수 있습니다. 같은 결과의 재조회는 charged 및 api.cost를 확인하세요. 잔액·이용 조건에 따라 요청이 거절될 수 있으므로 오류 응답도 처리해야 합니다.
과금은 인증요청 발송과 결과 최초 제공 두 지점에서만 발생합니다.
개인정보
조회 결과는 요청에 대한 응답으로만 쓰이며, 조회 시각 기준 24시간 뒤에는 재조회가 만료됩니다.
받은 결과는 이용하는 서비스의 개인정보 처리방침에 맞게 직접 보관·파기해야 합니다.
인증 대기중(AUTH_WAITING)과 조회 중(COLLECTING)은 실패가 아닙니다. 개발 중에 이 응답을 오류로 처리해 사용자에게 "실패"라고 보여주는 경우가 많습니다. resultAvailable=false 는 "아직 준비 중"이라는 뜻이고, resultAvailable=true 일 때만 결과를 사용하세요. 같은 transactionId 를 다른 조회 항목의 엔드포인트로 조회하면 실패합니다. 인증요청에 사용한 /rest/req_<항목> 과 같은 항목의 /rest/get_<항목> 을 짝으로 사용하세요.

개발 체크리스트

아래 순서대로 구현하면 조회 상품 하나를 연동할 수 있습니다.

단계
할 일
1
인증키를 발급받아 서버 환경변수에 넣습니다. 브라우저에서 직접 호출하면 키가 노출되므로 반드시 자체 백엔드에서 호출하세요.
2
사용자에게 이름·생년월일·휴대전화번호를 입력받고, 간편인증 방식(authProvider)을 고르게 합니다. 서버로는 숫자만 남긴 번호를 보내세요(하이픈 제거).
3
/rest/req_<항목> 을 호출하고 응답의 transactionId 를 보관합니다. 이 시점에 20P 가 과금됩니다.
4
사용자에게 간편인증 요청이 발송됐음을 안내하고, 인증 완료를 기다립니다. 남은 시간은 expiresAt 으로 안내하세요.
5
/rest/get_<항목> 로 상태를 확인합니다. resultAvailable 이 true 가 되면 폴링을 멈추고 결과를 사용하세요.
6
transactionId 로 결과물을 조회합니다. 정상 완료 결과는 수집 시각 기준 24시간을 기본 보관기간으로 사용합니다. resultExpiresAt과 응답 상태를 확인하고 부분 성공 결과도 즉시 저장하세요.
7
AUTH_EXPIRED · AUTH_REJECTED는 종료 상태이며 errorCode=RESULT_EXPIRED는 재조회 만료를 뜻하므로, 사용자에게 다시 시도할지 물어보는 흐름으로 처리하세요.
인증 승인은 사용자가 직접 해야 합니다. 승인 대행·자동 승인·인증 정보 저장은 지원하지 않으며, 사용자에게 승인 화면을 안내하는 흐름을 직접 만들어야 합니다. 승인 전 화면을 이탈한 사용자가 많다면 클라이언트 최대 대기시간 지정 남은 시간을 표시하고, 만료 후에는 재요청 버튼을 제공하세요. 만료된 transactionId 는 재사용할 수 없습니다.

연동 전에 확인하세요

실제 고객 연동에서 자주 나오는 질문입니다. 이 항목들을 먼저 정하면 시행착오를 줄일 수 있습니다.

확인 항목
내용
이유
인증키 발급·보관
인증키는 마이페이지에서 확인합니다(별도 신청 절차 없음). Header Authorization: Bearer 에 마이페이지에 표시된 인증키 값을 그대로 넣으세요. 서버 환경변수에 두고 브라우저·앱 클라이언트에는 넣지 마세요. 노출이 의심되면 마이페이지에서 재발급하면 기존 키는 즉시 무효가 됩니다.
인증키는 비밀번호와 같습니다. 앱에 심으면 누구나 추출해 과금을 발생시킬 수 있습니다.
사용자 동의
조회 전에 이용자가 본인 정보 조회에 동의한다는 사실을 서비스 약관·동의 화면에서 받아 두세요. 인증 승인은 그 동의를 확인하는 절차이지 동의를 대신하지 않습니다.
조회 결과를 서비스에 활용하려면 동의 근거가 필요합니다.
제3자 제공 동의는 따로
조회 결과를 이용자 본인에게 보여주거나 본인이 제출하는 용도로만 쓰면 별도 동의가 필요하지 않습니다. 반대로 금융사·렌탈사 등 제3자에게 제공하거나 대출·보증 심사에 쓰면 제3자 제공 동의를 별도로 받아야 합니다. 본인 조회 동의와 제3자 제공 동의는 서로 다른 동의입니다.
제3자 제공은 본인 조회와 법적 성격이 달라, 같은 조회라도 동의 근거가 하나 더 필요합니다.
이용목적 기록
요청 본문에 user.purpose 를 넣으면 이용목적이 원장에 함께 남습니다. 넣지 않아도 조회는 정상 처리되지만, 제3자 제공이나 심사 목적이면 남겨 두세요.
제공 목적과 근거를 남겨 두면 사후 분쟁·감독 대응에서 사실 확인이 쉬워집니다.
보내는 개인정보
보내는 값은 이름 · 생년월일 · 휴대전화번호 뿐입니다. 주민등록번호는 받지 않습니다. 화면에서도 주민등록번호 입력칸을 만들지 마세요.
수집 항목을 최소로 줄이면 보관·파기 부담과 유출 위험이 함께 줄어듭니다.
테스트 방법
샌드박스·모의 승인은 없습니다. 테스트도 실제 사용자 승인이 필요하고 실제로 과금됩니다. 본인 또는 동의한 사용자의 정보로 소액 검증하세요.
승인 대행은 지원하지 않으므로 자동 테스트로는 끝까지 검증할 수 없습니다.
본문 형식
form-data(multipart/form-data)로 보내세요. 입력은 name·birthDate·phone 처럼 최상위 이름 그대로 보냅니다.
기존 레거시 API와 같은 규격입니다. 인증 요청과 결과 조회 모두 파라미터가 적어 form-data 하나로 충분합니다.
요청 ID
transactionId 는 인증요청 응답에서 받아 보관하고, 결과 조회·재조회에 그대로 쓰세요. 서버가 반환하는 값 외에 직접 만들지 마세요.
이 값이 없으면 결과를 다시 꺼낼 수 없고 인증요청부터 다시 해야 합니다.
요금 확인
인증요청과 결과조회 모두 요청을 보내기 전에 예상 포인트를 계산할 수 있습니다. 계산식과 상품별 예시는 요금과 포인트를 참고하세요.
포인트가 부족하면 HTTP 402 로 거절됩니다(api.cost=0). 이때는 과금되지 않습니다.
시간대
expiresAt · checkedAt · resultExpiresAt 을 포함한 응답의 모든 시각은 한국시간(UTC+09:00) 입니다. 2026-09-20T05:24:07+09:00 처럼 오프셋이 붙어 오므로 그대로 표시하면 됩니다.
UTC 로 저장해야 한다면 오프셋(+09:00)만 빼세요. 시각을 더하거나 빼서 맞추지 마세요.

요금과 포인트

조회는 인증요청 20P 와 결과 단가 두 번 과금됩니다. 포인트가 부족하면 HTTP 402 로 거절되고 그 호출은 과금되지 않습니다.

구분
계산
설명
인증요청
20P 고정
인증요청이 사용자에게 발송된 시점에 발생합니다. 사용자가 승인을 거부하거나 5분 안에 승인하지 않아 AUTH_EXPIRED 가 되어도 환불되지 않습니다.
결과 단가
60P × 데이터셋 수 × 기간 배수
결과가 처음 제공된 응답에서만 발생합니다. 재조회·폴링은 무과금입니다.
기간 배수
기본 1년, 추가 1년마다 +50%
1년 = 1배, 2년 = 1.5배, 3년 = 2배, 5년 = 3배입니다. 월 단위 상품은 12개월을 1년으로 올림 환산합니다(6개월 → 1년, 13개월 → 2년). 기간 배수 옵션이 없는 상품은 조회 기간과 무관하게 1배입니다.
묶음 할인
결과 단가 30% 할인
여러 항목을 한 번 인증으로 한 응답에 받는 묶음 상품은 개별 구매 합계에서 30% 깎습니다.
무과금 구간
0P
인증 대기·조회 중 폴링, 결과 재조회(24시간), 오류 응답(402·408 포함), 인증 거부·실패.
예상 금액 계산 예시
상황
계산
합계
개인소득 1년 조회 (기본, 데이터셋 1개)
20P + (60P × 1 × 1배)
80P
개인소득 3년 조회 (데이터셋 1개)
20P + (60P × 1 × 2배)
140P
지방세 납부내역 24개월 (월 단위, 데이터셋 4개)
20P + (60P × 4 × 1.5배)
380P
데이터셋 4개 상품을 5년 범위로 조회
20P + (60P × 4 × 3배)
740P
정확한 값은 상품 페이지의 요금 표에 있습니다. 데이터셋 수와 기간 옵션이 상품마다 다르므로, 화면에서 범위를 고르게 했다면 요청 전에 예상 포인트를 함께 표시해 주세요. 응답의 api.cost 는 이번 호출에서 실제로 발생한 포인트, data.charged 는 이번 응답에서 과금이 일어났는지 여부입니다. 두 값을 함께 기록해 두면 고객 문의에 대응하기 쉽습니다. 포인트는 마이페이지에서 잔액을 확인하고 충전합니다. 잔액 부족으로 실패한 요청은 충전 후 기존 transactionId의 상태와 과금 내역을 확인한 뒤 다시 진행하면 됩니다(transactionId 는 새로 발급됩니다).

호출 제한과 재시도

결과가 준비되지 않은 대기 조회에는 간격을 두세요. 실제 비용은 각 응답의 api.cost로 확인합니다. 결과를 받은 뒤에는 폴링을 멈추는 것이 가장 중요합니다.

항목
권장
비고
폴링 간격
5초 → 10초 → 20초 → 30초, 이후 30초 유지
간격 제한은 없습니다. 위 값은 권장 사항입니다.
폴링 최대 시간
클라이언트 최대 대기시간 지정
인증 승인 유효시간은 expiresAt(요청 후 5분)입니다. 수집·결과 조회에는 별도의 클라이언트 최대 대기시간을 정하세요. expiresAt 이 지나면 AUTH_EXPIRED 로 끝나므로 폴링을 멈추고 재시작 여부를 물어보세요.
결과 수신 후
즉시 폴링 중단
resultAvailable=true 를 받은 순간 멈추세요. 같은 결과의 재조회 여부와 과금은 charged 및 api.cost를 확인하세요.
동시 처리
동일 APICK 계정·같은 상품은 기존 요청 확인
동일 계정·상품의 요청은 기존 transactionId가 반환될 수 있습니다. 다른 대상자의 인증 요청을 동시에 보내지 말고 기존 요청 상태를 먼저 확인하세요.
분당 호출 제한
없음
별도의 레이트 리밋이나 IP 제한을 두지 않습니다. 다만 과도한 호출은 서버 전체에 영향을 주므로 위 간격을 지켜주세요.
HTTP 424는 현재 요청 처리 중이거나 처리 잠금을 획득하지 못한 경우입니다. 인증 요청을 자동 재전송하지 마세요. 같은 transactionId 로 잠시 후 다시 조회하면 정상 흐름으로 이어집니다. HTTP 408 은 서버가 제한 시간 안에 끝내지 못한 경우입니다. 본문 오류와 기존 transactionId를 확인한 후 재조회 여부를 판단하세요. 인증 요청을 자동으로 다시 보내지 마세요. 결과 조회가 408 이면 transactionId 는 그대로 쓸 수 있습니다.

자주 묻는 질문

질문
답변
한 사용자가 여러 상품을 동시에 조회할 수 있나요?
가능합니다. 상품마다 별도의 transactionId 가 발급되며 각각 독립적으로 진행됩니다. 다만 상품별로 인증요청을 각각 해야 하고, 인증요청 단가(20P)도 상품마다 따로 발생합니다. 여러 상품을 한 번의 승인으로 처리하는 묶음 조회는 제공하지 않습니다.
같은 사람을 다시 조회하면 사용자가 매번 승인해야 하나요?
인증요청은 매번 필요합니다. 다만 동일 APICK 계정·같은 상품에 진행 중 요청 또는 최근 30초 내 요청이 있으면 인증을 재발송하지 않고 기존 transactionId 를 그대로 반환하며 과금되지 않습니다. 승인 후에는 기존 transactionId로 결과를 조회합니다. 재조회 시 과금은 charged와 api.cost로 확인하고 resultExpiresAt 이후에는 자동 조회를 중단하세요.
결과를 얼마나 보관할 수 있나요?
정상 완료 결과의 기본 보관기간은 수집 시각 기준 24시간입니다. 실제 응답의 resultExpiresAt을 확인하고, 부분 성공을 포함해 받은 자료를 즉시 보관하세요. 영구 보관이 필요하면 고객 서비스가 직접 결과를 저장하고, 이용자의 개인정보 처리방침에 따라 파기해야 합니다.
웹훅·콜백으로 결과를 받을 수 있나요?
지원하지 않습니다. 결과조회 API 를 폴링해 resultAvailable=true 를 확인하는 방식만 제공합니다.
인증키를 재발급하면 언제 무효가 되나요?
재발급 즉시 기존 키가 바로 무효가 됩니다(유예 기간 없음). 운영 중인 서버가 있으면 재발급 직후 키를 교체하고 재배포하세요. 키를 여러 곳에서 중복 사용하지 않는 편이 안전합니다.
조회 범위를 최대로 늘리면 응답이 매우 커지나요?
범위를 늘려도 응답은 기간별 합계·구간 목록으로 집계되어 항목당 행 수가 급증하지는 않습니다. 다만 상품에 따라 행이 수백 건까지 늘 수 있으므로, 화면 표시는 페이지 단위로 나누는 것을 권장합니다.
샌드박스나 테스트 키가 있나요?
없습니다. 모든 호출이 실제 인증과 실제 과금을 발생시킵니다. 개발 단계에서는 본인 또는 동의한 사용자의 정보로 가장 짧은 조회 범위를 선택해 검증하세요.
포인트 잔액은 어디서 확인하나요?
마이페이지에서 잔액 확인과 충전을 합니다. 잔액 부족은 HTTP 402 로 돌아오며 과금되지 않으므로, 충전 후 같은 요청을 다시 보내면 됩니다.

결과는 위택스 이(가) 보유한 자료를 조회한 값입니다.

2단계 · 결과조회 엔드포인트

Method
URL
POST
https://apick.app/rest/get_local_tax_payment
이 API 는 polling 용도입니다. 호출 자체는 언제든 무료이며, 실제 결과가 최초로 반환되는 1회에만 과금됩니다. 같은 transactionId 로 다시 조회하면 charged=false 로 추가 과금이 없습니다. 인증 대기(AUTH_WAITING)·조회 중(COLLECTING)·실패(FAILED)·만료(AUTH_EXPIRED) 응답은 과금되지 않습니다. 결과를 받을 때까지 안심하고 반복 조회하세요. 결과가 준비된 뒤에는 조회 시각 기준 24시간 동안 재조회할 수 있습니다. 이 기간의 재조회는 무과금입니다. 응답에는 실제 정보를 확인한 시각이 checkedAt 으로 포함됩니다. 저장해 둔 값을 돌려주는 것이 아니라 그 시점에 확인한 값입니다. 폴링은 resultAvailable=true 를 받는 순간 멈추세요. 최대 시간은 expiresAt(인증 대기)까지이고, 그 뒤로는 결과가 나올 때까지입니다. 자세한 값은 호출 제한과 재시도를 참고하세요. 조회 항목이 여러 개인 상품은 일부만 성공하면 PARTIAL_SUCCESS 로 반환하며, 이때도 실제 조회된 데이터가 있으면 최초 1회 과금됩니다. 어느 항목이 성공·실패했는지는 sources 에 표시됩니다.
결과 단가는 60P × 데이터셋 수(4) × 기간 배수입니다 (기간 months, 12개월 = 1년 올림, 기본 12개월). 기간 배수는 상품의 기간 입력 조건에 따라 적용됩니다.

연동 시 확인할 내용

예제는 경로별로 최소 요청과 오류 처리 포함 모드를 제공합니다. 실제 사용 환경의 시간 제한·취소·업무 성공 판정을 적용하세요.

추가 예제·서비스별 연동 안내
인증 대기중 (무과금)

{
    "data": {
        "schemaVersion": "1.0",
        "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
        "product": "local_tax_payment",
        "status": "AUTH_WAITING",
        "resultAvailable": false,
        "charged": false,
        "sources": [],
        "message": "인증 대기중입니다.",
        "expiresAt": "2026-09-20T05:24:07+09:00",
        "success": 0
    },
    "api": {
        "success": true,
        "cost": 0,
        "ms": 42,
        "pl_id": -1
    }
}
조회 중 (무과금)

{
    "data": {
        "schemaVersion": "1.0",
        "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
        "product": "local_tax_payment",
        "status": "COLLECTING",
        "resultAvailable": false,
        "charged": false,
        "sources": [],
        "progress": { "total": 1, "completed": 0 },
        "message": "정보를 조회하고 있습니다.",
        "success": 0
    },
    "api": {
        "success": true,
        "cost": 0,
        "ms": 38,
        "pl_id": -1
    }
}
조회 완료 (과금)

{
    "data": {
        "schemaVersion": "1.0",
        "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
        "product": "local_tax_payment",
        "status": "SUCCESS",
        "resultAvailable": true,
        "charged": true,
        "sources": [

            { "source": "위택스", "type": "LOCAL_TAX_PAYMENT", "status": "SUCCESS" }

        ],
        "checkedAt": "2026-09-20T04:47:33+09:00",
        "resultExpiresAt": "2026-09-21T04:47:33+09:00",
        "result": {
            "localTaxPayment": {
                "조회기간": {
                    "시작": "2023-10-01",
                    "끝": "2025-09-30"
                },
                "합계": {
                    "납부건수": 12,
                    "납부금액": 1280000,
                    "납부대상건수": 1,
                    "납부대상금액": 154000,
                    "통합납부건수": 0,
                    "통합납부금액": 0,
                    "환급신청건수": 0,
                    "미수령환급금건수": 0
                },
                "미수령환급금": {
                    "지방세": 0,
                    "국세": 0,
                    "환경개선부담금": 0
                },
                "납부내역": [
                    {
                        "납부일": "2025-03-14",
                        "세목": "재산세",
                        "구분": "지방세",
                        "자치단체": "서울특별시 강남구",
                        "과세대상": "자동차",
                        "납부금액": 1280000,
                        "자동납부": "아니오",
                        "전자납부번호": "2025-0001234"
                    }
                ],
                "납부대상": [
                    {
                        "납부기한": "2025-03-14",
                        "세목": "재산세",
                        "자치단체": "서울특별시 강남구",
                        "과세대상": "자동차",
                        "고지금액": 154000,
                        "납부금액": 0,
                        "귀속연도": "2025",
                        "귀속월": "03",
                        "전자납부번호": "2025-0001234"
                    }
                ],
                "통합납부내역": [
                    {
                        "납부일": "2025-03-14",
                        "세목": "재산세",
                        "구분": "지방세",
                        "납세자": "홍길동",
                        "자치단체": "서울특별시 강남구",
                        "납부금액": 1280000
                    }
                ],
                "환급신청내역": [
                    {
                        "신청일": "2025-03-14",
                        "신청인": "홍길동",
                        "자치단체": "서울특별시 강남구",
                        "환급구분": "01",
                        "전자납부번호": "2025-0001234"
                    }
                ]
            }
        },
        "message": "인증이 완료되었습니다.",
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 240,
        "ms": 318,
        "pl_id": 4903
    }
}
위 값은 응답 구조를 보여주기 위한 예시입니다. 값은 가상이지만 필드 구성과 타입은 실제 응답과 같습니다. 전체 항목은 결과 규격을 참고하세요. expiresAt 은 SUCCESS 응답에 없습니다. 인증 대기 기한(AUTH_WAITING)에만 있고, 결과를 받은 뒤에는 resultExpiresAt 이 그 역할을 대신합니다. 둘 중 어느 것이 오는지로 "지금이 승인 대기인지 결과 보관 기간인지"를 구분할 수 있습니다.

개발가이드 검색

필요한 API와 이용 요금을 함께 확인하세요.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.