> For the complete documentation index, see [llms.txt](https://docs.contiple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contiple.com/jp/api/open-api.md). # Open API *** ## **➊ API認証方法** ### **1-1. OPEN API 有効化** * \[サービス管理]→\[認証]でOPEN APIを有効にしてください。 * 有効化すると、サービス Keyが自動生成されます。 * API の呼び出しおよび送信されるデータの暗号化に使用される認証キーです。 * **API Key変更**ボタンをクリックして変更することができます。 *** ### **1-2. 認証 Header** > 各リクエストヘッダーに下記の値を必ず設定しなければなりません。 {% hint style="info" %} * 「セキュリティサービス」機能を使用しているサービスの場合、\[サービス管理] → \[セキュリティ管理] → \[スパム管理]メニューで顧客のIPを基準にスパムポリシーを有効化できます。 * Open APIを通じてチケットを作成する際、リクエストヘッダーにOC-Client-IP値を設定すると、該当IPを基準にスパムかどうかが判断されます。 {% endhint %} * **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 有効化](#id-1-1) にて発行された API Key を使用して暗号化し、認証キーを生成します。 * 暗号化方式には **HmacSHA256** を使用します。 #### ③ **認証キーの送信** * 生成した認証キーを、リクエスト Header の **Authorization** に設定し、Contiple に送信します。 * Contiple は、受信した Header および Body の変数値を同一の API Key で暗号化し、Hash 値を比較します。 * 一致した場合、API は正常に処理され、一致しない場合は **エラーコード 400** を返却します。 ### **1-4. JAVA 例題** #### **(1) 一般リクエスト(GET)** ```java // 顧客チケットリスト 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)** ```java // チケット作成 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) ファイルアップロード** ```java 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側の認証方法** ```java // 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 params = request.getParameterMap(); if (!params.isEmpty()) { // Sort parameter Map treeMap = new TreeMap<>(params); for (Map.Entry 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 文字列の暗号化方式が正しいかご確認ください。） ```json { "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. リターン結果例題** ```json //成功: 詳細 { "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. リターン結果の説明**
名称変数データタイプ説明
HeaderresultCodeIntegerリターン結果コード：正常時は 200
resultMessageStringリターン エラーメッセージ
isSuccessfulBoolean実行結果(成功: true、失敗: false)
ResultcontentsJSON一覧結果内容
contentJSON詳細結果内容
*** ### **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
Alphahttps://{domain}.oc.alpha-nhncloud.com
Betahttps://{domain}.oc.beta-nhncloud.com
Realhttps://{domain}.oc.nhncloud.com
*** ### **3-2. Security Key URL**
Security KeyURL
サービスの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を基準に再お問い合わせ |