의료기기정책 > 알기쉬운 의료기기 제도

의료기기정책

알기쉬운 의료기기 제도

의료기기정책

알기쉬운 의료기기 제도

의료기기 통합정보시스템 공개 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-8

Access_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-8

Access_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 - 수입 : INCME	string
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-8

Access_token을 Authorization Header에 담아 요청 내용을 JSON string으로 만들어 POST 로
요청합니다.

요청필드

키	설명	타입
meddevItemSeq	품목허가 일련번호	number
mebTypeName	모델명	string
udiDiCode	UDI-DI 코드	string
codeSystem	UDI-DI 코드체계 GS1 / HIBCC / ICCBBA	string
isForExport	수출용 여부 true / false	boolean

예제

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 - 수입 : INCME	string
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자리여야 합니다"}]}

추가 내용은 첨부파일에서 확인하여 주시기 바랍니다.

PUBLIC-API-매뉴얼_V1.9.pdf

의료기기 통합정보시스템 제도안내

식품의약품안전처 규제혁신 사례집

연관 콘텐츠

연관 콘텐츠가 존재하지 않습니다.