사용자가 아직 승인하지 않은 상태입니다. 조회하면 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 는 동작하지 않습니다.
본문 형식은 JSON(Content-Type: application/json)과
form-urlencoded(application/x-www-form-urlencoded)를 모두 받습니다.
multipart/form-data 는 중첩 이름(user[name])을 해석하지 않습니다.요청 본문 형식을 참고하세요.
인증키
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)을 고르게 합니다. 서버로는 숫자만 남긴 번호를 보내세요(하이픈 제거).
3
/rest/req_<항목> 을 호출하고 응답의 transactionId 를 보관합니다. 이 시점에 20P 가 과금됩니다.
4
사용자에게 간편인증 요청이 발송됐음을 안내하고, 인증 완료를 기다립니다. 남은 시간은 expiresAt 으로 안내하세요.
5
/rest/get_<항목> 로 상태를 확인합니다. resultAvailable 이 true 가 되면 폴링을 멈추고 결과를 사용하세요.
6
transactionId 로 결과물을 조회합니다. 같은 결과는 24시간 동안 다시 꺼낼 수 있습니다.
7
AUTH_EXPIRED · AUTH_REJECTED · RESULT_EXPIRED 는 각각 시간 초과·사용자 거부·재조회 만료이므로, 사용자에게 다시 시도할지 물어보는 흐름으로 처리하세요.
인증 승인은 사용자가 직접 해야 합니다. 승인 대행·자동 승인·인증 정보 저장은 지원하지 않으며, 사용자에게 승인 화면을 안내하는 흐름을 직접 만들어야 합니다.
승인 전 화면을 이탈한 사용자가 많다면 expiresAt 까지 남은 시간을 표시하고, 만료 후에는 재요청 버튼을 제공하세요. 만료된 transactionId 는 재사용할 수 없습니다.
서버가 제한 시간 안에 끝내지 못했습니다. 과금되지 않습니다. 잠시 후 같은 요청을 다시 보내세요.
정상 응답은 HTTP 200 입니다. 상태가 인증 대기중·조회 중 이어도 200 이며, data.success 만 0 입니다. HTTP 코드로 성공을 판단하지 말고 data.status 와 data.resultAvailable 을 보세요.
api.success 는 "APICK 서버가 요청을 정상 처리했는가"만 뜻합니다. 포인트가 모자라 HTTP 402 로 거절돼도 api.success=true 입니다. 과금 여부는 api.cost 와 data.charged 로 판단하세요.
연동 전에 확인하세요
실제 고객 연동에서 자주 나오는 질문입니다. 이 항목들을 먼저 정하면 시행착오를 줄일 수 있습니다.
확인 항목
내용
이유
인증키 발급·보관
인증키는 마이페이지에서 확인합니다(별도 신청 절차 없음). Header CL_AUTH_KEY 에 마이페이지에 표시된 인증키 값을 그대로 넣으세요. 서버 환경변수에 두고 브라우저·앱 클라이언트에는 넣지 마세요. 노출이 의심되면 마이페이지에서 재발급하면 기존 키는 즉시 무효가 됩니다.
인증키는 비밀번호와 같습니다. 앱에 심으면 누구나 추출해 과금을 발생시킬 수 있습니다.
사용자 동의
조회 전에 이용자가 본인 정보 조회에 동의한다는 사실을 서비스 약관·동의 화면에서 받아 두세요. 인증 승인은 그 동의를 확인하는 절차이지 동의를 대신하지 않습니다.
조회 결과를 서비스에 활용하려면 동의 근거가 필요합니다.
보내는 개인정보
보내는 값은 이름 · 생년월일 · 휴대전화번호 뿐입니다. 주민등록번호는 받지 않습니다. 화면에서도 주민등록번호 입력칸을 만들지 마세요.
수집 항목을 최소로 줄이면 보관·파기 부담과 유출 위험이 함께 줄어듭니다.
테스트 방법
샌드박스·모의 승인은 없습니다. 테스트도 실제 사용자 승인이 필요하고 실제로 과금됩니다. 본인 또는 동의한 사용자의 정보로 소액 검증하세요.
승인 대행은 지원하지 않으므로 자동 테스트로는 끝까지 검증할 수 없습니다.
본문 형식
JSON 또는 form-urlencoded 를 쓰세요. 중첩 값은 JSON 의 {"user":{"name":"홍길동"}} 형태가 가장 안전합니다. multipart/form-data 는 중첩 이름을 평면 키로 받아 user[name] 이 그대로 남으므로 쓰지 마세요.
인증 요청과 결과 조회 모두 파라미터가 적어 JSON 하나로 충분합니다.
요청 ID
transactionId 는 인증요청 응답에서 받아 보관하고, 결과 조회·재조회에 그대로 쓰세요. 서버가 반환하는 값 외에 직접 만들지 마세요.
이 값이 없으면 결과를 다시 꺼낼 수 없고 인증요청부터 다시 해야 합니다.
요금 확인
인증요청과 결과조회 모두 요청을 보내기 전에 예상 포인트를 계산할 수 있습니다. 계산식과 상품별 예시는 요금과 포인트를 참고하세요.
포인트가 부족하면 HTTP 402 로 거절됩니다(api.cost=0). 이때는 과금되지 않습니다.
시간대
expiresAt · checkedAt · resultExpiresAt 을 포함한 응답의 모든 시각은 한국시간(UTC+09:00) 입니다. 2026-09-20T05:24:07+09:00 처럼 오프셋이 붙어 오므로 그대로 표시하면 됩니다.
UTC 로 저장해야 한다면 오프셋(+09:00)만 빼세요. 시각을 더하거나 빼서 맞추지 마세요.
요청 본문 형식
인증요청·결과조회 모두 POST + 본문입니다. 같은 값을 아래 세 가지 형식으로 보낼 수 있습니다.
{"name":"홍길동","birthday":"900101","provider":"kakao"} 처럼 user 를 생략해도 서버가 받아줍니다. 신규 연동에는 권장하지 않습니다.
multipart/form-data 는 쓰지 마세요. 서버가 multipart 를 받더라도 user[name] 같은 중첩 이름을 평면 키 그대로 두기 때문에 user 객체를 풀지 못하고 "입력 항목이 잘못됐습니다." 로 거절됩니다. 파일 업로드가 없는 API 이므로 multipart 를 쓸 이유가 없습니다.
형식이 섞여도 됩니다. JSON 본문에 user.name 처럼 점 표기를 쓰거나, form-urlencoded 에 user 만 보내면 중첩으로 해석됩니다. 다만 문서·코드·테스트가 모두 같은 형식을 쓰는 편이 안전합니다.
요금과 포인트
조회는 인증요청 20P 와 결과 단가 두 번 과금됩니다. 포인트가 부족하면 HTTP 402 로 거절되고 그 호출은 과금되지 않습니다.
구분
계산
설명
인증요청
20P 고정
인증요청이 사용자에게 발송된 시점에 발생합니다. 사용자가 승인을 거부하거나 5분 안에 승인하지 않아 AUTH_EXPIRED 가 되어도 환불되지 않습니다.
결과 단가
60P × 데이터셋 수 × 조회범위 단위
결과가 처음 제공된 응답에서만 발생합니다. 재조회·폴링은 무과금입니다.
조회범위 단위
1년 = 1단위, 월 단위 상품은 올림
예: 3년 → 3단위, 6개월 → 1단위, 24개월 → 2단위. 범위 옵션이 없는 상품은 항상 1단위입니다.
무과금 구간
0P
인증 대기·조회 중 폴링, 결과 재조회(24시간), 오류 응답(402·408 포함), 인증 거부·실패.
예상 금액 계산 예시
상황
계산
합계
개인소득 3년 조회 (데이터셋 1개)
20P + (60P × 1 × 3년)
200P
지방세 납부내역 24개월 (월 단위, 데이터셋 1개)
20P + (60P × 1 × 2단위)
140P
데이터셋 4개 상품을 5년 범위로 조회
20P + (60P × 4 × 5년)
1,220P
정확한 값은 상품 페이지의 요금 표에 있습니다. 데이터셋 수와 조회범위 옵션이 상품마다 다르므로, 화면에서 범위를 고르게 했다면 요청 전에 예상 포인트를 함께 표시해 주세요.
응답의 api.cost 는 이번 호출에서 실제로 발생한 포인트, data.charged 는 이번 응답에서 과금이 일어났는지 여부입니다. 두 값을 함께 기록해 두면 고객 문의에 대응하기 쉽습니다.
포인트는 마이페이지에서 잔액을 확인하고 충전합니다. 잔액 부족으로 실패한 요청은 충전 후 같은 요청을 그대로 다시 보내면 됩니다(transactionId 는 새로 발급됩니다).
상태와 성공 판정
필드가 여러 곳에 흩어져 있어 "무엇으로 성공을 판단해야 하는가" 가 가장 많이 나오는 질문입니다. 결론은 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 · RESULT_EXPIRED. SUCCESS 일 때만 결과를 사용하세요.
data.resultAvailable
지금 응답에 쓸 수 있는 결과가 들어 있는지
true 이면 폴링을 멈추고 result 를 사용하세요. false 는 실패가 아니라 아직 준비 중입니다.
data.success
이 응답이 결과 제공 응답인지 (1/0)
성공 경로에서 1 입니다. 처리 시간 초과(408)에서는 3 이 오므로 "1 인지"로 비교하세요.
data.charged · api.cost
이번 호출의 과금 여부·금액
과금 회계 확인용입니다. 성공 판정에 쓰지 마세요.
성공 판정 정본:data.status === "SUCCESS" && data.resultAvailable === true 이면 성공입니다. 그 외 상태는 진행 중이거나 종료이며, 종료 상태는 사용자에게 다시 시도할지 물어보세요.
호출 제한과 재시도
폴링은 무과금·무제한이지만 서버 부하를 줄이려면 간격을 두세요. 결과를 받은 뒤에는 폴링을 멈추는 것이 가장 중요합니다.
항목
권장
비고
폴링 간격
5초 → 10초 → 20초 → 30초, 이후 30초 유지
간격 제한은 없습니다. 위 값은 권장 사항입니다.
폴링 최대 시간
expiresAt 까지
인증 대기라면 expiresAt(요청 후 5분), 조회 중이라면 그 이후 결과가 나올 때까지입니다. expiresAt 이 지나면 AUTH_EXPIRED 로 끝나므로 폴링을 멈추고 재시작 여부를 물어보세요.
결과 수신 후
즉시 폴링 중단
resultAvailable=true 를 받은 순간 멈추세요. 계속 호출해도 무과금이지만 서버 부하만 늘어납니다.
동시 처리
같은 사용자·같은 항목은 1건
처리 중에 다시 보내면 HTTP 424 로 거절되고 과금되지 않습니다. 다른 항목·다른 사용자는 병렬로 진행할 수 있습니다.
분당 호출 제한
없음
별도의 레이트 리밋이나 IP 제한을 두지 않습니다. 다만 과도한 호출은 서버 전체에 영향을 주므로 위 간격을 지켜주세요.
HTTP 424(SIMPLE_AUTH_BUSY) 는 오류가 아니라 "앞선 요청을 아직 처리하고 있다"는 뜻입니다. 같은 transactionId 로 잠시 후 다시 조회하면 정상 흐름으로 이어집니다.
HTTP 408 은 서버가 제한 시간 안에 끝내지 못한 경우입니다. 과금되지 않으므로 잠시 뒤 같은 요청을 다시 보내면 됩니다. 결과 조회가 408 이면 transactionId 는 그대로 쓸 수 있습니다.
자주 묻는 질문
질문
답변
한 사용자가 여러 상품을 동시에 조회할 수 있나요?
가능합니다. 상품마다 별도의 transactionId 가 발급되며 각각 독립적으로 진행됩니다. 다만 상품별로 인증요청을 각각 해야 하고, 인증요청 단가(20P)도 상품마다 따로 발생합니다. 여러 상품을 한 번의 승인으로 처리하는 묶음 조회는 제공하지 않습니다.
같은 사람을 다시 조회하면 사용자가 매번 승인해야 하나요?
인증요청은 매번 필요합니다. 다만 같은 사용자·같은 항목을 30초 안에 다시 요청하면 인증을 재발송하지 않고 기존 transactionId 를 그대로 반환하며 과금되지 않습니다. 승인 후에는 재승인이 아니라 결과 재조회이므로 24시간 동안 같은 transactionId 로 무과금 조회할 수 있습니다.
결과를 얼마나 보관할 수 있나요?
APICK 은 결과를 24시간 동안 재조회할 수 있게 보관한 뒤 파기합니다. 영구 보관이 필요하면 고객 서비스가 직접 결과를 저장하고, 이용자의 개인정보 처리방침에 따라 파기해야 합니다.
웹훅·콜백으로 결과를 받을 수 있나요?
지원하지 않습니다. 결과조회 API 를 폴링해 resultAvailable=true 를 확인하는 방식만 제공합니다.
인증키를 재발급하면 언제 무효가 되나요?
재발급 즉시 기존 키가 바로 무효가 됩니다(유예 기간 없음). 운영 중인 서버가 있으면 재발급 직후 키를 교체하고 재배포하세요. 키를 여러 곳에서 중복 사용하지 않는 편이 안전합니다.
조회 범위를 최대로 늘리면 응답이 매우 커지나요?
범위를 늘려도 응답은 기간별 합계·구간 목록으로 집계되어 항목당 행 수가 급증하지는 않습니다. 다만 상품에 따라 행이 수백 건까지 늘 수 있으므로, 화면 표시는 페이지 단위로 나누는 것을 권장합니다.
샌드박스나 테스트 키가 있나요?
없습니다. 모든 호출이 실제 인증과 실제 과금을 발생시킵니다. 개발 단계에서는 본인 또는 동의한 사용자의 정보로 가장 짧은 조회 범위를 선택해 검증하세요.
포인트 잔액은 어디서 확인하나요?
마이페이지에서 잔액 확인과 충전을 합니다. 잔액 부족은 HTTP 402 로 돌아오며 과금되지 않으므로, 충전 후 같은 요청을 다시 보내면 됩니다.
조회 상품 목록
아래 상품마다 /rest/req_<항목> 과 /rest/get_<항목> 두 엔드포인트가 있습니다. 상품을 고르면 입력 항목·결과 규격·예시를 볼 수 있습니다.
