사용자가 아직 승인하지 않은 상태입니다. 조회하면 status AUTH_WAITING 과 "인증 대기중입니다." 메시지를 돌려줍니다.
결과조회 API 를 주기적으로 호출하세요. 이 구간은 무과금입니다.
3. 사용자인증완료
사용자가 간편인증을 승인하면 서버가 정보를 조회하기 시작합니다.
별도 호출이 필요 없습니다. 다음 조회에서 status 가 AUTH_COMPLETED → COLLECTING 으로 바뀝니다.
4. 정보조회
요청한 항목의 최종 정보를 조회해 결과를 만듭니다.
계속 조회하세요. 이 구간도 무과금입니다.
5. 정보제공
status SUCCESS 로 표준화된 결과가 result 에 담겨 반환됩니다.
이 최초 응답에서만 charged=true 로 결과 단가가 과금됩니다. 결과는 이 시각부터 24시간 동안 재조회할 수 있습니다.
인증요청 5분 · 결과 재조회 24시간은 서로 다른 기한입니다. 5분(AUTH_WAITING 중 expiresAt)은 "사용자가 승인해야 하는 시간"이고, 24시간(resultExpiresAt)은 "받은 결과를 다시 꺼내볼 수 있는 시간"입니다.
5분 안에 승인하지 못하면 그 요청은 AUTH_EXPIRED 로 끝나고 결과 단가는 발생하지 않습니다. 인증요청 단가 20P 는 발송이 성공한 시점에 이미 발생하므로 승인 실패·거부와 무관하게 환불되지 않습니다. 결과를 받고 24시간이 지나면 RESULT_EXPIRED 가 반환되며, 다시 받으려면 인증요청부터 새로 해야 합니다(인증요청 단가만 재과금).
같은 사용자가 같은 조회 항목을 30초 안에 다시 요청하면 인증을 재발송하지 않고 기존 transactionId 를 그대로 반환합니다. 이때는 success=0, charged=false 로 돌아오며 과금되지 않습니다. 인증요청은 사용자 1명에게 한 번만 발송됩니다.
모든 조회 상품에 공통인 계약
항목
내용
비고
엔드포인트
조회 항목마다 전용 2개입니다. /rest/req_<항목> 으로 인증요청, /rest/get_<항목> 으로 결과조회를 합니다.
조회 항목을 지정하는 product 파라미터가 없습니다. 엔드포인트 자체가 항목입니다.
HTTP Method
POST 만 지원합니다. GET·PUT·DELETE 는 동작하지 않습니다.
요청 본문은 FormData(multipart) 또는 form-urlencoded 로 보내세요.
인증키
Header CL_AUTH_KEY 에 발급받은 키를 넣습니다.
키가 없거나 틀리면 인증 없이 거절되며 과금되지 않습니다.
회신 형식
모든 응답이 data(상태·결과)와 api(호출 공통 정보) 두 덩어리로 고정됩니다.
api.success 는 API 서버 정상 응답 여부이고, 과금 여부는 data.success(0/1)입니다.
입력값
성명·생년월일·휴대전화번호는 인증받는 본인의 정보여야 합니다. 타인 명의로는 승인되지 않습니다.
휴대전화번호는 숫자만 넣으세요(하이픈 없이).
동시 호출
같은 사용자·같은 조회 항목의 동시 요청은 하나로 합쳐 처리됩니다. 두 번째 요청은 첫 요청의 transactionId 를 재사용하며 추가 과금되지 않습니다.
서버가 처리 중일 때는 잠시 후 다시 시도하라는 응답이 올 수 있습니다.
재시도
인증 대기·조회 중 구간은 무과금이므로 부담 없이 반복 호출할 수 있습니다. 결과를 받은 뒤의 재조회도 24시간 동안 무과금입니다.
과금은 인증요청 발송과 결과 최초 제공 두 지점에서만 발생합니다.
개인정보
조회 결과는 요청에 대한 응답으로만 쓰이며, 조회 시각 기준 24시간 뒤에는 재조회가 만료됩니다.
받은 결과는 이용하는 서비스의 개인정보 처리방침에 맞게 직접 보관·파기해야 합니다.
인증 대기중(AUTH_WAITING)과 조회 중(COLLECTING)은 실패가 아닙니다. 개발 중에 이 응답을 오류로 처리해 사용자에게 "실패"라고 보여주는 경우가 많습니다. resultAvailable=false 는 "아직 준비 중"이라는 뜻이고, resultAvailable=true 일 때만 결과를 사용하세요.
같은 transactionId 를 다른 조회 항목의 엔드포인트로 조회하면 실패합니다. 인증요청에 사용한 /rest/req_<항목> 과 같은 항목의 /rest/get_<항목> 을 짝으로 사용하세요.
개발 체크리스트
아래 순서대로 구현하면 조회 상품 하나를 연동할 수 있습니다.
단계
할 일
1
인증키를 발급받아 서버 환경변수에 넣습니다. 브라우저에서 직접 호출하면 키가 노출되므로 반드시 자체 백엔드에서 호출하세요.
2
사용자에게 이름·생년월일·휴대전화번호를 입력받고, 간편인증 방식(authProvider)을 고르게 합니다. 값 검증은 한글 이름·8자리 생년월일·숫자만 번호 순으로 하세요.
3
/rest/req_<항목> 을 호출하고 응답의 transactionId 를 사용자 세션에 저장합니다. 이 시점에 20P 가 과금됩니다.
4
사용자에게 간편인증 승인 화면을 보여주고, 남은 시간은 expiresAt 으로 안내하세요.
5
/rest/get_<항목> 을 5초 → 10초 → 20초 → 30초 간격으로 폴링하고, 이후 30초 간격을 유지합니다. resultAvailable 이 true 가 되면 폴링을 멈춥니다.
6
결과를 화면에 보여주고, transactionId 로 24시간 안에 다시 꺼낼 수 있도록 저장합니다. 24시간이 지나면 인증요청부터 다시 시작해야 합니다.
7
AUTH_EXPIRED · AUTH_REJECTED · RESULT_EXPIRED 는 각각 시간 초과·사용자 거부·재조회 만료이므로, 사용자에게 다시 시도할지 물어보는 흐름으로 처리하세요.
인증 승인은 사용자가 직접 해야 합니다. 승인 대행·자동 승인·인증 정보 저장은 지원하지 않으며, 사용자에게 승인 화면을 안내하는 흐름을 직접 만들어야 합니다.
승인 전 화면을 이탈한 사용자가 많다면 expiresAt 까지 남은 시간을 표시하고, 만료 후에는 재요청 버튼을 제공하세요. 만료된 transactionId 는 재사용할 수 없습니다.
공통 오류 응답
아래 항목은 조회 항목과 무관하게 공통으로 발생합니다. 오류 응답은 과금되지 않습니다.
상황
확인할 값
대응
인증키 누락·오류
api.success=false
Header CL_AUTH_KEY 를 확인하세요. 과금되지 않습니다.
입력값 누락·형식 오류
오류 메시지에 어느 항목이 잘못됐는지 표시됩니다.
이름·생년월일·휴대전화번호·인증방식을 다시 확인하세요.
조회 항목에 필요한 추가 입력 누락
오류 메시지에 필요한 입력 이름이 표시됩니다.
아래 요청 표의 requestData.* 항목을 채우세요.
없는 transactionId · 만료된 요청
요청을 찾을 수 없다는 응답 또는 status AUTH_EXPIRED
인증요청부터 다시 하세요.
처리 중 재요청
앞선 요청을 처리하고 있다는 응답
잠시 후 같은 transactionId 로 다시 조회하세요.
결과 재조회 기한 만료
errorCode=RESULT_EXPIRED
24시간이 지났습니다. 인증요청부터 다시 하세요.
사용자 인증 거부
errorCode=AUTH_REJECTED
사용자에게 다시 시도할지 안내하세요. 과금되지 않습니다.
정보 조회 실패
errorCode=COLLECT_FAILED · status FAILED
잠시 후 인증요청부터 다시 시도하세요. 결과 단가는 과금되지 않습니다.
보유 포인트 부족
HTTP 402 · data.error 에 사유 · api.cost=0
과금되지 않습니다. 포인트를 충전한 뒤 다시 요청하세요.
정상 응답은 HTTP 200 입니다. 상태가 인증 대기중·조회 중 이어도 200 이며, data.success 만 0 입니다. HTTP 코드로 성공을 판단하지 말고 data.status 와 data.resultAvailable 을 보세요.
연동 전에 확인하세요
실제 고객 연동에서 자주 나오는 질문입니다. 이 5가지를 먼저 정하면 시행착오를 줄일 수 있습니다.
확인 항목
내용
이유
인증키 발급·보관
인증키는 마이페이지에서 확인합니다. 별도 발급 요청은 없습니다. 서버 환경변수에 넣고 브라우저·앱 클라이언트에 넣지 마세요. 노출이 의심되면 마이페이지에서 재발급하면 기존 키는 즉시 무효가 됩니다.
인증키는 비밀번호와 같습니다. 앱에 심으면 누구나 추출해 과금을 발생시킬 수 있습니다.
사용자 동의
조회 전에 이용자가 본인 정보 조회에 동의한다는 사실을 서비스 약관·동의 화면에서 받아 두세요. 인증 승인은 그 동의를 확인하는 절차이지 동의를 대신하지 않습니다.
조회 결과를 서비스에 활용하려면 동의 근거가 필요합니다.
보내는 개인정보
보내는 값은 이름 · 생년월일 · 휴대전화번호 뿐입니다. 주민등록번호는 받지 않습니다. 화면에서도 주민등록번호 입력칸을 만들지 마세요.
수집 항목을 최소로 줄이면 보관·파기 부담과 유출 위험이 함께 줄어듭니다.
테스트 방법
샌드박스·모의 승인은 없습니다. 테스트도 실제 사용자 승인이 필요하고 실제로 과금됩니다. 본인 또는 동의한 사용자의 정보로 소액 검증하세요.
승인 대행은 지원하지 않으므로 자동 테스트로는 끝까지 검증할 수 없습니다.
시간대
expiresAt · checkedAt · resultExpiresAt 은 모두 ISO 8601 UTC(Z) 입니다. 한국시간으로 보여주려면 +9시간 하세요.
로컬 시간으로 착각하면 만료 안내가 9시간 어긋납니다.
1단계 조회 인증 요청 → 2단계 결과조회 순서입니다. 인증은 한 번만 받고, 결과는 준비될 때까지 반복 조회해도 추가 과금이 없습니다.
조회 인증 요청은 인증 1건 20P 로 고정입니다. 결과조회는 60P × 결과 데이터셋 수(1) × 조회범위 단위 수 이며, 실제 결과가 처음 나올 때 한 번만 과금됩니다.
이름·생년월일·휴대전화번호와 간편인증 방식을 입력하면 사용자에게 간편인증 요청을 보내고, 결과 조회에 사용할 transactionId 를 즉시 반환합니다.
1단계 · 조회 인증 요청
Method
URL
POST
https://apick.app/rest/req_health_checkup
인증요청과 결과조회는 완전히 분리되어 있습니다. 이 호출은 인증요청만 보내고 transactionId 를 즉시 반환합니다. 결과는 사용자가 승인한 뒤 /rest/get_health_checkup 에 transactionId 를 넣어 확인합니다.
조회 항목마다 담당 기관이 다르지만, 인증기관은 엔드포인트로 자동 선택되므로 기관을 지정하는 파라미터는 없습니다.
이 응답의 expiresAt 까지만 승인할 수 있습니다. 남은 시간을 화면에 표시하고, 만료되면 사용자가 다시 요청할 수 있게 해 주세요.
요청
Header
이름
필수
설명
CL_AUTH_KEY
O
인증키(MD5)
FormData
이름
타입
필수
설명
user.name
String
O
이름
user.birthDate
String
O
생년월일 8자리(YYYYMMDD)
user.phone
String
O
휴대전화 번호 (본인 명의, 숫자만)
authProvider
String
O
간편인증 방식 (아래 지원 목록 참고)
businessNo
String
X
사업자등록번호 10자리 (이 조회 항목에서는 사용하지 않습니다)
이름·생년월일·휴대전화번호는 위 중첩 입력(user.*)을 쓰세요.name·birthday·phone·provider 라는 평면 이름도 같은 값으로 인정되지만, 새로 만드는 코드에는 user.name · user.birthDate · user.phone · authProvider 를 권장합니다.
조회 항목마다 필요한 추가 입력(requestData.*) 이 다릅니다. 값이 비어 있으면 인증을 보내지 않고 무과금으로 거절하며, 이때는 결과 단가도 발생하지 않습니다.
간편인증 방식(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
조회 항목 코드. 결과조회에도 같은 값이 오므로 어느 항목의 결과인지 대조할 수 있습니다.
이 API 는 polling 용도입니다. 호출 자체는 언제든 무료이며, 실제 결과가 최초로 반환되는 1회에만 과금됩니다. 같은 transactionId 로 다시 조회하면 charged=false 로 추가 과금이 없습니다.
인증 대기(AUTH_WAITING)·조회 중(COLLECTING)·실패(FAILED)·만료(AUTH_EXPIRED) 응답은 과금되지 않습니다. 결과를 받을 때까지 안심하고 반복 조회하세요.
결과가 준비된 뒤에는 조회 시각 기준 24시간 동안 재조회할 수 있습니다. 이 기간의 재조회는 무과금입니다.
응답에는 실제 정보를 확인한 시각이 checkedAt 으로 포함됩니다. 저장해 둔 값을 돌려주는 것이 아니라 그 시점에 확인한 값입니다.
5초 → 10초 → 20초 → 30초 간격으로 조회하고, 이후에는 30초 간격을 권장합니다. 무과금 구간이므로 호출 간격만 지키면 됩니다.
조회 항목이 여러 개인 상품은 일부만 성공하면 PARTIAL_SUCCESS 로 반환하며, 이때도 실제 조회된 데이터가 있으면 최초 1회 과금됩니다. 어느 항목이 성공·실패했는지는 sources 에 표시됩니다.
요청
Header
이름
필수
설명
CL_AUTH_KEY
O
인증키(MD5)
FormData
이름
타입
필수
설명
transactionId
String
O
/rest/req_health_checkup 가 반환한 트랜잭션 ID
응답
처리 상태(status)
값
의미
과금
AUTH_REQUESTED
조회 인증 요청 (/rest/req_health_checkup 응답)
인증요청 시 과금
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)
progress
Object
진행률(COLLECTING 일 때). total(전체 항목), completed(완료 항목)
위 값은 응답 구조를 보여주기 위한 예시입니다. 실제 조회 결과와 무관한 가상의 값이며, 항목 구성과 타입은 결과 규격과 같습니다.
결과 규격
result.healthCheckup
경로
타입
값 존재
설명
예시
이름
String
O
검진 대상자 이름
홍길동
건수
Integer
O
조회된 검진 건수
12
검진내역
Array<Object>
O
연도별 검진 결과. 없으면 빈 배열이다.
검진연도
String
O
검진받은 연도
2025
검진종류
String
O
검진 종류
일반건강검진
검진일자
String
O
검진받은 날
2025-03-14
검진기관
String
O
검진을 시행한 기관
한빛종합병원
타입 읽는 법 — String 은 문자열, Integer 는 소수점 없는 정수(원 단위 금액 포함), Boolean 은 true/false, Object 는 이름이 있는 하위 항목 묶음, Array<Object> 는 같은 구조가 여러 건 오는 목록, Array<String> 은 문자열 목록입니다. String(YYYY-MM-DD) 처럼 괄호가 붙으면 그 형식의 문자열이라는 뜻이고 날짜 타입이 아닙니다.
값 존재 — O 는 정상 응답에 항상 있는 항목, 조건부 는 값이 없으면 응답에서 빠지거나 빈 문자열이 되는 항목입니다. 없는 값을 0 이나 null 로 바꾸지 않으니 그대로 저장하지 말고 존재 여부를 먼저 확인하세요.
예시 — 응답에 들어오는 형태 그대로의 값입니다. 실제 조회 결과가 아니며 개인을 특정할 수 없는 가상의 값입니다. 이 열이 비어 있으면 하위 항목이 있는 묶음이거나 값이 빠질 수 있는 항목입니다.
들여쓰기된 항목은 바로 위 부모 안에 들어 있는 하위 항목입니다. 경로 표기에서 . 는 하위 항목, [ ] 를 붙인 항목은 그 안에 여러 건이 오는 목록이라는 뜻입니다.
