Open API

Contiple provides various support resources—such as Help Center notices, FAQs, and ticket information—via the Open API.

---

➊ API Authentication

1-1. Enable OPEN API

1. Go to [Service Management] → [Authentication].

2. Enable Open API.

3. When Open API is enabled, a Service API Key is automatically generated.

   • The API Key is used to authenticate API requests and encrypt transmitted data.

   • You can regenerate the API Key by clicking Change API Key.

---

1-2. Authorization Header

Please make sure to set the following values in every request header.

• If your service uses Security Service features, you can enable IP-based spam policies from [Service Management] → [Security Management] → [Spam Management].

• When creating tickets via the Open API, if you include the OC-Client-IP value in the request header, spam detection will be performed based on the request’s IP address.

• Authorization : Authentication string generated using the Security Key

• X-TC-Timestamp : Current UTC timestamp {new Date().getTime()}

• OUCODE : User Code (If not set, the default value is Owner)

---

1-3. Authorization Generation

1

Generate the string according to the rules below.

1. Organization ID

   • You can find this value on the [Global Management] → [Contract Service Status] → [Organization Information] screen.

   • It is composed in a format similar to the following: AbcdE1fghIj23K4x

2. API URI

   • Enter the URI of the API you want to call. The URI must include the Service ID.

     • Example: /yourService/openapi/v1/ticket.json

3. Query Parameters

   • If the API you are calling includes query parameters, sort the parameters by key name in alphabetical order first. Then concatenate only the parameter values using the & character. If there is only one parameter, do not include the & character. If there are no query parameters, this step can be omitted.

     • Example: Query parameter 1234

       1. Sorted by key (alphabetical): language=ko&page=1&pageSize=10

       2. Concatenated values: ko&1&10

4. Timestamp

   • Apply the timestamp of the time when the API request is made. This value must be identical to the X-TC-Timestamp value sent in the request header.

     • Example: 1764031689401

2

String Encryption

• Encrypt the generated string using the API Key created in 1-1. Enable Open API to generate the authentication key.

• The encryption method used is HmacSHA256.

3

Sending the Authentication Key

• Set the generated authentication key as the value of the Authorization request header and send the request to Contiple.

• Contiple encrypts the received header and body values using the same API Key and compares the resulting Hash value.

• If the values match, the API request is processed successfully.

• If they do not match, an error code 400 is returned.

---

1-4. JAVA Example

(1) Standard Request (GET)

// 유저 티켓 리스트
String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket/enduser/usercode/list.json?categoryId=1&language=ko";
String organizationId = "WopqM8euoYw89B7i"; // 조직ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // 서비스 Key
String uri = "/APISimple/openapi/v1/ticket/enduser/usercode/list.json"; // request uri
long timestamp = new Date().getTime();
StringBuilder sb = new StringBuilder();
sb.append(organizationId);
sb.append(uri);
sb.append("1").append("&").append("ko"); // 매개변수 이름의 알파벳 순서에 따라(categoryId=1&language=ko)& 기호로 매개변수 값을 연결해 주세요 (1&ko)
sb.append(timestamp);// X-TC-Timestamp값과 동일

SecretKeySpec signingKey = new SecretKeySpec(securityKey.getBytes("UTF-8"), "HmacSHA256");
Mac mac = Mac.getInstance(signingKey.getAlgorithm());
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(sb.toString().getBytes("UTF-8"));
String authorization = new String(Base64.encodeBase64(rawHmac));

Request request = new Request.Builder().url(URL).get()
.header("Content-Type", "application/json")
.header("Authorization", authorization)
.header("X-TC-Timestamp", Long.toString(timestamp))
.build();
Call call = client.newCall(request);
Response response = call.execute();

(2) Standard Request (POST)

// 티켓 생성
String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket.json?language=ko";
String organizationId = "WopqM8euoYw89B7i"; // 조직ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // 서비스 Key
String uri = "/APISimple/openapi/v1/ticket.json"; // request uri
long timestamp = new Date().getTime();
StringBuilder sb = new StringBuilder();

String body = mapper.writeValueAsString(bodyContentObject);

sb.append(organizationId);
sb.append(uri);
sb.append("ko").append("&"); // 매개변수 이름의 알파벳 순서에 따라 & 기호로 매개변수 값을 연결해 주세요.
sb.append(body);// 매개변수 뒤에 body의 문자열 내용을 추가해 주세요.
sb.append(timestamp);// X-TC-Timestamp값과 동일

SecretKeySpec signingKey = new SecretKeySpec(securityKey.getBytes("UTF-8"), "HmacSHA256");
Mac mac = Mac.getInstance(signingKey.getAlgorithm());
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(sb.toString().getBytes("UTF-8"));
String authorization = new String(Base64.encodeBase64(rawHmac));

RequestBody body = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), body);

Request request = new Request.Builder().url(URL).post(body)
.header("Content-Type", "application/json")
.header("Authorization", authorization)
.header("X-TC-Timestamp", Long.toString(timestamp))
.header("OC-Client-IP", ip)
.build();

Call call = client.newCall(request);
Response response = call.execute();

(3) File Upload

String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket/attachments/upload.json";
String organizationId = "WopqM8euoYw89B7i"; // NHN Cloud 조직ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // 서비스 Key
String uri = "/APISimple/openapi/v1/ticket/attachments/upload.json"; // request uri
StringBuilder sb = new StringBuilder();
sb.append(organizationId);
sb.append(uri);
DigestUtils.appendMd5DigestAsHex(file.getInputStream(), sb);// 파일 첨부 시 , 파일의 MD5는 파라미터 값으로 인증 문자열에 추가
sb.append(new Date().getTime());// X-TC-Timestamp값과 동일
SecretKeySpec signingKey = new SecretKeySpec(securityKey.getBytes("UTF-8"), "HmacSHA256");
Mac mac = Mac.getInstance(signingKey.getAlgorithm());
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(sb.toString().getBytes("UTF-8"));
String authorization = new String(Base64.encodeBase64(rawHmac));

(3) Contiple-side authentication method

// Generate authorization string sample with request
StringBuilder sb = new StringBuilder();
sb.append(org.getId()); // organization Id
sb.append(request.getRequestURI()); // request URI
// upload file
if (request instanceof MultipartHttpServletRequest) {
    MultipartHttpServletRequest mpRequest = (MultipartHttpServletRequest) request;
    MultipartFile file = mpRequest.getFile("file");
    DigestUtils.appendMd5DigestAsHex(file.getInputStream(), sb);
// other
} else {
    Map<String, String[]> params = request.getParameterMap();
    if (!params.isEmpty()) {
        // Sort parameter
        Map<String, String[]> treeMap = new TreeMap<>(params);
        for (Map.Entry<String, String[]> entry : treeMap.entrySet()) {
            sb.append(entry.getValue()[0]).append("&");
        }
        sb.deleteCharAt(sb.length() - 1); // Delete '&' character
    }   
    if (request instanceof BodyReaderHttpServletRequestWrapper) {
        BodyReaderHttpServletRequestWrapper requestWrapper = (BodyReaderHttpServletRequestWrapper) request;
        if (requestWrapper.hasBody()) {
            String body = new String(requestWrapper.getBody(), StandardCharsets.UTF_8);
            if (!params.isEmpty()) {
                // params is not empty, add '&' character
                sb.append("&");
            }
            sb.append(body);
        }
    }   
}
String time = request.getHeader("X-TC-Timestamp");
// No '&' character
sb.append(time);

return sb.toString();

• If Contiple authentication fails, the result is returned as shown below.

• (Please verify that the Authorization string is encrypted using the correct method.)

{
    "header": {
        "resultCode": 400,
        "resultMessage": "무효한 요청입니다.",
        "isSuccessful": false
    },
    "result": null
}

• Authentication failure condition:

400

1. Authorization is blank

2. X-TC-Timestamp is not numeric

3. X-TC-Timestamp is expired (valid within 5 minutes)

4. Multipart request but file is null

5. Authorization is incorrect

403

1. securityKey is null

2. clientIp is not allowed

---

➋ Common Return Results

2-1. Return Result Example

//성공: 상세
{
    "header": {
        "resultCode": 200,
        "resultMessage": "",
        "isSuccessful": true
    },
    "result": {
        "content": {
        }
    }
}

//성공: 리스트
{
    "header": {
        "resultCode": 200,
        "resultMessage": "",
        "isSuccessful": true
    },
    "result": {
        "contents": [{
        }]
    }
}

//실패
{
    "header": {
        "resultCode": 403,
        "resultMessage": "Access Denied",
        "isSuccessful": false
    },
    "result": null
}

---

2-2. Return Result Description

명칭	변수	데이터 타입	설명
Header	resultCode	Integer	Return result code, 200 indicates a successful request.
	resultMessage	String	Return error message
	isSuccessful	Boolean	Execution result (Sucess: true, Failure: false)
Result	contents	JSON	List result content
	content	JSON	Detail result content

---

2-3. Return Code

• 200 : SUCCESS

• 400 : Bad Request

• 403 : Access Denied(Forbidden)

• 404 : Not Data Found

• 500 : Server Error

• 9007 : The related data already exists.

• 9005 : No related data exists.

• 1001 : he inquiry limit has been exceeded. Please try again later.

  • The following cases apply when [Spam Management] → [Spam Inquiry Blocking] is enabled:

  • If inquiry creation is attempted 3 or more times within 1 minute from the same IP, ticket creation is blocked for 24 hours.

• 1002 : he inquiry limit has been exceeded. Please try again later.

  • The following cases apply when [Spam Management] → [Spam Inquiry Blocking] is enabled:

  • If inquiry creation is attempted 10 or more times within 24 hours from the same IP, ticket creation is blocked for 24 hours.

---

2-4. Return Code Details (Failure)

400

1. Authorization is blank

2. X-TC-Timestamp is not numeric

3. X-TC-Timestamp is expired (valid within 5 minutes)

4. Multipart request but file is null

5. Authorization is incorrect

403

1. securityKey is null

2. clientIp is not allowed

---

➌ API List

3-1. Development Environment URL

환경	BaseUrl
Alpha	https://{domain}.oc.alpha-nhncloud.com
Beta	https://{domain}.oc.beta-nhncloud.com
Real	https://{domain}.oc.nhncloud.com

---

3-2. Security Key URL

Security Key	URL
Security Key of Service	/{serviceId}/openapi/v1/*
Available for direct use without authentication	/{serviceId}/api/v2/*

---

3-3. API List

그룹	명칭	유형	URL	설명
Service	Service Details	GET	/{serviceId}/api/v2/service.json	Retrieve service information using the Service ID
Notice	Heading List	GET	/{serviceId}/api/v2/notice/categories.json	Retrieve the list of notice headings
	Tag List	GET	/{serviceId}/api/v2/notice/tags.json	Retrieve the list of notice tags
	Notice List	GET	/{serviceId}/api/v2/notice/list.json	Retrieve the Help Center notice list
	Notice Details	GET	/{serviceId}/api/v2/notice/detail/{id}.json	Retrieve notice content using the Notice ID
	Open & Download Notice Attachments	GET	/{serviceId}/api/v2/notice/attachments/{id}	Open or download notice attachments
FAQ	Category List	GET	/{serviceId}/api/v2/helpdoc/categories.json	Retrieve the FAQ category list
	FAQ List	GET	/{serviceId}/api/v2/helpdoc/list.json	Retrieve the Help Center FAQ list
	FAQ Detail	GET	/{serviceId}/api/v2/helpdoc/detail/{id}.json	Retrieve FAQ content using the FAQ ID
	Open & Download FAQ Attachments	GET	/{serviceId}/api/v2/helpdoc/attachments/{id}	Open or download FAQ attachments
Submit Inquiry	Inquiry Type List	GET	/{serviceId}/api/v2/ticket/categories.json	Retrieve the list of inquiry types within the service
	Inquiry Type Field List	GET	/{serviceId}/api/v2/ticket/field/user/{categoryId}.json	Retrieve the list of fields associated with a specific inquiry type
	Ticket Attachment Upload	POST	/{serviceId}/openapi/v1/ticket/attachments/upload.json	Upload files to the server
	Create Ticket	POST	/{serviceId}/openapi/v1/ticket.json	Create a new ticket
Inquiry History	Customer Ticket List	GET	/{serviceId}/openapi/v1/ticket/enduser/{usercode}/list.json	Display a customer’s ticket list based on search conditions
	Ticket Details	GET	/{serviceId}/openapi/v1/ticket/enduser/{usercode}/{ticketId}/detail.json	Retrieve details of a ticket submitted by the customer
	Open & Download Ticket Attachments	GET	/{serviceId}/api/v2/ticket/attachments/{id}	Open or download ticket attachments
	Customer Follow-up Inquiry	POST	/{serviceId}/openapi/v1/ticket/enduser/{usercode}/{ticketId}/comment.json	Submit a follow-up inquiry based on the Ticket ID