본문영역 바로가기 메인메뉴 바로가기 하단링크 바로가기

식품의약품안전처 의료기기정보포털 로고

이 웹사이트는 대한민국 공식 의료기기정보포털 웹사이트 입니다.    

  • 네이버 블로그 바로가기
  • 인스타그램 바로가기
  • 유튜브 바로가기
  • 페이스북 바로가기
  • 트위터 바로가기
udi 표준코드 검색
검색
검색창 닫기

의료기기정책

의료기기 통합정보시스템 공개 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자리여야 합니다"}]}

 

 

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

 

연관 콘텐츠

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