국세 신고내역 조회 인증 요청 API

인증요청 5분 · 결과 재조회 24시간은 서로 다른 기한입니다. 5분(AUTH_WAITING 중 expiresAt)은 "사용자가 승인해야 하는 시간"이고, 24시간(resultExpiresAt)은 "받은 결과를 다시 꺼내볼 수 있는 시간"입니다. 5분 안에 승인하지 못하면 그 요청은 AUTH_EXPIRED 로 끝나고 결과 단가는 발생하지 않습니다. 인증요청 단가 20P 는 발송이 성공한 시점에 이미 발생하므로 승인 실패·거부와 무관하게 환불되지 않습니다. 결과 보관 만료는 errorCode=RESULT_EXPIRED로 구분합니다. 새 인증·조회에는 각 단계의 과금 조건이 다시 적용됩니다. 동일 APICK 계정·같은 상품의 진행 중 요청 또는 최근 30초 내 요청이 있으면 인증을 재발송하지 않고 기존 transactionId 를 그대로 반환합니다. 이때는 success=0, charged=false 로 돌아오며 과금되지 않습니다. 중복 판정은 조회 대상자의 이름·전화번호가 아닌 계정·상품 기준입니다. 다른 대상자의 인증을 동시에 요청하지 마세요.

인증 대기중(AUTH_WAITING)과 조회 중(COLLECTING)은 실패가 아닙니다. 개발 중에 이 응답을 오류로 처리해 사용자에게 "실패"라고 보여주는 경우가 많습니다. resultAvailable=false 는 "아직 준비 중"이라는 뜻이고, resultAvailable=true 일 때만 결과를 사용하세요. 같은 transactionId 를 다른 조회 항목의 엔드포인트로 조회하면 실패합니다. 인증요청에 사용한 /rest/req_<항목> 과 같은 항목의 /rest/get_<항목> 을 짝으로 사용하세요.

인증 승인은 사용자가 직접 해야 합니다. 승인 대행·자동 승인·인증 정보 저장은 지원하지 않으며, 사용자에게 승인 화면을 안내하는 흐름을 직접 만들어야 합니다. 승인 전 화면을 이탈한 사용자가 많다면 expiresAt 으로 남은 시간을 표시하고, 만료 후에는 재요청 버튼을 제공하세요. 만료된 transactionId 는 재사용할 수 없습니다.

인증 요청

POST/rest/req_tax_return_history

Bearer 인증
multipart/form-data
JSON 응답

요청 예제

curl --fail-with-body --request POST 'https://apick.app/rest/req_tax_return_history' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'name=홍길동' \
  --form-string 'birthDate=19900101' \
  --form-string 'phone=01011112222' \
  --form-string 'authProvider=kakao' \
  --form-string "business_type=${APICK_BUSINESS_TYPE}" \
  --form-string "certificate_id=${APICK_CERTIFICATE_ID}" \
  --form-string "auth_type=${APICK_AUTH_TYPE}" \
  --form-string "cert_file=${APICK_CERT_FILE}" \
  --form-string "key_file=${APICK_KEY_FILE}" \
  --form-string 'cert_password=HRD-0000-0000' \
  --form-string 'years=3'

curl --fail-with-body --request POST 'https://apick.app/rest/req_tax_return_history' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'name=홍길동' \
  --form-string 'birthDate=19900101' \
  --form-string 'phone=01011112222' \
  --form-string 'authProvider=kakao' \
  --form-string "business_type=${APICK_BUSINESS_TYPE}" \
  --form-string "certificate_id=${APICK_CERTIFICATE_ID}" \
  --form-string "auth_type=${APICK_AUTH_TYPE}" \
  --form-string "cert_file=${APICK_CERT_FILE}" \
  --form-string "key_file=${APICK_KEY_FILE}" \
  --form-string 'cert_password=HRD-0000-0000' \
  --form-string 'years=3'

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

const form = new FormData();
form.append("name", "홍길동");
form.append("birthDate", "19900101");
form.append("phone", "01011112222");
form.append("authProvider", "kakao");
form.append("business_type", process.env.APICK_BUSINESS_TYPE);
form.append("certificate_id", process.env.APICK_CERTIFICATE_ID);
form.append("auth_type", process.env.APICK_AUTH_TYPE);
form.append("cert_file", process.env.APICK_CERT_FILE);
form.append("key_file", process.env.APICK_KEY_FILE);
form.append("cert_password", "HRD-0000-0000");
form.append("years", "3");
const response = await fetch("https://apick.app/rest/req_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);

const form = new FormData();
form.append("name", "홍길동");
form.append("birthDate", "19900101");
form.append("phone", "01011112222");
form.append("authProvider", "kakao");
form.append("business_type", process.env.APICK_BUSINESS_TYPE);
form.append("certificate_id", process.env.APICK_CERTIFICATE_ID);
form.append("auth_type", process.env.APICK_AUTH_TYPE);
form.append("cert_file", process.env.APICK_CERT_FILE);
form.append("key_file", process.env.APICK_KEY_FILE);
form.append("cert_password", "HRD-0000-0000");
form.append("years", "3");
const response = await fetch("https://apick.app/rest/req_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);

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

import os
import requests
parts = [
    ("name", (None, "홍길동")),
    ("birthDate", (None, "19900101")),
    ("phone", (None, "01011112222")),
    ("authProvider", (None, "kakao")),
    ("business_type", (None, os.environ["APICK_BUSINESS_TYPE"])),
    ("certificate_id", (None, os.environ["APICK_CERTIFICATE_ID"])),
    ("auth_type", (None, os.environ["APICK_AUTH_TYPE"])),
    ("cert_file", (None, os.environ["APICK_CERT_FILE"])),
    ("key_file", (None, os.environ["APICK_KEY_FILE"])),
    ("cert_password", (None, "HRD-0000-0000")),
    ("years", (None, "3")),
]
response = requests.request("POST", "https://apick.app/rest/req_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)

import os
import requests
parts = [
    ("name", (None, "홍길동")),
    ("birthDate", (None, "19900101")),
    ("phone", (None, "01011112222")),
    ("authProvider", (None, "kakao")),
    ("business_type", (None, os.environ["APICK_BUSINESS_TYPE"])),
    ("certificate_id", (None, os.environ["APICK_CERTIFICATE_ID"])),
    ("auth_type", (None, os.environ["APICK_AUTH_TYPE"])),
    ("cert_file", (None, os.environ["APICK_CERT_FILE"])),
    ("key_file", (None, os.environ["APICK_KEY_FILE"])),
    ("cert_password", (None, "HRD-0000-0000")),
    ("years", (None, "3")),
]
response = requests.request("POST", "https://apick.app/rest/req_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)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'name' => '홍길동',
    'birthDate' => '19900101',
    'phone' => '01011112222',
    'authProvider' => 'kakao',
    'business_type' => getenv('APICK_BUSINESS_TYPE'),
    'certificate_id' => getenv('APICK_CERTIFICATE_ID'),
    'auth_type' => getenv('APICK_AUTH_TYPE'),
    'cert_file' => getenv('APICK_CERT_FILE'),
    'key_file' => getenv('APICK_KEY_FILE'),
    'cert_password' => 'HRD-0000-0000',
    'years' => '3',
];
$curl = curl_init('https://apick.app/rest/req_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);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'name' => '홍길동',
    'birthDate' => '19900101',
    'phone' => '01011112222',
    'authProvider' => 'kakao',
    'business_type' => getenv('APICK_BUSINESS_TYPE'),
    'certificate_id' => getenv('APICK_CERTIFICATE_ID'),
    'auth_type' => getenv('APICK_AUTH_TYPE'),
    'cert_file' => getenv('APICK_CERT_FILE'),
    'key_file' => getenv('APICK_KEY_FILE'),
    'cert_password' => 'HRD-0000-0000',
    'years' => '3',
];
$curl = curl_init('https://apick.app/rest/req_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);

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

응답 예시200

{
  "data": {
    "schemaVersion": "1.0",
    "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a",
    "product": "tax_return_history",
    "status": "AUTH_REQUESTED",
    "resultAvailable": false,
    "charged": true,
    "sources": [],
    "message": "인증 대기중입니다.",
    "approvals": 1,
    "expiresAt": "2026-09-20T05:24:07+09:00",
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 20,
    "ms": 1284,
    "pl_id": 4902
  }
}

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

요청 파라미터 12개 · 필수 4

파라미터

설명

namestring필수

조회 대상의 이름입니다. 개인 조회에서는 성명, 기업 조회에서는 법인명·상호를 뜻합니다. 같은 요청의 생년월일·전화번호 또는 사업자등록번호와 함께 확인하세요.

최대 길이: 40자
예시: 홍길동

birthDatestring필수

대상자의 생년월일 8자리입니다. 예: 19900101. 하이픈 없이 숫자만 보내며, 인증 대상자와 정확히 일치해야 합니다.

형식: ^[0-9]{8}$
예시: 19900101

phonestring필수

본인 명의 휴대전화 번호입니다. 하이픈 없이 숫자만 입력하며, 인증 문자를 받을 수 있는 번호여야 합니다.

형식: ^01[0-9]{8,9}$
예시: 01011112222

authProviderstring필수

사용할 간편인증 수단의 식별자입니다. 예: kakao, naver, toss, pass. 지원 값은 이 문서의 간편인증 목록을 확인하세요. pass(통신사 PASS)를 고르면 telco(통신사 코드)를 반드시 함께 보냅니다. 가능한 값은 13가지입니다. kakao = kakao 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. naver = naver 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. toss = toss 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. pass = pass 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. samsung = samsung 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. kb = kb 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. shinhan = shinhan 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. hana = hana 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. woori = woori 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. ibk = ibk 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. nh = nh 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. kakaobank = kakaobank 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. banksalad = banksalad 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요.

허용값: kakao naver toss pass samsung kb shinhan hana woori ibk nh kakaobank banksalad
예시: kakao

telcostring조건부

통신사 코드. authProvider=pass(통신사 PASS)일 때 필수이며, 빠지거나 허용값이 아니면 인증 요청 없이 400으로 거절합니다. S SKT·K KT·L LGU+·SA SKT알뜰폰·KA KT알뜰폰·LA LGU+알뜰폰 가능한 값은 6가지입니다. S = S 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. K = K 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. L = L 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. SA = SA 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. KA = KA 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. LA = LA 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요.

허용값: S K L SA KA LA

business_typestring선택

사업자 구분. corporate(법인)는 공동인증서가 필수, personal(개인)은 간편인증·공동인증서 모두 가능. 없으면 personal

certificate_idstring선택

등록한 공동인증서 ID. 없으면 기본 인증서를 쓴다 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

auth_typestring선택

인증 방식. certificate(공동인증서) 또는 simple(간편인증). 없으면 business_type·certificate_id 로 정한다

cert_filestring선택

공동인증서 인증서 파일(signCert.der)을 base64 로 보낸다. key_file·cert_password 와 함께 보내면 인증서를 등록하지 않고 바로 인증하며, certificate_id 보다 우선한다

key_filestring선택

공동인증서 개인키 파일(signPri.key)을 base64 로 보낸다. cert_file 과 함께 보낸다

cert_passwordstring선택

공동인증서 비밀번호. 이번 인증에만 쓰고 보관하지 않는다 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

예시: HRD-0000-0000

yearsinteger선택

신고내역 조회 연수 (1~10, 생략 시 1) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

범위: 1 ~ 10
예시: 3

응답 필드 17개

응답 필드

설명

dataobject

요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

data.schemaVersionstring

응답 스키마의 버전입니다. 현재 "1.0"으로 고정되어 있으며, 필드 구조가 바뀌면 값이 올라갑니다. 클라이언트는 이 값을 저장해 두고 파싱 로직을 분기할 수 있습니다.

data.transactionIdstring

간편인증 요청에서 발급된 거래 ID입니다. 인증요청 응답의 transactionId와 같으며, 같은 거래의 결과를 조회하거나 문의할 때 사용합니다. 인증이 만료되면 새 거래를 만들어야 합니다.

data.productstring

조회한 상품 코드입니다. 인증요청 때 보낸 product와 같은 값이며, 응답의 result 구조를 해석할 때 기준이 됩니다.

data.statusstring

현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 9가지입니다. AUTH_REQUESTED = 인증 요청만 접수되어 사용자 승인을 기다리는 상태, AUTH_WAITING = 승인 전 대기, AUTH_COMPLETED = 승인은 끝났고 결과 준비 전, COLLECTING = 결과 준비 중, SUCCESS = 정상 완료되어 결과 사용 가능, PARTIAL_SUCCESS = 일부 자료만 준비되어 sources의 항목별 status 확인 필요, FAILED = 서버 처리 실패, AUTH_REJECTED = 사용자가 인증 거부, AUTH_EXPIRED = 승인 유효시간(300초) 만료입니다.

data.resultAvailableboolean

결과 데이터 포함 여부. 인증 요청 응답은 항상 false 입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 결과를 지금 사용할 수 있는 경우, false = 아직 처리 중이거나 실패·만료되어 결과가 없는 경우입니다. false면 data.status를 확인하세요.

data.chargedboolean

이번 호출의 과금 발생 여부. 실제 발송에 성공하면 true 입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이번 조회에서 포인트가 실제로 차감된 경우(유료 결과를 처음 받은 때), false = 이미 차감된 결과를 다시 조회했거나 무료 응답인 경우입니다. api.cost가 0이면 false입니다.

data.sourcesarray

자료 항목별 처리 결과 목록입니다. 항목별 성공·실패를 구분하므로 일부만 성공한 응답을 판단할 때 사용합니다.

data.messagestring

상태 메시지 (고정값: "인증 대기중입니다."). 안내 문구입니다. 오류 원인과 다음 행동을 설명합니다.

data.approvalsinteger

사용자가 휴대폰에서 승인해야 하는 횟수. 같은 인증으로 처리되는 조회는 묶음이어도 1회입니다.

data.expiresAtstring

이 응답이나 인증 요청의 유효 만료 시각입니다. 한국시간(UTC+09:00) ISO 8601 형식이며, 이 시각을 넘기면 같은 요청을 다시 접수해야 합니다.

data.successinteger

업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

apiobject

API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

api.successboolean

API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

api.costinteger

이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

api.msinteger

서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

api.pl_idinteger

포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

하위 필드 0개 더 보기

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

{ "data": { "schemaVersion": "1.0", "transactionId": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a", "product": "tax_return_history", "status": "AUTH_REQUESTED", "resultAvailable": false, "charged": true, "sources": [], "message": "인증 대기중입니다.", "approvals": 1, "expiresAt": "2026-09-20T05:24:07+09:00", "success": 1 }, "api": { "success": true, "cost": 20, "ms": 1284, "pl_id": 4902 } }

알아둘 점

한눈에 보는 진행 절차

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

개발 체크리스트

연동 전에 확인하세요

요금과 포인트

예상 금액 계산 예시

호출 제한과 재시도

자주 묻는 질문

요청과 응답

인증 요청

요청 파라미터 12개 · 필수 4

응답 필드 17개

입력 조건·전송 규칙

요청 본문 형식

1단계 · 조회 인증 요청

간편인증 방식(authProvider)

응답 처리

Body

오류 코드

업무 실패 응답 data.error

서비스 코드·조건

공통 오류 응답

상태와 성공 판정

인증·포인트 오류 result.error 문구

폼 입력 오류 error.code

요금·이용 조건

연동 팁

요청 예시

응답 예시

개발가이드 검색

AI•LLM

전체상품

API 체험하기

요금정책

고객지원

개발가이드