無害化リクエスト

SHIELDEX CDR 無害化リクエストのために使用します。

非同期で動作し、リクエストをキューに挿入した後、即座に応答します。

検査結果は別の状態照会APIまたはCallbackを通じて確認できます。

備考

Important Notes

Protocol: HTTPフォーム送信方式(multipart/form-data)を使用します。

Encoding: すべてのテキストデータはUTF-8でエンコードされる必要があります。

Callback: コールバック URL はresult.callbackURLフィールドに設定し、無害化完了後に結果を受け取ることができます。

Job ID Length: 最大36文字まで許可されており、超過した場合は有効性検査に失敗します。

Authentication : Authorization: Bearer <API-KEY>ヘッダーで連携システムを識別します。APIキーはウェブコンソール → ポリシー → 連携システムポリシーから発行できます。 :::

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キーを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​