도브러너 Distributor Watermarking API 가이드

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

API 공통 규격

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

API 인증 토큰

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

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

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

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

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

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

• URL: https://dwm.pallycon.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.pallycon.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	성공
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.pallycon.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.pallycon.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.pallycon.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.pallycon.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.pallycon.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.pallycon.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” : 성공, 그 외 실패.)
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.pallycon.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.pallycon.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.pallycon.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.pallycon.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.pallycon.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.pallycon.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.pallycon.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.pallycon.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"
  }
}