---
title: "워터마크 검출 API 가이드"
description: "도브러너 API 규격을 통해 wm 검출을 요청하고 결과를 확인하는 방법을 안내합니다."
---
> For the complete documentation index, see [llms.txt](/llms.txt).

도브러너의 워터마크 검출은 '블라인드' 검출방식을 사용합니다. 검출 과정에서 영상의 각 프레임을 분석하여 삽입된 원본 워터마크 패턴을 감지하고 임베딩시 사용한 비밀 키로 워터마크 페이로드를 복호화합니다. 검출과정을 통해 워터마크 페이로드를 찾아내면, 세션 데이터베이스에서 해당 페이로드를 키 값으로 하는 세션 정보를 찾아 검출결과로 리포트 합니다.

```mermaid
sequenceDiagram
    participant A as 서비스 사이트
    participant B as 도브러너 서비스
    A ->> B: 유출 의심 영상
    Note right of B: 워터마크(페이로드) 검출
    B -->> B: 영상 프레임 분석
    opt 워터마크 검출 시
    Note right of B: 워터마크 세션 데이터베이스
    B -->> B: 해당 세션 정보 검색
    end
    B ->> A: 검출 결과 리포트
```

## 워터마크 검출 요구사항

:::note 

워터마크 검출을 위해서는 최소 5분 이상의 연속된 녹화 영상이 필요합니다. 도브러너 포렌식 워터마크 제품은 리사이징을 비롯한 각종 공격에 대한 강인성을 가지고 있습니다. 그러나 실제 워터마크의 검출 성공률은 검출에 사용되는 영상의 화질(해상도, 비트레이트, 카메라의 흔들림 등)에 따라 달라질 수 있습니다. 신뢰할수 있는 검출을 위한 최소 사양은 480p 1Mbps 이상이며, 일반적으로 720p 이상의 영상에서 성공적으로 검출 할 수 있습니다. 자동 검출이 실패한 경우, 도브러너는 non-blind 검출도 지원하므로 원본 영상 또는 원본 콘텐츠의 스냅샷을 TS를 통해 제공해 주시면 전문가 팀이 수동검출을 시도할 수 있습니다.

:::

워터마크 검출에 필요한 상세 요구 사항은 다음과 같습니다.

| 항목 | 내용 | 
| :--- | :-- |
| 최소 영상 길이 | 워터마크 검출을 위해서는 최소 5분 이상 길이의 구간 반복 없이 연속된 녹화 영상이 필요 |
| 검출 영상 화질 | 검출을 위해서는 최소 480p 1Mbps 이상 화질 필요. 720p 이상의 화질 권장 |
| 영상 안정성 | 흔들림 없이 고정된 녹화 영상 필요. 핸드헬드 카메라 또는 스마트폰으로 촬영되어 화면이 흔들리는 경우 검출 불가 |
| 버퍼링 또는 화면 멈춤 | 최소 5분 이상 버퍼링이나 화면 멈춤 현상 없이 정상 재생된 구간이 있어야 함 |

## 연동 방식
검출 매니져 API 는 2가지 요청 방법을 지원합니다.    
Authorization 헤더가 Http Header에 포함되어 있으면 JWT 인증 방식으로 작동합니다.
- pallycon-apidata 연동 (aes 암호화 방식)
- JWT 인증

## 도브러너 HTTP API 규격

도브러너 서비스에서 사용하는 각종 HTTP API 요청시 아래 규격을 따릅니다.

> API 요청 규격에 대한 샘플 코드는 [샘플 다운로드 페이지](/content-security/forensic-watermarking/getting-started/fwm-downloads/)에서 확인하시기 바랍니다.

### 요청 규격

|Name|Value|
| :--- | :--- |
|pallycon-apidata|base64 Encoding ( JSON string )|

### 요청 데이터 JSON 형식

```json
{
    "data":"{각 API 별 `API data` JSON 값을 aes256 cbc 암호화한 base64 문자열}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{아래 'SHA256 입력 형식'의 문자열 값을 sha256 해시 처리한 base64 문자열}"
}
```

**요청 데이터 명세**

| <div style="width:60px">Name</div> | <div style="width:50px">Value</div> | <div style="width:70px">Required</div> | Description |
| :---- | :----- | :-- | :---------- |
| `data` | String | Y | 각 API마다 정의된 규격으로 생성한 JSON 문자열을 AES 암호화하고, 결과값을 base64 문자열로 입력 |
| `timestamp` | String | Y | GMT 시간대 기준으로 요청 시점의 시간을 "yyyy-mm-ddThh:mm:ssZ" 형식으로 입력 |
| `hash` | String | Y | 아래 규격에 따라 생성한 해시값을 입력 |

**AES256 암호화**

AES256 암호화는 도브러너 Cloud 서비스 사이트 생성 시 발급 되는 Site 키 값을 이용하여 아래와 같이 처리 합니다. ( 도브러너 콘솔 사이트에서 확인 )

  - Mode : CBC
  - AES key : 32 byte (도브러너 콘솔 사이트에서 발급 되는 site key)
  - AES IV : fixed 16 byte (0123456789abcdef)
  - Padding : pkcs7

**SHA256 입력 형식**

SHA256 해시의 입력값은 다음과 같은 문자열을 조합해 입력합니다.

  ```txt
  [site access key] + [site_id] + [json.data] + [json.timestamp]
  ```

  - site access key: 도브러너 Cloud 서비스 사이트 생성 시 발급 되는 access key 값이며 도브러너 콘솔 사이트에서 확인 가능합니다.
  - sha256 해시 함수의 결과 값은 문자열로 변환하지 않고 바이너리 데이터 형태 그대로 base64 함수에 입력되어야 합니다.

## JWT 인증 규격
`Authorization` 헤더에 토큰 api를 통해 발급된 데이터를 설정하여 검출 API를 호출할 수 있습니다.

## JWT Token 발급 API
- JWT 인증 규격을 통한 검출 API 호출 시 아래 과정을 통해 생성한 인증 토큰을 설정해야 합니다.

**1단계: Base64 인코딩된 인증 매개변수 생성**

1. 웹 브라우저로 도브러너 데브콘솔의 [Base64 Enc/Dec 페이지](https://devconsole.doverunner.com/common-tools/#base64)에 접속합니다.
2. `Encrypt` 옵션이 선택된 상태에서 `AccountID:AccessKey` 형태의 값을 왼쪽 필드에 입력합니다.
3. 아래 스크린샷 이미지와 같이 Base64 인코딩 된 값이 화면 오른쪽에 출력됩니다.
4. 다음 단계에서 사용을 위해 출력된 값을 복사해둡니다.
> `AccountID`와 `AccessKey` 값은 각각 도브러너 서비스 가입 시 입력한 계정 ID와 가입 후 콘솔에 표시되는 엑세스 키를 입력해야 합니다.

**2단계: 인코딩 된 매개변수를 이용해 인증 토큰 생성**

1단계에서 생성한 Base64 인코딩 결과 값을 아래 토큰 API 요청의 `Authorization` 헤더에 설정해 API를 호출합니다.

- URL: https://wm-detection.doverunner.com/api/token/[SITE_ID]/
- Method: GET

#### 경로 매개변수

| 매개변수 | 유형 | 설명 |
| --- | --- | --- |
| siteId | 네자리 영숫자 | 콘솔에 표시되는 도브러너 사이트 ID |

#### 요청 헤더

| 헤더 명 | 설명 | 
| --- | --- |
| Authorization | 기본 인증 : Basic base64encode(userId:accessKey) | 

**요청 예제**

```
GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: wm-detection.doverunner.com
```

#### 응답 데이터 필드

| 필드 | 유형 | 값 |
| --- | --- | --- |
| error_code | String | 에러 코드 |
| error_message | String | 에러 메시지 |
| data.token | String | API 인증 토큰 |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 112
{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "token" : "Bearer valid-token"
  }
} 
```

### API 요청 헤더

Authorization 헤더에 토큰 API를 통해 발급된 데이터를 설정하여 세션 매니저 API를 호출할 수 있습니다.

#### 공통 응답 규격

**응답 상태**

| HTTP 상태 코드 | 설명 | 
| --- | --- |
| 200 | 성공 | 
| 401 | JWT 토큰 규격이 잘못 되었거나 사용자 정보를 찾을 수 없습니다. | 
| 403 | API 이용 권한이 없습니다. | 

**응답 데이터 필드**

| 키 | 유형 | 값 |
| --- | --- | --- |
| error_code | String | 0000: 성공 / 실패 시 해당 에러코드 | 
| error_message | String | 에러 메시지 | 
| data | Json | API 수행 결과 | 


## Url을 이용한 검출 요청 등록 API

유출이 의심되는 영상에 대해 url을 이용하여 워터마크 검출을 요청하는 API 입니다.

* 신규 url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/url
* method : POST
* content type : application/json;charset=UTF-8

#### 경로 매개변수

| 매개변수 | 설명                                                       | 
| --- |----------------------------------------------------------|
| SITE_ID | 콘솔에 표시되는 도브러너 사이트 ID                                 | 
| SERVICE_CODE | 검출 서비스 요청 제품 코드 FWM - PD002, DWM - PD006. default: PD002 | 

### API 데이터 JSON 형식

```json
{
    "title": "title",
    "file_path": "aaa.mp4",
    "demo_contents": false,
    "metadata": {
      "{key}": "{value}"
    }
}
```

### API 데이터 규격

| Key           | type    | required | description                                       |
|:--------------|:--------|:---------|:--------------------------------------------------|
| title         | String  | Y        | 콘텐츠 타이틀                                           |
| file_path     | String  | Y        | 검출 대상 파일의 다운로드 링크                                 |
| demo_contents | Boolean | N        | DoveRunner demo contents 검출 요청 여부. default: false |
| metadata      | Object  | N        | 검출 요청과 함께 저장되는 선택 key-value 항목                    |

### 응답 데이터 JSON 형식

```json
{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "detection_id": "detection id"
}
```

### 응답 데이터 규격

|Key  | type  |description|
|:----| :-----| :----------|
| error_code | String |  `0000` : 성공, 에러인 경우 영문/숫자로 정의된 에러코드  |
| error_message | String |  에러인 경우 에러 메시지 |
| detection_id | Number | 해당 검출 요청에 대해 서버에서 자동 생성한 일련번호 |

## URL을 이용한 검출 요청 등록 API (라이브)

URL을 통해 워터마크 라이브 검출을 요청하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/live
* method : POST
* content type : application/json;charset=UTF-8

### 경로 매개변수

| 매개변수         | 설명                                       |
|--------------|------------------------------------------|
| SITE_ID      | 콘솔에 표시되는 도브러너 사이트 ID                     |
| SERVICE_CODE | 검출 서비스 요청 제품 코드. 라이브 검출은 FWM - PD002만 지원 |

### API 데이터 JSON 형식

```json
{
  "title": "title",
  "file_path": "https://example.cdn.com/live/stream/playlist.m3u8",
  "demo_contents": false,
  "metadata": {
    "{key}": "{value}"
  }
}
```

### API 데이터 명세

| Key           | type    | required | description                       |
|:--------------|:--------|:---------|:----------------------------------|
| title         | String  | Y        | 콘텐츠 제목                            |
| file_path     | String  | Y        | HLS (.m3u8) 라이브 스트림 manifest URL  |
| demo_contents | Boolean | N        | `도브러너 데모 콘텐츠` 플래그. default: false |
| metadata      | Object  | N        | 검출 요청과 함께 저장되는 선택 key-value 항목.   |

### 응답 데이터 JSON 형식

```json
{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "detection_id": "detection id"
}
```

### 응답 데이터 명세

| Key           | type   | description                         |
|:--------------|:-------|:------------------------------------|
| error_code    | String | "0000" : 성공, 에러인 경우 영문/숫자로 정의된 에러코드 |
| error_message | String | 에러인 경우 에러 메시지                       |
| detection_id  | Number | 도브러너 시스템에서 생성된 검출 요청 ID             |

## 파일 업로드로 검출 요청을 하기 위한 signed url 발급 API
검출 요청은 직접 파일을 업로드하여 요청할 수도 있습니다.
파일 업로드하기 위한 AWS S3 signed url을 발급하는 api 입니다.
발급받은 url로 파일 업로드 시 검출 요청이 진행 됩니다.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/token
* method : POST
* content type : application/json;charset=UTF-8

#### 경로 매개변수

| 매개변수 | 설명                                                       | 
| --- |----------------------------------------------------------|
| SITE_ID | 콘솔에 표시되는 도브러너 사이트 ID                                 | 
| SERVICE_CODE | 검출 서비스 요청 제품 코드 FWM - PD002, DWM - PD006. default: PD002 | 

### API 데이터 JSON 형식
```json
{
    "title": "title",
    "file_extension": "mp4",
    "demo_contents": false,
    "metadata": {
      "{key}": "{value}"
    }
}
```

### API 데이터 규격
| Key            | type    | required | description                                   |
|:---------------|:--------|:---------|:----------------------------------------------|
| title          | String  | Y        | 콘텐츠 title                                     |
| file_extension | String  | Y        | 파일 확장자 (mp4, mkv, mov)                        |
| demo_contents  | Boolean | N        | `도브러너 demo contents` 검출 요청 여부. default: false |
| metadata       | Object  | N        | 업로드 토큰과 함께 저장되는 선택 key-value 항목.              |

### 응답 데이터 JSON 형식
```json
{
    "error_code": "error code",
    "error_message": "error message",
    "upload_url": "upload url"
}
```

### 응답 데이터 규격
| Key           | type   | description                         |
|:--------------|:-------|:------------------------------------|
| error_code    | String | “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드 |
| error_message | String | 에러인 경우 에러 메시지                       |
| upload_url    | String | 1분동안 업로드 가능한 signed url             |

:::caution[즉시 업로드 필요]
`upload_url`은 발급 후 **1분** 이 지나면 만료됩니다. 응답을 받은 즉시 파일 업로드를 시작해야 합니다. 업로드를 대기열에 넣거나 실제 사용 시점보다 훨씬 앞서 url을 발급받는 등 지연이 발생하면 업로드가 실패하며, 이 경우 signed url을 새로 발급받아야 합니다.
:::

### 파일 업로드 샘플 (curl)
```txt
curl -v --upload-file {filename.mp4} {signed upload url}
```

## 검출 결과 조회

등록된 검출 요청 항목들과 각각의 진행 상황, 검출 결과를 조회하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/list
* method : GET
* content type : application/json;charset=UTF-8

#### 경로 매개변수

| 매개변수 | 설명                                                       | 
| --- |----------------------------------------------------------|
| SITE_ID | 콘솔에 표시되는 도브러너 사이트 ID                                 | 
| SERVICE_CODE | 검출 서비스 요청 제품 코드 FWM - PD002, DWM - PD006. default: PD002 | 

### API 데이터 JSON 형식

```json
{
    "search_keyword": "{search keyword}",
    "search_condition": "{search condition}",
    "detect_status": "FD001",
    "from": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "to": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "page_unit": "{long value}",
    "page_index": "{long value}",
    "time_zone": "{hh:mm}",
    "site_id": "{site id}"
}
```

### API 데이터 규격

| Key              | type  |required| description                  |
|:-----------------| :-----| :------|:-----------------------------|
| search_keyword   | String | N | 검색어                          |
| search_condition | String | N | 검색타입(`title`, `detectionId`). 기본값: `title` |
| detect_status    | String | N | 검출 상태값(FD001 ~ FD005)        |
| from             | String | N | 등록 날짜 검색 조건                  |
| to               | String | N | 등록 날짜 검색 조건                  |
| page_unit        | Int | N | 검색 갯수. 기본값 : 25              |
| page_index       | Int | N | 검색 페이지. 기본값 : 1              |
| time_zone        | String | N | 검색 기준 시간대                    |
| site_id          | String | N | 콘솔에 표시되는 도브러너 사이트 ID     |

### 응답 데이터 JSON 형식

```json
{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "total_count": "total count",
    "time_zone": "{hh:mm}",
    "data": [{
        "detection_id" : "{detection id}",
        "site_id" : "{site id}",
        "title": "{title}",
        "demo_contents": "{demo contents}",
        "detect_status" : "{detect status}",
        "file_id" : "{file id}",
        "file_path": "{file path}",
        "region_code": "{region code}",
        "service_code": "{service code}",
        "wm_key": "{wm key}",
        "wm_data": "{wm data}",
        "reg_date" : "{register date}",
        "update_date": "{update date}"
     }]
}
```

### 응답 데이터 규격

| Key                         | type   | description                                                |
|:----------------------------|:-------|:-----------------------------------------------------------|
| error_code                  | String | `0000` : 성공, 에러인 경우 영문/숫자로 정의된 에러코드                        |
| error_message               | String | 에러인 경우 에러 메시지                                              |
| total_count                 | String | 총 list 갯수                                                  |
| time_zone                   | String | 검색 기준 시간대                                                  |
| data.detection_id           | Number | 검출 ID                                                      |
| data.site_id                | String | 고객사 Site ID                                                |
| data.title                  | String | 콘텐츠 제목                                                     |
| data.demo_contents          | String | 도브러너 데모 콘텐츠로 검출 요청한 경우                                      |
| data.file_id                | Number | Anti Piracy 에서 검출 요청 시 테이크다운 ID, 포렌식 워터마킹에서 요청한 경우에는 파일 ID |
| data.file_path              | String | 파일 경로                                                      |
| data.region_code            | String | 지역 코드                                                      |
| data.service_code           | String | 제품 코드(DWM-PD006, FWM-PD002)                                |
| data.wm_key                 | String | fwm -해당 사이트의 FWM 인증키, dwm - dwmId                          |
| data.wm_data                | String | fwm -세션 매니저를 통해 설정한 워터마크 정보, dwm - recipient               |
| data.reg_date               | String | 등록 날짜                                                      |
| data.update_date            | String | 수정 날짜                                                      |

## 검출 상세 조회

등록된 검출 요청의 상세 조회 하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/detail
* method : GET
* content type : application/json;charset=UTF-8

#### 경로 매개변수

| 매개변수 | 설명                                                       | 
| --- |----------------------------------------------------------|
| SITE_ID | 콘솔에 표시되는 도브러너 사이트 ID                                 | 
| SERVICE_CODE | 검출 서비스 요청 제품 코드 FWM - PD002, DWM - PD006. default: PD002 | 

### API 데이터 JSON 형식

```json
{
    "detection_id": "{detection id}",
    "site_id": "{site id}"
}
```

### API 데이터 규격

| Key          | type   | required | description              |
|:-------------|:-------|:---------|:-------------------------|
| detection id | Number | Y        | 검출 ID                    |
| site_id      | String | N        | 콘솔에 표시되는 도브러너 사이트 ID |

### 응답 데이터 JSON 형식

```json
{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "data": {
        "detection_id" : "{detection id}",
        "site_id" : "{site id}",
        "title": "{title}",
        "req_type": "{req_ ype}",
        "demo_contents": "{demo contents}",
        "detect_status" : "{detect status}",
        "detect_progress_status": "{detect progress status}",
        "file_path": "{file path}",
        "file_id" : "{file id}",
        "service_code": "{service code}",
        "wm_key": "{wm key}",
        "wm_data": "{wm data}",
        "wm_seed_key": "{wm seed key}",
        "error_code": "{error code}",
        "error_message": "{error message}",
        "reg_date" : "{register date}",
        "update_date": "{update date}",
        "sha256": "{sha256 hash}",
       "metadata": {
          "{key}": "{value}"
          }
        },
        "detection_location": [
            {
                "frame_index": { "start": 12288, "end": 12671 },
                "timestamp": { "start": "512000", "end": "527999" }
            }
        ]
     }
}
```

### 응답 데이터 규격

| Key                                         | type   | description                                                |
|:--------------------------------------------|:-------|:-----------------------------------------------------------|
| error_code                                  | String | `0000` : 성공, 에러인 경우 영문/숫자로 정의된 에러코드                        |
| error_message                               | String | 에러인 경우 에러 메시지                                              |
| data.detection_id                           | Number | 검출 ID                                                      |
| data.site_id                                | String | 고객사 Site ID                                                |
| data.title                                  | String | 콘텐츠 제목                                                     |
| data.req_type                               | String | 검출 등록 요청 타입(url, file)                                     |
| data.demo_contents                          | String | 도브러너 데모 콘텐츠로 검출 요청한 경우                                     |
| data.detect_status                          | String | 검출 상태값(FD001 ~ FD007)                                      |
| data.detect_progress_status                 | String | 검출 진행 상태값(FD100 ~ FD700)                                   |
| data.file_id                                | Number | Anti Piracy 에서 검출 요청 시 테이크다운 ID, 포렌식 워터마킹에서 요청한 경우에는 파일 ID |
| data.file_path                              | String | 파일 경로                                                      |
| data.service_code                           | String | 제품 코드(DWM-PD006, FWM-PD002)                                |
| data.wm_key                                 | String | fwm -해당 사이트의 FWM 인증키, dwm - dwmId                          |
| data.wm_data                                | String | fwm -세션 매니저를 통해 설정한 워터마크 정보, dwm - recipient               |
| data.wm_seed_key                            | String | ADMIN만 사용                                                  |
| data.reg_date                               | String | 등록 날짜                                                      |
| data.update_date                            | String | 수정 날짜                                                      |
| data.error_code                             | String | internal error 에러 코드                                       |
| data.error_message                          | String | initernal error 에러 설명                                      |
| data.sha256                                 | String | 분석한 영상의 SHA-256 해시값(16진수)입니다.                              |
| data.metadata                               | Object | 검출 요청 시 전달한 `metadata` 를 전달한 순서 그대로 key-value 객체로 반환합니다.   |
| data.detection_location                     | Array  | 워터마크가 검출된 영상 구간 목록입니다. 저장된 구간이 없으면 응답에 포함되지 않습니다           |
| data.detection_location[].frame_index.start | Number | 해당 구간의 시작 프레임 인덱스                                          |
| data.detection_location[].frame_index.end   | Number | 해당 구간의 종료 프레임 인덱스                                          |
| data.detection_location[].timestamp.start   | String | 해당 구간의 시작 타임스탬프. 검출기가 보고한 값을 문자열로 전달합니다                    |
| data.detection_location[].timestamp.end     | String | 해당 구간의 종료 타임스탬프. 검출기가 보고한 값을 문자열로 전달합니다                    |

## 검출 상태 이력 조회

등록된 검출 요청의 상태 변경 이력을 조회하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/history
* method : GET
* content type : application/json;charset=UTF-8

#### 경로 매개변수

| 매개변수    | 설명                   |
|---------|----------------------|
| SITE_ID | 콘솔에 표시되는 도브러너 사이트 ID |

### 쿼리 파라미터

| Key          | type   | required | description |
|:-------------|:-------|:---------|:------------|
| detection_id | Number | Y        | 조회할 검출 ID   |

### 응답 데이터 JSON 형식

```json
{
  "error_code": "0000",
  "error_message": "Success.",
  "data": {
    "detection_id": 12345,
    "histories": [
      { "detect_status": "FD001", "reg_date": "20260703090000" },
      { "detect_status": "FD002", "reg_date": "20260703090230" },
      { "detect_status": "FD003", "reg_date": "20260703091015" },
      { "detect_status": "FD004", "reg_date": "20260703094512" }
    ]
  }
}
```

### 응답 데이터 규격

| Key                            | type   | description                               |
|:-------------------------------|:-------|:------------------------------------------|
| error_code                     | String | `0000` : 성공, 에러인 경우 영문/숫자로 정의된 에러코드       |
| error_message                  | String | 에러인 경우 에러 메시지                             |
| data.detection_id              | Number | 조회한 검출 ID                                 |
| data.histories                 | Array  | 상태 이력 항목 목록. 성공 응답에서는 비어 있지 않습니다          |
| data.histories[].detect_status | String | 검출 상태값(FD001 ~ FD007)                     |
| data.histories[].reg_date      | String | 해당 상태가 처음 기록된 시각. UTC `yyyyMMddHHmmss` 형식 |

`data.histories` 의 항목은 `detect_progress_status` 가 아니라 [워터마크 검출 상태 코드](#워터마크-검출-상태-코드)에 정리된 `detect_status` 값을 사용합니다.


## 검출 중지 요청

등록된 검출 요청을 중지하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/stop
* method : PUT
* content type : application/json;charset=UTF-8

#### 경로 매개변수

| 매개변수 | 설명                                                       | 
| --- |----------------------------------------------------------|
| SITE_ID | 콘솔에 표시되는 도브러너 사이트 ID                                 | 
| SERVICE_CODE | 검출 서비스 요청 제품 코드 FWM - PD002, DWM - PD006. default: PD002 | 

### API 데이터 JSON 형식

```json
{
    "detection_id": "{detection id}"
}
```

### API 데이터 규격

| Key          | type   | required | description              |
|:-------------|:-------|:---------|:-------------------------|
| detection id | Number | Y        | 검출 ID                    |

### 응답 데이터 JSON 형식

```json
{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "data": "{detection id}"
}
```


### 응답 데이터 규격

| Key                        | type   | description                                                |
|:---------------------------|:-------|:-----------------------------------------------------------|
| error_code                 | String | `0000` : 성공, 에러인 경우 영문/숫자로 정의된 에러코드                        |
| error_message              | String | 에러인 경우 에러 메시지                                              |
| data                       | Number | 검출 ID                                                      |


## 검출 상태 알림 API

검출이 종결 상태에 도달하면 도브러너가 서비스에 알릴 수 있도록 AWS SNS 토픽을 설정합니다. 성공·실패와 무관하게 검출 건마다 메시지가 한 번 발송되므로, 유출된 워터마크의 세션을 차단하는 등의 후속 처리를 자동화할 수 있습니다.

### 경로 매개변수

| 매개변수 | 설명 |
|----------|-------------|
| SITE_ID | DoveRunner 사이트 ID (4자리 영숫자) |
| NOTI_ID | 알림 ID (상세조회, 업데이트, 삭제 작업에 사용) |

### 알림 메시지

검출이 종결 상태에 도달하면 도브러너가 등록된 SNS 토픽으로 다음 JSON 메시지를 발송합니다.

```json
{
  "detection_id": 12345,
  "detection_status": "FD004",
  "forensic_mark": "0123456789abcdef",
  "watermark_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "error_code": null,
  "error_message": null
}
```

| Key              | type   | 설명                                                                                           |
|:-----------------|:-------|:---------------------------------------------------------------------------------------------|
| detection_id     | Number | 해당 메시지가 가리키는 검출 ID                                                                           |
| detection_status | String | 종결 검출 상태 코드: `FD004`(검출 완료), `FD006`(에러), `FD007`(검출 실패). [워터마크 검출 상태 코드](#워터마크-검출-상태-코드) 참고 |
| forensic_mark    | String | 추출된 워터마크 페이로드입니다. 검출이 성공한 경우에만 포함됩니다                                                         |
| watermark_token  | String | 추출된 페이로드에 해당하는 워터마크 토큰으로, 세션 차단에 사용합니다. 검출이 성공한 경우에만 포함됩니다                                   |
| error_code       | String | 실패 시 에러 코드입니다. 검출이 실패한 경우에만 포함됩니다                                                            |
| error_message    | String | 실패 시 에러 메시지입니다. 검출이 실패한 경우에만 포함됩니다                                                           |

### 알림 등록

검출 상태 알림을 발송할 AWS SNS 토픽을 등록하는 API입니다.

:::caution[사이트당 알림 1개]
SNS 알림은 사이트당 **하나만** 등록할 수 있습니다. 이미 등록된 사이트에 대해 이 API를 다시 호출하면 `A4029` 에러가 반환됩니다. 대상을 변경하려면 새로 등록하는 대신 아래의 [알림 수정](#알림-수정) / [알림 삭제](#알림-삭제)를 통해 기존 알림을 수정하거나 삭제하세요.
:::

* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]
* method : POST
* content type : application/json;charset=UTF-8

#### API 데이터 JSON 형식

```json
{
  "noti_name": "my_revoke_notification",
  "aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
  "aws_access_key": "AKIAEXAMPLEKEY123",
  "aws_secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
```

#### API 데이터 규격

| key | type | required | description |
|:----| :-----| :------|:---------------------------------------------|
| noti_name | String | Y | 알림 이름 |
| aws_arn | String | Y | AWS ARN |
| aws_access_key | String | Y | AWS 액세스 키 |
| aws_secret_key | String | Y | AWS 시크릿 키 |

#### 응답 데이터 JSON 형식

```json
{
    "error_code": "0000",
    "error_message": "Success.",
    "data": {
        "noti_id": 1
    }
}
```

#### 응답 데이터 규격

| key | type | description |
|:----| :-----| :----------|
| error_code | String | `0000`: 성공, 기타 코드: 에러 |
| error_message | String | 에러 메시지 |
| data.noti_id | Number | 알림 ID |

### 알림 목록 조회

등록된 모든 알림을 조회하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]
* method : GET
* content type : application/json;charset=UTF-8

#### 응답 데이터 JSON 형식

```json
{
    "error_code": "0000",
    "error_message": "Success.",
    "data": {
        "total_count": 1,
        "noti_list": {
            "noti_id": 1,
            "noti_name": "my_revoke_notification",
            "aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
            "reg_time": "2025-07-20T09:00:00",
            "update_time": "2025-07-21T13:00:00"
        }
    }
}
```

#### 응답 데이터 규격

| key                        | type   | description           |
|:---------------------------|:-------|:----------------------|
| error_code                 | String | `0000`: 성공, 기타 코드: 에러 |
| error_message              | String | 에러 메시지                |
| data.total_count           | Number | 알림 수                  |
| data.noti_list.noti_id     | Number | 알림 ID                 |
| data.noti_list.noti_name   | String | 알림 이름                 |
| data.noti_list.aws_arn     | String | AWS ARN               |
| data.noti_list.reg_time    | String | 등록 일시 (UTC)           |
| data.noti_list.update_time | String | 업데이트 일시 (UTC)         |

### 알림 상세 조회

특정 알림의 상세 정보를 조회하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]/[NOTI_ID]
* method : GET
* content type : application/json;charset=UTF-8

#### 응답 데이터 JSON 형식

```json
{
    "error_code": "0000",
    "error_message": "Success.",
    "data": {
        "noti_id": 1,
        "noti_name": "my_revoke_notification",
        "aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
        "reg_time": "2025-07-20T09:00:00",
        "update_time": "2025-07-21T13:00:00"
    }
}
```

#### 응답 데이터 규격

| key              | type   | description           |
|:-----------------|:-------|:----------------------|
| error_code       | String | `0000`: 성공, 기타 코드: 에러 |
| error_message    | String | 에러 메시지                |
| data.noti_id     | Number | 알림 ID                 |
| data.noti_name   | String | 알림 이름                 |
| data.aws_arn     | String | AWS ARN               |
| data.reg_time    | String | 등록 일시 (UTC)           |
| data.update_time | String | 업데이트 일시 (UTC)         |

### 알림 수정

기존 알림 설정을 수정하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]/[NOTI_ID]
* method : PUT
* content type : application/json;charset=UTF-8

#### API 데이터 JSON 형식

```json
{
  "noti_name": "updated_notification",
  "aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:updated-sns",
  "aws_access_key": "AKIAEXAMPLEKEY456",
  "aws_secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
```

#### API 데이터 규격

| key            | type   | required | description |
|:---------------|:-------|:---------|:------------|
| noti_name      | String | N        | 알림 이름       |
| aws_arn        | String | N        | AWS ARN     |
| aws_access_key | String | N        | AWS 액세스 키   |
| aws_secret_key | String | N        | AWS 시크릿 키   |

#### 응답 데이터 JSON 형식

```json
{
    "error_code": "0000",
    "error_message": "Success.",
    "data": {
        "noti_id": 1
    }
}
```

#### 응답 데이터 규격

| key           | type   | description           |
|:--------------|:-------|:----------------------|
| error_code    | String | `0000`: 성공, 기타 코드: 에러 |
| error_message | String | 에러 메시지                |
| data.noti_id  | Number | 알림 ID                 |

### 알림 삭제

등록된 알림을 삭제하는 API입니다.

* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]/[NOTI_ID]
* method : DELETE
* content type : application/json;charset=UTF-8

#### 응답 데이터 JSON 형식

```json
{
    "error_code": "0000",
    "error_message": "Success.",
    "data": {
        "noti_id": 1
    }
}
```

#### 응답 데이터 규격

| key           | type   | description           |
|:--------------|:-------|:----------------------|
| error_code    | String | `0000`: 성공, 기타 코드: 에러 |
| error_message | String | 에러 메시지                |
| data.noti_id  | Number | 알림 ID                 |

## 상태 및 에러 코드

### 워터마크 검출 상태 코드

**`detect_status` - 전체 검출 상태**

| 상태 코드 | 상태       |
|:------|:---------|
| FD001 | 검출 작업 준비 |
| FD002 | 다운로드 중   |
| FD003 | 검출 중     |
| FD004 | 작업 완료    |
| FD005 | 검출 취소    |
| FD006 | 에러       |
| FD007 | 검출 실패    |

**`detect_progress_status` - 검출 진행 중 보고되는 세부 진행 상태**

| 상태 코드 | 상태             |
|:------|:---------------|
| FD100 | 검출 요청 접수       |
| FD110 | 미디어 정보 확인 중    |
| FD210 | 다운로드 시작됨       |
| FD220 | 다운로드 완료        |
| FD311 | 자동 검출 시작됨      |
| FD312 | 자동 검출 완료       |
| FD321 | 수동 검출 시작됨      |
| FD322 | 자동 검출 실패       |
| FD400 | 작업 완료 (진행)     |
| FD520 | 검출 취소 완료       |
| FD600 | 에러 (진행)        |
| FD601 | 미디어 정보 확인 실패   |
| FD700 | 검출 실패 (진행)     |

### 워터마크 검출 에러 코드

| 에러 코드 | 에러 메시지                     | 원인                                                                  | 해결 방안                                                         |
|:------|:---------------------------|:--------------------------------------------------------------------|:--------------------------------------------------------------|
| A1000 | 요청 파라미터 또는 `pallycon-apidata` 오류 | 필수 값이 누락되었거나 형식이 잘못되었습니다. 또는 `pallycon-apidata` 값을 디코딩할 수 없거나 `encData` / `hash` 가 누락되었습니다. | API 가이드에 따라 정확한 파라미터를 입력해 다시 호출합니다. 에러 메시지의 콜론 뒤에 문제가 된 필드명이 표시됩니다. |
| A1002 | 타임스탬프 오류               | `pallycon-apidata` 의 `timestamp` 가 누락되었거나 허용된 형식이 아닙니다. | 타임스탬프를 `yyyy-MM-ddTHH:mm:ssZ` 형식으로 입력합니다.                 |
| A1006 | 사이트 키 복호화 실패           | 사이트 키 또는 액세스 키를 복호화하지 못했거나, 사이트 키로 `encData` 를 복호화하지 못했습니다. | 도브러너 콘솔 사이트에서 정확한 사이트 키와 액세스 키 값을 확인해 적용합니다.              |
| A1007 | 해시 검증 실패                   | API 요청 데이터의 해시 값이 잘못 생성되었습니다.                                       | API 가이드 문서를 참고해 정확한 해시 값을 적용합니다.                              |
| A1108 | 서비스 상태이지 않음                | 서비스 사용중이지 않습니다.                                                     | 서비스를 요청하세요.                                                   |
| A4001 | 지원하지 않는 서비스 코드         | 지원하지 않는 서비스 코드를 요청하였습니다.            | 지원하는 서비스 코드로 요청하여야 합니다(VOD 검출은 FWM, DWM / live 검출은 FWM만 지원). |
| A4002 | 검출 요청 등록 실패            | 검출 요청을 저장하는 중 내부 서버 에러가 발생했습니다.     | 1. 요청 데이터의 파라미터를 확인 후 재시도합니다.<br/>2. 헬프데스크 티켓으로 기술 지원을 요청합니다. |
| A4006 | 검출 상태 업데이트 실패              | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4009 | 검출 정보를 찾을 수 없음         | 요청한 검출 정보를 찾을 수 없거나, 해당 검출 ID가 이 사이트의 것이 아닙니다. | 검출 ID와 사이트 ID를 확인한 후 재시도합니다. 동일 에러 발생 시 헬프데스크 티켓으로 기술 지원을 요청합니다. |
| A4010 | 워터마크 키를 찾을 수 없음        | 요청한 키 값과 일치하는 워터마크 키가 이 사이트에 없습니다.  | 워터마크 키와 사이트 ID를 확인한 후 재시도합니다.                             |
| A4016 | dwmId list 검색 실패           | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4017 | 최대 사용 중인 dwm Id 검색 실패      | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4018 | 검출 list count 검색 실패        | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4019 | 검출 요청 수 제한 초과          | 검출 요청 수 제한에 도달했습니다. 트라이얼 계정은 누적 2회까지만 검출할 수 있으며 이 한도는 초기화되지 않습니다. 상용 계정은 동시에 진행 중인 검출이 50건으로 제한됩니다. | 상용 플랜은 진행 중인 검출이 완료된 후 다시 요청합니다. 트라이얼 플랜은 한도가 소진되면 복구되지 않으므로 헬프데스크로 문의합니다. |
| A4020 | 검출 update시 검출 정보 검색 실패     | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4022 | 다운로드 url 발급 시 검출 정보를 찾을 수 없음 | 다운로드를 요청한 검출 정보를 찾을 수 없습니다.         | 검출 ID를 확인한 후 재시도합니다.                                      |
| A4023 | 파일 확장자가 맞지 않음              | 파일 확장자(mp4, mpk, mov) 가 맞지 않습니다.                                    | 파일 확장자(mp4, mkv, mov)를 맞춰주세요.                                 |
| A4025 | 업데이트 상태가 순서대로 오지 않음        | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4026 | S3에서 비디오 파일 접근 실패          | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4027 | S3에서 로그 파일 접근 실패           | 내부 서버 에러로 인해 발생합니다.                                                 | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4029 | 세션 차단 알림 중복 등록             | 사이트당 하나의 알림만 등록할 수 있습니다.                                            | 새 알림을 등록하기 전에 기존 알림을 삭제하거나 기존 알림을 수정합니다.                      |
| A4030 | 잘못된 AWS SNS ARN 등록         | AWS ARN 형식이 유효하지 않거나 SNS ARN이 아닙니다.                                 | AWS SNS ARN 형식을 확인합니다. (arn:aws:sns:region:account:topic)     |
| A4032 | 알림 정보를 찾을 수 없음         | 해당 사이트에 지정한 알림이 존재하지 않습니다.          | 알림 ID와 사이트 ID를 확인한 후 올바른 정보로 요청합니다.                       |
| A4033 | AWS SNS 연결 실패          | 전달된 자격 증명으로 AWS SNS 토픽에 연결하지 못했습니다. | AWS 자격 증명, 리전 설정 및 네트워크 연결을 확인합니다.                        |
| A4034 | SNS 알림 등록 실패               | 알림 등록 중 내부 서버 오류가 발생했습니다.                                           | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4035 | SNS 알림 수정 실패               | 알림 업데이트 중 내부 서버 오류가 발생했습니다.                                         | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4036 | SNS 알림 삭제 실패               | 알림 삭제 중 내부 서버 오류가 발생했습니다.                                           | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                      |
| A4040 | 잘못된 metadata           | `metadata` 항목이 20개를 초과했거나, key가 128자를 초과했거나, value가 2048자를 초과했거나, key/value에 제어 문자가 포함되어 있습니다. | `metadata` 는 20개 이하, key는 128자 이하, value는 2048자 이하로 구성하고 제어 문자를 제거합니다. |
| A4041 | 검출 상태 이력을 찾을 수 없음      | 요청한 검출에 대한 상태 이력이 존재하지 않습니다.        | 검출 ID와 사이트 ID를 확인한 후 다시 요청합니다.                            |
| A7001 | 워터마크가 검출되지 않음          | 검출은 정상적으로 완료되었으나 콘텐츠에서 워터마크를 찾지 못했습니다. | 실패가 아닌 정보성 결과이며, 검출 상세 조회의 `data.error_code` 로 전달됩니다.     |
| A9998 | 허용되지 않는 HTTP 메서드       | 요청한 엔드포인트에서 허용하지 않는 HTTP 메서드를 사용했습니다. | 본 가이드에 명시된 HTTP 메서드를 사용합니다.                               |
| A9999 | 정의되지 않은 내부 오류          | 요청 처리 중 예기치 않은 내부 오류가 발생했습니다.       | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                  |
| E9000 | Authorization 헤더 누락    | `Authorization` 헤더와 `pallycon-apidata` 값이 모두 전달되지 않았거나, 해당 엔드포인트가 허용하지 않는 인증 방식을 사용했습니다. | `Authorization` 헤더에 Bearer 토큰을 전달하거나, AES 인증을 지원하는 엔드포인트에서는 `pallycon-apidata` 를 전달합니다. |
| E9001 | 유효하지 않은 토큰 값           | `Authorization` 헤더 형식이 잘못되었거나 Bearer 스킴을 사용하지 않았습니다. | `Authorization: Bearer TOKEN` 형식 그대로 전달합니다.               |
| E9002 | 유효하지 않은 토큰 페이로드        | 토큰은 읽었으나 페이로드 검증에 실패했거나 필수 클레임이 누락되었습니다. | 도브러너 콘솔에서 토큰을 재발급한 후 재시도합니다.                              |
| E9003 | 만료된 토큰                 | 토큰의 만료 시간이 지났습니다.                   | 토큰을 새로 발급받은 후 재시도합니다.                                     |
| E9006 | 해당 사이트 ID에 대한 권한 없음    | 계정에 요청한 사이트 ID에 대한 권한이 없거나, 관리자 계정이 필요한 엔드포인트입니다. | 요청 경로의 siteId를 확인하고, 관리자 전용 엔드포인트는 관리자 계정으로 호출합니다.        |
| E9008 | 계정 정보를 확인할 수 없음        | 토큰으로 확인된 계정에 등록된 API 토큰이 없습니다.      | 도브러너 콘솔에서 계정 설정을 확인하거나 헬프데스크에 문의합니다.                      |
| E9015 | 복호화된 요청 본문의 파라미터 오류    | 복호화된 `pallycon-apidata` 본문이 올바른 JSON이 아닙니다. | `pallycon-apidata` 로 암호화하는 JSON이 올바른 형식인지 확인합니다.          |
| E9996 | 인증 서버에 연결할 수 없음        | 계정 조회 서비스에 일시적으로 연결할 수 없습니다.        | 잠시 후 재시도합니다. 문제가 지속되면 헬프데스크 티켓으로 기술 지원을 요청합니다.            |
| E9997 | 서버 응답 파싱 실패            | 내부 서버 응답을 처리하는 중 예기치 않은 오류가 발생했습니다. | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                  |
| E9999 | 계정 조회 중 정의되지 않은 내부 오류  | 요청의 계정 정보를 확인하는 중 예기치 않은 오류가 발생했습니다. | 헬프데스크 티켓으로 기술 지원을 요청합니다.                                  |


### 검출 실패에 대한 에러 코드

| 에러 코드 | 설명                                                                         |
|:------|:---------------------------------------------------------------------------|
| D000  | 기타 에러 (검출 실패 관련 정의되지 않은 에러)                                                |
| D002  | 영상 길이가 5분 미만입니다.                                                           |
| D003  | 지원되는 코덱이 아닙니다. (H.264(AVC), H.265(HEVC), Apple ProRes 코덱 지원)               |
| D004  | 영상 해상도가 480P 미만입니다.                                                        |
| D005  | 영상 비트레이트가 1 Mbps 미만입니다.                                                    |
| D010  | 지원되는 확장자가 아닙니다. (.mp4, .mkv, .mov 지원)                                      |
| D011  | 영상의 미디어 스펙을 추출하지 못했습니다.                                                    |
| D017  | DWM 검출을 위한 영상 길이가 너무 짧습니다. 최소 30초 이상이어야 합니다.                               |
| D018  | 검출 요청 수 제한을 초과했습니다. 허용된 최대 검출 수를 확인해 주세요.                                  |
| D019  | 스트림 URL 확장자가 잘못되었습니다. 라이브 검출은 .m3u8 파일만 지원합니다.                             |
| D020  | 스트림 URL 형식이 잘못되었습니다. 라이브 검출에 사용할 올바른 URI를 입력해 주세요.                         |
| D021  | 스트림 URL이 잘못되었습니다. 해당 주소에서 플레이리스트(스트림 정보)를 가져올 수 없습니다.                      |
| D022  | 마스터 플레이리스트에서 유효한 스트림 경로를 찾지 못했습니다. 플레이리스트에 .m3u8 스트림 참조가 포함되어 있는지 확인해 주세요. |
| D023  | DRM으로 보호된 스트림(SAMPLE-AES)이 감지되었습니다. 암호화된 스트림은 라이브 검출을 진행할 수 없습니다.          |