Skip to content

codef-health-check-reference.md

Latest commit

 

History

History
271 lines (197 loc) · 9.54 KB

codef-health-check-reference.md

File metadata and controls

271 lines (197 loc) · 9.54 KB

CODEF 건강검진결과 참고 메모

검증 기준일: 2026-03-08

이 문서는 아래 공식 자료에서 실제로 확인된 내용만 정리한다.

1. 상품 식별 정보

  • 상품명: 건강검진결과
  • menuCode: KR_PB_PP_004
  • 라우터: /products/public/each/pp/nhis-health-check
  • 엔드포인트: /v1/kr/public/pp/nhis-health-checkup/result
  • timeout: 300

2. 공식 입력 파라미터

공식 입력 파라미터 명세에서 확인된 주요 키:

  • organization
  • loginType
  • certType
  • certFile
  • keyFile
  • certPassword
  • identity
  • birthDate
  • identityEncYn
  • loginTypeLevel
  • userName
  • telecom
  • phoneNo
  • id
  • inquiryType
  • searchStartYear
  • searchEndYear
  • type

연도 관련 공식 키는 searchStartYear, searchEndYear이다. START_YEAR, END_YEAR는 공식 입력 파라미터 명세나 공식 샘플 JSON에서 확인되지 않았다.

3. 간편인증 샘플 JSON에서 확인된 값

공식 간편인증 샘플 JSON에는 다음 키가 포함된다.

{
  "organization": "0002",
  "loginType": "5",
  "loginTypeLevel": "1",
  "userName": "홍길동",
  "phoneNo": "010********",
  "id": "사용자 계정을 식별할 수 있는 유일 값 세팅",
  "identity": "19**0101",
  "inquiryType": "0",
  "searchStartYear": "2021",
  "searchEndYear": "2021",
  "type": "1",
  "telecom": "0"
}

공식 샘플 JSON에는 simpleAuth 키가 1차 요청 입력부에 없다.

간편인증 수단 선택 관련 공식 입력 설명은 아래와 같다.

  • loginType="5"일 때 loginTypeLevel 필수
  • 공식 문서에 기재된 주요 값:
    • 1: 카카오톡
    • 3: 삼성패스
    • 4: KB모바일
    • 5: 통신사(PASS)
    • 6: 네이버
    • 7: 신한인증서
    • 8: toss
    • 10: NH인증서
  • loginTypeLevel="5"인 경우 telecom 필수
    • 0: SKT (SKT 알뜰폰)
    • 1: KT (KT 알뜰폰)
    • 2: LG U+ (LG U+ 알뜰폰)

4. 공식 문서의 추가인증(two-way) 관련 내용

메뉴 상세 문서에서 확인된 내용:

  • 이 상품은 추가인증 대상 상품이다.
  • 추가 인증이 필요한 경우 응답 코드가 CF-03002이고 data.continue2Way=true가 내려온다.
  • 추가 인증 방식은 data.method에서 확인한다.
  • two-way code 목록:
    • 005: 전자서명
    • 003: 간편인증
    • 001: 보안문자

4.0 twoWayInfo가 필요한 시점

공식 문서와 easycodef-java 기준으로 정리하면 아래와 같다.

  • 이 상품은 "추가인증 대상 상품"이다.
  • 하지만 twoWayInfo는 모든 응답에 항상 존재하는 값이 아니다.
  • twoWayInfo는 1차 요청 결과가 추가인증 단계일 때만 필요하다.
  • 판단 기준:
    • 응답 코드가 CF-03002
    • data.continue2Way=true
    • 응답에 data.twoWayInfo 또는 동등한 two-way 정보가 존재
  • 위 조건일 때만 2차 요청으로 전환한다.
  • 2차 요청이 성공하면 최종 응답은 일반 성공 응답(CF-00000)이 될 수 있으며, 이때는 더 이상 twoWayInfo가 필요하지 않다.

즉, "추가인증 대상 상품"과 "twoWayInfo가 항상 내려온다"는 의미는 다르다.

4.1 간편인증(two-way code 003)

공식 two-way 정보에서 확인된 입력/출력:

  • 추가인증 입력 파라미터: simpleAuth
  • 설명: "0": cancel, "1": ok
  • 추가인증 출력 파라미터: commSimpleAuth
  • 입력 샘플:
{
  "simpleAuth": "1"
}

4.2 추가인증 입력부 공통 조건

메뉴 상세 및 easycodef-java에서 공통으로 확인되는 조건:

  • is2Way는 true
  • twoWayInfo는 포함되어야 함
  • twoWayInfo 필수 키:
    • jobIndex
    • threadIndex
    • jti
    • twoWayTimestamp

easycodef-java의 requestCertification은 위 조건을 만족하지 않으면 추가인증 요청으로 보지 않는다.

4.3 최종 성공 응답과 twoWayInfo

실무 해석상 중요한 점:

  • 간편인증 승인 후 2차 요청이 성공하면 최종 응답은 CF-00000일 수 있다.
  • 이 최종 성공 응답에는 twoWayInfo가 더 이상 포함되지 않을 수 있다.
  • 따라서 성공 응답의 일반 data 필드(resReferenceList, resResultList, resCheckupTarget 등)를 twoWayInfo로 해석하면 안 된다.
  • CF-00000인데 twoWayInfo가 없다는 이유만으로 추가인증 미완료로 처리하면 오동작할 수 있다.

이번 확인에서 본 DEMO 성공 응답 예시는 아래 특성을 가졌다.

  • result.code = CF-00000
  • result.message = 성공
  • serviceType = DEMO
  • data.resReferenceList 존재
  • data.resResultList = []
  • twoWayInfo 없음

이 패턴은 "추가인증이 끝난 성공 응답"으로 해석하는 것이 자연스럽다. 다만 DEMO에서는 실제 결과 목록이 비어 있을 수 있다.

5. 문서에 있는 간편인증 주의사항

메뉴 상세 문서의 twowayNote에 있는 내용:

  • 간편인증 타임아웃: 4분 30초
  • 간편인증 시 인증을 완료하지 않고 simpleAuth에 "1"을 입력할 경우:
    • 2번까지는 재시도
    • 3번 시도시 CF-12872 오류 발생

6. id에 대한 공식 설명

메뉴 상세 문서의 입력부 특이사항:

  • id는 금융인증서 사용 시 필수 입력
  • id는 간편인증 사용 시 선택 입력
  • 간편인증에서 id를 입력하면 일정 시간 동안 사용자 계정을 식별하는 값으로 사용된다.
  • 문서에는 다건 요청을 위해 id 값이 필수이며, id를 입력하지 않을 경우 단건 처리라고 설명되어 있다.

7. 주민번호/생년월일 입력 방식

메뉴 상세 문서의 입력부 특이사항:

7.1 주민등록번호 뒷자리 암호화가 필요한 경우

  • identityEncYn: "Y"
  • birthDate: yymmdd
  • identity: 주민등록번호 뒤 7자리

7.2 주민등록번호 뒷자리 암호화가 필요하지 않은 경우

  • birthDate: 미입력
  • identity: 주민등록번호 13자리

입력 파라미터 명세에서는 간편인증(loginType="5")일 때 identity 설명이 생년월일(YYYYMMDD)로 기재되어 있다.

8. easycodef-java에서 확인된 요청 방식

8.1 1차 요청 / 2차 요청 분리

EasyCodef.java에는 메서드가 분리되어 있다.

  • requestProduct(...): 일반 상품 요청
  • requestCertification(...): 추가인증 요청

requestProduct(...)는 is2Way, twoWayInfo가 요청 파라미터에 포함되어 있으면 유효하지 않은 요청으로 본다.

requestCertification(...)는 아래를 확인한다.

  • is2Way == true
  • twoWayInfo 존재
  • twoWayInfo 안에 jobIndex, threadIndex, jti, twoWayTimestamp 존재

8.2 바디 전송 방식

EasyCodefConnector.execute(...)에서 확인된 처리:

  • bodyMap을 JSON 문자열로 직렬화
  • 그 JSON 문자열 전체를 URLEncoder.encode(..., "UTF-8") 처리
  • 인코딩된 문자열을 POST body로 전송

requestProduct(...)는 Accept: application/json 헤더를 설정한다.

8.3 액세스 토큰

EasyCodefConnector에서 확인된 토큰 처리:

  • OAuth endpoint는 EasyCodefConstant.OAUTH_DOMAIN + EasyCodefConstant.GET_TOKEN
  • grant type: client_credentials
  • scope: read
  • Authorization: Basic clientId/clientSecret

9. 이번 작업 중 확인된 오류와 대응 근거

9.1 CF-12872

공식 메뉴 상세 문서의 twowayNote에 원인이 직접 기재되어 있다.

  • 인증 완료 전 simpleAuth="1" 반복 입력
  • 2번까지 재시도
  • 3번째에 CF-12872

9.2 CF-13002 with simpleAuth(userError:commSimpleAuth)

공식 two-way 정보 기준으로 간편인증 추가인증 입력은 simpleAuth이고, 출력 확인 값은 commSimpleAuth이다.

확인 가능한 사실:

  • 간편인증 추가인증 입력 샘플에 simpleAuth: "1"이 존재한다.
  • 간편인증 추가인증 출력 파라미터에 commSimpleAuth가 존재한다.

10. 구현 시 체크리스트

아래 항목은 위 공식 자료에서 직접 확인된 사실만 기반으로 한 체크리스트다.

  • 1차 요청 엔드포인트는 /v1/kr/public/pp/nhis-health-checkup/result
  • 연도 키는 searchStartYear, searchEndYear
  • 간편인증 1차 요청은 loginType="5" 사용
  • 간편인증 수단 선택은 loginTypeLevel로 구분
  • PASS는 loginTypeLevel="5"와 telecom(0|1|2) 조합 사용
  • CF-03002 또는 continue2Way=true일 때만 2차 요청으로 전환
  • 간편인증 2차 요청은 is2Way=true 필요
  • 간편인증 2차 요청은 twoWayInfo 필수
  • data.method == simpleAuth인 경우 2차 입력값 simpleAuth 사용
  • 최종 성공 응답(CF-00000)에는 twoWayInfo가 없을 수 있음
  • 최종 성공 응답의 일반 data 필드를 two-way 정보로 오인하면 안 됨
  • 간편인증 승인 전에 simpleAuth="1"을 반복 전송하면 CF-12872가 발생할 수 있음
  • 간편인증 타임아웃은 문서상 4분 30초