Contact Center > Online Contact > API 가이드 > Open API 개요

Online Contact에서는 헬프센터 공지사항, FAQ, 티켓 정보, 티켓 생성 등 다양한 상담 정보를 Open API로 제공합니다.

Open API를 활용하여 외부 시스템에서 Online Contact의 상담 정보를 쉽게 확인할 수 있습니다.

API 인증방법

Open API 설정

OpenAPI_설정

Online Contact에서 제공하는 Open API를 사용하려면 [서비스관리 → 인증] 메뉴에서 기능을 활성화해야 합니다.

① OPEN API 활성화

  • Open API 기능을 사용하려면 활성화 버튼을 클릭합니다.
  • 활성화 시 서비스 Key가 자동 생성됩니다.

② 서비스 Key

  • API를 호출하고, 전송되는 데이터를 암호화하는데 사용되는 인증 키입니다.
  • Open API 활성화 시 자동 생성되며, API Key 변경을 클릭하면 Key 값을 변경할 수 있습니다.

각 Request Header에 아래의 값들을 반드시 설정해야 합니다.

  • Authorization: Security Key를 통해 생성된 인증 문자열
  • X-TC-Timestamp: 현재 UTC 시간 값{new Date().getTime()}

'보안 서비스' 기능을 사용하는 서비스의 경우, '서비스 관리 → 보안서비스 → 스팸 관리' 메뉴에서 고객의 IP를 통한 스팸 정책을 활성화할 수 있습니다. Open API를 통해 티켓 생성 시, OC-Client-IP 값을 Request Header에 설정하시면 해당 IP를 기준으로 스팸 여부를 판단합니다.

  • OC-Client-IP: 고객 IP 주소

Authorization 문자열 생성 방법

HmacSHA256로 암호화하거나, (NHN Cloud 조직ID + request URI + 파라미터 값 + 현재 UTC시간 값)문자열에 대해 암호화하여 Authorization 문자열을 생성하실 수 있습니다.

※ 참고사항

NHN Cloud 조직ID는 [전체관리 → 계약 서비스 현황 → 조직 정보] 에서 확인할 수 있습니다.

Java 예제

일반 요청(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();
일반 요청(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();
파일 업로드
String URL = "http://nhn-cs.oc.nhncloud.com/APISimple/openapi/v1/ticket/attachments/upload.json";
String organizationId = "WopqM8euoYw89B7i"; // 조직ID
String securityKey = "431402c0eaaf46d889f243db9e7492e2"; // 서비스 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);// 파일 첨부 시 , 파일의 MD5는 파라미터 값으로 인증 문자열에 추가
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 = 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();
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();

공통 리턴 결과

리턴 결과 예제

//성공: 상세
{
    "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
}

리턴 결과 설명

명칭 변수 데이터 타입 설명
Header resultCode Integer 리턴 결과 Code, 정상은 200
resultMessage String 리턴 오류 메시지
isSuccessful Boolean 실행 결과(성공: true, 실패: false)
Result contents JSON 목록 결과 내용
content JSON 상세 결과 내용

리턴 코드

  • 200: SUCCESS
  • 400: Bad Request
  • 403: Access Denied(Forbidden)
  • 404: Not Data Found
  • 500: Server Error
  • 9007: 관련된 데이터가 이미 존재
  • 9005: 관련된 데이터가 없음
  • 1001, 1002: 문의 횟수 상한 초과 ('스팸 관리 → 반복 문의 차단' 기능 사용 시)

리턴 코드(실패) 상세

400
  1. Authorization is blank
  2. X-TC-Timestamp is not numeric
  3. X-TC-Timestamp is expired(5분 내 유효)
  4. Multipart request but file is null
  5. Authorization is incorrect
403
  1. securityKey is null
  2. clientIp is not allowed

API 목록

개발 환경 URL

환경 BaseUrl
알파 https://{domain}.oc.alpha-nhncloud.com
리얼 https://{domain}.oc.nhncloud.com

Security Key URL

Security Key URL
서비스의 Security Key /{serviceId}/openapi/v1/*
인증 없이 직접 사용 가능 /{serviceId}/api/v2/*

API 목록

그룹 명칭 유형 URL 설명
서비스 서비스 상세 GET /{serviceId}/api/v2/service.json 서비스 ID를 통해 서비스 정보 조회
공지사항 말머리 리스트 GET /{serviceId}/api/v2/notice/categories.json 공지사항 말머리 리스트 취득
태그 리스트 GET /{serviceId}/api/v2/notice/tags.json 공지사항 태그 리스트 취득
공지사항 리스트 GET /{serviceId}/api/v2/notice/list.json 헬프센터 공지사항 리스트
공지사항 상세 GET /{serviceId}/api/v2/notice/detail/{id}.json 공지사항 ID를 통해 공지사항 내용 취득
공지사항 첨부파일 열기 및 다운로드 GET /{serviceId}/api/v2/notice/attachments/{id} 공지사항 첨부파일 열기/다운로드
FAQ 카테고리 리스트 GET /{serviceId}/api/v2/helpdoc/categories.json FAQ 카테고리 리스트 취득
FAQ 리스트 GET /{serviceId}/api/v2/helpdoc/list.json 헬프센터 FAQ 리스트
FAQ 상세 GET /{serviceId}/api/v2/helpdoc/detail/{id}.json FAQ ID를 통해 FAQ 내용 취득
FAQ 첨부파일 열기 및 다운로드 GET /{serviceId}/api/v2/helpdoc/attachments/{id} FAQ 첨부파일 열기 및 다운로드
문의 접수 접수유형 리스트 GET /{serviceId}/api/v2/ticket/categories.json 서비스 내 접수유형 리스트 조회
접수유형 필드 리스트 GET /{serviceId}/api/v2/ticket/field/user/{categoryId}.json 접수유형을 통하여 대응되는 필드 리스트 확인
티켓 첨부파일 업로드 POST /{serviceId}/openapi/v1/ticket/attachments/upload.json 서버에 파일 업로드
티켓 생성 POST /{serviceId}/openapi/v1/ticket.json 신규 티켓 생성
문의 내역 고객 티켓 리스트 GET /{serviceId}/openapi/v1/ticket/enduser/{usercode}/list.json 검색 조건을 통해 조건에 맞는 고객의 티켓 리스트 노출
티켓 상세 GET /{serviceId}/openapi/v1/ticket/enduser/{usercode}/{ticketId}/detail.json 고객이 접수한 티켓 상세 조회
티켓 첨부파일 열기 및 다운로드 GET /{serviceId}/api/v2/ticket/attachments/{id} 티켓 첨부파일 열기/다운로드
고객 재문의 POST {serviceId}/openapi/v1/ticket/enduser/{usercode}/{ticketId}/comment.json 티켓 ID 기준으로 고객 재문의
목차
TOP