국세 신고내역 결과조회

명세 내보내기

OpenAPI 3.0.3 Postman 컬렉션 Markdown

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

POST/rest/get_tax_return_history

요청 예제로 이동 ↓

기능·제공 범위

인증: Bearer 키
요청: form-data
응답: JSON
요금·이용 조건: 기본 단가 60P · 건당

빠른 시작

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

요청과 응답

API 요청 예제직접 실행하지 않습니다POST /rest/get_tax_return_history

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

curl --fail-with-body --request POST 'https://apick.app/rest/get_tax_return_history' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'transactionId=9f2c4a7b1d8e35c60a4f7b2d1e9c803a'

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
form.append("transactionId", "9f2c4a7b1d8e35c60a4f7b2d1e9c803a");
const response = await fetch("https://apick.app/rest/get_tax_return_history", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
parts = [
    ("transactionId", (None, "9f2c4a7b1d8e35c60a4f7b2d1e9c803a")),
]
response = requests.request("POST", "https://apick.app/rest/get_tax_return_history",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'transactionId' => '9f2c4a7b1d8e35c60a4f7b2d1e9c803a',
];
$curl = curl_init('https://apick.app/rest/get_tax_return_history');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

curl --fail-with-body --request POST 'https://apick.app/rest/get_tax_return_history' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'transactionId=9f2c4a7b1d8e35c60a4f7b2d1e9c803a'

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

const form = new FormData();
form.append("transactionId", "9f2c4a7b1d8e35c60a4f7b2d1e9c803a");
const response = await fetch("https://apick.app/rest/get_tax_return_history", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

import os
import requests
parts = [
    ("transactionId", (None, "9f2c4a7b1d8e35c60a4f7b2d1e9c803a")),
]
response = requests.request("POST", "https://apick.app/rest/get_tax_return_history",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'transactionId' => '9f2c4a7b1d8e35c60a4f7b2d1e9c803a',
];
$curl = curl_init('https://apick.app/rest/get_tax_return_history');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

API 요청

POST/rest/get_tax_return_history

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

입력 항목

폼 항목·타입

필수

설명·예제

transactionIdstring

필수

동일 상품의 req_tax_return_history 응답에서 받은 transactionId (소문자 16진수 32자리)형식: ^[a-f0-9]{32}$예: 9f2c4a7b1d8e35c60a4f7b2d1e9c803a

응답과 성공 판정

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

응답 상태

{
  "data": {
    "schemaVersion": "1.0",
    "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
    "product": "tax_return_history",
    "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
  }
}

필드·타입

의미·조건

dataobject

상태·결과

data.schemaVersionstring

결과 스키마 버전 (고정값: "1.0")

data.transactionIdstring

트랜잭션 ID

data.productstring

조회 항목 코드. 인증요청 응답과 같은 값입니다.

data.statusstring

처리 상태 (위 표 참고)

data.resultAvailableboolean

실제 결과 포함 여부. 과금 여부도 이 값으로 결정됩니다.

data.chargedboolean

이번 호출의 과금 발생 여부. 최초 결과 반환에서만 true 입니다.

data.sourcesarray

항상 포함됩니다. 값이 없으면 빈 배열 [] 입니다. 항목이 여러 개인 상품에서 어느 것이 성공·실패했는지 알려줍니다. 각 항목은 source(제공 기관명), type(데이터 종류), status(SUCCESS/FAILED). 수집이 끝나기 전에는 아직 확정되지 않은 기관이 FAILED 로 보일 수 있습니다.

data.sources[].sourcestring

아래 하위 항목을 확인하세요.

data.sources[].typestring

아래 하위 항목을 확인하세요.

data.sources[].statusstring

아래 하위 항목을 확인하세요.

data.messagestring

상태 메시지

data.expiresAtstring

아래 하위 항목을 확인하세요.

data.successinteger

과금 여부0: 결과 없음 또는 재조회(무과금)1: 최초 결과 반환(과금)

data.progressobject

진행률(COLLECTING 일 때). total(전체 항목), completed(완료 항목)

data.progress.totalinteger

아래 하위 항목을 확인하세요.

data.progress.completedinteger

아래 하위 항목을 확인하세요.

data.checkedAtstring

실제 정보를 확인한 시각. 한국시간(UTC+09:00) ISO 8601 이며 재조회 유효기간의 기준입니다.

data.resultExpiresAtstring

결과 재조회 만료 시각. 한국시간(UTC+09:00) ISO 8601 입니다.

data.resultobject

조회된 결과 묶음. 실제 데이터가 있을 때만 포함됩니다.

data.result.taxReturnHistoryobject

이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요.

data.result.taxReturnHistory.조회기간object

신고내역 조회 구간.

data.result.taxReturnHistory.조회기간.시작string

조회 구간 시작(8자리)

data.result.taxReturnHistory.조회기간.끝string

조회 구간 끝(8자리)

data.result.taxReturnHistory.합계object

조회 구간 전체 합계.

data.result.taxReturnHistory.합계.건수integer

신고서 건수

data.result.taxReturnHistory.합계.납부금액integer

납부금액 합계(원)

data.result.taxReturnHistory.합계.고지금액integer

고지금액 합계(원)

data.result.taxReturnHistory.신고내역object

제출된 신고서 목록. 신고가 없으면 빈 배열이다.

data.result.taxReturnHistory.신고내역.신고일string

신고서 제출일 원문. 예: YYYYMMDD. 구분 기호는 자료에 따라 다르다.

data.result.taxReturnHistory.신고내역.과세기간string

신고서에 적힌 과세기간

data.result.taxReturnHistory.신고내역.신고서string

신고서 종류

data.result.taxReturnHistory.신고내역.신고구분string

정기·수정 등 신고 구분

data.result.taxReturnHistory.신고내역.신고상세string

신고 상세 구분

data.result.taxReturnHistory.신고내역.세목string

세목

data.result.taxReturnHistory.신고내역.작성방법string

작성 방법

data.result.taxReturnHistory.신고내역.납부년월string

납부 연월 원문. 예: YYYYMM. 납부 내역이 없으면 빈 값이다.

data.result.taxReturnHistory.신고내역.납부금액integer

납부금액(원)

data.result.taxReturnHistory.신고내역.고지금액integer

고지금액(원)

data.errorCodestring

오류 구분. RESULT_EXPIRED(재조회 기간 만료) / AUTH_EXPIRED / AUTH_REJECTED / COLLECT_FAILED

apiobject

API 호출 공통 데이터

api.successboolean

API 서버 정상 응답 여부

api.costinteger

API 호출 요금

api.msinteger

API 응답 시간

api.pl_idinteger

API 결제 로그 ID

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

추가 입력 조건·전송 규칙

요청 본문 형식

인증요청·결과조회 모두 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

Bearer 인증키

본문은 transactionId 하나입니다. 결과조회 엔드포인트는 인증요청과 짝이 되는 /rest/get_tax_return_history 이며, 다른 항목의 엔드포인트로 조회하면 실패합니다. 조회 시각 기준 24시간이 지나면 RESULT_EXPIRED 가 반환됩니다. 이때는 인증요청부터 다시 시작해야 하며, 인증요청 단가(20P)가 다시 발생합니다.

요청 예시

form-data 전체 예제 보기

응답 상세

서비스 고유 응답·필드 상세 설명

처리 상태(status)

값

의미

과금

AUTH_REQUESTED

조회 인증 요청 (/rest/req_tax_return_history 응답)

인증요청 시 과금

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

조회된 결과 묶음. 실제 데이터가 있을 때만 포함됩니다.

taxReturnHistory

Object

이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요.

message

String

상태 메시지

success

Integer

과금 여부
0: 결과 없음 또는 재조회(무과금)
1: 최초 결과 반환(과금)

api

Object

API 호출 공통 데이터

success

Boolean

API 서버 정상 응답 여부

cost

Integer

API 호출 요금

Integer

API 응답 시간

pl_id

Integer

API 결제 로그 ID

결과 규격

result.taxReturnHistory

경로

타입

값 존재

설명

예시

조회기간

Object

신고내역 조회 구간.

시작

String(YYYYMMDD)

조회 구간 시작(8자리)

20210101

끝

String(YYYYMMDD)

조회 구간 끝(8자리)

20251231

합계

Object

조회 구간 전체 합계.

건수

Integer

신고서 건수

납부금액

Integer

납부금액 합계(원)

1280000

고지금액

Integer

고지금액 합계(원)

신고내역

Array<Object>

제출된 신고서 목록. 신고가 없으면 빈 배열이다.

신고일

String

신고서 제출일 원문. 예: YYYYMMDD. 구분 기호는 자료에 따라 다르다.

20250531

과세기간

String

신고서에 적힌 과세기간

2024-01-01 ~ 2024-12-31

신고서

String

신고서 종류

종합소득세

신고구분

String

정기·수정 등 신고 구분

정기신고

신고상세

String

신고 상세 구분

일반

세목

String

세목

소득세

작성방법

String

작성 방법

전자신고

납부년월

String

납부 연월 원문. 예: YYYYMM. 납부 내역이 없으면 빈 값이다.

202505

납부금액

Integer

납부금액(원)

1280000

고지금액

Integer

고지금액(원)

타입 읽는 법 — 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_<항목> 을 짝으로 사용하세요.

개발 체크리스트

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

단계

할 일

인증키를 발급받아 서버 환경변수에 넣습니다. 브라우저에서 직접 호출하면 키가 노출되므로 반드시 자체 백엔드에서 호출하세요.

사용자에게 이름·생년월일·휴대전화번호를 입력받고, 간편인증 방식(authProvider)을 고르게 합니다. 서버로는 숫자만 남긴 번호를 보내세요(하이픈 제거).

/rest/req_<항목> 을 호출하고 응답의 transactionId 를 보관합니다. 이 시점에 20P 가 과금됩니다.

사용자에게 간편인증 요청이 발송됐음을 안내하고, 인증 완료를 기다립니다. 남은 시간은 expiresAt 으로 안내하세요.

/rest/get_<항목> 로 상태를 확인합니다. resultAvailable 이 true 가 되면 폴링을 멈추고 결과를 사용하세요.

transactionId 로 결과물을 조회합니다. 정상 완료 결과는 수집 시각 기준 24시간을 기본 보관기간으로 사용합니다. resultExpiresAt과 응답 상태를 확인하고 부분 성공 결과도 즉시 저장하세요.

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% 깎습니다.

무과금 구간

인증 대기·조회 중 폴링, 결과 재조회(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_tax_return_history

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

결과 단가는 60P × 데이터셋 수(1) × 기간 배수입니다 (기간 years, 기본 1년). 기간 배수는 상품의 기간 입력 조건에 따라 적용됩니다.

연동 시 확인할 내용

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

추가 예제·서비스별 연동 안내

인증 대기중 (무과금)


{
    "data": {
        "schemaVersion": "1.0",
        "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
        "product": "tax_return_history",
        "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": "tax_return_history",
        "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": "tax_return_history",
        "status": "SUCCESS",
        "resultAvailable": true,
        "charged": true,
        "sources": [

            { "source": "국세청", "type": "TAX_RETURN_HISTORY", "status": "SUCCESS" }

        ],
        "checkedAt": "2026-09-20T04:47:33+09:00",
        "resultExpiresAt": "2026-09-21T04:47:33+09:00",
        "result": {
            "taxReturnHistory": {
                "조회기간": {
                    "시작": "20210101",
                    "끝": "20251231"
                },
                "합계": {
                    "건수": 12,
                    "납부금액": 1280000,
                    "고지금액": 0
                },
                "신고내역": [
                    {
                        "신고일": "20250531",
                        "과세기간": "2024-01-01 ~ 2024-12-31",
                        "신고서": "종합소득세",
                        "신고구분": "정기신고",
                        "신고상세": "일반",
                        "세목": "소득세",
                        "작성방법": "전자신고",
                        "납부년월": "202505",
                        "납부금액": 1280000,
                        "고지금액": 0
                    }
                ]
            }
        },
        "message": "인증이 완료되었습니다.",
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 60,
        "ms": 318,
        "pl_id": 4903
    }
}

위 값은 응답 구조를 보여주기 위한 예시입니다. 값은 가상이지만 필드 구성과 타입은 실제 응답과 같습니다. 전체 항목은 결과 규격을 참고하세요. expiresAt 은 SUCCESS 응답에 없습니다. 인증 대기 기한(AUTH_WAITING)에만 있고, 결과를 받은 뒤에는 resultExpiresAt 이 그 역할을 대신합니다. 둘 중 어느 것이 오는지로 "지금이 승인 대기인지 결과 보관 기간인지"를 구분할 수 있습니다.