---
title: "도브러너 Distributor Watermarking API 가이드"
description: "본 문서는 HTTP API를 통해 `도브러너 Distributor Watermarking` 서비스를 사용하는 방법을 안내합니다."
---
> For the complete documentation index, see [llms.txt](/llms.txt).

본 문서는 HTTP API를 통해 `도브러너 Distributor Watermarking` 서비스를 사용하는 방법을 안내합니다.

## API 공통 규격

본 문서에 명시된 모든 API에는 아래와 같은 공통 규격이 적용됩니다.

### API 인증 토큰

Distributor Watermarking API 호출 시 아래 과정을 통해 생성한 인증 토큰을 설정해야 합니다.

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

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

![](/img/content-security/tnp-token-auth-base64.png)

> `AccountID`와 `AccessKey` 값은 각각 도브러너 서비스 가입 시 입력한 계정 ID와 가입 후 콘솔에 표시되는 엑세스 키를 입력해야 합니다.

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

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

- URL: `https://dwm.doverunner.com/api/token/{siteId}`
- Method: GET

#### 경로 매개변수

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

#### 요청 헤더

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

**요청 예제**

```
GET /api/token/UNIT HTTP/1.1
Authorization: basic authInfo
Host: dwm.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를 통해 발급된 데이터를 설정하여 Distributor Watermarking API를 호출할 수 있습니다.

#### 공통 응답 규격

**응답 상태**

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

**응답 데이터 필드**

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


### 상태 코드

#### 작업 상태 코드

| 코드    | 설명            |
|-------|---------------|
| DM000 | READY         |
| DM001 | PREPROCESSING |
| DM500 | COMPLETED     |
| DM600 | ERROR         |

#### 태스크 상태 코드

| 코드    | 설명           |
|-------|--------------|
| TK000 | READY        |
| TK001 | PROGRESSING  |
| TK002 | COMPLETE     |
| TK005 | FAIL         |


## 작업 API

### 작업 목록 검색

생성된 작업의 목록을 검색할 수 있는 API입니다.

- URL: `https://dwm.doverunner.com/api/job/{siteId}`
- Method: GET

#### 경로 매개변수

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


#### 요청 매개변수

| 매개변수       | 유형     | 설명                                         | 
|------------|--------|--------------------------------------------|
| content_id | String | 검색할 고유값(Content ID). 최대 200자               |
| job_status | Array  | 검색할 작업 상태                                  |
| from       | String | 검색 날짜-시작일(yyyy-MM-dd)                      |
| to         | String | 검색 날짜-종료일(yyyy-MM-dd)                      |
| page_unit  | Number | 검색 결과 수 지정. 기본값: 25, 최대: 1000.             |
| page_index | Number | 검색 결과 페이지 번호. 기본값: 1                       |
| time_zone  | String | 검색에 사용될 시간대 설정. (+/-hh:mm) default: +00:00 |


**요청 예제**

```
GET /api/job/UNIT?content_id=test&job_status=DM500&job_status=DM600&from=2023-11-07&to=2023-11-09&page_unit=10&page_index=1&time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.doverunner.com
```

#### 응답 데이터 필드

| 필드                  | 유형 | 설명     | 
|---------------------| --- |--------|
| error_code          | String | 에러 코드  | 
| error_message       | String | 에러 메시지 | 
| time_zone           | String | 시간대            | 
| total_count         | Number | 전체 검색 결과 수     | 
| data                | Array | 작업 목록          | 
| data.[].job_id      | Number | 작업 ID       | 
| data.[].content_id  | String | 작업 명       | 
| data.[].job_status  | String | 작업 상태 코드       | 
| data.[].reg_time    | String | 작업 생성 시간       | 
| data.[].update_time | String | 작업 최종 업데이트 시간  |  

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "total_count" : 1,
  "data" : [ {
    "job_id" : 1111,
    "content_id" : "content_id",
    "job_status" : "DM000",
    "reg_time" : "2022-10-27T15:33:47",
    "update_time" : "2022-10-27T15:34:05"
  } ]
}
```



### 작업 상세 조회

생성된 작업의 상세 정보를 조회하는 API입니다.

- URL: `https://dwm.doverunner.com/api/job/{siteId}/{jobId}`
- Method: GET

#### 경로 매개변수

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

#### 요청 매개변수

| 매개변수      | 유형     | 설명                                         | 
|-----------|--------|--------------------------------------------|
| time_zone | String | 검색에 사용될 시간대 설정. (+/-hh:mm) default: +00:00 |
 

**요청 예제**

```
GET /api/job/UNIT/727?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.doverunner.com
```

#### 응답 데이터 필드

| 필드               | 유형 | 설명     | 
|------------------| --- |--------|
| error_code       | String | 에러 코드  | 
| error_message    | String | 에러 메시지 | 
| time_zone        | String | 시간대            | 
| data             | Object | 작업 정보          |
| data.job_id      | Number | 작업 ID       |
| data.content_id  | String | 작업 명       |
| data.job_status  | String | 작업 상태 코드       |
| data.reg_time    | String | 작업 생성 시간       |
| data.update_time | String | 작업 최종 업데이트 시간  |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 266

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
    "job_id" : 727,
    "content_id" : "content_id",
    "job_status" : "DM500",
    "reg_time" : "2022-09-13T18:46:28",
    "update_time" : "2022-09-13T18:56:02"
  }
}
```


### 작업의 Recipient 조회

특정 DWM Job(job_id) 와 관련된 모든 recipient 목록을 조회하는 API입니다.

- URL: `https://dwm.doverunner.com/api/job/{siteId}/{jobId}/recipient`
- Method: GET

#### 경로 매개변수

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

#### 요청 매개변수

| 매개변수      | 유형     | 설명                                         | 
|-----------|--------|--------------------------------------------|
| time_zone | String | 검색에 사용될 시간대 설정. (+/-hh:mm) default: +00:00 |

**요청 예제**

```
GET /api/job/UNIT/727/recipient?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.doverunner.com
```

#### 응답 데이터 필드

| 필드                         | 유형 | 설명                                         | 
|----------------------------| --- |--------------------------------------------|
| error_code                 | String | 에러 코드                                      | 
| error_message              | String | 에러 메시지                                     | 
| time_zone           | String | 시간대                                        | 
| total_count         | Number | 전체 검색 결과 수                                 | 
| data                | Array | Recipient 목록                               | 
| data.[].dwm_id	 | Number | recipient의 dwm_id                          |
| data.[].recipient	 | String | recipient의 이름                              |
| data.[].description	 | String | recipient에 대한 설명                           |
| data.[].task_status	 | String | PreEmbedder 작업 상태값                         |
| data.[].cli_error_code	 | String | PreEmbedder Error Code ("0" : 성공, 그 외 실패.). 0이 아닌 값은 [DWM PreEmbedder 작업 에러 코드 표](/ko/content-security/distributor-watermarking/distributor-watermarking-guide/#dwm-임베딩-작업-에러-코드)의 `D0000`–`D0401`, `Axxxx`에 해당합니다. |
| data.[].reg_time	 | String | 작업 생성 시간                                   |
| data.[].update_time	 | String | 작업 최종 업데이트 시간                              |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "total_count" : 1,
  "data" : [ {
    "dwm_id" : 74,
    "recipient" : "test1",
    "description" : "description",
    "task_status" : "TK001",
    "cli_error_code" : "0",
    "reg_time" : "2022-04-05T14:35:39",
    "update_time" : "2022-04-05T17:35:39"
  } ]
}
```


## Recipient

> 수신자 이름은 유일해야 하며 영어 알파벳, 십진수 숫자, `-`, `_`, `.`만 사용할 수 있습니다. 이 외 `@`, `!`, `%` 등의 특스 문자는 사용할 수 없습니다. 영어 알파벳은 대소문자를 구분하지 않습니다. 따라서 `Test`를 등록하면 `TEST`, `test` 등을 추가로 등록할 수 없습니다. 마찬가지로 수신자 이름을 사용할 때에도 `Test`가 등록되어 있는 경우 `test`를 사용하면 `Test`가 사용됩니다.

### Recipient 목록 조회

등록된 recipient 목록을 조회하는 API입니다.

- URL: `https://dwm.doverunner.com/api/recipient/{siteId}`
- Method: GET

#### 경로 매개변수

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

#### 요청 매개변수

| 매개변수             | 유형     | 설명                                                           | 
|------------------|--------|--------------------------------------------------------------|
| search_keyword | Array  | 검색할 recipient 의 이름   |
| from       | String | 검색 날짜-시작일(yyyy-MM-dd)                              |
| to         | String | 검색 날짜-종료일(yyyy-MM-dd)                              |
| page_unit  | Number | 검색 결과 수 지정. 기본값: 25, 최대: 1000. |
| page_index | Number | 검색 결과 페이지 번호. 기본값: 1 |
| time_zone  | String | 검색에 사용될 시간대 설정. (+/-hh:mm) default: +00:00   |

**요청 예제**

```
GET /api/recipient/UNIT?search_keyword=test&from=2023-11-07&to=2023-11-09&page_unit=10&page_index=1&time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.doverunner.com
```

#### 응답 데이터 필드

| 필드                   | 유형     | 설명                | 
|----------------------|--------|-------------------|
| error_code           | String | 에러 코드             | 
| error_message        | String | 에러 메시지            | 
| time_zone            | String | 시간대               | 
| total_count          | Number | 전체 검색 결과 수        | 
| data                 | Array  | Recipient 목록      |
| data.[].dwm_id	      | Number | recipient의 dwm_id |
| data.[].name         | String | recipient의 이름     |
| data.[].description	 | String | recipient에 대한 설명  |
| data.[].reg_time	    | String | recipient 생성 시간   |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 235

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "total_count" : 1,
  "data" : [ {
      "dwm_id" : 9,
      "name" : "distributor_1",
      "description" : "8337",
      "reg_time" : "2023-01-12T13:30:30"
  } ]
}
```

### Recipient 상세 조회

등록된 recipient을 상세 조회하는 API입니다.

- URL: `https://dwm.doverunner.com/api/recipient/{siteId}/{dwmId}`
- Method: GET

#### 경로 매개변수

| 매개변수   | 설명                       | 
|--------|--------------------------|
| siteId | 콘솔에 표시되는 도브러너 사이트 ID |
| dwmId  | Recipient의 DWM ID        |

#### 요청 매개변수

| 매개변수             | 유형     | 설명                                                           | 
|------------------|--------|--------------------------------------------------------------|
| time_zone  | String | 검색에 사용될 시간대 설정. (+/-hh:mm) default: +00:00   |

**요청 예제**

```
GET /api/recipient/UNIT/1011?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.doverunner.com
```

#### 응답 데이터 필드

| 필드                   | 유형     | 설명                | 
|----------------------|--------|-------------------|
| error_code           | String | 에러 코드             | 
| error_message        | String | 에러 메시지            | 
| time_zone            | String | 시간대               | 
| data                 | Object | Recipient 목록      |
| data.dwm_id	      | Number | recipient의 dwm_id |
| data.name         | String | recipient의 이름     |
| data.description	 | String | recipient에 대한 설명  |
| data.reg_time	    | String | recipient 생성 시간   |
| data.update_time	 | String | recipient 수정 시간   |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 235

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
      "dwm_id" : 1011,
      "name" : "distributor_1",
      "description" : "8337",
      "reg_time" : "2023-01-12T13:30:30",
      "update_time" : "2023-07-22T03:39:11"
  }
}
```


### Recipient 생성

Recipient를 등록하는 API입니다.   
호출당 150개 까지 등록 가능합니다.   
등록가능한 개수를 넘어가면 등록할 수 없습니다.

- URL: `https://dwm.doverunner.com/api/recipient/{siteId}`
- Method: POST

#### 경로 매개변수

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

#### 요청 데이터 필드

| 매개변수                       | 유형     | 필수값 여부 | 설명                                            | 
|----------------------------|--------|--------|-----------------------------------------------|
| recipients	                | Array  | 	Y	    | 등록할 recipient 리스트                             |
| recipients.[].name	        | String | 	Y	    | 이름 (maximum 128 length) 알파벳,숫자, (-_.) 만 사용 가능 |
| recipients.[].description	 | String | 		     | 설명 (maximum 50 length)                        |

**요청 예제**

```
POST /api/recipient/UNIT HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 86
Host: dwm.doverunner.com

{
  "recipients" : [ {
    "name" : "test",
    "description" : "test corp."
  } ]
}
```

#### 응답 데이터 필드

| 필드                   | 유형     | 설명                | 
|----------------------|--------|-------------------|
| error_code           | String | 에러 코드             | 
| error_message        | String | 에러 메시지            | 
| time_zone            | String | 시간대               |
| data                 | Array  | 등록된 Recipient 목록  |
| data.[].dwm_id	      | Number | recipient의 dwm_id |
| data.[].name         | String | recipient의 이름     |
| data.[].description	 | String | recipient에 대한 설명  |
| data.[].reg_time	    | String | recipient 생성 시간   |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 220

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : [ {
    "dwm_id" : 10,
    "name" : "test",
    "description" : "test corp.",
    "reg_time" : "2023-01-12T13:30:30"
  } ]
}
```

### Recipient 수정

등록된 Recipient를 수정하는 API입니다. DWM 임베딩 작업에 등록된 적이 없는 경우에 한해서만 수정이 가능합니다.    

- URL: `https://dwm.doverunner.com/api/recipient/{siteId}/{dwmId}`
- Method: PUT

#### 경로 매개변수

| 매개변수 | 설명 | 
| --- | --- |
| siteId | 콘솔에 표시되는 도브러너 사이트 ID |
| dwmId  | Recipient의 DWM ID        |


#### 요청 데이터 필드
최소 1개의 "name 혹은 description 필드"가 전달되어야 합니다. 

| 매개변수            | 유형     | 필수값 여부 | 설명                     | 
|---------------------|--------|--------|------------------------|
| name	            | String | 		    | 이름 (maximum 128 length)   |
| description	        | String | 		     | 설명 (maximum 50 length) |

**요청 예제**

```
PUT /api/recipient/UNIT/1011 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 86
Host: dwm.doverunner.com

{
    "name" : "change_name",
    "description" : "change_name corp."
}
```

#### 응답 데이터 필드

| 필드               | 유형     | 설명                | 
|------------------|--------|-------------------|
| error_code       | String | 에러 코드             | 
| error_message    | String | 에러 메시지            | 
| time_zone        | String | 시간대(UTC +00:00)   |
| data             | Object | 수정된 Recipient 정보  |
| data.dwm_id	     | Number | recipient의 dwm_id |
| data.update_time | String | recipient 수정 시간   |

**응답 예제**

```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 220

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
    "dwm_id" : 1011,
    "update_time" : "2023-07-22T03:39:11"
  }
}
```