의료기기 통합정보시스템 공개 API 활용 방법

2022-07-27
  • 의료기기 표준코드(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자리여야 합니다"}]}

     

     

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

     

연관 콘텐츠

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