Open API Overview - NHN Cloud User Guide

Contact Center > Online Contact > API Guide for Developers > Open API Overview

In Online Contact, various support information such as Help Center announcements, FAQs, ticket information, and ticket creation is provided through the Open API.

By utilizing the Open API, support information from Online Contact can be easily accessed from external systems.

API Certification Method

Set Open API

To use the Open API provided by Online Contact, you must activate the feature in the [Service Management → Authentication] menu.

① Activate Open API

To use the Open API feature, click the Enable button.
When activated, a service key is automatically generated.

② Service Key

This is an authentication key used to call the API and encrypt transmitted data.
It is automatically generated when the Open API is activated, and you can change the key value by clicking Change API Key.

Authorization Header

You should set the following values to each request header.

Authorization: Authentication string generated by the security key
X-TC-Timestamp: Current UTC time value {new Date().getTime()}

For services that use the 'Security Service' feature, you can activate spam policies based on the customer's IP in the [Service Management → Security Service → Spam Management] menu. When creating tickets via the Open API, set the OC-Client-IP value in the Request Header, and the system will determine spam based on that IP.

OC-Client-IP: Customer IP address

To Create an Authorization String

You could create authorization string through encrypting by HmacSHA256, or encrypting(Organization ID + request URI + parameter value + Current UTC time value) string.

※ Note

You can check the NHN Cloud Organization ID in [Global Management → Contract Service Status → Organization Information].

Java Example

General Request(GET)

// Customer Ticket List
String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket/enduser/usercode/list.json?categoryId=1&language=ko";
String organizationId = "WopqM8euoYw89B7i"; // Organization ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // Service 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"); // Please connect the parameter values using the "&" symbol in alphabetical order of the parameter names (categoryId=1&language=ko) → (1&ko)
sb.append(timestamp);// Same as X-TC-Timestamp value

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();

General Request(POST)

// Create Ticket
String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket.json?language=ko";
String organizationId = "WopqM8euoYw89B7i"; // Organization ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // Service 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("&"); // Please connect the parameter values using the "&" symbol in alphabetical order of the parameter names.
sb.append(body);// Please append the string content of the body after the parameters.
sb.append(timestamp);// Same as X-TC-Timestamp value

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();

Upload File

String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket/attachments/upload.json";
String organizationId = "WopqM8euoYw89B7i"; // Organization ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // Service Key
String uri = "/APISimple/openapi/v1/ticket/attachments/upload.json"; // request uri
long timestamp = new Date().getTime();
StringBuilder sb = new StringBuilder();
sb.append(organizationId);
sb.append(uri);
DigestUtils.appendMd5DigestAsHex(file.getInputStream(), sb);// When attaching a file, the MD5 of the file should be added to the authentication string as a parameter value.
sb.append(timestamp);// Same as X-TC-Timestamp value

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 = new MultipartBody.Builder().setType(MultipartBody.FORM).addFormDataPart("file", file.getOriginalFilename(),
RequestBody.create(MediaType.parse(file.getContentType()), file.getBytes())).build();
Request request = new Request.Builder().url(ticketUploadUrl).post(body)
.header("Content-Type", "application/json")
.header("Authorization", signString)
.header("X-TC-Timestamp", Long.toString(timestamp))
.build();
Call call = client.newCall(request);
Response response = call.execute();

Authentication Method for OC

// 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();

Common Return Result

Example of Return Results

//Success: Details
{
    "header": {
        "resultCode": 200,
        "resultMessage": "",
        "isSuccessful": true
    },
    "result": {
        "content": {
        }
    }
}

//Success: Lists
{
    "header": {
        "resultCode": 200,
        "resultMessage": "",
        "isSuccessful": true
    },
    "result": {
        "contents": [{
        }]
    }
}

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

Return Result Description

Name	Variable	Data Type	Details
Header	resultCode	Integer	Result code, success is 200
	resultMessage	String	Result message(error)
	isSuccessful	Boolean	Execution result(Success: true, Failure: false)
Result	contents	JSON	Contents of result list
	content	JSON	Detailed contents of result

Return Code

200: SUCCESS
400: Bad Request
403: Access Denied(Forbidden)
404: Not Data Found
500: Server Error
9007: Related data exists
9005: No related data
1001, 1002: Inquiry limit exceeded (when using the 'Spam Management → Spam Inquiry Blocking' feature)

Return Code(Failure) Details

400

Authorization is blank
X-TC-Timestamp is not numeric
X-TC-Timestamp is expired(Valid in 5 minutes)
Multipart request but file is null
Authorization is incorrect

403

securityKey is null
clientIp is not allowed

List of APIs

Development Environment URL

Environment	BaseUrl
alpha	https://{domain}.oc.alpha-nhncloud.com
real	https://{domain}.oc.nhncloud.com

Security Key URL

Security Key	URL
Security Key of service	/{serviceId}/openapi/v1/*
Direct use without authentication	/{serviceId}/api/v2/*

API List

Group	Name	Type	URL	Description
Service	Service Details	GET	/{serviceId}/api/v2/service.json	Query service information via service ID
Notice	Heading List	GET	/{serviceId}/api/v2/notice/categories.json	Obtain a list of headings
	Tag List	GET	/{serviceId}/api/v2/notice/tags.json	Obtain a list of notice tags
	Notice List	GET	/{serviceId}/api/v2/notice/list.json	Help Center notice list
	Notice Details	GET	/{serviceId}/api/v2/notice/detail/{id}.json	Obtain the contents of notice through notice ID
	Open and Download Notice Attachments	GET	/{serviceId}/api/v2/notice/attachments/{id}	Open/download notice attachments
FAQ	Category List	GET	/{serviceId}/api/v2/helpdoc/categories.json	Acquire FAQ category list
	FAQ List	GET	/{serviceId}/api/v2/helpdoc/list.json	Help center FAQ list
	FAQ Details	GET	/{serviceId}/api/v2/helpdoc/detail/{id}.json	Obtain the contents of FAQ via FAQ ID
	Open and Download FAQ Attachments	GET	/{serviceId}/api/v2/helpdoc/attachments/{id}	Open/download FAQ attachments
Inquiry	Submission Type List	GET	/{serviceId}/api/v2/ticket/categories.json	Inquire list of in-service submission types
	List of Submission Type fields	GET	/{serviceId}/api/v2/ticket/field/user/{categoryId}.json	Check the list of corresponding fields through the submission type
	Upload Ticket Attachments	POST	/{serviceId}/openapi/v1/ticket/attachments/upload.json	Upload a file to the server
	Create Ticket	POST	/{serviceId}/openapi/v1/ticket.json	Create new ticket
Inquiry History	Customer Ticket List	GET	/{serviceId}/openapi/v1/ticket/enduser/{usercode}/list.json	View a list of tickets for customers who meet the search criteria
	Ticket Details	GET	/{serviceId}/openapi/v1/ticket/enduser/{usercode}/{ticketId}/detail.json	Inquire ticket details received by the customer
	Open and Download Ticket Attachments	GET	/{serviceId}/api/v2/ticket/attachments/{id}	Open/download ticket attachments
	Customer Re-Inquiry	POST	{serviceId}/openapi/v1/ticket/enduser/{usercode}/{ticketId}/comment.json	Re-inquiry based on ticket ID

Contact Center > Online Contact > API Guide for Developers > Open API Overview
API Certification Method
Common Return Result
List of APIs

TOP