Open API

Contiple が提供するヘルプセンターのお知らせ、FAQ、チケット情報など、さまざまな問い合わせ関連情報を Open API を通じてご活用いただけます。

---

➊ API認証方法

1-1. OPEN API 有効化

• [サービス管理]→[認証]でOPEN APIを有効にしてください。

• 有効化すると、サービス Keyが自動生成されます。

  • API の呼び出しおよび送信されるデータの暗号化に使用される認証キーです。

  • API Key変更ボタンをクリックして変更することができます。

---

1-2. 認証 Header

各リクエストヘッダーに下記の値を必ず設定しなければなりません。

• 「セキュリティサービス」機能を使用しているサービスの場合、[サービス管理] → [セキュリティ管理] → [スパム管理]メニューで顧客のIPを基準にスパムポリシーを有効化できます。

• Open APIを通じてチケットを作成する際、リクエストヘッダーにOC-Client-IP値を設定すると、該当IPを基準にスパムかどうかが判断されます。

• Authorization: Security Keyで生成された認証文字列

• X-TC-Timestamp: 現在のUTC時間値{newDate().getTime()}

• OC-Client-IP: 顧客のIPアドレス (設定しない場合、デフォルトのOwner)

---

1-3. Authorization 文字列の生成方法

① 下記のルールに従って文字列を生成

• 組織ID(Organization ID)

  • NHN Cloudの組織IDです。［全体管理 ＞ 契約サービス管理 ＞ 組織情報］画面から確認できます。

  • AbcdE1fghIj23K4x のような形式で構成されています。

• API URI

  • 呼び出す API の URI を入力します。URI にはサービス ID を含める必要があります。

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

• クエリパラメータ

  • 呼び出す API にクエリパラメータが存在する場合、キー（Key）をアルファベット順に並び替えた後、値（Value）を & 記号で連結します。パラメータが 1 件のみの場合は & 記号を使用せず、パラメータが存在しない場合は省略します。

  • 例:

    • クエリパラメータが page=1&pageSize=10&language=ko の場合、

    • キー（Key）をアルファベット順に並び替え : language=ko&page=1&pageSize=10

    • 値（Value）を & 記号で連結 : ko&1&10

• タイムスタンプ

  • API をリクエストする時点の Timestamp を適用します。リクエスト Header に送信される X-TC-Timestamp の値と一致している必要があります。

  • 例: 1764031689401

② 文字列の暗号化

• 生成した文字列を、1-1. Open API 有効化 にて発行された API Key を使用して暗号化し、認証キーを生成します。

• 暗号化方式には HmacSHA256 を使用します。

③ 認証キーの送信

• 生成した認証キーを、リクエスト Header の Authorization に設定し、Contiple に送信します。

• Contiple は、受信した Header および Body の変数値を同一の API Key で暗号化し、Hash 値を比較します。

• 一致した場合、API は正常に処理され、一致しない場合は エラーコード 400 を返却します。

1-4. JAVA 例題

(1) 一般リクエスト(GET)

// 顧客チケットリスト
String URL = "http://yourOrg.oc.nhncloud.com/yourService/openapi/v1/ticket/enduser/usercode/list.json?categoryId=1&language=ko";
String organizationId = "AbcdE1fghIj23K4x"; // OrganizationID
String securityKey = "123456a0bcde12a789b123bc4d1234a1"; // Service API Key
String uri = "/yourService/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) 一般リクエスト(POST)

// チケット作成
String URL = "http://yourOrg.oc.nhncloud.com/yourService/openapi/v1/ticket.json?language=ko";
String organizationId = "AbcdE1fghIj23K4x"; // OrganizationID
String securityKey = "123456a0bcde12a789b123bc4d1234a1"; // Service API Key
String uri = "/yourService/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) ファイルアップロード

String URL = "http://yourOrg.oc.nhncloud.com/yourService/openapi/v1/ticket/attachments/upload.json";
String organizationId = "AbcdE1fghIj23K4x"; // OrganizationID
String securityKey = "123456a0bcde12a789b123bc4d1234a1"; // Service API Key
String uri = "/yourService/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();

(3) Contiple側の認証方法

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

• Contipleの認証に失敗した場合、結果は以下のとおり返却されます。 （Authorization 文字列の暗号化方式が正しいかご確認ください。）

{    
    "header": {        
        "resultCode": 400,        
        "resultMessage": "無効なリクエストです。",        
        "isSuccessful": false    
        },    
        "result": null
}​​

• 認証失敗のケース

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

---

➋ 共通リターン結果

2-1. リターン結果例題

//成功: 詳細
{
    "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. リターン結果の説明

名称	変数	データタイプ	説明
Header	resultCode	Integer	リターン結果コード：正常時は 200
	resultMessage	String	リターン エラーメッセージ
	isSuccessful	Boolean	実行結果(成功: true、失敗: false)
Result	contents	JSON	一覧結果内容
	content	JSON	詳細結果内容

---

2-3. リターンコード情報

• 200 : SUCCESS

• 400 : Bad Request

• 403 : Access Denied(Forbidden)

• 404 : Not Data Found

• 500 : Server Error

• 9007 : 関連データが既に存在

• 9005 : 関連データなし

• 1001 : お問い合わせの回数が上限を超えています。 しばらくしてからお問い合わせください。

  • [スパム管理] → [スパム問い合わせのブロック] 機能使用時に作動

  • 同一IPで1分以内に3回以上問い合わせを試みた場合、24時間チケットの生成がブロックされます。

• 1002 : お問い合わせの回数が上限を超えています。 しばらくしてからお問い合わせください。

  • [スパム管理] → [スパム問い合わせのブロック] 機能使用時に作動

  • 同一IPで24時間以内に10回以上問い合わせを試みた場合、24時間チケットの生成がブロックされます。

---

2-4. リターン コード(失敗) 詳細

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

6. Invalid parameter

403

1. securityKey is null

2. clientIp is not allowed

---

➌ API 目録

3-1. 開発環境 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	/{serviceId}/openapi/v1/*
認証なしで直接使用可能	/{serviceId}/api/v2/*

---

3-3. 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を基準に再お問い合わせ