의료기기 통합정보시스템 공개 API 활용 방법
-
의료기기 표준코드(UDI) 기반 통합정보시스템 구축 OpenAPI 가이드
1. 개요
본 문서는 의료기기 통합정보시스템(이하 ‘통합정보시스템’이라 한다)에 의료기기 표준코드(UDI) 및 통합정보 등록을 위해 공개된 API 활용법을 설명하는 개발자용 문서입니다.
1.1. 구성
통합정보시스템 공개 API는 HTTP REST, JSON 포맷 통신규약을 전제하여 구성되어 있습니다. 모든 응답은 JSON Object로 진행됩니다.
1.2. 보안
통합정보시스템 공개 API는 OAuth2 스펙을 통해 인증을 제공합니다. token 요청을 제외한 모든 기능은 Header에 Authorization: {access_token}을 포함하여야 합니다.
1.3. 제공하는 기능
기능명칭 기능설명 Access Token 발급 Access Token 발급 품목 목록 조회 사용자 업체의 허가(인증·신고) 품목 목록을 조회 모델 목록 조회 사용자 업체의 허가(인증·신고) 모델 목록을 조회 UDI-DI 통합정보 목록 조회 모델별 등록된 UDI-DI 코드 및 통합정보를 조회 UDI-DI 코드 및 통합정보 추가 모델별 UDI-DI 코드 등록 UDI-DI 코드 수정 등록된 UDI-DI 코드 정보를 수정 UDI-DI 코드 삭제 등록된 UDI-DI 코드를 삭제 통합정보 수정 통합정보를 수정 물류바코드 목록 조회 통합정보 항목 중 물류바코드 정보를 조회 물류바코드 추가 통합정보 항목 중 물류바코드 정보를 추가 물류바코드 수정 통합정보 항목 중 물류바코드 정보를 수정 물류바코드 삭제 통합정보 항목 중 물류바코드 정보를 삭제 요양급여 정보 조회 요양급여코드로 해당 코드의 요양급여정보를 조회 거래처 목록 조회 공급내역보고를 위해 등록된 거래처 목록 조회 통합업체 목록 조회 거래처를 등록하기 위한 통합정보시스템에 등록된 업체 목록 조회 도로명주소 조회 거래처 등록 시 필요한 도로명 주소를 조회 거래처 등록 공급내역보고를 위한 거래처 등록 거래처 수정 등록된 거래처 수정 공급내역 보고자료 목록 조회 공급내역 보고자료 목록 조회 공급내역 보고자료 추가 공급내역 보고자료 추가 공급내역 보고자료 수정 공급내역 보고자료 수정 공급내역 보고자료 일괄 삭제 기준 월의 공급내역 보고자료 일괄 삭제 공급내역 보고자료 단건 삭제 공급내역 보고자료 단건 삭제 고유식별자(UDI-DI) 품목 정보 조회 고유식별자(UDI-DI) 코드의 품목 정보 조회 공급내역 보고 이력 목록 조회 기준 월 별로 공급내역 보고된 요약정보 목록 조회 공급내역 보고 현황 목록 조회 공급내역 보고된 현황 목록 조회 공급내역 보고 및 재보고 처리 공급내역 보고자료 정보를 보고 및 재보고 처리 수행 1.4. 개발환경 구성
HTTP 요청을 보낼 수 있는 환경이면 어디에서든 이용 가능합니다.1.4.1. API Test 제공
아래 소개하는 OAuth2 인증을 제외한 모든 API는 /api/v1/{resource}/** 로 구성되어있으며, 해당 기능을 테스트하기 위해서는 /api/test/v1/{resource}/** 와 같이 api하위로 test경로만 추가 하면 테스트 해 보실 수 있습니다. 조회 기능을 제외한 등록, 수정, 삭제 기능들은 실제로 등록, 수정, 삭제가 수행되지 않고 입력값 검증 결과만 확인하기 때문에 응답값이 본 문서에 설명과는 다를 수 있음을 알려드립니다. 응답값을 제대로 입력했는지 테스트 하는 용도로 사용하실 수 있습니다.1.5. 제한사항
1.5.1. HTTP Method
HTTP REST 스펙을 구현함에 있어서 CRUD에 HTTP Method를 적절히 사용해야 하나, 식품의약품안전처 시스템 보안 규정상 GET, POST 외의 Method를 사용할 수 없어 부득이 변형된 형태를 사용하게 됨을 양해바랍니다.1.5.2. 예제코드
HTTP 프로토콜에 대한 예제만 제공하며, 상세한 예제코드는 Java 기반으로만 제공합니다. 다른 언어는 Java 코드를 참고하여 개발해야 합니다. 예제코드의 restTemplate은 Spring Framework의 RestTemplate를 사용했습니다.2. USECASE
일반적인 업무 흐름에 따른 API USECASE를 설명합니다.2.1. AccessToken 발급
통합정보시스템의 모든 API를 사용하기 위해서는 OAuth2 기반 인증절차가 선행되어야 합니다. 관련 상세 스펙은 [?]을 참고하여 API를 사용하기 위한 유효한 Access Token을 유지해야 합니다.2.2. UDI-DI 코드 및 통합정보 등록
모델별 UDI-DI 코드 및 통합정보를 등록하는 시나리오를 설명합니다.
UDI-DI 코드 및 통합정보 등록을 위해서는 우선 UDI-DI 코드를 등록할 모델을 [모델 목록 조회] API로 식별하여, [UDI-DI 코드 및 통합정보 추가] API를 통해 UDI-DI코드를 등록하고 그에 따른 통합정보 내용을 [통합정보 수정] API를 통해 등록하는 절차를 따라야 합니다. 이때, 요양급여 정보는 [요양급여 정보 조회] API로 조회한 정보를 설정해야 합니다. [UDI-DI 코드 및 통합정보 추가] 과정에서 통합정보 일부 항목(허가정보 연계항목)은 자동으로 입력됩니다.이후 상세 물류 바코드를 [물류바코드 추가] API로 등록하는 과정을 통해 통합정보 입력이 진행되며, 통합정보 등록이 완료되는 기준(웹서비스와 동일)을 충족하면 통합정보 등록이 완료된 것으로 처리됩니다. 물류바코드 추가 과정에서 수정 혹은 삭제 요구 발생 시에는 [물류바코드 수정], [물류바코드 삭제] API를 통해 이를 수행할 수 있습니다.
등록된 혹은 등록중인 UDI-DI 코드 및 통합정보는 [UDI-DI 통합정보 목록 조회] API를 통해 조회할 수 있으며, 통합정보의 점진적 작성을 위해서는 [UDI-DI 통합정보 목록 조회]의 결과정보로 반복적인 통합정보 수정 작업을 진행할 수 있습니다.2.3. 공급내역 보고 처리
업체 별 공급내역 보고를 처리하는 시나리오를 설명합니다.
공급내역 보고 처리를 위해서는 우선 특정 기준 월의 [공급내역 보고자료 추가] API를 통해 공급내역 보고자료를 추가합니다. 이때, 공급내역 보고자료에 추가하는 품목정보를 [고유식별자(UDI-DI) 품목 정보 조회] API를 통해 조회할 수 있습니다.등록된 공급내역 보고자료 정보를 [공급내역 보고자료 목록 조회] API를 통해 조회합니다. 이때, 잘못 등록된 공급내역 보고자료가 있을 경우 [공급내역 보고자료 수정] 및 [공급내역 보고자료 단건 삭제] API를 통해 한 건 씩 수정, 삭제 할 수 있으며, [공급내역 보고자료 일괄 삭제] API를 통해 해당 기준 월의 공급내역 보고자료를 한 번에 삭제할 수 있습니다.
이후 기준 월에 등록된 공급내역 보고자료를 [공급내역 보고 및 재보고] API로 공급내역 보고 처리 요청을 합니다.(보고 가능 기한 내에 보고자료는 재보고 가능합니다.) [공급내역 보고 이력 목록 조회] API로 공급내역 보고 요약 정보를 조회할 수 있고, [공급내역보고 현황 목록 조회] API를 통해 공급내역 보고 상세 정보를 확인할 수 있습니다.
3. OAUTH2 Access Token 요청
통합정보시스템의 API를 사용하기 위해서는 OAuth2기반의 인증정보가 필요합니다. 클라이언트에서 API에 제공하는 인증정보를 Access Token이라고 하며 Access Token을 HTTP 헤더의 Authorization 에 설정함으로써 시스템이 API를 호출하는 클라이언트를 식별할 수 있도록 합니다. 본 절은 Access Token을 발급받는 방법을 설명합니다.
3.1. Request
OAUTH2 Access Token 요청 Request POST /api/oauth/token HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Basic {auth}
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept: application/json;charset=UTF-8통합정보시스템 웹서비스의 회원정보수정 화면에서 ClientId와 ClientSecret을 확인합니다. 이 값을 “{ClientId}:{ClientSecret}“ 형태의 문자열로 만들어 Base64로 인코딩하고 HTTP Header의 Authorization 에 설정하고 아래 필드를 form submit (form-urlencoded) 형태로 POST 요청합니다.
- 요청필드
- 요청예제
POST /api/oauth/token HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Basic {base64 encoded clientId:clientSecret}
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept: application/json;charset=UTF-8
grant_type=client_credentials- 예제 코드 (Java, Spring)
public static String obtainAccessToken(String clientId, String clientSecret) throws JSONException {
String authService = "https://udiportal.mfds.go.kr/api/oauth/token";String value = String.format("%s:%s", clientId, clientSecret);
String authorization = "Basic " +
Base64.getEncoder().encodeToString(value.getBytes(Charset.forName("UTF-8")));MultiValueMap<String, String> formParam = new LinkedMultiValueMap<>();
formParam.add("grant_type", "client_credentials");HttpHeaders headers = new HttpHeaders();
headers.add(HttpHeaders.AUTHORIZATION, authorization);
headers.add(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_UTF8_VALUE);HttpEntity<MultiValueMap<String, String>> requestEntity = new HttpEntity<>(formParam, headers);
ResponseEntity<String> responseEntity =
restTemplate.exchange(URI.create(authService),
HttpMethod.POST,
requestEntity,
String.class);
return new JSONObject(responseEntity.getBody()).getString("access_token");}
3.2. Response
- 응답코드
코드 설명 200 정상 응답 401 ClientID 가 존재하지 않거나 ClientSecret이 잘못된 경우 500 처리 중 오류가 발생했을 경우 - 응답필드
키 설명 타입 access_token Access Token string token_type Access Token의 타입. "bearer" 고정값 string expires_in Access Toke 만료 시간(초). 기본값 86400초(1일) numaber scope 접근할 수 있는 권한 범위 string - 응답예제
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{"access_token":"{access_token}","token_type":"bearer","expires_in":63849,"scope":"api_call"}{access_token}값을 이후 요청시 Authorization 헤더에 Bearer {access_token} 형태로 추가해 사용합니다. Access Token은 expires_in 필드의 값으로 계산하여 만료되기 전 새로운 Access Token을 발급받아 놓거나, 응답 코드가 401(인증정보 없음)일 때 재발급 받아서 다시 요청하는 등 유효기간 만료에 대비해야 합니다.
- 에러 응답 예제 – ClientId 가 존재하지 않거나 ClientSecret이 잘못된 경우
HTTP/1.1 401 UNAUTHORIZED
WWW-Authenticate: Basic realm="oauth2/client"
Content-Type: application/json;charset=UTF-8
{"timestamp":"2019-08-11T09:53:58.998+0000","status":401,"error":"Unauthorized","message":"Unauth
orized","path":"/oauth/token"}4. 품목 목록 조회
본 API는 품목허가 목록을 조회합니다. UDI-DI 통합정보 관련 API를 사용하는데 필요한 값은 응답필드에 굵은글씨(Bold)처리 되어있습니다.4.1. Request
GET /api/v1/int-info/items?offset=1&limit=50 HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Accept: application/json;charset=UTF-8.Access_token을 Authorization Header에 담아 GET 으로 요청합니다.
- 요청필드
키 설명 구분 필수 타입 offset 페이징이 시작될 숫자 Query O number limit 페이징에 담길 개수 (최대 100) Query O number itemName 검색할 품목명 (LIKE 검색) Query X sring productName 검색할 제품명 (LIKE 검색) Query X sring grade 등급 Query X sring searchStart 검색 시작일자
format : YYYY-MM-DD
Query X sring searchEnd 검색 종료일자
format : YYYY-MM-DD
Query X sring udiDiCode 검색할 UDI-DI 코드 (LIKE 검색)
해당 코드가 포함된 품목들을 조회
Query X sring - 예제
UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl("http://udiportal.mfds.go.kr/api/v1/int-info/items")
.queryParam("offset", 1)
.queryParam("limit", 10);
HttpHeaders headers = new HttpHeaders();
String accessToken = obtainAccessToken(clientId, clientSecret);
headers.add(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
headers.add(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_UTF8_VALUE);
HttpEntity httpEntity = new HttpEntity(headers);ResponseEntity<String> responseEntity = restTemplate.exchange(uriBuilder.toUriString(),
HttpMethod.GET,
httpEntity,
String.class);
JSONObject body = new JSONObject(responseEntity.getBody());4.2. Response
- 응답코드
코드 설명 200 정상응답 400 입력값이 잘못되었을 경우 403 해당 정보에 접근 권한이 없을 경우 401 인증정보가 존재하지 않을 경우 500 처리 중 오류가 발생했을 경우 - 응답필드
키 설명 타입 page 현재 페이지 번호 number pageSize 페이지 크기 number totalElements 총 갯수 number items[].itemName 품목명 string items[].permititemNo 품목허가번호 string items[].permitDate 품목허가일자 string items[].grade 등급 string items[].meddevItemSeq 품목일련번호 string items[].isForExport 수출용 여부 string items[].cobFlagCode 제조/수입 구분
- 제조 : MNFCTUR
- 수입 : INCME
string items[].udidiCount 등록된 UDI-DI 코드 개수 number - 응답예제
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"pageSize": 10,
"page": 1,
"items": [
{
"itemName": "탄력밴드",
"grade": "1",
"permitDate": "2006-11-03",
"meddevItemSeq": "20060105",
"isForExport": false,
"mebTypeName": null,
"meddevItemNo": "부산 제신 06-121 호",
"cobFlagCode": "MNFCTUR"
},
...
],
"totalElements": 120
}5. 모델 목록 조회
전체 모델 목록을 조회합니다. 모델 정보는 매우 중요합니다. 향후 설명할 UDI-DI 통합정보에 관련된 API는 모델 정보에 종속적이기 때문입니다. 통합정보를 조회하고 등록하고 수정하는데 모델의 정보가 필수 매개변수로써 사용됩니다. UDI-DI 통합정보 관련 API를 사용하는데 필요한 값은 응답필드에 굵은글씨(Bold)처리 되어있습니다.
5.1. Request
GET /api/v1/int-info/models?offset=1&limit=50 HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Accept: application/json;charset=UTF-8Access_token을 Authorization Header에 담아 GET 으로 요청합니다.
- 요청필드
키 설명 구분 필수 타입 offset 페이징이 시작될 숫자 Query O number limit 페이징에 담길 개수 (최대 100) Query O number modelNameLike 검색할 모델명 Query O string - 예제
GET /api/v1/int-info/models?offset=1&limit=10 HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Accept: application/json;charset=UTF-8- 예제코드 (Java, Spring)
UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl("https://udiportal.mfds.go.kr/api/v1/int-info/models")
.queryParam("offset", 1)
.queryParam("limit", 10);
HttpHeaders headers = new HttpHeaders();
String accessToken = obtainAccessToken(clientId, clientSecret);
headers.add(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
headers.add(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_UTF8_VALUE);
HttpEntity httpEntity = new HttpEntity(headers);
ResponseEntity<String> responseEntity = restTemplate.exchange(uriBuilder.toUriString(),
HttpMethod.GET,
httpEntity,
String.class);JSONObject body = new JSONObject(responseEntity.getBody());
5.2. Response
- 응답코드
코드 설명 200 정상응답 400 입력값이 잘못되었을 경우 403 해당 정보에 접근 권한이 없을 경우 401 인증정보가 존재하지 않을 경우 500 처리 중 오류가 발생했을 경우 - 응답필드
키 설명 타입 page 현재 페이지 번호 number pageSize 페이지 크기 number totalElements 총 갯수 number items[].modelName 모델명 string items[].itemName 품목명 string items[].permitItemNo 품목허가번호 string items[].permitDate 품목허가일자 string items[].grade 등급 string items[].udiDiCount 등록된 UDI-DI 통합정보 갯수 string items[].meddevItemSeq 품목일련번호 string items[].isForExpert 수출용 여부 boolean items[].seq 모델 일련번호 string items[].cobFlagCode 제조/수입 구분
- 제조 : MNFCTUR
- 수입 : INCME
string - 응답예제
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8{
"pageSize": 10,
"page": 1,
"items": [
{
"modelName": "맨담서포트 무릎튼튼 프리미엄+",
"itemName": "탄력밴드",
"permitItemNo": "부산 제신 06-120 호",
"permitDate": "2006-10-27",
"grade": "1",
"udidiCount": "2",
"meddevItemSeq": 20060048,
"isForExport": false,
"seq": "7147",
"cobFlagCode": null
},
...
],
"totalElements": 308
}6. UDI-DI 통합정보 목록 조회
해당 모델의 UDI-DI 코드 및 통합정보 목록을 조회합니다. 본 API의 매개변수로 쓰이는 값들은 [?]에서 확인할 수 있습니다.
6.1. Request
GET /api/v1/int-info/udidi-unity?meddevItemSeq={meddevItemSeq}&mebTypeName={mebTypeNam
e}&isForExport={isForExport} HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Accept: application/json;charset=UTF-8Access_token을 Authorization Header에 담아 GET 으로 요청합니다.
- 요청필드
키 설명 구분 필수 타입 meddevItemSeq 품목일련번호 Query O number mebTypeName 모델명
URL encoding해야 하며 아래 문자는 별도로 URL encoding 전에 치환해줘야 합니다.- “+” -> “%2B”
- “&” -> “%26”
Query O string isForExport 수출용 여부
true/false
Query O boolean - 예제
GET /api/v1/int-info/udidi-unity?meddevItemSeq=20060048&mebTypeName=%25ED%2583%2584%2
5EB%25A0%25A5%25EB%25B0%25B4%25EB%2593%259C(JC-7500%2520SPEC)&exportYn=false HTT
P/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Accept: application/json;charset=UTF-8- 예제코드 (Java, Spring)
UriComponentsBuilder uriBuilder = UriComponentsBuilder.fromHttpUrl("https://udiportal.mfds.go.kr/api/v1/int-info/udidi-unity")
.queryParam("meddevItemSeq", 20060048)
.queryParam("mebTypeName", "탄력밴드(JC-7500 SPEC)".replace("+", "%2B").replace("&", "%26"))
.queryParam("isForExport", false);
HttpHeaders headers = new HttpHeaders();
String accessToken = obtainAccessToken(clientId, clientSecret);
headers.add(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
headers.add(HttpHeaders.ACCEPT, MediaType.APPLICATION_JSON_UTF8_VALUE);
HttpEntity httpEntity = new HttpEntity(headers);ResponseEntity<String> responseEntity = restTemplate.exchange(uriBuilder.build(false).toUriString(),
HttpMethod.GET,
httpEntity,
String.class);JSONObject body = new JSONObject(responseEntity.getBody());
6.2. Response
- 응답코드
코드 설명 200 정상응답 400 입력값이 잘못되었을 경우 403 해당 정보에 접근 권한이 없을 경우 401 인증정보가 존재하지 않을 경우 500 처리 중 오류가 발생했을 경우 - 응답필드
키 설명 타입 items[].udiDiSeq UDI-DI 일련번호 number items[].productItemInfo 제품정보 object items[].productItemInfo.meddevItemSeq 품목일련번호 number items[].productItemInfo.itemName 품목명 string items[].productItemInfo.grade 등급 string items[].productItemInfo.meddevItemNo 품목허가번호 string items[].productItemInfo.permitDate 품목허가일자 string items[].productItemInfo.mebTypeName 형명(모델명) string items[].productItemInfo.isForExport 수출용 여부 boolean items[].productItemInfo.cobFlagCode 제조/수입 구분
- 제조 : MNFCTUR
- 수입 : INCMEstring items[].meddevItemSeq 품목일련번호 number items[].udiDiCode UDI-DI 코드 string items[].codeSystemFlag 구분코드 구분 string items[].packQuantity 포장 내 수량 number items[].isUseEnd 사용종료여부 boolean items[].useEndDate 사용종료일자 string items[].useEndReason 사용종료사유 string items[].unityInfoRegisted 통합정보 등록 여부 boolean items[].unityInfoRegistComptDate 통합정보 등록 완료일 string items[].isSupplyHist 공급내역여부 boolean items[].useLotNo 로트번호 사용 여부 boolean items[].useItemSeq 일련번호 사용 여부 boolean items[].useManufYm 제조연월 사용 여부 boolean items[].useTimeLimit 사용기한 사용 여부 boolean items[].isSterilizationMeddev 멸균의료기기여부 boolean items[].needSterilization 사용전 멸균 필요 여부 boolean items[].sterilizationMethods 멸균방법 array items[].sterilizationMethods[].order 멸균방법 순번 number items[].sterilizationMethods[].code 멸균방법코드
“1”:고압증기멸균
“2”:건열멸균
“3”:에틸렌옥사이드가스멸균
“4”:의료용포름알데이드가스멸균
“5”:의료용저온플라즈마멸균
“6”:냉액멸균
“7”:마이크로파멸균
“8”:이산화염소가스멸균
“99”:기타string items[].sterilizationMethods[].name 멸균방법 string items[].sterilizationMethods[].etc 멸균방법 기타 멸균방법 string items[].isRcperSalaryTarget 요양급여대상여부 boolean items[].rcperSalarys 요양급여 정보 array items[].rcperSalarys[].order 요양급여정보 순번 number items[].rcperSalarys[].code 요양급여정보 재료대 코드 string items[].rcperSalarys[].name 요양급여정보 재료대 품목명 string items[].rcperSalarys[].mlsfcName 요양급여정보치료재료대중분류명 string items[].rcperSalaryCodeNoinputReas 요양급여 코드 미입력 사유 string items[].includeLatex 라텍스 포함 여부 boolean items[].includePhthalate 프탈레이트 포함 여부 boolean items[].mriSafeExpsrCode MRI 안전 노출 여부 코드
"1" : 안전
"2" : 안전하지 않음
"3" : 조건부 안전
"4" : 평가되지 않음
"5" : 해당사항 없음string items[].swVer 소프트웨어 버전 string items[].itemAddDescription 추가 설명 string items[].warnTabooDetail 비고(치명적인 경고 또는 금기사항) string items[].storageCond 저장조건 string items[].distbTreatCond 유통취급조건 string items[].managerTelNo 관리책임자 연락처 string items[].managerEmail 관리책임자 이메일 string items[].consumerStateCenterName 소비자센터 명칭 string items[].consumerStateCnterTelNo 소비자센터 연락처 string items[].registDate 최초 등록일 string - 응답예제
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8{
"items": [
{
"unityInfoRegistYn": true,
"rcperSalarys": [],
"managerTelNo": null,
"consumerStateCnterTelNo": "0435112111",
"distbTreatCond": null,
"consumerStateCenterName": "소비자센터",
"useItemSeq": false,
"itemAddDescription": "추가설명",
"meddevItemSeq": "20060048",
"useEndReason": "",
"includePhthalate": false,
"warnTabooDetail": "비고",
"sterilizationMethods": [
{
"code": "1",
"etc": "",
"name": "고압증기멸균",
"order": 1
},
{
"code": "99",
"etc": "알코올",
"name": "기타",
"order": 2
}
],
"unityInfoRegistComptDate": "2019-07-23",
"useTimeLimit": false,
"managerEmail": "test@xn--asdfasdf-6b5a4aj5d58f",
"swVer": "",
"codeSystemFlag": null,
"isSterilizationMeddev": true,
"storageCond": "",
"productItemInfo": {
"itemName": "탄력밴드",
"grade": "1",
"permitDate": "2006-10-27",
"meddevItemSeq": "20060048",
"isForExport": false,
"mebTypeName": "탄력밴드(JC-7500 SPEC)",
"meddevItemNo": "부산 제신 06-120 호",
"cobFlagCode": null
},
"packQuantity": 10,
"rcperSalaryCodeNoinputReas": "미입력",
"isRcperSalaryTarget": true,
"isUseEnd": false,
"useEndDate": null,
"mriSafeExpsrCode": "1",
"codeSystemName": "GS1",
"udiDiSeq": 1957,
"udiDiCode": "08811234787870",
"useManufYm": true,
"isSupplyHist": false,
"useLotNo": true,
"needSterilization": true,
"includeLatex": true,
"registDate": "2019-07-23"
}, ...
]7. UDI-DI 코드 및 통합정보 추가
모델별 UDI-DI 코드를 생성합니다. UDI-DI 코드를 등록하면 통합정보 일부 항목(허가정보 연계항목)이 함께 입력됩니다. 본 API의 매개변수로 쓰이는 값들은 [?]에서 확인할 수 있습니다.
7.1. Request
POST /api/v1/int-info/udidi-unity HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Content-Type: application/json;charset=UTF-8Access_token을 Authorization Header에 담아 요청 내용을 JSON string으로 만들어 POST 로
요청합니다.- 요청필드
키 설명 타입 meddevItemSeq 품목허가 일련번호 number mebTypeName 모델명 string udiDiCode UDI-DI 코드 string codeSystem UDI-DI 코드체계
GS1 / HIBCC / ICCBBA
string isForExport 수출용 여부
true / falseboolean - 예제
POST /api/v1/int-info/udidi-unity HTTP/1.1
Host: udiportal.mfds.go.kr
Authorization: Bearer {access_token}
Content-Type: application/json;charset=UTF-8
{
"codeSystem": "GS1",
"udiDiCode": "08811234787870",
"meddevItemSeq": 20060048,
"isForExport": false,
"mebTypeName": "탄력밴드(JC-7500 SPEC)"
}- 예제코드 (Java, Spring)
UriComponentsBuilder uriBuilder =
UriComponentsBuilder.fromHttpUrl( "https://udiportal.mfds.go.kr/api/v1/int-info/udidi-unity");
HttpHeaders headers = new HttpHeaders();
String accessToken = obtainAccessToken(clientId, clientSecret);
headers.add(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
headers.add(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_UTF8_VALUE);
Map<String, Object> body = new HashMap<>();
body.put("meddevItemSeq", 20060048); // 품목일련번호. number.
body.put("mebTypeName", "탄력밴드(JC-7500 SPEC)"); // 형명(모델명). string.
body.put("udiDiCode", "08811234787870"); // UDI-DI 코드. string.
body.put("codeSystem", "GS1"); // 코드구분. string. "GS1", "HIBCC", "ICCBBA"
body.put("isForExport", false); // 수출용 여부. boolean.
HttpEntity<Map<String, Object>> httpEntity = new HttpEntity<>(body, headers);ResponseEntity<String> responseEntity = restTemplate.exchange(uriBuilder.toUriString(),
HttpMethod.POST,
httpEntity,
String.class);
JSONObject response = new JSONObject(responseEntity.getBody());7.2. Response
추가된 UDI-DI 코드 및 통합정보가 반환됩니다.
- 응답코드
코드 설명 200 정상응답 400 입력값이 잘못되었을 경우 403 해당 정보에 접근 권한이 없을 경우 401 인증정보가 존재하지 않을 경우 500 처리 중 오류가 발생했을 경우 - 응답필드
키 설명 타입 udiDiSeq UDI-DI 일련번호 number productItemInfo 제품정보 object productItemInfo.meddevItemSeq 품목일련번호 number productItemInfo.itemName 품목명 string productItemInfo.grade 등급 string productItemInfo.meddevItemNo 품목허가번호 string productItemInfo.permitDate 품목허가일자 string productItemInfo.mebTypeName 형명(모델명) string productItemInfo.isForExport 수출용 여부 boolean productItemInfo.cobFlagCode 제조/수입 구분
- 제조 : MNFCTUR
- 수입 : INCMEstring meddevItemSeq 품목일련번호 number mebTypeSeq 형명(모델)일련번호 number udiDiCode UDI-DI 코드 string codeSystemFlag 구분코드 구분 string packQuantity 포장 내 수량 number isUseEnd 사용종료여부 boolean useEndDate 사용종료일자 string useEndReason 사용종료사유 string unityInfoRegisted 통합정보 등록 여부 boolean unityInfoRegistComptDate 통합정보 등록 완료일 string isSupplyHist 공급내역여부 boolean useLotNo 로트번호 사용 여부 boolean useItemSeq 일련번호 사용 여부 boolean useManufYm 제조연월 사용 여부 boolean useTimeLimit 사용기한 사용 여부 boolean isSterilizationMeddev 멸균의료기기여부 boolean needSterilization 사용전 멸균 필요 여부 boolean sterilizationMethods 멸균방법 array sterilizationMethods[].order 멸균방법 순번 number sterilizationMethods[].code 멸균방법코드
“1”:고압증기멸균
“2”:건열멸균
“3”:에틸렌옥사이드가스멸균
“4”:의료용포름알데이드가스멸균
“5”:의료용저온플라즈마멸균
“6”:냉액멸균
“7”:마이크로파멸균
“8”:이산화염소가스멸균
“99”:기타string sterilizationMethods[].name 멸균방법 string sterilizationMethods[].etc 멸균방법 기타 멸균방법 string isRcperSalaryTarget 요양급여대상여부 boolean rcperSalarys 요양급여 정보 array rcperSalarys[].order 요양급여정보 순번 number rcperSalarys[].code 요양급여정보 재료대 코드 string rcperSalarys[].name 요양급여정보 재료대 품목명 string rcperSalarys[].mlsfcName 요양급여정보치료재료대중분류명 string rcperSalaryCodeNoinputReas 요양급여 코드 미입력 사유 string includeLatex 라텍스 포함 여부 boolean includePhthalate 프탈레이트 포함 여부 boolean mriSafeExpsrCode MRI 안전 노출 여부 코드
"1" : 안전
"2" : 안전하지 않음
"3" : 조건부 안전
"4" : 평가되지 않음
"5" : 해당사항 없음string swVer 소프트웨어 버전 string itemAddDescription 추가 설명 string warnTabooDetail 비고(치명적인 경고 또는 금기사항) string storageCond 저장조건 string distbTreatCond 유통취급조건 string managerTelNo 관리책임자 연락처 string managerEmail 관리책임자 이메일 string consumerStateCenterName 소비자센터 명칭 string consumerStateCnterTelNo 소비자센터 연락처 string registDate 최초 등록일 string - 응답예제
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{"udiDiSeq":1956,"productItemInfo":null,"meddevItemSeq":"20060048","udiDiCode":"08801123487448","codeSystemFlag":null,"codeSystemName":"GS1","packQuantity":5,"useEndYn":false,"useEndDate":null,"
useEndReason":"","unityInfoRegistYn":true,"unityInfoRegistComptDate":"2019-07-24","isSupplyHist":false,"useLotNo":true,"useItemSeq":false,"useManufYm":false,"useTimeLimit":true,"isSterilizationMeddev":false,"needSterilization":true,"sterilizationMethods":[{"order":1,"code":"1","name":"고압증기멸균","etc":""},{"order":2,"code":"99","name":"기타","etc":"기타멸균방법명"}],"isRcperSalaryTarget":false,"rcperSalarys":[{"
order":1,"code":"1","name":"2","mlsfcName":"3"}],"rcperSalaryCodeNoinputReas":"요양급여대상이 아님.","includeLatex":true,"includePhthalate":false,"mriSafeExpsrCode":"1","swVer":"1.1","itemAddDescription":"","warnTabooDetail":"","storageCond":"상온보관","distbTreatCond":null,"managerTelNo":null,"managerEmail":"manager@example.com","consumerStateCenterName":"C/S센터","consumerStateCnterTelNo":"
0000000000","registDate":"2019-07-23"}- 오류 응답 예제 - 중복된 UDI-DI 코드
HTTP/1.1 400 BAD_REQUEST
Content-Type: application/json;charset=UTF-8
{"message":"Invalid Input","status":400,"errors":[{"field":"udiDiCode","value":"08811234787870","reason":"UDI-DI 코드가 '탄력밴드(JC-7500 SPEC)' (품목허가 '부산 제신 06-120 호') 와 중복됩니다"}]}- 오류 응답 예제 - UDI-DI 코드 정합성 오류
HTTP/1.1 400 BAD_REQUEST
Content-Type: application/json;charset=UTF-8
{"message":"Invalid Input","status":400,"errors":[{"field":"udiDiCode","value":"998811234787870","reason":"코드는 13자리 또는 14자리여야 합니다"}]}추가 내용은 첨부파일에서 확인하여 주시기 바랍니다.
연관 콘텐츠
-
- 연관 콘텐츠가 존재하지 않습니다.
