주택연금 보증잔액 조회 인증 요청

기능·제공 범위

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

빠른 시작

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

요청과 응답

인증 요청 예제직접 실행하지 않습니다POST /rest/req_housing_pension_balance

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

curl --fail-with-body --request POST 'https://apick.app/rest/req_housing_pension_balance' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'name=홍길동' \
  --form-string 'birthDate=19900101' \
  --form-string 'phone=01011112222' \
  --form-string 'authProvider=kakao'

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

const form = new FormData();
form.append("name", "홍길동");
form.append("birthDate", "19900101");
form.append("phone", "01011112222");
form.append("authProvider", "kakao");
const response = await fetch("https://apick.app/rest/req_housing_pension_balance", {
  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 = [
    ("name", (None, "홍길동")),
    ("birthDate", (None, "19900101")),
    ("phone", (None, "01011112222")),
    ("authProvider", (None, "kakao")),
]
response = requests.request("POST", "https://apick.app/rest/req_housing_pension_balance",
    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 = [
    'name' => '홍길동',
    'birthDate' => '19900101',
    'phone' => '01011112222',
    'authProvider' => 'kakao',
];
$curl = curl_init('https://apick.app/rest/req_housing_pension_balance');
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/req_housing_pension_balance' \
  --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'

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

const form = new FormData();
form.append("name", "홍길동");
form.append("birthDate", "19900101");
form.append("phone", "01011112222");
form.append("authProvider", "kakao");
const response = await fetch("https://apick.app/rest/req_housing_pension_balance", {
  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 = [
    ("name", (None, "홍길동")),
    ("birthDate", (None, "19900101")),
    ("phone", (None, "01011112222")),
    ("authProvider", (None, "kakao")),
]
response = requests.request("POST", "https://apick.app/rest/req_housing_pension_balance",
    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 = [
    'name' => '홍길동',
    'birthDate' => '19900101',
    'phone' => '01011112222',
    'authProvider' => 'kakao',
];
$curl = curl_init('https://apick.app/rest/req_housing_pension_balance');
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);

인증 요청

POST/rest/req_housing_pension_balance

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

입력 항목

폼 항목·타입

필수

설명·예제

namestring

필수

이름예: 홍길동

birthDatestring

필수

생년월일 8자리(YYYYMMDD)예: 19900101

phonestring

필수

휴대전화 번호 (본인 명의, 숫자만)예: 01011112222

authProviderstring

필수

간편인증 방식 (아래 지원 목록 참고)예: kakao

응답과 성공 판정

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

응답 상태

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

필드·타입

의미·조건

dataobject

인증 요청 결과

data.schemaVersionstring

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

data.transactionIdstring

결과 조회에 사용하는 트랜잭션 ID

data.productstring

조회 항목 코드. 결과조회에도 같은 값이 오므로 어느 항목의 결과인지 대조할 수 있습니다.

data.statusstring

처리 상태 (AUTH_REQUESTED: 인증 요청 완료)

data.resultAvailableboolean

결과 데이터 포함 여부. 인증 요청 응답은 항상 false 입니다.

data.chargedboolean

이번 호출의 과금 발생 여부. 실제 발송에 성공하면 true 입니다.

data.sourcesarray

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

data.messagestring

상태 메시지 (고정값: "인증 대기중입니다.")

data.expiresAtstring

인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다.

data.successinteger

과금 여부0: 실패 또는 재사용(무과금)1: 발송 성공(과금)

data.approvalsinteger

필요한 간편인증 승인 횟수. 조회 항목 하나당 1회입니다.

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 로 통일합니다.

1단계 · 조회 인증 요청

Method

URL

POST

https://apick.app/rest/req_housing_pension_balance

Header

이름

필수

설명

Authorization

O

Bearer 인증키

모든 입력은 하위 객체 없이 최상위 이름 그대로 보냅니다. user·requestData·options 같은 묶음은 쓰지 않습니다. 형식별 예시는 요청 본문 형식을 참고하세요. 조회 항목마다 필요한 추가 입력 이 다릅니다. 값이 비어 있으면 인증을 보내지 않고 무과금으로 거절하며, 이때는 결과 단가도 발생하지 않습니다.

간편인증 방식(authProvider)

값

인증 방식

kakao

카카오톡

naver

네이버

toss

토스

pass

통신사 PASS

samsung

삼성패스

kb

KB국민은행

shinhan

신한은행

hana

하나은행

woori

우리은행

ibk

IBK기업은행

nh

NH농협은행

kakaobank

카카오뱅크

banksalad

뱅크샐러드

응답 상세

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

Body

이름

타입

설명

data

Object

인증 요청 결과

schemaVersion

String

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

transactionId

String

결과 조회에 사용하는 트랜잭션 ID

product

String

조회 항목 코드. 결과조회에도 같은 값이 오므로 어느 항목의 결과인지 대조할 수 있습니다.

status

String

처리 상태 (AUTH_REQUESTED: 인증 요청 완료)

message

String

상태 메시지 (고정값: "인증 대기중입니다.")

approvals

Integer

필요한 간편인증 승인 횟수. 조회 항목 하나당 1회입니다.

resultAvailable

Boolean

결과 데이터 포함 여부. 인증 요청 응답은 항상 false 입니다.

charged

Boolean

이번 호출의 과금 발생 여부. 실제 발송에 성공하면 true 입니다.

expiresAt

String

인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다.

success

Integer

과금 여부
0: 실패 또는 재사용(무과금)
1: 발송 성공(과금)

api

Object

API 호출 공통 데이터

success

Boolean

API 서버 정상 응답 여부

cost

Integer

API 호출 요금

ms

Integer

API 응답 시간

pl_id

Integer

API 결제 로그 ID

경로별 응답 예시와 필드 명세는 위 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 로 돌아오며 과금되지 않으므로, 충전 후 같은 요청을 다시 보내면 됩니다.

조회 자료 제공 기관은 한국주택금융공사 입니다. 본인 인증은 한 번만 하면 되고, 담당 기관은 엔드포인트로 자동 선택됩니다.

인증요청과 결과조회는 완전히 분리되어 있습니다. 이 호출은 인증요청만 보내고 transactionId 를 즉시 반환합니다. 결과는 사용자가 승인한 뒤 /rest/get_housing_pension_balance 에 transactionId 를 넣어 확인합니다. 조회 항목마다 담당 기관이 다르지만, 인증기관은 엔드포인트로 자동 선택되므로 기관을 지정하는 파라미터는 없습니다. 이 응답의 expiresAt 까지만 승인할 수 있습니다. 남은 시간을 화면에 표시하고, 만료되면 사용자가 다시 요청할 수 있게 해 주세요.

연동 시 확인할 내용

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

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

요청 예시

form-data 전체 예제 보기

응답 예시


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