This documentation is also available as markdown. For a complete index of all pages, see llms.txt at /llms.txt

도브러너 Distributor Watermarking API 가이드

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

API 공통 규격

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

API 인증 토큰

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

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

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

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 인증 토큰

응답 예제

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	성공
400	Bad Request: 요청이 잘못되었습니다. 수신 대상 이름 중복(E4004), 사이트 키 복호화·AES 검증 실패(E1003) 등이 해당됩니다.
401	Unauthorized: 인증 토큰이 없거나 형식이 잘못되었거나 만료되었습니다.
402	Invalid Parameter: 필수 파라미터가 누락되었거나 값·형식·타입이 올바르지 않습니다.
403	Forbidden: 해당 API 또는 사이트 ID에 대한 이용 권한이 없습니다.
405	Method Not Allowed: 해당 엔드포인트가 지원하지 않는 HTTP 메서드입니다.
422	Unprocessable Entity: 요청 형식은 올바르나 처리할 수 없습니다. 요청당 수신 대상 수 제한 또는 플랜 전체 할당량을 초과한 경우가 해당됩니다.
500	Internal Server Error: 요청 처리 중 서버에서 예기치 않은 오류가 발생했습니다.
503	Service Unavailable: 인증 서버 또는 DWM 서비스에 일시적으로 연결할 수 없거나 서비스가 중지되었습니다.

응답 데이터 필드

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

에러 코드

요청이 성공하면 error_code 필드는 0000이며, 그 외의 값은 실패를 의미합니다. 실패 사유는 error_message에 담깁니다. 아래 표는 본 문서에서 설명하는 Distributor Watermarking API가 반환할 수 있는 에러 코드입니다.

인증 에러 코드

아래 에러는 API 로직이 실행되기 전 공통 인증 단계에서 반환됩니다. Distributor Watermarking API는 Authorization 헤더의 Bearer 토큰과 pallycon-apidata 값을 이용한 AES 인증을 모두 지원하므로, 두 방식의 에러 코드를 함께 안내합니다.

에러 코드	설명	해결 방안
E9000	사용 가능한 인증 정보가 요청에 포함되지 않았거나, 해당 엔드포인트가 지원하지 않는 인증 방식을 사용했습니다.	`Authorization: Bearer TOKEN` 헤더를 전송하거나, AES 인증을 지원하는 엔드포인트에서는 `pallycon-apidata` 값을 전송하세요.
E9001	`Authorization` 헤더 형식이 올바르지 않거나 Bearer 방식이 아닙니다.	헤더를 `Authorization: Bearer TOKEN` 형식으로 정확히 전송하세요.
E9002	토큰을 읽었지만 페이로드 검증에 실패했거나 필수 클레임이 누락되었습니다.	도브러너 콘솔에서 토큰을 다시 발급받아 재시도하세요.
E9003	토큰이 만료되었습니다.	토큰을 새로 발급받아 재시도하세요.
E9006	요청한 사이트 ID에 대한 권한이 없거나, 관리자 계정만 사용할 수 있는 엔드포인트입니다.	요청 경로의 사이트 ID를 확인하고 해당 사이트를 소유한 계정으로 호출하세요.
E9008	토큰으로 확인된 계정에 등록된 API 토큰이 없습니다.	도브러너 콘솔에서 계정 설정을 확인하거나 헬프데스크에 문의하세요.
E9015	`pallycon-apidata` 복호화 결과가 올바른 JSON 형식이 아닙니다.	`pallycon-apidata`로 암호화하는 JSON이 올바른 형식인지 확인하세요.
A1000	`pallycon-apidata` 값을 디코딩할 수 없거나 `encData` 또는 `hash` 필드가 누락되었습니다.	연동 가이드에 따라 `pallycon-apidata` 값을 다시 생성하세요.
A1002	`pallycon-apidata`의 timestamp가 누락되었거나 허용되지 않는 형식입니다.	timestamp를 `yyyy-MM-ddTHH:mm:ssZ` 형식으로 전송하세요.
A1006	사이트 키 또는 액세스 키를 복호화할 수 없거나, 사이트 키로 `encData`를 복호화할 수 없습니다.	도브러너 콘솔에서 발급된 사이트 키와 액세스 키가 일치하는지 확인하세요.
A1007	`pallycon-apidata`의 hash 값이 액세스 키, 사이트 ID, `encData`, timestamp로 계산한 값과 일치하지 않습니다.	액세스 키, 사이트 ID, `encData`, timestamp 순으로 SHA-256 해시를 다시 계산하세요.

API 에러 코드

에러 코드	설명	해결 방안
E1000	요청 매개변수가 누락되었거나 값·형식·유형이 올바르지 않습니다. 에러 메시지에 문제가 된 필드 이름이 표시됩니다.	`error_message`에 표시된 필드를 수정한 후 재시도하세요.
E1005	해당 사이트의 Distributor Watermarking 서비스가 활성화되어 있지 않습니다.	도브러너 콘솔에서 서비스를 활성화하거나 헬프데스크에 문의하세요.
E2003	작업 목록 조회에 실패했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E2004	작업 조회에 실패했습니다. 요청한 작업 ID가 해당 사이트 ID에 존재하지 않을 수 있습니다.	요청 경로의 작업 ID를 확인한 후 재시도하세요.
E2005	작업의 수신자 목록 조회에 실패했습니다.	요청 경로의 작업 ID를 확인하고 재시도한 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E4000	수신자 목록 조회에 실패했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E4001	한 번의 등록 요청에 150개를 초과하는 수신자를 전송했습니다.	150개 이하 단위로 나누어 여러 번 호출하세요.
E4002	수신자 등록에 실패했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E4003	요금제에서 허용하는 수신자 수를 초과했습니다.	수신자 허용 수를 늘리려면 헬프데스크에 문의하세요.
E4004	요청한 수신자 이름이 모두 이미 등록되어 있습니다. 수신자 이름은 유일해야 하며 대소문자를 구분하지 않고 비교합니다.	아직 등록되지 않은 이름으로만 요청하세요.
E4005	트라이얼에서 허용하는 수신자 수(10개)를 초과했습니다.	더 많은 수신자를 등록하려면 상용 요금제로 업그레이드하세요.
E4006	해당 수신자가 이미 워터마킹 작업에 사용되어 수정할 수 없습니다.	새 수신자를 등록해 사용하세요. 한 번 사용된 수신자 이름은 변경할 수 없습니다.
E4007	수신자 정보 수정에 실패했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E4008	요청한 DWM ID가 요청한 사이트 ID에 속하지 않습니다.	요청 경로의 DWM ID와 사이트 ID를 확인하세요.
E4009	수신자 조회에 실패했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E4010	요청한 DWM ID에 해당하는 수신자가 없습니다.	수신자 목록에서 DWM ID를 확인한 후 재시도하세요.
E4017	해당 사이트의 최초 수신자 등록 과정에서 DWM ID 구간 할당에 실패했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E9997	서버 응답을 처리하는 중 내부 오류가 발생했습니다.	재시도 후에도 문제가 지속되면 헬프데스크에 문의하세요.
E9998	요청한 URL에서 지원하지 않는 HTTP 메서드입니다.	본 가이드에서 메서드와 URL을 확인하세요.
E9999	내부 오류가 발생했습니다.	요청 시각과 함께 헬프데스크에 문의하세요.

E1000은 HTTP 상태 코드 402 Payment Required와 함께 반환됩니다. 상태 코드 이름과 달리 결제 문제가 아니라, 요청 매개변수가 누락되었거나 값이 올바르지 않다는 의미입니다.

상태 코드

작업 상태 코드

코드	설명
DM000	READY
DM100	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	작업 최종 업데이트 시간

응답 예제

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	작업 최종 업데이트 시간

응답 예제

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 작업 에러 코드 표의 `D0000`–`D0401`, `Axxxx`에 해당합니다.
data.[].reg_time	String	작업 생성 시간
data.[].update_time	String	작업 최종 업데이트 시간

응답 예제

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 생성 시간

응답 예제

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 수정 시간

응답 예제

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 생성 시간

응답 예제

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 수정 시간

응답 예제

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"
  }
}