顧客API連携
顧客社API連携は、CLUeデバイスが認識したクレデンシャル（顔、指紋、RFカード、PIN、CLUe QR、カスタムQRなど）を顧客社が運用する外部APIに送信し、その応答に応じて入室を許可または拒否する入退室方式です。 この方式を使うと、入室権限、勤怠、訪問者管理などの顧客社固有のポリシーを、個別開発なしでCLUe入退室制御に直接反映できます。
CLUeはクレデンシャルを認識して顧客社APIへ送信する役割のみを担い、実際の入室許可可否は顧客社APIの応答で決まります。
開始する前に
対象
この文書はプレース グループ管理者とプレース管理者を対象にしています。
-
プレース グループ管理者: 顧客社（Vendor）APIを登録、編集、削除し、クレデンシャルタイプとAPIをマッピングし、設定を下位プレースに適用します。
-
プレース管理者: プレース グループから継承した設定を確認し、必要なときにプレース別の上書きを適用します。
この文書は、HTTPS、HTTPステータスコード、Webhook（HTTP POST）、JSON、JSONPathに慣れたIT管理者を対象にしています。 顧客社API仕様（URL、認証ヘッダー、リクエスト/レスポンスJSON構造）は、事前に顧客担当者と相談してください。
事前準備
-
このメニューにアクセスするには、対象のプレース グループ（またはプレース）に管理者として招待されている必要があります。
-
顧客社の認証用Webhook URL（HTTPS必須、HTTP POST受信）と必要な認証ヘッダー値を事前に準備してください。
主な用語
| 用語 | 説明 |
|---|---|
| 顧客社API連携（Customer API Integration） | ユーザーがデバイスにクレデンシャルを提示すると、クレデンシャルデータを顧客社（Vendor）が運用する外部APIへ送信して検証する入退室方式です。 |
| クレデンシャル（Credential） | 顔 / 指紋 / RFカード / ユーザーPIN / CLUe QR / カスタムQR |
| Webhook URL | CLUeからの認証リクエスト（HTTP POST、Content-Type: application/json）を受信するために、顧客社サーバーが公開するHTTPSエンドポイントです。 |
| リクエストヘッダー（Request Header） | 認証と権限付与のために、リクエストと一緒に送信するKey/Valueペアです。 （例: Authorizationトークン） |
| 自動フィールド | システムがリクエスト本文に自動で入力する値です。 必要なフィールドだけを選択してください。 |
| 手動フィールド | 管理者がリクエスト本文に含めるために直接入力する固定値です。 |
| 判定基準（Judgment Criteria） | 顧客社応答を入室許可または拒否として解釈するルールセット（statusCode、成功結果Key/Value、成功/失敗メッセージキー）です。 画面では レスポンス解析 セクションとして表示されます。 |
| 判定モード（Judgment Mode） | 判定基準を構成する要素です。 HTTP応答コードのみ使用 / 応答本文フィールドのみ使用 / 両方の組み合わせから1つを選択します。 |
顧客社API連携
顧客社API連携は、CLUeデバイスが認識したクレデンシャルデータを顧客社が運用するHTTPS APIへ送信し、その応答を基に入室の許可/拒否を判定する入退室方式です。 これにより、入室権限、勤怠、訪問者管理などの顧客社固有のポリシーをCLUe入退室制御に直接反映できます。
-
顔、指紋、RFカード、PIN、CLUe QR、カスタムQRなど、クレデンシャルタイプごとに異なる顧客社APIを連携できます。
-
登録を保存する前に、テスト呼び出しで連携動作を事前に確認できます。
-
CLUeはクレデンシャルを識別して送信する役割のみを担い、実際の許可または拒否の判断は顧客社APIの応答で決まります。
対応クレデンシャル
-
顔
-
指紋
-
RFカード
-
ユーザーPIN
-
CLUe QR
-
カスタムQR
プレース グループとプレースの役割
| レベル | 役割 | 担当業務 |
|---|---|---|
| プレース グループ | プレース グループ管理者 | 顧客社APIの登録/編集/削除、APIとクレデンシャルの連携 |
| プレース | プレース管理者 | 継承した設定の確認、必要に応じたプレース別上書きの適用 |
適用ルール
-
プレース グループレベルで保存: 同じ設定が、そのプレース グループのすべての下位プレースに即時適用されます。 既存のプレース別上書きは、プレース グループ値で上書きされます。
-
プレースレベルで保存: そのプレースにのみ適用されます。 他のプレースや上位のプレース グループには影響しません。
主な作業ワークフロー
顧客社API連携は、大きく2つのワークフロー（Workflow）で構成されます。 管理者が最初に行う設定ワークフローと、ユーザーが実際に入室を試行したときに進行する入室イベントワークフローです。
設定ワークフローの概要
管理者が実行するステップです。 各ステップは第4章から詳しく説明します。
-
（プレース グループ）入退室方式を選択してください。
-
お客様の確認 または 混合 / 高度な方法
-
左サイドバーで 顧客先API連携 項目が有効になります。
-
-
（プレース グループ）顧客先API連携 でAPIを登録してください。
基本情報 → カスタムヘッダー → 自動フィールド → 手動フィールド → テスト実行 → 応答パース設定 → 保存
-
（プレース グループ）登録したAPIを各クレデンシャルに連携してください。
保存すると、同じ設定がすべての下位プレースに自動適用されます。
-
（オプション）プレース別の上書きを設定してください。
選択したプレースにのみ適用されます。 既定値はプレース グループ設定をそのまま使用します。
入室イベントワークフローの概要
設定完了後、ユーザーが実際に入室を試行するときの処理順です。
-
ユーザーがデバイスにクレデンシャルを提示します。 （顔 / 指紋 / RFカード / PIN / CLUe QR / カスタムQR）
-
デバイス → CLUeサーバーへ検証リクエストを送信します。
-
CLUeサーバー → 顧客社サーバーへ検証リクエストを送信します。
登録済みWebhook URL、カスタムヘッダー、自動フィールド、手動フィールドを含みます
-
CLUeサーバーが顧客社応答を基に入室可否を判定します。
設定した判定基準に従って、許可/拒否を決定します。
-
結果をデバイスへ返します。
応答にメッセージが含まれている場合、デバイス画面に表示されます。
設定ワークフロー
1段階 — 顧客社API連携を有効化
-
CLUe Webポータルにログインしてください。
-
プレース グループを選択してください。
-
画面右上の → 詳細設定 をクリックしてください。
-
画面左側のサイドバーで サービス設定 をクリックします。
初期状態では アクセス方法 は 選択無し に設定されています。 この状態では、どの設定も有効になりません。
-
アクセス方法 で お客様の確認 を選択してください。
-
確認対象 セクションが表示されます。
確認対象 セクションには、対応する6つのクレデンシャルがすべて表示されます。 その後、各クレデンシャルに登録した顧客社APIを連携できます。
-
左サイドバーで 顧客先API連携 が有効になったらクリックしてください。
-
顧客先API連携 は、アクセス方法 が お客様の確認 または 混合 / 高度な方法 に設定されているときに有効になります。
-
この段階では保存は不要です。 連携するAPIを登録するには、#vendorApiregistrationを参照してください。
2段階 — 顧客社API登録
API追加
-
画面右上の API ボタンをクリックしてください。
-
API パネルが表示されたら、必要な情報を入力してください。
基本情報入力
| フィールド | 説明 | 必須かどうか | 入力ルール |
|---|---|---|---|
| コネクタ名 | この連携を識別する名前を入力してください。 | 必須 | 最大64文字まで入力できます。 |
| 認証方式 | このAPIを使用するクレデンシャルを選択してください。 | 必須 | 6つのタイプから1つを選択してください。 |
| Webhook URL | 顧客社Webhook URLです。 | 必須 | https://で始まる必要があり、最大512文字です。 http:// URLは保存できません。 |
認証方式 は一度設定すると変更できません。 他のクレデンシャルタイプで使うには、新しいAPIを登録してください。
リクエスト仕様
CLUeは、登録したURLにHTTP POST、Content-Type: application/jsonリクエストのみ送信します。 顧客社APIはこの形式のリクエストを受信できる必要があり、GET、PUT など他のメソッドのみを許可するエンドポイントは使用できません。
応答仕様
顧客社APIは応答ヘッダーに Content-Type: application/json を含め、応答本文をJSON形式で返す必要があります。 HTMLエラーページ、プレーンテキスト、XMLなどのJSON以外の応答はCLUeがパースできないため、テストと実際の入室検証の両方が失敗します。
{
"valid": true,
"message": "Access granted."
}
上の例では、判定基準の Key を $.valid、Value を true（BOOLEAN）に設定して成功条件を定義し、成功メッセージ JSONPath を $.message に設定して成功メッセージを表示できます。 実際のキー名と構造は、顧客社API仕様に合わせてください。
登録制限
クレデンシャルタイプごとに最大3件のAPIを登録できます。 つまり、顔、指紋、RFカード、PIN、CLUe QR、カスタムQRの6タイプを合わせて、プレース グループごとに最大18件のAPIを登録できます。 すでに3件登録されているクレデンシャルタイプには、追加登録できません。 各クレデンシャルで実際に使用するAPIは、#credentialApiAssignmentで選択します。
カスタムヘッダー追加
顧客社APIでAuthentication/Authorization headersを要求する場合は、カスタムヘッダーを追加してください。
例:
Authorizationトークン、APIキー
| フィールド | 説明 |
|---|---|
| ヘッダー名 | ヘッダー名（例: Authorization）を入力してください。 重複した名前は許可されません。 |
| ヘッダー値 | ヘッダー値を入力してください。 |
-
カスタムヘッダーは最大10件まで追加できます。
-
顧客社APIが公開エンドポイントである場合や、別途ヘッダーが不要な場合は、このセクションを空のままにしてください。
-
行を挿入するには 追加 ボタンをクリックし、削除するには ボタンをクリックしてください。
固定ヘッダーは設定できません
Content-Type と Accept はカスタムヘッダーとして追加できません。 CLUeが内部的に Content-Type: application/json と Accept: application/json を固定値で送信するため、管理者が別途指定する必要はありません。 この名前でヘッダーを追加しようとしても保存されません。 顧客社APIは、この2つのヘッダーを前提に設計してください。
自動フィールド選択
自動フィールドは、システムがリクエスト本文に自動で入力する値です。 使用できる自動フィールドは、クレデンシャルタイプによって異なります。 各フィールドの値の位置は {{...}} プレースホルダーで表示され、リクエスト時に実際のデバイス/ユーザー値に置き換えられます。
| 基本キー | プレースホルダー（値の位置） | 使用可能対象 | 実際の値 |
|---|---|---|---|
deviceId | {{DEVICE_SERIAL}} | すべてのクレデンシャルタイプ | 要求したデバイスのシリアル番号 |
userKey | {{USER_KEY}} | 顔 / 指紋 / CLUe QR | CLUeが管理するユーザー識別子 |
rfCard | {{CARD_NUMBER}} | RFカード | 提示したカード番号 |
uniquePin | {{UNIQUE_PIN}} | ユーザーPIN | 入力したPIN値 |
qrCode | {{QR_CODE}} | カスタムQR | QRペイロード |
フィールド選択ルール
-
各フィールド左側のチェックボックスで、リクエストに含めるかどうかを決定します。
-
すべてを選択する必要はありません。 顧客社APIが判定に実際に必要とする値だけを選択してください。 不要なデータを減らすと、問題の診断が容易になります。
-
キー（フィールド名）は編集できます。 顧客社APIが要求する名前（例:
userKey → employeeId）に合わせて変更してください。 値の位置のプレースホルダーはシステムで固定されるため、変更できません。 -
各フィールドのデータ形式（例:
STRING）は、フィールド右側に表示されます。
-
5つ以外のプレースホルダーは追加できません。 顧客社APIが追加値を要求する場合は、#manualFieldを参照して固定値を追加するか、顧客社と相談してデバイスシリアル番号やユーザーキーから顧客社側で派生させるようにしてください。
-
自動フィールドと手動フィールドを合わせて、リクエスト本文に最大10件のフィールドを含められます。 自動フィールドを多く選択するほど、使用できる手動フィールド数は減ります。
手動フィールド追加
顧客社APIが固定値をリクエストに含めるよう要求する場合は、手動フィールドを追加してください。
| フィールド | 説明 |
|---|---|
| フィールド名 | フィールド名は一意である必要があり、自動フィールド名とも異なる必要があります。 |
| フィールドタイプ | STRING、NUMBER、BOOLEAN から選択してください。 |
| 値 | このフィールドの値を入力してください。 選択したタイプに応じて、適切なJSONデータ型に変換されます。 例: NUMBER: 123、STRING: \"123\"、BOOLEAN: true/false |
-
自動フィールドと手動フィールドを合わせて、最大10件まで含められます。
-
追加された手動フィールドがない場合は、手動フィールドが定義されていません。 メッセージが表示されます。
-
行を挿入するには 追加 ボタンをクリックし、削除するには ボタンをクリックしてください。
APIテスト実行
基本情報、カスタムヘッダー、自動フィールド、手動フィールドを完了したら、判定基準（judgment criteria）を構成する前にテストを実行してください。 テストで得た実際の応答（response）は、判定基準の構成（#responseParsing）に必要です。
API パネル右側の API テストコンソール を使用してください。
テストパラメーター
テストコンソールに表示される入力フィールドは、クレデンシャルタイプによって異なります。 端末 ID（デバイスシリアル番号）はすべてのタイプで必須です。残りの入力値は、該当クレデンシャルタイプで使う値を顧客社が管理する形式のまま入力してください。
| 認証方式 | 入力する値 | 対応するプレースホルダー |
|---|---|---|
| すべてのタイプ | 端末 ID — 9~12桁の数字、デバイスシリアル番号 | {{DEVICE_SERIAL}} |
| 顔 / 指紋 / CLUe QR | ユーザー キー — 1~64文字、CLUeが管理するユーザー識別子 | {{USER_KEY}} |
| RFカード | 顧客社が管理するカード番号 | {{CARD_NUMBER}} |
| ユーザーPIN | 顧客社が管理するユーザーPIN | {{UNIQUE_PIN}} |
| カスタムQR | 顧客社が管理するQRペイロード | {{QR_CODE}} |
テストコンソールに入力した値は、自動フィールドのプレースホルダーを置き換え、実際のリクエスト本文として送信されます。 テストでは、顧客社データベースに実際に存在する値を入力し、許可と拒否の応答の両方を確認してください。 実運用環境では、デバイスが認識した値が自動で代入されます。
テスト実行
-
コンソール下部の テスト実行 ボタンをクリックしてください。
-
テスト実行中は進行表示が出ます。
-
結果を受け取ると、リクエスト/レスポンス内容が ターミナル出力 コンソール領域に表示されます。
実行中にパネルを閉じるか、前のステップへ移動するとテストは中断されます。
応答を正常に受信したら、次のステップに進み、応答内容を基に判定基準（judgment criteria）を構成してください。 URL、ヘッダー、フィールド設定の問題で応答を受信できなかった場合は、該当入力値を確認してから再度テストしてください。
保存前の必須条件
設定を保存 ボタンは、少なくとも1回テストに成功すると有効になります。 ここでの成功とは、顧客社サーバーから何らかのHTTP応答（4xx、5xxを含む）を受信したことを意味します。 ネットワークエラーで応答を受信できなかった場合は保存できません。
テスト失敗例 — 応答本文がJSONではない場合
顧客社サーバーが応答を返しても、本文がJSON形式でないか、応答ヘッダーの Content-Type が application/json でない場合は、テストコンソールにエラーと失敗ログが表示され、設定を保存 ボタンは有効になりません。
#responseSpecを参照し、顧客担当者と一緒にAPIが次の2条件を両方満たすか確認してください。
-
応答ヘッダーに
Content-Type: application/jsonが含まれているか -
応答本文が有効なJSONか（HTMLエラーページ、プレーンテキスト、XMLなどではないか）
応答パース設定
受信した応答を基に、この段階でどの応答を入室許可（成功）として解釈するかを定義します。 設定した基準に一致する応答は入室許可として、それ以外はすべて入室拒否として処理します。
判定モードは、入力したフィールドに応じて自動で決まります。 statusCode と 成功結果 JSONPath の少なくとも1つは必ず入力する必要があり、両方空のままでは保存できません。
| # | モード | 入力 | 成功基準 |
|---|---|---|---|
| 1 | 応答コード検証 | statusCode のみ | HTTPステータスコードが一覧の値のいずれかと一致すると成功します。 |
| 2 | 応答本文検証 | 成功結果 JSONPath のみ | HTTP応答コードに関係なく、本文の Key = Value 条件を満たすと成功します。 条件を満たせば、4xx/5xx応答でも許可されます。 |
| 3 | 結合検証 | 両方 | ステータスコードが一致し、同時に本文条件も満たすと成功します。 ステータスコードが一致しない場合は、本文を評価しません。 |
statusCode（モード1、3で使用）
-
100〜399の範囲の整数のみ指定できます。
4xx、5xxコードは成功として指定できません。 -
最大3件まで指定でき、重複値は許可されません。
-
複数値を指定した場合は、いずれか1つでも一致すれば成功（例:
200、201）として処理します。
成功結果 JSONPath（モード2、3で使用）
-
成功応答を識別する
Key、Value、データ形式（BOOLEAN、STRING、NUMBER）を入力します。 -
成功キー条件は1件だけ設定できます。
-
この条件に一致しない応答は入室拒否として処理されます。
成功メッセージ JSONPath / 失敗メッセージ JSONPath（オプション）
-
認証成功/失敗時に、それぞれデバイス画面に表示する文字列を抽出するキーを指定します。 通常は
$.messageを使用します。 -
指定しなくても保存できます。 空のままにすると、許可/拒否のみ判定し、デバイス画面にメッセージは表示されません。
-
成功と失敗で異なるキーを指定できます。
-
指定したキーの値は必ず文字列である必要があり、デバイス画面サイズを考慮して長すぎないようにしてください。
JSONPathを直接入力しづらい場合
応答領域からフィールドを 成功結果 JSONPath、成功メッセージ JSONPath、失敗メッセージ JSONPath の入力欄へドラッグ＆ドロップすると、JSONパスが自動で入力されます。 JSONPathを直接書く必要はありません。
保存
API パネル下部の 設定を保存 ボタンは、すべての必須項目と判定基準が正しく入力され、APIテストが少なくとも1回成功したときに有効になります。
-
必須フィールドの不足、URL形式エラー、指定タイプに変換できない手動フィールド値、判定基準の未入力、テスト未成功（ネットワークエラー含む）のいずれかがある場合、設定を保存 ボタンは無効のままです。
-
登録を完了するには、設定を保存 ボタンをクリックしてください。
APIを保存するとパネルが閉じ、新しく登録したAPIが一覧にカードとして表示されます。 カードには、名前、クレデンシャルタイプ、登録済みURLなどの情報が表示されます。
-
APIを編集するには、カードをクリックしてください。 編集パネルが開きます。 コネクタ名、Webhook URL、自動フィールド、手動フィールド、レスポンス解析 を編集できます。 認証方式 は編集できません。
-
削除: 登録したAPIを削除します。 このAPIがクレデンシャルに連携されていた場合、その連携も自動で解除され、変更はすぐにデバイスへ適用されます。 連携解除されたクレデンシャルは、その後は顧客社検証なしでデバイス本体認証のみで動作します。 運用の空白が心配な場合は、削除前に代替APIを先に登録して連携してください。
3段階 — 各クレデンシャルへのAPI割り当て
画面左側のサイドバーで サービス設定 → サービス設定 をクリックしてください。 確認対象 セクションで、各クレデンシャルに使用するAPIを指定してください。
-
各クレデンシャル横のドロップダウンをクリックすると、登録済みAPIの一覧が表示されます。 選択したクレデンシャルと認証方式が一致するAPIのみ表示されます。
-
顔、指紋、RFカード、PIN、CLUe QR、カスタムQRの各クレデンシャルに使用するAPIを選択してください。 クレデンシャルごとに異なるAPIを指定できます。
-
APIを指定していないクレデンシャルは、デバイス本体認証のみで動作します。 そのクレデンシャルには顧客社APIへの検証リクエストは送信されません。 顧客社検証が不要と判断したクレデンシャルだけを、未指定のままにしてください。
保存と適用ルール
クレデンシャルに登録したAPIを指定して 修正 ボタンをクリックすると、変更を下位プレースに適用するかどうかの確認ダイアログが表示されます。
-
確認: 同じ設定が現在のプレース グループのすべての下位プレースに即時適用されます。 既存のプレース別上書きは、プレース グループ値で上書きされます。
-
キャンセル: 変更を保存しません。
ほとんどの場合、プレース グループレベルの設定だけで、すべての下位プレースを同じように運用できます。 特定のプレースに別のAPIを上書きする方法は、#spaceOverrideを参照してください。
4段階 — プレース別上書き設定（オプション）
プレース グループから継承した設定とは別に、特定のプレースにだけ別のAPIを指定する方法を案内します。 特定のプレースにのみ適用した設定は、他のプレースや上位のプレース グループに影響しません。
-
プレース グループ配下の特定のプレースへ移動してください。
-
画面左側のサイドバーで 設定 → サービス設定 をクリックしてください。
-
確認対象 セクションの各クレデンシャルのドロップダウンで、このプレースでのみ使用する別のAPIを選択してください。
-
変更を保存するには、修正 ボタンをクリックしてください。
変更は現在のプレースにのみ保存されます。 他のプレースには適用されません。
そのプレースに管理者として招待されたプレース管理者だけが、設定 → サービス設定 にアクセスできます。
特定のプレースにAPIを指定した後、上位のプレース グループでクレデンシャル-API指定を変更して保存すると、プレース別上書きはプレース グループ値で上書きされます。 プレース グループ変更後もプレース別設定を維持する必要がある場合は、プレース グループ更新後に特定のプレースの 設定 → サービス設定 で再指定してください。
入力ルール要約
| フィールド | 必須かどうか | ルール |
|---|---|---|
| コネクタ名 | 必須 | 最大64文字 |
| 認証方式 | 必須 | 保存後は変更不可 |
| Webhook URL | 必須 | https://必須 / 最大512文字 / CLUeはこのURLにHTTP POST/application/jsonリクエストのみ送信 |
| 認証方式 API数 | - | クレデンシャルタイプごとに最大3件のAPI登録が可能 |
| カスタムヘッダー | 任意 | Key/Valueペアは最大10件 / 重複名不可（大文字小文字を区別しない） |
| 自動フィールド | 任意 | チェックした項目のみリクエストに含める / キー（名前）は編集可能 / 値はシステムが自動入力 |
| 手動フィールド | 任意 | 自動フィールドと合わせて最大10件登録 / 重複名不可 / 値は指定したタイプ（STRING/NUMBER/BOOLEAN）に応じてJSONデータに変換される |
| ユーザー キー(テスト) | 認証方式によって異なる | 1〜64文字 |
| 端末 ID(テスト) | 必須 | 9〜12桁の数字のみ |
| レスポンス解析 | - | statusCode または 成功結果 JSONPath の少なくとも1つが必須（両方入力すると結合検証が有効化） |
| statusCode | - | 100〜399の範囲の整数 / 最大3件 / 重複不可 |
| 成功結果 JSONPath | - | 1件: Key + Value + データ形式（BOOLEAN/STRING/NUMBER） |
| 成功メッセージ JSONPath/失敗メッセージ JSONPath | 任意 | 指定すると応答本文から抽出するキー（値は文字列である必要があり、デバイス画面サイズを考慮する必要あり）、指定しないとデバイスにメッセージは表示されない |
| 保存条件 | - | テスト成功時のみ保存可能 |
トラブルシューティング
入室問題（段階別診断）
#settingWorkflowを参照して、問題箇所を絞り込んでください。
| 手順 | 症状 | 確認事項 |
|---|---|---|
| 1 | 特定のクレデンシャルが認識されない | クレデンシャルがデバイスに登録され、有効になっているか確認してください。 |
| 2 | デバイス-サーバー間の通信失敗 | ネットワーク接続状態、デバイス登録状態を確認してください。 |
| 3 | リクエストが顧客社サーバーに到達しない | 登録済みURL（HTTPS）、カスタムヘッダー、ファイアウォールルールを確認してください。 |
| 4 | 顧客社は応答するが、すべての試行が拒否される | 判定基準（判定モード、成功キー/値、HTTPステータスコード）を確認してください。 |
| 5 | 許可/拒否は正しく動作するが、メッセージが表示されない | 成功メッセージ JSONPath/失敗メッセージ JSONPath、応答本文のメッセージ文字列を確認してください。 |
設定を保存 ボタン無効
設定を保存 ボタンをクリックできない場合は、次の項目を順番に確認してください。
-
必須フィールド: コネクタ名、認証方式、Webhook URL のうち空の項目がないか確認してください。
-
Webhook URL:
https://で始まり、最大長（512文字）を超えていないか確認してください。 -
手動フィールド: 値を指定したタイプ（
STRING/NUMBER/BOOLEAN）に変換できるか確認してください例:
NUMBERに数字以外の文字を入力した場合 -
レスポンス解析: statusCode または 成功結果 JSONPath の少なくとも1つを入力したか確認してください。
-
成功結果 JSONPathを使用する場合は、
Key、Value、データ形式をすべて入力したか確認してください。 -
成功メッセージ JSONPath/失敗メッセージ JSONPathはオプションで、保存に影響しません。
-
-
APIテスト: 少なくとも1回テストに成功したか確認してください。 テスト成功なしでは保存できません。
テスト失敗
テスト失敗は3種類に分かれます。
（A）入力値検証段階でブロックされた
入力値がルールに合わず、リクエスト自体が送信されません。
| 症状 | 確認事項 |
|---|---|
| Webhook URL形式エラー | Webhook URL が https://で始まり、512文字を超えないか確認してください。 |
| 判定基準キー形式エラー | 成功結果 JSONPath/成功メッセージ JSONPath/失敗メッセージ JSONPath が $. で始まるJSONPath形式（最大128文字）か確認してください。 |
| 判定基準未指定 | statusCode または 成功結果 JSONPath の少なくとも1つを入力したか確認してください。 |
| 成功ステータスコード範囲/件数エラー | 各値が100〜399の範囲内か、3件以下か、重複がないか確認してください。 |
| フィールドキー重複 | 自動フィールド と 手動フィールド のキーが互いに重複なく一意か確認してください。 |
| リクエストヘッダーキー重複 | リクエストヘッダーキーが互いに重複なく一意か（大文字小文字を区別しない）確認してください。 |
| 制限されたヘッダー名を使用 | Content-Type または Accept をカスタムヘッダーとして追加していないか（大文字小文字を区別しないシステム固定値）確認してください。 |
| フィールド/ヘッダー数超過 | 自動フィールド と 手動フィールド のフィールドが最大10件、カスタムヘッダーが最大10件か確認してください。 |
| 認証方式 登録件数超過 | 該当クレデンシャルタイプにすでに3件のAPIが登録されているか確認してください。 |
| ユーザー キー 形式エラー | テストコンソールの ユーザー キー が、許可文字（英字、数字、-、_、@、.）の範囲と1〜64文字の長さを満たすか確認してください。 |
| 端末 ID 形式エラー | テストコンソールの 端末 ID が9〜12桁の数字か確認してください。 |
（B）リクエストは送信されたがテスト失敗
テスト結果が success = false と表示され、この状態では保存できません。
| 症状 | 確認事項 |
|---|---|
| 接続失敗/ネットワークエラー（顧客社サーバーから応答を受信できない） | 顧客社サーバーの外部アクセス可否、HTTPS証明書の有効性、ファイアウォール/ポート設定、カスタムヘッダー（期限切れトークン、 টাইポ） |
| タイムアウト（応答なし） | 顧客社サーバーの応答遅延、ネットワーク状態。 テストは数秒以内に応答がないと失敗として処理します |
| 応答は受信したが、本文がJSONではない | 顧客社がJSON応答を返すか、応答 Content-Type が application/json に設定されているか。 HTMLエラーページ、空テキストなどが該当します |
（C）応答は受信したが期待した結果ではない
success = true とともに、実際のHTTPステータスコードが statusCode に、顧客社の元応答が ターミナル出力 に表示されます。 保存可能であり、この段階で応答を基に応答パースを構成する必要があります。
| 症状 | 確認事項 |
|---|---|
| ステータスコードは受信したが、すべての入室が拒否される | モード1、3: 成功として認めるステータスコード一覧を確認してください。 モード2: 本文のキー/値条件を確認してください。 ステータスコードは無視されます。 |
| 本文フィールド条件が一致しない | 成功結果 JSONPath に入力した Key、Value、データ形式（BOOLEAN/STRING/NUMBER）を再確認してください。 応答が "true"（STRING）か true（BOOLEAN）かを確認してください。 タイプが一致している必要があります。 |
| 手動フィールド がリクエスト本文で不正な形式として表示される | 手動フィールド のタイプ（STRING/NUMBER/BOOLEAN）が実際の入力値と一致しているか再確認してください。 |
-
テストAPIは応答本文をパースせずそのまま表示するため、ターミナル出力 に表示された実際の応答JSONを基に、JSONPath、キー、値の設定を合わせてください。
-
デバイス側で失敗原因を特定するには、#accessTroubleshootingを参照してください。
名前重複の問題
自動フィールド と 手動フィールド のキー名は互いに重複できません。 リクエストヘッダーキーも互いに重複できません。 自動フィールド のキー名を変更した場合は、手動フィールド と衝突しないか確認してください。
デバイスにメッセージが表示されない
-
応答本文に 成功メッセージ JSONPath または 失敗メッセージ JSONPath で指定したフィールドが実際に存在するか確認してください。
-
そのキーの値が文字列か確認してください。 数値、オブジェクト、配列は表示されません。
-
設定した 成功メッセージ JSONPath / 失敗メッセージ JSONPath 名が、実際の応答のキーと正確に一致するか確認してください。