{"openapi":"3.0.3","info":{"title":"APICK 국민연금 통합조회","version":"1.0.0","description":"본인 간편인증 후 국민연금 통합조회 자료를 확인합니다. 조회기간: 가입내역 조회 구간(연월). 합계: 조회 구간 전체 합계. 금액은 원 단위 정수다. 가입내역: 구간별 가입 이력. 구간이 나뉘어 있으면 여러 건이 온다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/req_nps_bundle":{"post":{"summary":"국민연금 통합조회","description":"본인 간편인증 후 국민연금 통합조회 자료를 확인합니다. 조회기간: 가입내역 조회 구간(연월). 합계: 조회 구간 전체 합계. 금액은 원 단위 정수다. 가입내역: 구간별 가입 이력. 구간이 나뉘어 있으면 여러 건이 온다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schemaVersion":{"type":"string","description":"결과 스키마 버전 (고정값: \"1.0\")"},"transactionId":{"type":"string","description":"결과 조회에 사용하는 트랜잭션 ID"},"product":{"type":"string","description":"조회 항목 코드. 결과조회에도 같은 값이 오므로 어느 항목의 결과인지 대조할 수 있습니다."},"status":{"type":"string","description":"처리 상태 (AUTH_REQUESTED: 인증 요청 완료)"},"resultAvailable":{"type":"boolean","description":"결과 데이터 포함 여부. 인증 요청 응답은 항상 false 입니다."},"charged":{"type":"boolean","description":"이번 호출의 과금 발생 여부. 실제 발송에 성공하면 true 입니다."},"sources":{"type":"array","items":{}},"message":{"type":"string","description":"상태 메시지 (고정값: \"인증 대기중입니다.\")"},"approvals":{"type":"integer","description":"사용자가 휴대폰에서 승인해야 하는 횟수. 같은 인증으로 처리되는 조회는 묶음이어도 1회입니다."},"expiresAt":{"type":"string","description":"인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다."},"success":{"type":"integer","description":"과금 여부0: 실패 또는 재사용(무과금)1: 발송 성공(과금)"}},"description":"인증 요청 결과"},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"API 서버 정상 응답 여부"},"cost":{"type":"integer","description":"API 호출 요금"},"ms":{"type":"integer","description":"API 응답 시간"},"pl_id":{"type":"integer","description":"API 결제 로그 ID"}},"description":"API 호출 공통 데이터"}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"조회 대상의 이름입니다. 간편인증·개인 조회에서는 성명, 기업 조회에서는 법인명·상호를 뜻합니다. 생년월일·전화번호 같은 보조 식별자와 함께 확인하세요. (string)","example":"홍길동"},"birthDate":{"type":"string","description":"대상자의 생년월일 8자리입니다. 예: 19900101. 주민등록상 생년월일과 같아야 하며, 하이픈·공백은 넣지 않습니다. (string)","example":"19900101"},"phone":{"type":"string","description":"본인 명의 휴대전화 번호입니다. 하이픈 없이 숫자만 입력하며(예: 01012341234), 인증 문자를 받을 수 있는 번호여야 합니다. (string)","example":"01011112222"},"authProvider":{"type":"string","description":"사용할 간편인증 수단의 식별자입니다. 예: kakao, naver, toss, pass. 지원 값과 표시 이름은 이 문서의 간편인증 목록을 확인하세요. (string)","example":"kakao"},"from":{"type":"string","description":"조회를 시작할 연월입니다. YYYY-MM 형식(예: 1995-01)으로 보내며, 생략하면 1988-01부터 조회합니다. 종료 연월보다 늦으면 빈 결과가 옵니다. (string)","example":"2025-01"},"to":{"type":"string","description":"조회를 끝낼 연월입니다. YYYY-MM 형식(예: 2025-12)으로 보내며, 생략하면 이번 달까지 조회합니다. 시작 연월보다 빠르면 빈 결과가 옵니다. (string)","example":"2025-12"},"years":{"type":"string","description":"조회 연수(1~5). 기본 1 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)"}},"required":["name","birthDate","phone","authProvider"]}}}}}},"/rest/get_nps_bundle":{"post":{"summary":"국민연금 통합조회","description":"본인 간편인증 후 국민연금 통합조회 자료를 확인합니다. 조회기간: 가입내역 조회 구간(연월). 합계: 조회 구간 전체 합계. 금액은 원 단위 정수다. 가입내역: 구간별 가입 이력. 구간이 나뉘어 있으면 여러 건이 온다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schemaVersion":{"type":"string","description":"결과 스키마 버전 (고정값: \"1.0\")"},"transactionId":{"type":"string","description":"트랜잭션 ID"},"product":{"type":"string","description":"조회 항목 코드. 인증요청 응답과 같은 값입니다."},"status":{"type":"string","description":"처리 상태 (위 표 참고)"},"resultAvailable":{"type":"boolean","description":"실제 결과 포함 여부. 과금 여부도 이 값으로 결정됩니다."},"charged":{"type":"boolean","description":"이번 호출의 과금 발생 여부. 최초 결과 반환에서만 true 입니다."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"}}},"description":"항상 포함됩니다. 값이 없으면 빈 배열 [] 입니다. 항목이 여러 개인 상품에서 어느 것이 성공·실패했는지 알려줍니다. 각 항목은 source(자료 이름), type(데이터 종류), status(SUCCESS/FAILED). 결과 준비가 끝나기 전에는 아직 확정되지 않은 항목이 FAILED 로 보일 수 있습니다."},"message":{"type":"string","description":"상태 메시지"},"expiresAt":{"type":"string"},"success":{"type":"integer","description":"과금 여부0: 결과 없음 또는 재조회(무과금)1: 최초 결과 반환(과금)"},"progress":{"type":"object","properties":{"total":{"type":"integer"},"completed":{"type":"integer"}},"description":"진행률(COLLECTING 일 때). total(전체 항목), completed(완료 항목)"},"checkedAt":{"type":"string","description":"실제 정보를 확인한 시각. 한국시간(UTC+09:00) ISO 8601 이며 재조회 유효기간의 기준입니다."},"resultExpiresAt":{"type":"string","description":"결과 재조회 만료 시각. 한국시간(UTC+09:00) ISO 8601 입니다."},"result":{"type":"object","properties":{"npsJoinHistory":{"type":"object","additionalProperties":true,"properties":{"조회기간":{"type":"object","description":"가입내역 조회 구간(연월).","properties":{"시작":{"type":"string","description":"조회 시작 연월"},"종료":{"type":"string","description":"조회 종료 연월"}}},"합계":{"type":"object","description":"조회 구간 전체 합계. 금액은 원 단위 정수다.","properties":{"납부개월":{"type":"integer","description":"납부한 개월 수"},"납부금액":{"type":"integer","description":"납부한 보험료 합계(원)"},"미납개월":{"type":"integer","description":"미납 개월 수"},"미납금액":{"type":"integer","description":"미납 금액(원)"}}},"가입내역":{"type":"array","description":"구간별 가입 이력. 구간이 나뉘어 있으면 여러 건이 온다.","items":{"type":"object","properties":{"시작":{"type":"string","description":"해당 구간 시작 연월"},"종료":{"type":"string","description":"해당 구간 종료 연월"},"기준소득월액":{"type":"integer","description":"그 구간의 기준소득월액(원)"},"납부개월":{"type":"integer","description":"해당 구간 납부 개월 수"},"납부금액":{"type":"integer","description":"해당 구간 납부 보험료(원)"},"미납개월":{"type":"integer","description":"해당 구간 미납 개월 수"},"미납금액":{"type":"integer","description":"해당 구간 미납 금액(원)"},"가입자구분":{"type":"string","description":"가입자 구분"},"사업장":{"type":"string","description":"가입 사업장명. 지역가입 등 사업장이 없으면 빈 값이다."}}}}},"description":"이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요."},"npsDeductionCert":{"type":"object","properties":{"조회기간":{"type":"object","properties":{"시작":{"type":"string","description":"가장 오래된 발급연도"},"끝":{"type":"string","description":"가장 최근 발급연도"}},"description":"조회한 발급연도 구간."},"신청인":{"type":"string","description":"증명서에 표시된 가입자 이름"},"생년월일":{"type":"string","description":"증명서에 표시된 생년월일(6~8자리)"},"연도별내역":{"type":"object","items":{"type":"object","properties":{"발급연도":{"type":"string"},"사업장가입자고지금액":{"type":"integer"},"지역가입자등납부금액":{"type":"integer"},"사업장가입자소급금액":{"type":"integer"},"추납보험료납부금액":{"type":"integer"},"실업크레딧납부금액":{"type":"integer"},"총합계":{"type":"integer"}}},"description":"발급연도별 납부금액 내역. 최근 연도가 먼저 온다.","properties":{"발급연도":{"type":"string","description":"해당 내역의 발급연도"},"사업장가입자고지금액":{"type":"integer","description":"사업장가입자 고지금액 합계(소급금액 포함, 원)"},"지역가입자등납부금액":{"type":"integer","description":"지역가입자 등 납부금액 합계(원)"},"사업장가입자소급금액":{"type":"integer","description":"사업장가입자 소급금액(원)"},"추납보험료납부금액":{"type":"integer","description":"추납보험료 납부금액(원)"},"실업크레딧납부금액":{"type":"integer","description":"실업크레딧 납부금액(원)"},"총합계":{"type":"integer","description":"위 항목을 합한 총 합계(원)"}}}},"description":"이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요."},"npsCareerHistory":{"type":"object","properties":{"조회기간":{"type":"object","properties":{"시작":{"type":"string","description":"조회 시작 연월"},"끝":{"type":"string","description":"조회 종료 연월"}},"description":"경력 조회 구간(연월)."},"합계":{"type":"object","properties":{"사업장수":{"type":"integer","description":"경력에 나타난 서로 다른 사업장 수"},"경력건수":{"type":"integer","description":"재직 구간 수. 같은 사업장을 다시 다니면 두 건이 된다."},"사업장납부개월":{"type":"integer","description":"사업장 가입 구간의 납부 개월 합계"},"사업장납부금액":{"type":"integer","description":"사업장 가입 구간의 납부 보험료 합계(원)"},"사업장외납부개월":{"type":"integer","description":"사업장이 없는 구간(지역가입 등)의 납부 개월 합계"}},"description":"사업장 경력 기준 합계. 금액은 원 단위 정수다."},"경력":{"type":"object","items":{"type":"object","properties":{"사업장":{"type":"string"},"시작":{"type":"string"},"종료":{"type":"string"},"기준소득월액":{"type":"integer"},"납부개월":{"type":"integer"},"미납개월":{"type":"integer"},"납부금액":{"type":"integer"}}},"description":"사업장 단위 재직 경력. 기간이 이어지면 한 건으로 합쳐서 준다.","properties":{"사업장":{"type":"string","description":"가입 사업장명"},"시작":{"type":"string","description":"해당 경력 시작 연월"},"종료":{"type":"string","description":"해당 경력 종료 연월"},"기준소득월액":{"type":"integer","description":"해당 경력의 마지막 기준소득월액(원)"},"납부개월":{"type":"integer","description":"해당 경력의 납부 개월 수"},"미납개월":{"type":"integer","description":"해당 경력의 미납 개월 수"},"납부금액":{"type":"integer","description":"해당 경력의 납부 보험료 합계(원)"}}},"사업장외가입":{"type":"object","items":{"type":"object","properties":{"시작":{"type":"string"},"종료":{"type":"string"},"가입자구분":{"type":"string"},"납부개월":{"type":"integer"},"납부금액":{"type":"integer"}}},"description":"사업장명이 없는 구간. 지역가입·임의가입 등이며 경력에는 넣지 않는다.","properties":{"시작":{"type":"string","description":"해당 구간 시작 연월"},"종료":{"type":"string","description":"해당 구간 종료 연월"},"가입자구분":{"type":"string","description":"가입자 구분"},"납부개월":{"type":"integer","description":"해당 구간 납부 개월 수"},"납부금액":{"type":"integer","description":"해당 구간 납부 보험료(원)"}}}},"description":"이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요."}},"description":"조회된 결과 묶음. 실제 데이터가 있을 때만 포함됩니다."},"errorCode":{"type":"string","description":"오류 구분. RESULT_EXPIRED(재조회 기간 만료) / AUTH_EXPIRED / AUTH_REJECTED / COLLECT_FAILED"}},"description":"상태·결과"},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"API 서버 정상 응답 여부"},"cost":{"type":"integer","description":"API 호출 요금"},"ms":{"type":"integer","description":"API 응답 시간"},"pl_id":{"type":"integer","description":"API 결제 로그 ID"}},"description":"API 호출 공통 데이터"}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"transactionId":{"type":"string","description":"인증요청 단계에서 발급된 거래 ID입니다. 인증요청 응답의 transactionId를 그대로 넣어야 하며, 임의 값이나 만료된 ID는 거부됩니다. (string)","example":"9f2c4a7b1d8e35c60a4f7b2d1e9c803a"}},"required":["transactionId"]}}}}}}},"x-code-tables":[{"title":"오류와 복구","columns":["상황","HTTP","data.error","해결"],"rows":[["이름·생년월일·휴대전화 번호가 비었거나 형식이 틀림","400","입력 항목이 잘못됐습니다.(이름) — 괄호 안에 항목 이름(생년월일 8자리·휴대전화 번호)이 표시됩니다.","값을 고쳐 인증 요청을 다시 보냅니다. 인증이 발송되지 않아 과금되지 않습니다."],["authProvider 가 허용값이 아니거나 지금 쓸 수 없는 인증방식","400","입력 항목이 잘못됐습니다.(인증방식)","간편인증 방식 표의 값(예: kakao)으로 보냅니다."],["같은 상품의 앞선 요청을 처리하는 중","429","앞선 요청을 처리하고 있습니다. 잠시 후 다시 시도해 주세요.","인증 요청을 다시 보내지 말고 잠시 뒤 받은 transactionId 로 결과를 조회합니다."],["보유 포인트가 이번 호출 단가보다 적음","200","data 대신 result.error 에 사용 가능한 포인트이 부족합니다.","충전한 뒤 다시 호출합니다. 결과조회는 같은 transactionId 를 그대로 씁니다."],["결과를 청구하는 순간 포인트가 부족함","402","결제 금액보다 보유 포인트이 부족합니다.","충전한 뒤 같은 transactionId 로 다시 조회합니다. 결과는 24시간 보관됩니다."],["결과조회에 transactionId 가 없음","400","입력 항목이 잘못됐습니다.(transactionId)","인증 요청 응답의 transactionId 를 보냅니다."],["없는 transactionId 또는 다른 상품의 결과조회 경로","404","요청을 찾을 수 없습니다.","인증 요청한 상품의 /rest/get_nps_bundle 로 조회합니다."],["사용자가 승인을 거부함","200","없음 — status=AUTH_REJECTED, errorCode=AUTH_REJECTED","다시 시도할지 사용자에게 묻고 인증 요청부터 다시 합니다(인증 요청 단가가 다시 발생)."],["5분 안에 승인하지 않음","200","없음 — status=AUTH_EXPIRED, errorCode=AUTH_EXPIRED","인증 요청부터 다시 합니다. 결과 단가는 발생하지 않습니다."],["조회하지 못함(대상이 아니거나 일시적으로 처리하지 못함)","200","없음 — status=FAILED, errorCode=COLLECT_FAILED","결과 단가는 발생하지 않습니다. 입력값을 확인한 뒤 잠시 후 인증 요청부터 다시 합니다."],["결과 재조회 기간(24시간)이 지남","200","없음 — errorCode=RESULT_EXPIRED","받은 결과는 바로 저장해 두세요. 다시 받으려면 인증 요청부터 합니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}