SHIELDEX 정책 연동 API 명세서

문서 정보

항목	내용
문서 버전	`6.2026.0211.05`
작성	소프트캠프
Content-Type	`application/json`

환경 설정 (필수)

IP 허용 사전 협의 필요

본 API는 IP 기반 접근 제어가 적용됩니다.
API를 사용하시려면 고객사의 접근 출발지 IP 주소를 사전에 소프트캠프에 전달해야 합니다.

고객사 측 준비 사항

API를 호출할 서버/시스템의 아래 정보를 전달해 주세요.

전달 정보

접근 출발지 IP 주소 (예: 192.168.1.50, 10.10.12.100)
용도 (예: 보안 포탈 서버, 배치 작업 서버)

소프트캠프 엔지니어 설정 방법

SHIELDEX 서버의 WebConsoleApi.properties 파일에 허용 IP를 등록합니다.

설정 파일 위치

{SHIELDEX 설치 경로}/config/WebConsoleApi.properties

IP 허용 설정

설정 키	설명	예시
`security.ip.allowed`	무토큰 호출 허용 IP 화이트리스트 (콤마 구분)	`10.10.12.43,10.10.12.44`

중요

허용 목록(security.ip.allowed)에 없는 IP에서 요청하면 차단되며, 아래와 같이 응답됩니다.

{
  "timestamp": "2026-02-11T06:12:33.739+0000",
  "status": 403,
  "error": "Forbidden",
  "message": "IP_ACCESS_DENIED",
  "path": "/WebConsoleApi/policy/targets"
}

status: 403
error: Forbidden
message: IP_ACCESS_DENIED

설정 변경 후에는 반드시 SHIELDEX WebConsole 서비스 재시작이 필요합니다.

Base URL

http://{serverIp}:{serverPort}/WebConsoleApi

모든 API 경로는 위 Base URL 뒤에 붙여서 호출합니다.

예시 — 서버 IP가 10.10.12.100, 포트가 9000인 경우:

http://10.10.12.100:9000/WebConsoleApi/policy/targets/merged/preview/user001

API 리소스 맵

본 문서에서 제공하는 API 목록입니다.

Base URL: http://{serverIp}:{serverPort}/WebConsoleApi

/policy/targets
├── GET    /policy/targets/merged/preview/{targetId}   # 정책 통합 조회
├── PATCH  /policy/targets                             # 정책 부분 업데이트
└── DELETE /policy/targets                             # 정책 선택 삭제

Method	URI	설명
GET	`/policy/targets/merged/preview/{targetId}`	전사+개별 정책을 병합한 전체 조회
PATCH	`/policy/targets`	요청한 정책만 추가/수정 (기존 유지)
DELETE	`/policy/targets`	요청한 정책만 해제 (상위 정책으로 복원)

1. 공통 규칙

1.1 응답 구조

모든 API 응답은 아래 형식을 따릅니다.

{
  "code": 0,
  "codeMessage": "SUCCESS",
  "data": { }
}

필드	타입	설명
`code`	`Integer`	처리 결과 코드
`codeMessage`	`String`	처리 결과 메시지
`data`	`Object`	응답 데이터 (GET 조회 시 반환, PATCH/DELETE 시 생략 가능)

1.2 응답 코드 정의

code	codeMessage	설명	HTTP Status
`0`	`SUCCESS`	정상 처리 완료	`200`
`1`	`FAIL`	처리하지 못함	`200`
`4000`	`INVALID_REQUEST`	잘못된 요청 (필수값 누락, 유효성 위반, 본문 형식/Content-Type 오류 등)	`400`
`4404`	`VALUE_NOT_FOUND`	존재하지 않는 대상 (targetId, policyId 등)	`404`
`5000`	`INTERNAL_ERROR`	서버 내부 오류	`500`

1.3 Timestamp 규칙

단위 주의: epoch milliseconds (13자리)

모든 timestamp 필드는 epoch milliseconds (1/1000초) 단위입니다.
Unix epoch seconds(10자리)가 아닙니다. 자릿수를 반드시 확인하세요.

epoch seconds     : 1761523200        (10자리) ← 이 단위가 아닙니다
epoch milliseconds: 1761523200000     (13자리) ← 이 API에서 사용하는 단위

Timestamp 관련 필드

필드	타입	방향	설명
`startTimestamp`	`Long` (int64)	입력/출력	정책 적용 시작 시각 (epoch ms, UTC). 생략 시 즉시 적용
`endTimestamp`	`Long` (int64)	입력/출력	정책 적용 종료 시각 (epoch ms, UTC). 생략 시 무기한
`startTimestampText`	`String`	출력 전용	KST 변환 날짜 (예: `2025-12-04 09:52:33`)
`endTimestampText`	`String`	출력 전용	KST 변환 날짜. 무기한이면 `null`

변환 코드 예시

// JavaScript
const start = Date.now();                                        // 1761523200000
const end   = new Date('2026-03-01T00:00:00Z').getTime();        // 1772092800000

// Java
long start = System.currentTimeMillis();
long end   = Instant.parse("2026-03-01T00:00:00Z").toEpochMilli();

유효성 규칙

둘 다 지정 시 endTimestamp가 startTimestamp보다 커야 합니다 (위반 시 400 INVALID_REQUEST)
둘 다 생략하면 즉시 적용, 무기한

1.4 정책 우선순위

정책 값은 아래 우선순위로 결정됩니다. 상위가 존재하면 하위를 override합니다.

사용자 개별 정책 (User)  ← 최우선
  ↓
소속 그룹 정책 (Group)
  ↓
전사 기본 정책 (Default)  ← 최하위

1.5 오버라이드 정보

조회 응답의 각 정책 항목에 포함되는 필드입니다. 해당 정책이 어디서 설정되었는지 알 수 있습니다.

필드	타입	설명
`overridden`	`Boolean`	개별 정책이 적용된 경우 `true`, 전사 기본값이면 `false`
`overriddenBy`	`String`	정책 출처: `"user"` / `"group"` / `"default"`
`overriddenById`	`String`	정책을 설정한 사용자 ID 또는 그룹 ID (`default`이면 `null`)

1.6 요청 본문 형식(Content-Type) 규칙

중요

PATCH /policy/targets, DELETE /policy/targets는 **반드시 JSON 본문 + Content-Type: application/json**으로 호출해야 합니다.
text/plain 등 JSON이 아닌 형식으로 호출하면 요청이 거부됩니다.

권장 헤더: Content-Type: application/json
비권장 예: Content-Type: text/plain;charset=UTF-8 (요청 거부)

실패 응답 예시 (본문 형식 오류)

{
  "code": 4000,
  "codeMessage": "INVALID_REQUEST"
}

2. 정책 통합 조회

`GET` /policy/targets/merged/preview/{targetId}

전사 정책과 타깃 개별 정책을 병합하여, 해당 사용자에게 실제 적용될 전체 정책 결과를 반환합니다.

전체 URL 예시

GET http://{serverIp}:{serverPort}/WebConsoleApi/policy/targets/merged/preview/user001

Path Parameters

파라미터	타입	필수	설명
`targetId`	`String`	O	조회 대상 사용자 ID

Response 필드

필드	타입	설명
`data.targetId`	`String`	대상 ID
`data.templates`	`Array`	카테고리별 정책 목록
`data.templates[].categoryId`	`Integer`	카테고리 ID
`data.templates[].categoryName`	`String`	카테고리명 (예: 공통, 예외, MS Office ...)
`data.templates[].policyList`	`Array`	해당 카테고리의 정책 항목 목록

정책 항목 (policyList) 필드

필드	타입	설명
`policyId`	`String`	정책 고유 식별자 (예: `SD_DOC_OP_MODE`)
`policyName`	`String`	정책 표시명
`policyValue`	`String` 또는 `Integer`	현재 적용 중인 정책 값
`policyDesc`	`String`	정책 상세 설명
`uiTypeCode`	`Integer`	UI 타입 — `1`: 텍스트 입력, `2`: 선택형
`uiOptions`	`Array`	선택형 옵션 목록 (`uiTypeCode=2`일 때만 존재)
`overridden`	`Boolean`	개별 정책 적용 여부
`overriddenBy`	`String`	정책 출처 (`user` / `group` / `default`)
`overriddenById`	`String`	정책을 설정한 주체 ID
`startTimestamp`	`Long`	적용 시작 시각 (epoch ms)
`endTimestamp`	`Long`	적용 종료 시각 (epoch ms)

curl 예시

curl -X GET   "http://{serverIp}:{serverPort}/WebConsoleApi/policy/targets/merged/preview/user001"   -H "Content-Type: application/json"

Response Example — `200 OK`

{
  "code": 0,
  "codeMessage": "SUCCESS",
  "data": {
    "targetId": "user001",
    "templates": [
      {
        "categoryId": 1,
        "categoryName": "공통",
        "policyList": [
          {
            "uiOrder": 1,
            "uiTypeCode": 2,
            "uiTypeDesc": "select",
            "policyId": "SD_DOC_OP_MODE",
            "policyName": "무해화 사용 설정",
            "policyDesc": "문서 무해화 기능의 사용 여부를 설정합니다.",
            "uiOptions": [
              { "value": 1, "label": "ON" },
              { "value": 0, "label": "OFF" }
            ],
            "policyValue": 1,
            "overridden": true,
            "overriddenBy": "user",
            "overriddenById": "user001",
            "startTimestamp": 1762300800000,
            "endTimestamp": 1862300801000,
            "startTimestampText": "2025-11-05 09:00:00",
            "endTimestampText": "2029-01-15 09:00:01"
          },
          {
            "uiOrder": 2,
            "uiTypeCode": 2,
            "uiTypeDesc": "select",
            "policyId": "SD_USE_FAST_SANITIZER",
            "policyName": "무해화 처리 강도 설정",
            "policyDesc": "문서 내 위협 요소 제거 수준을 설정합니다.",
            "uiOptions": [
              { "value": 1, "label": "최대 보안" },
              { "value": 0, "label": "최대 정합성" }
            ],
            "policyValue": 1,
            "overridden": false,
            "overriddenBy": "default",
            "overriddenById": null
          }
        ]
      },
      {
        "categoryId": 2,
        "categoryName": "예외",
        "policyList": [
          {
            "uiOrder": 1,
            "uiTypeCode": 1,
            "uiTypeDesc": "text",
            "policyId": "SD_FORCE_BYPASS_EXT",
            "policyName": "특정 확장자 강제 반입 설정",
            "policyDesc": "무해화 과정을 거치지 않고 원본으로 반입할 확장자를 설정합니다.",
            "placeholder": "예: ppt;pptx;docx;",
            "policyValue": ";",
            "overridden": false,
            "overriddenBy": "default",
            "overriddenById": null
          }
        ]
      }
    ]
  }
}

3. 정책 등록/수정 (부분 업데이트)

`PATCH` /policy/targets

특정 사용자에게 정책을 부분적으로 등록하거나 수정합니다.

전체 URL 예시

PATCH http://{serverIp}:{serverPort}/WebConsoleApi/policy/targets

핵심 동작 — 부분 업데이트 (Partial Update)

요청에 포함된 정책만 추가 또는 업데이트됩니다.
기존에 등록된 다른 정책은 건드리지 않고 그대로 유지됩니다.
이미 존재하는 policyId를 보내면 해당 정책의 값/기간이 새 값으로 덮어쓰기 됩니다.

동작 예시

기존 상태: A, B, C 정책이 등록되어 있음

PATCH 요청: policyList에 C(새 값), D를 전달

결과: A, B 유지 + C 업데이트 + D 신규 추가

Request Body

필드	타입	필수	설명
`targetId`	`String`	O	정책 대상 사용자 ID
`manager_id`	`String`	X	정책 변경 요청자 ID (이력 식별용, 생략 가능)
`updateReason`	`String`	X	변경 사유 (이력 관리용)
`policyList`	`Array`	O	업데이트할 정책 목록
`policyList[].policyId`	`String`	O	정책 식별자 (예: `SD_DOC_OP_MODE`)
`policyList[].policyValue`	`String` 또는 `Integer`	O	설정할 정책 값
`policyList[].startTimestamp`	`Long` (int64)	X	적용 시작 시각 (epoch ms). 생략 시 즉시 적용
`policyList[].endTimestamp`	`Long` (int64)	X	적용 종료 시각 (epoch ms). 생략 시 무기한

Content-Type 필수 조건

PATCH /policy/targets는 반드시 아래 헤더로 요청해야 합니다.

Content-Type: application/json

text/plain으로 호출 시 오류 응답:

{
  "code": 4000,
  "codeMessage": "INVALID_REQUEST"
}

curl 예시

curl -X PATCH   "http://{serverIp}:{serverPort}/WebConsoleApi/policy/targets"   -H "Content-Type: application/json"   -d '{
    "targetId": "user001",
    "manager_id": "portal-admin-01",
    "updateReason": "무해화 모드 OFF 전환 (기간 설정)",
    "policyList": [
      {
        "policyId": "SD_DOC_OP_MODE",
        "policyValue": 0,
        "startTimestamp": 1761523200000,
        "endTimestamp": 1762128000000
      }
    ]
  }'

Response — `200 OK`

{
  "code": 0,
  "codeMessage": "SUCCESS"
}

Error Responses

상황	code	codeMessage
`targetId`가 존재하지 않음	`4404`	`VALUE_NOT_FOUND`
`policyId`가 존재하지 않음	`4404`	`VALUE_NOT_FOUND`
`endTimestamp`가 `startTimestamp` 이하	`4000`	`INVALID_REQUEST`
`Content-Type`이 JSON 아님 (`text/plain` 등)	`4000`	`INVALID_REQUEST`

4. 정책 삭제

`DELETE` /policy/targets

특정 사용자에게 적용된 개별 정책을 선택적으로 해제합니다.
해제된 정책은 정책 우선순위 체인에 따라 **상위 정책(소속 그룹 정책 또는 전사 기본값)**이 자동으로 적용됩니다.

전체 URL 예시

DELETE http://{serverIp}:{serverPort}/WebConsoleApi/policy/targets

Request Body

필드	타입	필수	설명
`targetId`	`String`	O	정책 대상 사용자 ID
`policyList`	`Array`	O	해제할 정책 목록
`policyList[].policyId`	`String`	O	정책 식별자

Content-Type 필수 조건

DELETE /policy/targets도 요청 본문이 있으므로 반드시 아래 헤더를 사용해 주세요.

Content-Type: application/json

curl 예시

curl -X DELETE   "http://{serverIp}:{serverPort}/WebConsoleApi/policy/targets"   -H "Content-Type: application/json"   -d '{
    "targetId": "user001",
    "policyList": [
      { "policyId": "SD_DOC_OP_MODE" },
      { "policyId": "SD_DOC_LIMIT_SIZE" }
    ]
  }'

Response — `200 OK`

{
  "code": 0,
  "codeMessage": "SUCCESS"
}

5. 연동 흐름 요약

아래 순서로 연동하시면 됩니다.

단계	Method	URI	설명
1	`GET`	`/policy/targets/merged/preview/{userId}`	현재 적용된 전체 정책 목록 확인
2	`PATCH`	`/policy/targets`	변경할 정책만 요청 (나머지는 자동 유지)
3	`DELETE`	`/policy/targets`	해제할 정책만 요청 (상위 정책으로 복원)
4	`GET`	`/policy/targets/merged/preview/{userId}`	변경 후 상태 재확인

연동 시 참고

1단계에서 조회한 응답의 policyId 값을 그대로 사용하여 2~3단계에서 변경/삭제합니다.
2단계 PATCH는 부분 업데이트이므로, 변경이 필요한 정책만 보내면 됩니다. 전체를 보낼 필요가 없습니다.
모든 변경은 자동으로 이력이 기록되어, 필요 시 이전 상태로 복원할 수 있습니다.
PATCH/DELETE 호출 시에는 반드시 Content-Type: application/json을 지정하세요.

문서 정보​

환경 설정 (필수)​

고객사 측 준비 사항​

소프트캠프 엔지니어 설정 방법​

IP 허용 설정​

Base URL​

API 리소스 맵​

1. 공통 규칙​

1.1 응답 구조​

1.2 응답 코드 정의​

1.3 Timestamp 규칙​

1.4 정책 우선순위​

1.5 오버라이드 정보​

1.6 요청 본문 형식(Content-Type) 규칙​

2. 정책 통합 조회​

GET /policy/targets/merged/preview/{targetId}​

Path Parameters​

Response 필드​

curl 예시​

Response Example — 200 OK​

3. 정책 등록/수정 (부분 업데이트)​

PATCH /policy/targets​

동작 예시​

Request Body​

Content-Type 필수 조건​

curl 예시​

Response — 200 OK​

Error Responses​

4. 정책 삭제​

DELETE /policy/targets​

Request Body​

Content-Type 필수 조건​

curl 예시​

Response — 200 OK​

5. 연동 흐름 요약​

문서 정보

환경 설정 (필수)

고객사 측 준비 사항

소프트캠프 엔지니어 설정 방법

IP 허용 설정

Base URL

API 리소스 맵

1. 공통 규칙

1.1 응답 구조

1.2 응답 코드 정의

1.3 Timestamp 규칙

1.4 정책 우선순위

1.5 오버라이드 정보

1.6 요청 본문 형식(Content-Type) 규칙

2. 정책 통합 조회

`GET` /policy/targets/merged/preview/{targetId}

Path Parameters

Response 필드

curl 예시

Response Example — `200 OK`

3. 정책 등록/수정 (부분 업데이트)

`PATCH` /policy/targets

동작 예시

Request Body

Content-Type 필수 조건

curl 예시

Response — `200 OK`

Error Responses

4. 정책 삭제

`DELETE` /policy/targets

Request Body

Content-Type 필수 조건

curl 예시

Response — `200 OK`

5. 연동 흐름 요약