Open API Overview - NHN Cloud User Guide

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

API Certification Method

Set Open API

You can create multiple services in one organization, and each service you create has a service key which is the only security key. From service key, the data sent to the API could be encrypted, and Open API related to service management could be used.(Ticket Management, FAQ, etc.)

You can ① enable/disable Open API on the Service Management → Authentication → OPEN API tab and view/change the ② Service Key.

Organization ID

You can view ① NHN Cloud Organization ID on the Global Management → Contract Service Status → Organization Information menu.

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()}
OUCODE：User code(Not required, default value is Owner if not set)

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.

Java Example

General Request(GET, POST)

String URL = "http://nhn-cs.alpha-oc.toast.com/APISimple/openapi/v1/ticket/enduser/usercode/list.json?categoryId=1&language=ko";
String organizationId = "WopqM8euoYw89B7i"; // NHN Cloud Organization ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // Service Key
String uri = "/APISimple/openapi/v1/ticket/enduser/usercode/list.json"; // request uri
StringBuilder sb = new StringBuilder();
sb.append(organizationId);
sb.append(uri);
sb.append("1").append("&").append("ko"); // Use in order(categoryId=1&language=ko) of parameters(1&ko)
sb.append(body);// If request body is present, add body string after the parameter
sb.append(new Date().getTime());// 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));

Upload File

String URL = "http://nhn-cs.alpha-oc.toast.com/APISimple/openapi/v1/ticket/attachments/upload.json";
String organizationId = "WopqM8euoYw89B7i"; // NHN Cloud Organization ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // Service 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);// When attaching a file, add the MD5 of the file to the authentication string as parameter value
sb.append(new Date().getTime());// 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));

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

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
Invalid paramter

403

securityKey is null
clientIp is not allowed

List of APIs

Development Environment URL

Environment	BaseUrl
alpha	https://{domain}.alpha-oc.toast.com
real	https://{domain}.oc.toast.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