003. 상품 요청 객체 생성

1. 상품 요청 객체 생성

Note

아래 예제는 건강보험공단 > 건강검진결과 API 개발가이드와
공통가이드 > 커넥티드 아이디를 기반으로 작성됐어요.

• path: Codef API에 요청할 경로. host를 제외한 /v1/kr/***/ 형태의 String 값
  
• requestBody: < 'key', 'value [ String ]' > 형식으로 입력부 추가
• requestObject: < 'key', 'value [ Object ]' > 형식으로 입력부 추가
• easycodef.encryptRSA : RSA 암호화가 필요한 파라미터에 암호화 적용

Warning

RequestBuilder 생성자는 아래의 예외 사항들을 같이 검증하고, 검증에 실패하면 예외를 반환해요.

• path 변수가 null이거나, /v1/kr/*** 형식을 따르지 않는 경우

a. 일반 입력부 (Type = String)

(1) Code

EasyCodefRequest request1 = EasyCodefRequestBuilder.builder()
    .path("/v1/kr/public/pp/nhis-health-checkup/result")
    .requestBody("organization", "0002")
    .requestBody("loginType", "5")
    .requestBody("loginTypeLevel", "1")
    .requestBody("identity", "19990101")
    .requestBody("userName", "홍길동")
    .requestBody("telecom", "1")
    .requestBody("phoneNo", "01012345678")
    .requestBody("searchStartYear", "2023")
    .requestBody("searchEndYear", "2023")
    .requestBody("inquiryType", "4")
    .build();

(2) Expected Result

{
  "organization": "0002",
  "loginType": "5",
  "loginTypeLevel": "1",
  "identity": "19990101",
  "userName": "홍길동",
  "telecom": "1",
  "phoneNo": "01012345678",
  "searchStartYear": "2023",
  "searchEndYear": "2023",
  "inquiryType": "4"
}

Note

개발가이드 각 파라미터에, Type이 String으로 명시된 경우에만 사용이 가능해요.

requestBody(key, value);

메소드 체이닝 형태의 requestBody 메소드를 통해 간편하게 String 파라미터를 추가할 수 있어요.

b. 객체 입력부 (Type = Object)

(1) Code

EasyCodefRequest request = EasyCodefRequestBuilder.builder()
    .path("/v1/account/create")
    .requestObject("accountList", params -> {
        params.put("countryCode", "KR");
        params.put("businessType", "BK");
        params.put("clientType", "P");
        params.put("organization", "0106");
    })
    .requestObject("accountList", params -> {
        params.put("countryCode", "KR");
        params.put("businessType", "BK");
        params.put("clientType", "P");
        params.put("organization", "0102");
        // 후략
    })
    .build();

(2) Expected Result

{
  "accountList": [
    {
      "countryCode": "KR",
      "businessType": "BK",
      "clientType": "P",
      "organization": "0106"
    },
    {
      "countryCode": "KR",
      "businessType": "BK",
      "clientType": "P",
      "organization": "0102"
    }
  ]
}

Note

위 예제는 Codef API > 개발가이드 > 공통가이드 > 커넥티드 아이디에서 확인 가능해요.
개발가이드 각 파라미터에, Type이 Object으로 명시된 경우에만 사용이 가능해요.

requestObject(mainKey, params -> {
   params.put(paramKey, value);
   params.put(paramKey, value); 
});

같은 이름의 Key가 요청된 경우, 자동으로 해당 키를 가진 리스트에 추가해요.
메소드 체이닝 형태의 `requestObject` 메소드를 통해 간편하게 입력부 파라미터를 추가할 수 있어요.

Tip

• Codef API 개발가이드 > REST API
  
• Codef API 개발가이드 > 상품 > 공동인증서 서비스

c. 암호화 입력부

(1) 일반 입력부 Code

EasyCodefRequest request1 = EasyCodefRequestBuilder.builder()
    .path("/v1/kr/public/pp/nhis-health-checkup/result")
    .requestBody("organization", "0002")
    .requestBody("identity", easyCodef.encryptRSA("1020304"))
    .requestBody("identityEncYn", "Y")
    .build();

(2) 일반 입력부 Expected Result

{
  "organization": "0011",
  "loginType": "1",
  "userId": "joker7011",
  "userPassword": "D+EEJ4vCfCHYp4jSTzxSU****중략****+ZXikGL85V6n5NzA=="
}

(3) 객체 입력부 Code

EasyCodefRequest request = EasyCodefRequestBuilder.builder()
    .path("/v1/account/create")
    .requestObject("accountList", params -> {
        params.put("countryCode", "KR");
        params.put("businessType", "BK");
        params.put("clientType", "P");
        params.put("organization", "0106");
        params.put("password", easyCodef.encryptRSA("myPassword!@#$"));
    })
    .requestObject("accountList", params -> {
        params.put("countryCode", "KR");
        params.put("businessType", "BK");
        params.put("clientType", "P");
        params.put("organization", "0102");
        params.put("password", easyCodef.encryptRSA("nicePassword!@#$"));
    })
    .build();

(4) 객체 입력부 Expected Result

{
  "accountList": [
    {
      "countryCode": "KR",
      "businessType": "BK",
      "clientType": "P",
      "organization": "0106",
      "password": "EznBOKbjOj5/bDW****중략****TWR3FxGtIgicZRvw=="
    },
    {
      "countryCode": "KR",
      "businessType": "BK",
      "clientType": "P",
      "organization": "0102",
      "password": "wjhu6kgcv3dNTSI****중략****xSffC2TxPCYeJMESkD2k6Tw=="
    }
  ]
}

Note

주민등록번호, 비밀번호 등 민감 데이터는 반드시 RSA 암호화를 진행해야 합니다.

easyCodef.encryptRSA(value);

002. 시크릿 키 기반 EasyCodef 객체 생성에서 만든 easyCodef 객체로 파라미터를 암호화하세요.

Important

적절하게 암호화하지 않으면 아래와 같은 오류를 반환합니다.

{  
  "data": {  
  
  },  
  "result": {  
    "code": "CF-04020",  
    "extraMessage": "",  
    "message": "비밀번호 복호화에 문제가 발생했습니다. 요청 파라미터 중 비밀번호 항목의 암호화 여부를 확인하세요.",  
    "transactionId": "67495898ec82470d00032680"  
  }  
}