無害化結果応答

SHIELDEX File 6.0無害化 API 連携時結果応答フィールドを定義します。

• 本文構成: 同期結果 → 非同期(受付・状態照会・コールバック) → 共通フィールド(code / detailCode / server)

---

1. 結果受信方式概要

区分	方式	エンドポイント	結果受信時点
同期	Sync	POST /v5/cdr-sync	リクエスト応答で最終結果を即時受信
非同期	受付	POST /v5/cdr	即時受付応答万返却（結果ではない）
非同期	状態照会（ポーリング）	GET /v5/cdr/{jobID}	周期照会（推奨 200ms）後、完了時結果応答
非同期	コールバック(Callback)	リクエスト時result.callbackURL指定	完了時に指定されたURLに結果 PUSH

受付応答 ≠ 結果応答非同期POST /v5/cdrの即時応答は受領確認(code · msg · jobID)だけです。実際の無害化結果は動機(/v5/cdr-sync) または状態照会·コールバックで受け取ります。

---

2. 動機 — 結果 応答 (POST /v5/cdr-sync)

同期APIはサーバーが無害化完了まで待機した後最終結果を一度に返します。code: 3(進行中)は返されず、実際の受信コードは0 / 1 / 2です。

2.1 応答フィールド

KEY	TYPE	必須	説明
jobID	String	必須	作業 ID
code	int	必須	結果等級コード (§5) — 同期では0 / 1 / 2万受信
msg	String	必須	結果理由メッセージ (=logReasonの理由テキスト)
logReason	int	必須	詳細結果（ログリズン）コード
detailCode	int	選択	付加分類値 (§6).連動協議で活性化された場合にのみ含む
server	Object	必須	ファイルを処理したサーバー情報 (§7)

2.2 detailCode特別な例

以下の例は同期(/v5/cdr-sync) · ステータス照会結果応答に共通して適用されます。serverオブジェクトはすべての例で同じ形です。

detailCode: 0— リスク要素なし (安全)

{
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
  "code": 0,
  "msg": "[안전] 컨텐츠 요소 없음",
  "logReason": 200004,
  "detailCode": 0,
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

detailCode: 1— リスク要因あり (疑い · 警告 · 危険 · 偽造)

{
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
  "code": 0,
  "msg": "[의심] 컨텐츠 요소 감지",
  "logReason": 200005,
  "detailCode": 1,
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

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

detailCode: 2— ワクチン（ウイルス）検出

{
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
  "code": 2,
  "msg": "[심각] 바이러스 검출 (감염 파일 삭제)",
  "logReason": 990003,
  "detailCode": 2,
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

detailCode: 3— 未サポートファイル (例外 · ブロック)

{
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
  "code": 2,
  "msg": "[차단] 미지원 확장자",
  "logReason": 210211,
  "detailCode": 3,
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

detailCode: -1— エラー

{
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
  "code": 2,
  "msg": "[오류] 인터페이스 통신 오류",
  "logReason": 900052,
  "detailCode": -1,
  "server": {
    "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
    "serverName": "SANITIZE-NODE-01",
    "ipList": ["10.10.12.226"],
    "macList": ["00:50:56:aa:41:ec"]
  }
}

核心: detailCode: -1はエラーを意味します。ログリズンマスターのlogtype_id=V20(エラー)に該当する多数のログリズンを個別の値に分けずに、共通で -1ロ統合処理します。どのエラーなのかの詳細な理由はlogReason / msgで確認します。

---

3. 非同期 — 受付応答 (POST /v5/cdr)

非同期リクエストの即時応答です。無害化結果ではないため detailCode · server は含まれていません。

KEY	TYPE	説明
code	int	受付コード (0受け付け成功 /1重複リクエスト /2ブロック /3サービス接続失敗 /5アクセス制御ブロック)
msg	String	受付メッセージ
jobID	String	作業 ID

{
  "code": 0,
  "msg": "success",
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e"
}

受付後の結果は**状態照会(§4)またはコールバック(§4.2)**で受信します。

---

4. 非同期 — 結果受信 (状態照会 · コールバック)

4.1 ステータス確認 (GET /v5/cdr/{jobID})

応答フィールド·の意味は**動機結果(§2)**と同じです。処理が終了していない場合code: 3(進行中)が返される可能性があります。

KEY	TYPE	必須	説明
jobID	String	必須	作業 ID
code	int	必須	結果等級コード (§5) —0 / 1 / 2 / 3(進行中)
msg	String	必須	結果理由メッセージ
logReason	int	必須	詳細結果（ログリズン）コード
detailCode	int	選択	付加分類値 (§6, 活性時のみ)
server	Object	必須	処理サーバー情報 (§7) — 結果応答に含まれる

detailCode別の JSON の例については §2.2 を参照してください。

4.2 コールバック（Callback）結果全文

リクエスト時result.callbackURLを指定すると、無害化完了時に該当URLに結果がPUSHされます。同期・状態照会応答とフィールド表記だけが一部異なります(値の意味は同じです)。

• 結果理由テキストを別フィールドlogReasonMsgロを提供します。
• msgは"success" 固定です(理由テキストはlogReasonMsgに 담김).

KEY	TYPE	説明
jobID	String	作業 ID
code	int	結果等級コード (§5)
detailCode	int	付加分類値 (§6, 活性時のみ)
logReason	int	詳細結果（ログリズン）コード
logReasonMsg	String	詳細結果理由テキスト
msg	String	"success"固定
server	Object	処理サーバー情報 (§7)

{
  "jobID": "ed43f9a5-8caa-11f1-a4cd-f5c4fa6d387e",
  "code": 0,
  "detailCode": 0,
  "logReason": 200004,
  "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"]
  }
}

detailCode 0~3 · -1意味とマッピングは §2.2 · §6 と同じです。

---

5. 結果code定義

code	意味	ダウンロード	性格
0	無害化成功（完了）	可能	最終
1	ポリシーによる原本ファイルの持ち込み	可能	最終
2	持ち込み禁止 / システム・エンジンエラー	不可能	最終
3	処理進行中	—	未完了(ポーリング専用)

• 動機(/v5/cdr-sync**)**は完了まで待機して返すため、実際の受信コードは0 / 1 / 2です。3(進行中)は返されません。
• code1つに多数のlogReasonこのマッピングです(1:N). 連動分岐は必ず code 値を基準として、logReason(msg）は詳細な理由の識別・ユーザー案内・ログ記録の目的で使用してください。
• 状態照会APIでは結果ではなく照会制御応答作業 ID がありません(-3), 無効なリクエスト(5)が返される可能性があります。

---

6. detailCode— 追加分類値

code(0/1/2)だけでは詳細な分岐が難しい連携のための整数附加分類値です。

**アクティブな連携でのみ応答に含まれます。**非アクティブ時にはフィールド自体が応答に現れないため、既存の規格と100%同じです。活性化の有無は連携時に協議します。

detailCode	意味	代表例 (logReason)
-1	エラー —logtype_id=V20ログリズンを共通 -1統合	900052等 V20(エラー) 系列多数
0	危険要素なし (安全)	200004[安全] コンテンツ要素なし
1	危険要素あり（疑い・警告・危険・偽造）	200005~`200007,220355` 等
2	ワクチン（ウイルス）検出	990003[深刻] ウイルス検出
3	未対応ファイル (例外 · ブロック)	210211, 230213, 240215

産出基準（要約）— 結果ログリズンとリスク道路を判定します。

• 明示的マッピング:200004→0, 200005~`200007/220355 등→1, 990003→2, 210211/230213/240215(미지원)→3`
• 'ファイル再構成完了'200000/200001）はリスクに応じて0(安全)/1(疑い・警告・危険・偽造)/2(深刻) と判定
• エラー(logtype_id=V20にシステム·エンジンエラー該当する多数のログリズン → 共通 detailCode: -1

全体のJSON例は§2.2を参照してください。

---

7. server— 処理サーバー情報

無害化実際に処理したサーバーを識別できるように結果応答に含まれます。

KEY	TYPE	説明
serverId	String	処理サーバーID
serverName	String	サーバ名
ipList	String[]	サーバー代表IP (1個)
macList	String[]	代表IPに対応するMACアドレス（1つ）

"server": {
  "serverId": "A64B2A42-99AF-CF00-29C1-366B9CCFE002",
  "serverName": "SANITIZE-NODE-01",
  "ipList": ["10.10.12.226"],
  "macList": ["00:50:56:aa:41:ec"]
}

• ipList · macListはサーバーの代表 IP/MAC 1組全てのNICリストではありませんが、含まれています。
• サーバー情報が見つからない場合serverId満たしてserverNameは空の文字列、ipList · macListは空の配列([])に応答します。
• 非同期**受付応答(§3)**にはserverが含まれていません。

---