문의 접수
문의 접수 기능을 자체적으로 구현하기 위해서는 아래와 같은 형태로 구현해야 합니다.
접수유형 리스트 조회
Contiple에 등록된 접수유형을 조회합니다.
조회된 접수유형은 사용자가 직접 선택할 수 있도록 UI를 구현합니다.
만약 특정 접수유형을 고정하고자 할 경우, [서비스관리 > 티켓 > 카테고리 관리] 화면으로 이동하여 카테고리 ID를 확인하고 category 변수를고정 값으로 지정합니다.
필드 리스트 조회
사용자가 선택한 접수유형을 변수로 하여 필드 목록을 조회합니다.
반환된 필드 목록의 Type에 따라 텍스트필드, 드롭다운, 체크박스 등의 UI를 구현합니다.
첨부파일 업로드
파일 첨부 기능을 구현할 경우, 파일 업로드 API를 호출하여 첨부 기능을 구현합니다.
업로드에 성공하면 시스템에서는 첨부파일 ID 값을 반환하며, 티켓 생성 시 해당 ID를 변수로제공해야 합니다.
티켓 생성
문의 제출 시 사용자가 필드에 입력한 값을 변수로 티켓 생성 API를 호출합니다.
➊ 접수유형 리스트
(1) 인터페이스 설명
URL: https://{domain}.oc.nhncloud.com/{serviceId}/api/v2/ticket/categories.json
접수유형 리스트
HTTPS
GET
UTF-8
JSON
서비스 내 접수유형 리스트 조회
필요 없음
(2) 요청 파라미터 정의
서비스 ID
serviceId
String
path
O
서비스 ID，URL PATH 중{serviceId}에 설정
상위 카테고리 ID
parent
Integer
query
X
상위 카테고리에 소속된 하위 카테고리 리스트
하위 카테고리 ID
child
Integer
query
X
하위 카테고리에 소속된 상위 카테고리 리스트
언어 코드
language
String
query
X
서비스 헬프센터 기본 언어 코드
(3) 결과 데이터
result.contents
categoryId
Integer
접수유형 ID
parent
Integer
상위 접수유형 ID
name
String
접수유형 명
level
Integer
접수유형 레벨(1, 2, 3, 4, 5)
path
String
접수유형 경로(\\로 각 뎁스 카테고리 ID 연결)
orderNo
Integer
표시 순서
languages
Object
카테고리 다국어 명
(4) Response Body
{
"header": {
"resultCode": 200,
"resultMessage": "",
"isSuccessful": true
},
"result": {
"contents": [
{
"categoryId": 2536,
"parent": 0,
"name": "유형1",
"level": 1,
"path": "\\",
"orderNo": 0,
"languages": {
"ko": "유형1",
"th": "พิมพ์1",
"ja": "タイプ1",
"en": "Type1",
"zh": "类型1"
}
},
{
"categoryId": 2537,
"parent": 0,
"name": "유형2",
"level": 1,
"path": "\\",
"orderNo": 0,
"languages": {
"ko": "유형2",
"th": "พิมพ์2",
"ja": "タイプ2",
"en": "Type2",
"zh": "类型2"
}
},
{
"categoryId": 2538,
"parent": 2536,
"name": "유형1-1",
"level": 2,
"path": "\\2536\\",
"orderNo": 0,
"languages": {
"ko": "유형1-1",
"th": "พิมพ์1-1",
"ja": "タイプ1-1",
"en": "Type1-1",
"zh": "类型1-1"
}
},
{
"categoryId": 2539,
"parent": 2536,
"name": "유형1-2",
"level": 2,
"path": "\\2536\\",
"orderNo": 0,
"languages": {
"ko": "유형1-2",
"th": "พิมพ์1-2",
"ja": "タイプ1-2",
"en": "Type1-2",
"zh": "类型1-2"
}
},
{
"categoryId": 2540,
"parent": 2538,
"name": "유형1-1-1",
"level": 3,
"path": "\\2536\\2538\\",
"orderNo": 0,
"languages": {
"ko": "유형1-1-1",
"th": "พิมพ์1-1-1",
"ja": "タイプ1-1-1",
"en": "Type1-1-1",
"zh": "类型1-1-1"
}
},
{
"categoryId": 2541,
"parent": 2540,
"name": "유형1-1-1-1",
"level": 4,
"path": "\\2536\\2538\\2540\\",
"orderNo": 0,
"languages": {
"ko": "유형1-1-1-1",
"th": "พิมพ์1-1-1-1",
"ja": "タイプ1-1-1-1",
"en": "Type1-1-1-1",
"zh": "类型1-1-1-1"
}
},
{
"categoryId": 2542,
"parent": 2541,
"name": "유형1-1-1-1-1",
"level": 5,
"path": "\\2536\\2538\\2540\\2541\\",
"orderNo": 0,
"languages": {
"ko": "유형1-1-1-1-1",
"th": "พิมพ์1-1-1-1-1",
"ja": "タイプ1-1-1-1-1",
"en": "Type1-1-1-1-1",
"zh": "类型1-1-1-1-1"
}
}
]
}
}➋ 접수유형 필드 리스트
(1) 인터페이스 설명
URL: https://{domain}.oc.nhncloud.com/{serviceId}/api/v2/ticket/field/user/{categoryId}.json
접수유형 필드 리스트
HTTPS
GET
UTF-8
JSON
접수유형을 통하여 대응되는 필드 리스트 확인
공통 인증
(2) 요청 파라미터 정의
서비스 ID
serviceId
String
path
O
서비스 ID, URL PATH 내에 설정한 {serviceId}
접수유형 ID
categoryId
Integer
path
O
접수유형 ID, URL PATH 내에 설정한 {categoryId}
언어 코드
language
String
query
X
서비스 헬프센터 기본 언어 코드
(3) 결과 데이터
result.contents
fieldId
Integer
고객 필드 ID
code
String
항목 코드
type
String
항목 유형
title
String
항목 명
description
String
안내 문구
placeholder
String
제시어
length
Integer
최대 길이(0: 길이 제한 없음)
required
Boolean
필수 항목 여부(true: yes, false: no)
encrypt
Boolean
저장 시 암호화 여부(true: yes, false: no)
holdingText
Boolean
클릭 시 삭제 여부(true: yes, false: no)
options
Array
텍스트 박스, 체크박스, 드롭박스, 예:[구분1,구분2,...]
value
String
사용자 입력 값
(4) Response Body
{
"header": {
"resultCode": 200,
"resultMessage": "",
"isSuccessful": true
},
"result": {
"contents": [
{
"fieldId": 1,
"code": "category",
"type": "dropdown",
"title": "유형",
"description": "",
"placeholder": "",
"length": 0,
"required": true,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 3,
"code": "mail",
"type": "text",
"title": "이메일",
"description": "",
"placeholder": "",
"length": 100,
"required": true,
"encrypt": true,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 5,
"code": "subject",
"type": "text",
"title": "제목",
"description": "",
"placeholder": "",
"length": 200,
"required": true,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 6,
"code": "content",
"type": "textarea",
"title": "문의내용",
"description": "",
"placeholder": "",
"length": 5000,
"required": true,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 2,
"code": "name",
"type": "text",
"title": "이름",
"description": "",
"placeholder": "",
"length": 100,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 4,
"code": "phone",
"type": "text",
"title": "전화번호",
"description": "",
"placeholder": "",
"length": 30,
"required": false,
"encrypt": true,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 9,
"code": "attachment",
"type": "file",
"title": "첨부파일",
"description": "10MB 이내 모든 이미지 및 허용된 문서 (MS office, hwp, pdf, txt)와 zip 파일을 5개까지 첨부가능합니다.",
"placeholder": "",
"length": 0,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 18,
"code": "typeOne",
"type": "text",
"title": "구분1",
"description": "",
"placeholder": "",
"length": 200,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 19,
"code": "typeTwo",
"type": "text",
"title": "구분2",
"description": "",
"placeholder": "",
"length": 200,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 720,
"code": "caption",
"type": "caption",
"title": "단순 텍스트 이름",
"description": "<div style=\"color:red\">단순 텍스트 설명</div>",
"placeholder": "<div style=\"font-size:20px;color:red\">단순 텍스트 내용</div>",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 721,
"code": "textbox",
"type": "text",
"title": "텍스트 박스 이름",
"description": "<div style=\"color:red\">텍스트 박스 설명</div>",
"placeholder": "텍스트 박스 자리 표시자",
"length": 50,
"required": true,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 722,
"code": "checkbox",
"type": "checkbox",
"title": "체크박스 이름",
"description": "체크박스 설명",
"placeholder": "",
"length": 50,
"required": false,
"encrypt": true,
"holdingText": true,
"options": [
"옵션1",
"옵션2",
"옵션3"
],
"value": null
},
{
"fieldId": 723,
"code": "dropdown",
"type": "dropdown",
"title": "드롭박스 이름",
"description": "드롭박스 설명",
"placeholder": "",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": [
"옵션1",
"옵션2",
"옵션3"
],
"value": null
},
{
"fieldId": 724,
"code": "radiobutton",
"type": "radio",
"title": "라디오 버튼 이름",
"description": "라디오 버튼 설명",
"placeholder": "",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": [
"옵션1",
"옵션2",
"옵션3"
],
"value": null
},
{
"fieldId": 725,
"code": "date",
"type": "date",
"title": "일자 이름",
"description": "일자 설명",
"placeholder": "2022-07-11",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 726,
"code": "datetime",
"type": "datetime",
"title": "일시",
"description": "일시",
"placeholder": "2022-07-11 00:00",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 727,
"code": "dateperiod",
"type": "date_period",
"title": "기간 일자 이름",
"description": "기간 일자 설명",
"placeholder": "2022-07-01 ~ 2022-07-31",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 728,
"code": "datetimeperiod",
"type": "datetime_period",
"title": "기간 일시 이름",
"description": "기간 일시 설명",
"placeholder": "2022-07-01 00:00 ~ 2022-07-31 23:59",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 729,
"code": "agreetotheterms",
"type": "agree",
"title": "동의하기 이름",
"description": "안내 문구",
"placeholder": "동의 문구",
"length": 50,
"required": false,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
},
{
"fieldId": 11,
"code": "personalAgree",
"type": "agree",
"title": "개인정보수집",
"description": "수집하는 개인 정보[(필수) 이메일, 휴대폰 번호, 문의내용, (선택) 첨부 파일]는 문의 내용 처리 및 고객 불만을 해결하기 위해 사용되며, <b><span style=\"font-size: 11pt;\">관련 법령에 따라 3년간 보관 후 삭제</span></b>됩니다. 문의 접수, 처리 및 회신을 위해 꼭 필요한 정보이므로 동의해 주셔야 서비스를 이용하실 수 있습니다.",
"placeholder": "위, 개인정보 수집 및 활용에 동의합니다.",
"length": 0,
"required": true,
"encrypt": false,
"holdingText": true,
"options": null,
"value": null
}
]
}
}➌ 티켓 첨부파일 업로드
(1) 인터페이스 설명
URL: https://{domain}.oc.nhncloud.com/{serviceId}/openapi/v1/ticket/attachments/upload.json
티켓 첨부파일 업로드
HTTPS
POST
UTF-8
JSON
서버에 파일 업로드
공통 인증
(2) 요청 파라미터 정의
서비스 ID
serviceId
String
path
O
URL PATH 내에 설정한 {serviceId}
업로드 파일
file
File
formData
O
파일을 form로 제출. 파일 지원 형식: jpg, png, gif, bmp, jpeg, tif, tiff, pdf, txt, hwp, xls, xlsx, doc, docx, ppt, pptx, mp3, wav, zip. 파일 사이즈<10M, 파일명 길이<100
(3) 결과 데이터 (성공)
result.content
attachmentId
String
첨부파일 ID
fileName
String
첨부파일 명
contentType
String
첨부파일 유형
disposition
String
파일 처리 방식(attachment: 첨부파일)
size
Long
첨부파일 사이즈(byte)
createdDt
Long
파일 첨부 시간
(4) Response Body (성공)
"header": {
"resultCode": 200,
"resultMessage": "",
"isSuccessful": true
},
"result": {
"content": {
"attachmentId": "8f0dc5854d2446b6aa2e6e41a0a2f55c",
"fileName": "image.png",
"contentType": "image/png",
"disposition": "attachment",
"size": 90576,
"createdDt": null
}
}
}(5) 결과 데이터 (실패)
result.content
exception
String
고정 값：OcException
message
String
오류 메시지 (10MB 이하의 파일만 첨부할수 있습니다. / 파일명 최대 길이 초과.(100) / 해당 파일 격식은 첨부할수 없습니다.
(6) Response Body (실패)
{
"header": {
"resultCode": 400,
"resultMessage": "해당 파일 격식은 첨부할 수 없습니다.",
"isSuccessful": false
},
"result": {
"content": {
"exception": "OcException",
"message": "해당 파일 격식은 첨부할 수 없습니다."
}
}
}➍ 티켓 생성
(1) 인터페이스 설명
URL : https://{domain}.oc.nhncloud.com/{serviceId}/openapi/v1/ticket.json
티켓 생성
HTTPS
POST
UTF-8
JSON
신규 티켓 생성
공통 인증
(2) 요청 파라미터 정의
서비스 ID
serviceId
String
path
O
서비스 ID，URL PATH 내에 설정한 {serviceId}
티켓 정보
request body
Object
body
O
티켓 정보(JSON)
카테고리
categoryId
Integer
O
카테고리(접수유형) ID
제목
subject
String
O
제목(max=255)
설명
content
String
O
원칙 상 단순 텍스트만 허용. Base64 내용으로 제출할 경우 티켓 확인시 내용이 많아 문제될 수 있음. 이미지는 첨부파일 형식으로 업로드하거나, 파일 업로드 후 html의 img src=""/{serviceId}/api/v2/ticket/attachments/{attachmentId}""/ 로 불러와서 사용
고객 정보
endUser
Object
O
고객 정보
아이디
endUser.usercode
String
X
ID(회원 고유 ID). 회원 연동 기능을 사용할 경우, 플랫폼 측의 사용자 고유 ID를 usercode로 사용할 수 있으며, 해당 usercode를 통해 회원의 문의 내역을 조회할수 있음. 비회원 문의일 경우 값을 전송할 필요 없음
메일
endUser.email
String
O
메일(서비스 관리 → 티켓 → 이메일 설정 메뉴에서 메일 정보를 설정하였을 경우, 티켓 처리 시 해당 메일 주소로 고객에게 메일 발송)
이름
endUser.username
String
O
이름(메일 파라미터 입력 시, 필수 입력 필요. 입력하지 않을 경우 메일 발송 불가)
전화
endUser.phone
String
X
전화
첨부파일
attachments
Array
X
첨부파일(max 5건)
첨부파일 ID
attachments.attachmentId
String
O
첨부파일 ID
구분1
typeOne
String
X
구분1(확장 시스템 필드1)
구분2
typeTwo
String
X
구분2(확장 시스템 필드2)
언어
language
String
X
언어
채널
source
String
X
티켓 채널(web: 웹, spweb: 모바일 웹, api: API, 기본 값: web)
사용자 필드
userFields
Array
O
사용자 필드 사용 시 필드별로 코드(code)와 값(value)으로 구성된 object를 array 형태로 제공 단, 사용자 필드를 사용하지 않을 경우에도 빈 array로 제공해야 함 → "userFields":[]
사용자필드 코드
userFields.code
String
O
사용자 필드, 항목 코드
사용자필드 입력 값
userFields.value
String
O
사용자 필드의 사용자 입력 값
(3) Response Body
{
"categoryId": "2542",
"subject": "유형",
"content": "문의내용",
"endUser": {
"usercode": "st18888",
"email": "[email protected]",
"username": "이름",
"phone": "13333333333"
},
"attachments": [
{
"attachmentId": "8f0dc5854d2446b6aa2e6e41a0a2f55c"
}
],
"typeOne": "구분1",
"typeTwo": "구분2",
"language": "ko",
"source": "web",
"userFields": [
{
"code": "textbox",
"value": "텍스트 박스 이름"
},
{
"code": "checkbox",
"value": [
"옵션1",
"옵션2"
]
},
{
"code": "dropdown",
"value": "옵션1"
},
{
"code": "radiobutton",
"value": "옵션1"
},
{
"code": "date",
"value": "2022-07-11"
},
{
"code": "datetime",
"value": "2022-07-11 00:00"
},
{
"code": "dateperiod",
"value": "2022-07-01 ~ 2022-07-31"
},
{
"code": "datetimeperiod",
"value": "2022-07-01 00:00 ~ 2022-07-31 23:59"
},
{
"code": "agreetotheterms",
"value": "true"
}
]
}(4) 결과 데이터 (성공)
result.content
ticketId
String
티켓 ID
categoryId
int
접수유형 ID
subject
String
티켓 제목
content
String
티켓 내용
status
String
티켓 상태(고정값: new(미힐당); open(처리중); closed(처리 완료)
createdDt
Long
티켓 생성 시간
updatedDt
Long
티켓 업데이트 시간
attachments
Array
첨부파일
attachments.attachmentId
String
첨부파일 ID
attachments.fileName
String
첨부파일 명
attachments.contentType
String
첨부파일 유형
attachments.disposition
String
파일 처리방식(attachment: 첨부파일)
attachments.size
String
첨부파일 사이즈(byt)
attachments.createdDt
String
티켓 업데이트 시간
(5) Response Body (성공)
{
"header": {
"resultCode": 200,
"resultMessage": "",
"isSuccessful": true
},
"result": {
"content": {
"ticketId": "T1658199661153IXTfw",
"subject": "유형",
"categoryId": 2542,
"categoryName": null,
"categoryFullName": null,
"status": "new",
"statusName": null,
"content": "문의내용",
"createdDt": 1658199661151,
"updatedDt": 1658199661151,
"contents": null,
"attachments": [
{
"attachmentId": "8f0dc5854d2446b6aa2e6e41a0a2f55c",
"fileName": "image.png",
"contentType": "image/png",
"disposition": "attachment",
"size": 90576,
"createdDt": 1658192910000
}
],
"displayDt": null
}
}
}(6) 결과 데이터 (실패)
result.contents
objectName
String
사용자 필드: 항목 코드
field
String
사용자 필드: 항목 ID
validate
String
invalid: 무효한 값, length: 최대 길이 초과, required: 항목을 입력하세요
key
String
"validate.ticket." + objectName + "." + validate
message
String
"validate.ticket." + objectName + "." + validate
(7-1) Response Body (실패)
{
"header": {
"resultCode": 400,
"resultMessage": null,
"isSuccessful": false
},
"result": {
"contents": [
{
"objectName": "mail",
"field": "3",
"validate": "invalid",
"key": "validate.ticket.mail.invalid",
"message": "validate.ticket.mail.invalid",
"rejectValue": ""
},
{
"objectName": "phone",
"field": "4",
"validate": "length",
"key": "validate.ticket.phone.length",
"message": "validate.ticket.phone.length",
"rejectValue": ""
},
{
"objectName": "textbox",
"field": "721",
"validate": "length",
"key": "validate.ticket.textbox.length",
"message": "validate.ticket.textbox.length",
"rejectValue": ""
},
{
"objectName": "checkbox",
"field": "722",
"validate": "invalid",
"key": "validate.ticket.checkbox.invalid",
"message": "validate.ticket.checkbox.invalid",
"rejectValue": ""
},
{
"objectName": "dropdown",
"field": "723",
"validate": "invalid",
"key": "validate.ticket.dropdown.invalid",
"message": "validate.ticket.dropdown.invalid",
"rejectValue": ""
}
]
}
}(7-2) Response Body (실패)
스팸 정책 적용으로 인한 실패
resultCode : 1001
동일 IP로 1분 내에 3번 이상 문의 생성 시도 시, 24시간 동안 티켓 생성 차단
resultCode : 1002
동일 IP로 24시간 내에 10번 이상 문의 생성 시도 시, 24시간 동안 티켓 생성 차단
{
"header": {
"resultCode": 1001,
"resultMessage": "문의 횟수가 상한을 초과했습니다. 잠시 후 문의하십시오.",
"isSuccessful": false
},
"result": {…...}
}{
"header": {
"resultCode": 1002,
"resultMessage": "문의 횟수가 상한을 초과했습니다. 잠시 후 문의하십시오.",
"isSuccessful": false
},
"result": {…...}
}Last updated