본문으로 건너뛰기

무해화 요청 - 동기방식

파일을 SHIELDEX 서버로 전송하여 무해화(CDR)를 요청하는 API입니다.

정보

Important Notes

  • Encoding : 모든 텍스트 데이터는 UTF-8로 인코딩되어야 합니다.
  • Callback : 콜백 URL은 result.callbackURL 필드에 설정하며, 무해화 완료 후 결과를 받을 수 있습니다.
  • Job ID Length : 최대 36자까지 허용되며, 초과시 유효성 검사 실패로 처리됩니다.
  • Authentication : Authorization: Bearer <API-KEY> 헤더로 연동 시스템을 식별합니다. API Key는 웹콘솔 → 정책 → 연동 시스템 정책에서 발급 가능합니다.

1. API 개요​

1.1 API 목록​

방식MethodAPI설명
동기POST/v5/cdr-sync무해화가 완료된 후 최종 결과를 반환합니다.

Base URL

http://{IP 또는 도메인}:{PORT}
항목내용
기본 포트8060 (환경에 따라 80 포트로 구성될 수 있습니다)
인코딩UTF-8

1.2 연동 방식 (request.type)​

파일 전달 방법을 요청 전문의 request.type 으로 선택합니다.

항목uploadshared
파일 전달요청 전문(JSON)과 파일을 multipart/form-data 로 함께 전송요청 전문(JSON)만 전송
사전 준비HTTP 통신만 가능하면 연동양측 서버 간 공유 폴더(NFS) 구성 필요
결과 파일GET /v5/download/{jobID}SD_OUT 폴더 또는 GET /v5/download/{jobID}

2. 인증 및 접근제어​

모든 요청은 Authorization 헤더에 API Key를 Bearer 토큰 형식으로 담아 호출합니다.

Authorization: Bearer <API-KEY>

2.1 API Key 인증​

항목내용
전달 위치HTTP Request Header Authorization
발급 위치SHIELDEX 웹콘솔 > 정책 > 연동 시스템 정책 화면에서 발급 및 조회 가능

2.2 인증 실패 응답​

상황HTTP Status응답 메시지
API Key 무효401 UnauthorizedThe API Key is invalid. Please verify the API Key.
연동 시스템 미존재401 UnauthorizedThe associated system was not found for this API Key.

3. 무해화 요청​

3.1 API 정보​

# 동기
POST /v5/cdr-sync
POST /v5/cdr-sync/{jobID}

3.2 HTTP Form 전송 방식 API​

Request Path Parameter

Field

Type

Required

Description

jobID

String

N

  • 무해화 작업 1건의 고유 식별자. 결과 조회·파일 다운로드에 동일하게 사용합니다. 미입력 시 서버가 자동 생성하여 응답에 담아 반환합니다.

  • 최대 36자 · 중복 불가 · 예)202308034b5a9049b9a73

Request Parts (multipart/form-data)

Part

Type

Required

Description

data

JSON

Y

  • 무해화 요청 전문 (요청자 정보 · 파일 정보 · 결과 통지 방법)

  • Content-Type application/json

file

File

Y

  • 무해화 대상 파일 본체.

  • 파일명은 fileinfo.filename 과 동일

Request Data JSON Structure

{
  "request": {
    "type": "upload",
    "id": "BATCH-20260818-001"
  },
  "userinfo": {
    "id": "user001",
    "name": "홍길동",
    "department": "개발팀",
    "dutyname": "책임연구원"
  },
  "fileinfo": {
    "filename": "2026_사업계획.hwp"
  },
  "result": {
    "callbackURL": "https://your-callback-url.com/callback"
  }
}

Request Data Fields

FieldTypeRequiredDescription
request.typeString==Y==파일 전달 방식 - ==upload==
request.idStringN작업 그룹 ID. 여러 jobID를 하나의 작업으로 묶는 상위 식별자이며, 최대 36자입니다.
userinfo.idString==Y==요청 사용자의 고유 식별 ID. 로그 추적과 사용자별 정책 적용의 기준값입니다.
userinfo.nameStringN사용자 이름
userinfo.departmentStringN사용자 부서명
userinfo.dutynameStringN사용자 직급·직책명
fileinfo.filenameString==Y==무해화 대상 파일명(확장자 포함). multipart file의 파일명과 동일해야 합니다.
result.callbackURLStringN무해화 처리 결과가 callback일 경우 사용 ( 해당 URL 로 “무해화 결과” 전문 전송 )

REQUEST Sample

curl -X POST "http://{IP}:8060/v5/cdr-sync" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: multipart/form-data" \
  -F 'data={
    "request": {
      "type": "upload",
      "id": "BATCH-20260818-001"
    },
    "userinfo": {
      "id": "user001",
      "name": "홍길동",
      "department": "개발팀",
      "dutyname": "책임연구원"
    },
    "fileinfo": {
      "filename": "test.pdf"
    },
    "result": {
      "callbackURL": "https://your-callback-url.com/callback"
    }
  };type=application/json' \
  -F "file=@/path/to/test.pdf"

RESPONSE — 무해화 결과 (200 OK)

동기 방식은 무해화가 완료된 후 최종 결과를 반환합니다.

{
  "jobID": "test-job-001",
  "code": 0,
  "detailCode": 0,
  "logReason": 200000,
  "logReasonMsg": "파일 재구성 완료",
  "msg": "success"
}

3.3 폴더 공유 방식 API​

Request Path Parameter

Field

Type

Required

Description

jobID

String

N

  • 무해화 작업 1건의 고유 식별자. 결과 조회·파일 다운로드에 동일하게 사용합니다. 미입력 시 서버가 자동 생성하여 응답에 담아 반환합니다.

  • 최대 36자 · 중복 불가 · 예)202308034b5a9049b9a73

Request Parts (multipart/form-data)

Part

Type

Required

Description

data

JSON

Y

  • 무해화 요청 전문 (요청자 정보 · 파일 정보 · 결과 통지 방법)

  • Content-Type application/json

file

File

N

  • shared 방식은 전송하지 않습니다.

Request Data JSON Structure

{
  "request": {
    "type": "shared",
    "id": "260622guid12345"
  },
  "userinfo": {
    "id": "user001",
    "name": "홍길동",
    "department": "개발팀",
    "dutyname": "책임연구원"
  },
  "fileinfo": {
    "filename": "57dac8bb-5324-11f1-939c-23ad1125b146.xlsx",
    "subDir": "/subPath1/subPath2/subPath3"
  },
  "result": {
    "callbackURL": "https://your-callback-url.com/callback"
  }
}

Request Data Fields

FieldTypeRequiredDescription
request.typeString==Y==파일 전달 방식 - ==shared==
request.idStringN작업 그룹 ID. 여러 jobID를 하나의 작업으로 묶는 상위 식별자이며, 최대 36자입니다.
userinfo.idString==Y==요청 사용자의 고유 식별 ID. 로그 추적과 사용자별 정책 적용의 기준값입니다.
userinfo.nameStringN사용자 이름
userinfo.departmentStringN사용자 부서명
userinfo.dutynameStringN사용자 직급·직책명
fileinfo.filenameString==Y==무해화 대상 파일명(확장자 포함). ==중복되지 않는 파일명 필수==
fileinfo.subDirStringN“폴더 공유 방식” 사용하는 경우, 옵션 값으로 사용 할 수 있습니다. subDir 값을 사용하는 경우, 무해화 요청 시에 jobID 값 전달이 반드시 필요합니다. - POST /v5/cdr/=={jobID}==
result.callbackURLStringN무해화 처리 결과가 callback일 경우 사용 ( 해당 URL 로 “무해화 결과” 전문 전송 )

REQUEST Sample

파일을 SD_IN 에 복사한 뒤 file 파트 없이 전문만 전송합니다.

curl -X POST "http://{IP}:8060/v5/cdr-sync" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: multipart/form-data" \
  -F 'data={
    "request": { "type": "shared" },
    "userinfo": { "id": "user001" },
    "fileinfo": { "filename": "57dac8bb-5324-11f1-939c-23ad1125b146.xlsx", "subDir": "/subPath1/subPath2/subPath3" }
  };type=application/json'

RESPONSE — 무해화 결과 (200 OK)

동기 방식은 무해화가 완료된 후 최종 결과를 반환합니다.

{
  "jobID": "test-job-001",
  "code": 0,
  "detailCode": 0,
  "logReason": 200000,
  "logReasonMsg": "파일 재구성 완료",
  "msg": "success"
}