> For the complete documentation index, see [llms.txt](https://docs.contiple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contiple.com/eng/api-guide/open-api/inquiry.md). # 1:1 Inquiry *** ## **➊ Submission Type list** #### **(1) Interface description** * URL: https\://{domain}.oc.nhncloud.com/{serviceId}/api/v2/ticket/categories.json | Interface name | Protocol | Request Format | Encoding | Request Format | Interface Description | Access Required | | ------------------------ | -------- | -------------- | -------- | -------------- | ----------------------------------------------------------------- | --------------- | | **Submission type list** | HTTPS | GET | UTF-8 | JSON | Retrieve the list of submission types associated with the service | Not required | *** #### **(2) Request parameter** | Name | Protocol | Type | Location | Required | Description | | ---------------------------------- | --------- | ------- | -------- | -------- | ---------------------------------------------------------- | | **Service ID** | serviceId | String | path | O | Service ID configured in the URL path | | **Parent category ID** | parent | Integer | query | X | Child category(Subcategory) list under the parent category | | **Child category(Subcategory) ID** | child | Integer | query | X | Parent list for the child category(Subcategory) | | **Language code** | language | String | query | X | Default helpcenter language of the service | *** #### **(3) Response data** | Name | Field (Parameter) | Type | Description | | ------------------- | ----------------- | ------- | ------------------------------------------------------------------------------ | | **result.contents** | categoryId | Integer | Submission type ID | | | parent | Integer | Parent submission Type ID | | | name | String | Submission type name | | | level | Integer | Submission type depth (1, 2, 3, 4, 5) | | | path | String | Submission type depth path (Each depth category ID is concatenated using \\\\) | | | orderNo | Integer | Display order | | | languages | Object | Submission type name (Multilingual) | *** #### **(4) Response Body** ```json { "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" } } ] } } ``` *** ## **➋ Submission Type Fields** #### **(1) Interface description** * URL: https\://{domain}.oc.nhncloud.com/{serviceId}/api/v2/ticket/field/user/{categoryId}.json | Interface Name | Protocol | Request Format | Encoding | Response Format | Interface Description | Access Required | | -------------------------- | -------- | -------------- | -------- | --------------- | ---------------------------------- | --------------------- | | **Submission type fields** | HTTPS | GET | UTF-8 | JSON | Retrieve fields by submission type | Common Authentication | *** #### **(2) Request parameter** | Name | Field (Parameter) | Type | Location | Required | Description | | ---------------------- | ----------------- | ------- | -------- | -------- | --------------------------------------------- | | **Service ID** | serviceId | String | path | O | Service ID configured in the URL path | | **Submission type ID** | categoryId | Integer | path | O | Submission type ID configured in the URL path | | **Language code** | language | String | query | X | Default helpcenter language of the service | *** #### **(3) Response data** | Name | Field (Parameter) | Type | Description | | ------------------- | ----------------- | ------- | ------------------------------------- | | **result.contents** | fieldId | Integer | Customer field ID | | | code | String | Field code | | | type | String | Field type | | | title | String | Field name | | | description | String | Notice | | | placeholder | String | Place holder | | | length | Integer | length (0: No length limit) | | | required | Boolean | Required (true: yes, false: no) | | | encrypt | Boolean | Encrypt (true: yes, false: no) | | | holdingText | Boolean | Click to reset (true: yes, false: no) | | | options | Array | Options | | | value | String | User input | *** #### **(4) Response Body** ```json { "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": "
단순 텍스트 설명
", "placeholder": "
단순 텍스트 내용
", "length": 50, "required": false, "encrypt": false, "holdingText": true, "options": null, "value": null }, { "fieldId": 721, "code": "textbox", "type": "text", "title": "텍스트 박스 이름", "description": "
텍스트 박스 설명
", "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": "수집하는 개인 정보[(필수) 이메일, 휴대폰 번호, 문의내용, (선택) 첨부 파일]는 문의 내용 처리 및 고객 불만을 해결하기 위해 사용되며, 관련 법령에 따라 3년간 보관 후 삭제됩니다. 문의 접수, 처리 및 회신을 위해 꼭 필요한 정보이므로 동의해 주셔야 서비스를 이용하실 수 있습니다.", "placeholder": "위, 개인정보 수집 및 활용에 동의합니다.", "length": 0, "required": true, "encrypt": false, "holdingText": true, "options": null, "value": null } ] } } ``` *** ## **➌ Upload Files** #### **(1) Interface description** * URL: https\://{domain}.oc.nhncloud.com/{serviceId}/openapi/v1/ticket/attachments/upload.json | Interface Name | Protocol | Request Format | Encoding | Response Format | Interface Description | Access Required | | -------------------------- | -------- | -------------- | -------- | --------------- | ---------------------------------- | --------------------- | | Upload files to the server | HTTPS | POST | UTF-8 | JSON | Upload files to the server(ticket) | Common Authentication | *** #### **(2) Request parameter**
NameField (Parameter)TypeLocationRequiredDescription
Service IDserviceIdStringpathOService ID configured in the URL path
Upload filefileFileformDataO

Submit the file as form.

  • Supported file formats: jpg, png, gif, bmp, jpeg, tif, tiff, pdf, txt, hwp, xls, xlsx, doc, docx, ppt, pptx, mp3, wav, zip.
  • Max file size : <10MB
  • Max filename length : <100 characters
*** #### **(3) Response data ****(Success)** | Name | Field (Parameter) | Type | Description | | ------------------ | ----------------- | ------- | ---------------------- | | **result.content** | attachmentId | String | Attachment ID | | | fileName | String | Attachment name | | | contentType | String | Attachment type | | | disposition | String | File disposition | | | size | Long | Attachment size(byte) | | | createdDt | Long | Upload attachment date | | | repealFlag | Boolean | File Deletion Flag | *** #### **(4) Response Body ****(Success)** ```json "header": { "resultCode": 200, "resultMessage": "", "isSuccessful": true }, "result": { "content": { "attachmentId": "8f0dc5854d2446b6aa2e6e41a0a2f55c", "fileName": "image.png", "contentType": "image/png", "disposition": "attachment", "size": 90576, "createdDt": null, "repealFlag": null } } } ``` *** #### **(5) Response data ****(Failure)**
NameField (Parameter)TypeDescription
result.contentexceptionStringfixed value : OcException
messageString

Error message

  • Refer to the failure cases below
**Failure cases** > **File size exceeds 10MB** > > ```json > { > "header": { > "resultCode": 4001, > "resultMessage": "Files can be attached within 10MB.", > "isSuccessful": false > }, > "result": { > "content": { > "exception": "OcException", > "message": "Files can be attached within 10MB." > } > } > } > ``` > > **File name exceeds 100 characters** > > ```json > { > "header": { > "resultCode": 4002, > "resultMessage": "You can only attach files that named within 100 characters.", > "isSuccessful": false > }, > "result": { > "content": { > "exception": "OcException", > "message": "You can only attach files that named within 100 characters." > } > } > } > ``` > > **Unsupported file format** > > ```json > { > "header": { > "resultCode": 4003, > "resultMessage": "This attachment format is not allowed.", > "isSuccessful": false > }, > "result": { > "content": { > "exception": "OcException", > "message": "This attachment format is not allowed." > } > } > } > ``` > > **Unsupported MIME type** > > * Allowed types: `"image", "application/pdf", "application/vnd", "text/plain", "application/zip", "application/x-tika-ooxml", "application/x-hwp", "application/x-tika-msoffice", "image/tiff", "audio/mpeg", "audio/wav", "audio/vnd.wave", "audio/x-wav"` > > ```json > { > "header": { > "resultCode": 9017, > "resultMessage": "The file content does not match an allowed MIME type.", > "isSuccessful": false > }, > "result": { > "content": { > "exception": "OcException", > "message": "The file content does not match an allowed MIME type." > } > } > } > ``` *** ## **➍ Create a Ticket** #### **(1) Interface description** * URL : https\://{domain}.oc.nhncloud.com/{serviceId}/openapi/v1/ticket.json * URL(Real Test Environment) : https\://{domain}.oc.beta-nhncloud.com/{serviceId}/openapi/v1/ticket.json * URL(Development Test Environment) : https\://{domain}.oc.alpha-nhncloud.com/{serviceId}/openapi/v1/ticket.json | Interface Name | Protocol | Request Format | Encoding | Response Format | Interface Description | Access Required | | ------------------ | -------- | -------------- | -------- | --------------- | --------------------- | --------------------- | | **Creat a ticket** | HTTPS | POST | UTF-8 | JSON | Create a ticket | Common Authentication | *** #### **(2) Request parameter**
NameField (Parameter)TypeLocationRequiredDescription
Service IDserviceIdStringpathOService ID configured in the URL path
Ticket datarequest bodyObjectbodyOTicket data(JSON)
CategorycategoryIdIntegerOCategory(Submission type) ID
SubjectsubjectStringOTitle (Max : 255)
ContentcontentStringOContent Policy:
In principle, only plain text is allowed.
Submitting content encoded in Base64 may cause issues when viewing tickets due to excessive content length.
Images should be uploaded as attachments, or uploaded as files first and then referenced using an HTML img src=""/{serviceId}/api/v2/ticket/attachments/{attachmentId}""/.
Customer informationendUserObjectOUser(Customer) information
IDendUser.usercodeStringXUser ID (When the member integration feature is enabled, the platform’s unique user ID can be used as the userCode.
This userCode allows inquiry history to be retrieved for the member.
For non-member inquiries, this value does not need to be provided.)
EmailendUser.emailStringOUser Email (If email information is configured in [Service Management] → [Ticket] → [Email Settings], emails will be sent to the customer using the configured email address during ticket processing.)
NameendUser.usernameStringOUser Name (Required when the email parameter is provided.
If not specified, the email cannot be sent.)
PhoneendUser.phoneStringXPhone
AttachmentattachmentsArrayXAttachment (Up to 5 files can be attached.)
Attachment IDattachments.attachmentIdStringOAttachment ID
Type1typeOneStringXType1 field (Extended system fields)
Type2typeTwoStringXType2 field (Extended system fields)
LanguagelanguageStringXLanguage
Channel (Inbound channel)sourceStringXTicket channel (web: Web(Default), spweb: Mobile web, api`: API)
User fielduserFieldsArrayXUser field
Field codeuserFields.codeStringOField code (User field)
User InputuserFields.valueStringOUser Input (User field)
*** #### **(3) Response Body** ```json { "categoryId": "2542", "subject": "유형", "content": "문의내용", "endUser": { "usercode": "st18888", "email": "enduser_simple@nhn-st.com", "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) Response data ****(Success)**
NameField (Parameter)TypeDescription
result.contentticketIdStringTicekt ID
categoryIdintSubmission type ID
subjectStringTicket title
contentStringTicket Contents
statusStringTicket status (Fixed value: new, open, closed)
createdDtLongCreated date
updatedDtLongUpdated date
attachmentsArrayAttchment
attachments.attachmentIdStringAttchment ID
attachments.fileNameStringAttchment Name
attachments.contentTypeStringAttchment Type
attachments.dispositionStringFile disposition
attachments.sizeStringAttchment size (byte)
attachments.createdDtStringAttchment updated date
*** #### **(5) Response Body ****(Success)** ```json { "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) Response data ****(Failure)**
NameField (Parameter)TypeDescription
result.contentsobjectNameStringUser field : Field code
fieldStringUser field : Field ID
validateStringinvalid: Invalid value, length: Maximum length exceeded, required: Please enter a value.
keyString"validate.ticket." + objectName + "." + validate
messageString"validate.ticket." + objectName + "." + validate
*** #### **(7-1) Response Body ****(Failure)** ```json { "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 ****(Failure)**: **Failure due to spam policy** * **resultCode : 1001** * If more than **3 inquiry creation attempts are made from the same IP within 1 minute**, ticket creation will be blocked for **24 hours** * **resultCode : 1002** * If more than **10 inquiry creation attempts are made from the same IP within 24 hours**, ticket creation will be blocked for **24 hours**. ```json { "header": { "resultCode": 1001, "resultMessage": "The number of inquiries has exceeded the limit. Please contact us again after a while.", "isSuccessful": false }, "result": {…...} } ``` ```json { "header": { "resultCode": 1002, "resultMessage": "The number of inquiries has exceeded the limit. Please contact us again after a while.", "isSuccessful": false }, "result": {…...} } ```