CDR無害化リクエスト

SHIELDEX CDRの無害化リクエストに使用します。
非同期で動作し、リクエストをキューに挿入した後、即座に応答します。
検査結果は別の状態照会APIまたはCallbackを通じて確認できます。

Important Notes

• Protocol: HTTP Form送信方式(multipart/form-data)を使用します。
• Encoding: すべてのテキストデータはUTF-8にエンコードされる必要があります。
• Callback: コールバック URL はresult.callbackURLフィールドに設定し、無害化が完了した後に結果を受け取ることができます。
• Job ID Length: 最大36文字まで許可されており、超過した場合はバリデーションエラーとして処理されます。

---

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",
    "sysCode": "string",
    "businessCode": "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.sysCode	String	No	チャンネルコード、APIアクセス制御に使用されます。（最大40文字）
userinfo.businessCode	String	No	業務コード、APIアクセス制御に使用されます。（最大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アクセス制御によりリクエストがブロックされました。
-1	エラーメッセージ	サーバーリクエスト処理失敗

---

Sample

REQUEST - Upload Type

curl -X POST "{{url}}/v5/cdr" \
  -H "Content-Type: multipart/form-data" \
  -F 'data={
    "request": {
      "type": "upload"
    },
    "userinfo": {
      "id": "user001",
      "name": "홍길동",
      "department": "개발팀",
      "dutyname": "개발자",
      "sysCode": "SYS001",
      "businessCode": "BIZ001"
    },
    "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"
}

:::info[参考 -code5 (APIアクセス制御)] 上記の応答はHTTP 200しかし、本文codeが5の場合であり、APIアクセス制御によって無害化リクエストがブロックされた場合です。

1. コード登録 (事前準備)

• メニュー:設定 → API アクセス制御 → コード登録
• 呼び出しに使用するチャンネルと業務を登録します。
• リクエストdataのuserinfo.sysCodeには登録したチャンネルコード, userinfo.businessCodeには登録した業務コードを入れます。(サンプルのSYS001, BIZ001は実際の登録値に合わせて変更します。)
• テスト時に2つの値はコード登録に登録した値と必ず一致正常に受け付ける必要があります(__PH_0__)code: 0)になります。

2. アクセス制御ログ (ブロック・許可確認)

• メニュー:設定 → API アクセス制御 → アクセス制御ログ
• リストから該当するリクエスト（またはjobID·タイムゾーンに合った行を見つけます。
• API申請状況列: 申請・承認などのAPI使用申請が反映されているか確認します。
• 制御状態列:ブロック認知許可認識を確認します。ブロックされている場合はアクセス制御ポリシーによって遮断されており、許可されている場合のみリクエストが通過します。

---

Callback

リクエスト時result.callbackURLフィールドにURLを入力した場合、無害化処理が完了すると、そのURLに結果を送信します。
状態照会APIまたはCallbackで無害化結果を受け取ることができます

Callback API JSON

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

{
     "jobID": "test-job-001",
     "code": 2,
     "msg": "success",
     "logReason": 220355,
     "logReasonMsg": "[차단] 확장자 위변조 파일 차단"
}

---

Processing Flow

• ここからは外部に公開してはいけない、開発情報です。

---