무해화 요청

SHIELDEX CDR 무해화 요청을 위해 사용합니다.

비동기로 동작하며, 요청을 대기열에 삽입한 뒤, 즉시 응답합니다.

검사 결과는 별도의 상태 조회 API 또는 Callback을 통해 확인할 수 있습니다.

정보

Important Notes

Protocol : HTTP Form 전송 방식(multipart/form-data)을 사용합니다.

Encoding : 모든 텍스트 데이터는 UTF-8로 인코딩되어야 합니다.

Callback : 콜백 URL은 result.callbackURL 필드에 설정하며, 무해화 완료 후 결과를 받을 수 있습니다.

Job ID Length : 최대 36자까지 허용되며, 초과시 유효성 검사 실패로 처리됩니다.

Authentication : Authorization: Bearer <API-KEY> 헤더로 연동 시스템을 식별합니다. API Key는 웹콘솔 → 정책 → 연동 시스템 정책에서 발급 가능합니다. :::

Authentication

무해화 요청 시 연동 시스템 식별을 위해 Authorization 헤더에 API Key를 포함합니다.

항목	값
Header	`Authorization: Bearer <API-KEY>`
발급 위치	웹콘솔 → 정책 → 연동 시스템 정책 → 연동 시스템 등록 시 자동 발급

Authentication Flow

웹콘솔에서 연동 시스템을 등록하면 API Key가 자동 발급됩니다.
(선택) 연동 시스템에 허용 IP를 등록하면, 해당 IP에서만 요청이 가능합니다.
무해화 요청 시 Authorization: Bearer <발급받은 API Key> 헤더를 포함합니다.
서버가 API Key로 연동 시스템을 자동 식별합니다.

IP Whitelist

API Key에 허용 IP가 등록된 경우, 등록되지 않은 IP에서의 요청은 차단됩니다.
허용 IP가 없으면 전체 허용(기본 동작)입니다.

Method

POST /v5/cdr
/v5/cdr/{jobID}

Request Path Parameter

KEY	OBJECT	DESC
jobID	String	작업 ID (선택사항, 미입력 시에 시간 기반 UUID가 자동 생성됩니다. 최대 36자)

Request Parts (multipart/form-data)

KEY	OBJECT	DESC
data	JSON	무해화 요청 데이터 (필수)
file	File	무해화 대상 파일 (필수)

Request Data JSON Structure

{
  "request": {
    "type": "upload"
  },
  "userinfo": {
    "id": "string",
    "department": "string",
    "name": "string",
    "dutyname": "string"
  },
  "fileinfo": {
    "filename": "string"
  },
  "result": {
    "callbackURL": "string"
  }
}

Request Data Fields

KEY	OBJECT	REQUIRED	DESC
request.type	String	Yes*	요청 타입 (`upload` 고정)
userinfo.id	String	Yes	사용자 ID (최대 40자)
userinfo.department	String	No	사용자 부서 (최대 256자)
userinfo.name	String	No	사용자 이름 (최대 40자)
userinfo.dutyname	String	No	사용자 직책명 (최대 40자)
userinfo.userNumber	Number	No	사용자 번호
fileinfo.filename	String	Yes*	파일명 (multipart 파일의 이름과 동일해야 함)
result.callbackURL	String	No	콜백 URL (결과 통지용)

Response Body (json)

KEY	OBJECT	DESC
code	int	응답 코드 (아래 테이블 참조)
msg	String	응답 메시지
jobID	String	작업 ID (검사 결과 조회 시 사용)

Response Code

CODE	MESSAGE	DESC
0	success	무해화 요청이 정상적 접수되었습니다. 무해화 결과는 상태조회 API로 확인하세요.
1	중복	무해화 요청 동일 요청 발생 (jobID 중복)
2	차단 메시지	차단 (유효성 검사 실패, 파일 생성 실패)
3	unavailable agent service	무해화 서비스 연결 실패
5	Sanitization Request Blocked by API Access control.	API 접근제어에 의해 요청이 차단되었습니다.

Sample

REQUEST - Upload Type

curl -X POST "{{url}}/v5/cdr" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer your-api-key-here" \
  -F 'data={
    "request": {
      "type": "upload"
    },
    "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)

{
  "code": 0,
  "msg": "success",
  "jobID": "test-job-001"
}

RESPONSE - 서비스 연결 실패 (200 OK)

{
  "code": 3,
  "msg": "unavailable agent service",
  "jobID": "test-job-001"
}

RESPONSE - 필수 필드 누락 (400 BAD_REQUEST)

{
  "timestamp": 1767768931518,
  "status": 400,
  "error": "Bad Request",
  "message": "400 BAD_REQUEST \"Invalid or missing fields in JSON: 'request.type'\"",
  "path": "/v5/cdr"
}

RESPONSE - 파일 필드 누락 (400 BAD_REQUEST)

{
  "code": 2,
  "msg": "Missing required file: 'file', The request must include a file upload in the 'file' field.",
  "jobID": "test-job-001"
}

RESPONSE - Access Denied (200 OK)

{
  "code": 5,
  "msg": "Sanitization Request Blocked by API Access control.",
  "jobID": "test-job-001"
}

RESPONSE - API Key 인증 실패 (401 Unauthorized)

{
  "code": 5,
  "msg": "The API Key is invalid. Please verify the API Key.",
  "jobID": ""
}

RESPONSE - IP 차단 (403 Forbidden)

{
  "code": 5,
  "msg": "Access denied. IP address 10.10.1.50 is not in the allowed list for this API Key.",
  "jobID": ""
}

경고

참고 - code 5 (API 접근 제어)

위 응답은 HTTP 200이지만, 본문 code가 5일 때이며 API 접근 제어에 의해 무해화 요청이 차단된 경우입니다.

1. 연동 시스템 등록 (사전 준비)

메뉴: 정책 → 연동 시스템 정책 → 연동 시스템 등록

연동할 외부 시스템을 등록하면 API Key가 자동 발급됩니다.

발급된 API Key를 Authorization: Bearer 헤더에 포함하여 요청합니다.

(선택) 허용 IP를 등록하면 해당 IP에서만 요청이 가능합니다.

2. 접근 제어 로그 (차단·허용 확인)

메뉴: 로그 → API 요청 로그

목록에서 해당 요청(또는 jobID·시간대)에 맞는 행을 찾습니다.

제어 상태 열: 차단인지 허용인지 확인합니다.

차단이면 접근 제어 정책에 의해 막힌 것이고, 허용일 때만 요청이 통과합니다. :::

Callback

요청 시 result.callbackURL 필드에 URL을 입력한 경우, 무해화 처리가 완료되면 해당 URL로 결과를 전송합니다.

상태 조회 API 또는 Callback으로 무해화 결과를 전달받을 수 있습니다.

결과 응답 전체 규격은 무해화 응답 (결과 규격) 문서를 참고하세요. 콜백 전문에는 부가 분류값 detailCode(연동 협의로 활성화 시)와 처리 서버 정보 server 가 함께 전송됩니다. 콜백 전문의 msg 는 "success" 고정이며, 결과 사유 텍스트는 logReasonMsg 로 전달됩니다.

Callback API JSON

{
  "jobID": "test-job-001",
  "code": 0,
  "detailCode": 0,
  "logReason": 200000,
  "logReasonMsg": "파일 재구성 완료",
  "msg": "success",
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

{
  "jobID": "test-job-001",
  "code": 2,
  "detailCode": 1,
  "logReason": 220355,
  "logReasonMsg": "[차단] 확장자 위변조 파일 차단",
  "msg": "success",
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

Authentication​

Authentication Flow​

IP Whitelist​

Method​

Request Path Parameter​

Request Parts (multipart/form-data)​

Request Data JSON Structure​

Request Data Fields​

Response Body (json)​

Response Code​

Sample​

REQUEST - Upload Type​

RESPONSE - 무해화 요청 성공 (200 OK)​

RESPONSE - 서비스 연결 실패 (200 OK)​

RESPONSE - 필수 필드 누락 (400 BAD_REQUEST)​

RESPONSE - 파일 필드 누락 (400 BAD_REQUEST)​

RESPONSE - Access Denied (200 OK)​

RESPONSE - API Key 인증 실패 (401 Unauthorized)​

RESPONSE - IP 차단 (403 Forbidden)​

Callback​

Callback API JSON​