SPLATS Developers Site

拡張版SPLATS API利用シーン

自動ドアや電気錠の施解錠を制御

パスコントローラー操作リクエストにより自動ドアや電気錠の施解錠を制御することができます。
パスコントローラー操作リクエストでは、制御対象が自動ドアまたは電気錠の場合、以下の操作をすることができます。

ドアを解錠する
ドアを施錠する
ドアを開いたままにする

それぞれの操作の利用シーンとリクエスト内容について説明します。

ドアを解錠する

利用シーン

SPLATSではメンバーやゲストに権限を付与することでカードやQRコードによる認証が可能ですが、「外部サービス内にてメンバーの認証を行ったタイミングでドアを解錠する」など、外部サービス内での操作をトリガーにデバイスの解錠をしたい場合に使用します。

デバイス（パスコントローラー）にはオートロックするまでの秒数が設定されています。この設定はメンバーサイトからのみ変更できます。
SPLATS APIによりドアを解錠した場合も、設定されている秒数が経過するとドアはオートロックされます。
オートロックされる前にドアを施錠したい場合は、ドアを施錠するパスコントローラー操作リクエストを行ってください。

リクエスト内容
項目	内容
操作	ドアを解錠する
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "unlock", "info": "ログに残す文字列" }`

ドアを開いたままにする・ドアを施錠する

利用シーン

以下のような時間帯別の入退室管理を実現したい場合に使用します。

営業時間中：ドアを開いたままにして自由な出入りを許可
営業時間外：ドアを施錠し、権限のある特定のメンバーのみが認証により解錠可能
緊急時：避難経路確保のためドアを開いたままに設定

ドアを施錠している時間は、通常通り、SPLATS上に登録された権限のあるメンバーやゲストがカードやQRコードを使用して解錠できます。

「ドアを開いたままにする」操作を行った場合、そのドアは認証を必要とせず誰でも通行できる状態になります。
また、ドアを閉めてもオートロックされません。施錠したい場合はSPLATS APIによりドアを施錠してください。

自動ドアに「ドアを開いたままにする」操作を行った場合、自動ドア自体はその自動ドアの仕様に従って開閉が行われます。自動ドア自体が開いたままになるのではなく、閉まっても施錠されないという動作を行います。

リクエスト内容
項目	内容
操作	ドアを開いたままにする
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "cont_unlock", "info": "ログに残す文字列" }`

項目内容

項目	内容
操作	ドアを施錠する
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "lock", "info": "ログに残す文字列" }`

操作

ドアを施錠する

エンドポイント

https://api-link.splats.jp/v1/devices/passes/{device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "lock",
  "info": "ログに残す文字列"
}

セキュリティゲートの施解錠を制御

パスコントローラー操作リクエストによりセキュリティゲートの施解錠を制御することができます。パスコントローラー操作リクエストでは、制御対象がセキュリティゲートの場合、以下の操作をすることができます。

ゲートを入室方向に開く
ゲートを退室方向に開く
ゲートを閉じる
ゲートを開いたままにする

セキュリティゲートゲートの基本事項、それぞれの操作の利用シーンとリクエスト内容について説明します。

「セキュリティゲートが開く」とは、セキュリティゲートに付属するフラップが開くことを意味します。
制御できるセキュリティゲートについてはお問い合わせください。

入室方向と退室方向

セキュリティゲートには「入室方向に開く」場合と「退室方向に開く」場合の二方向の開き方があります。
入室方向や退室方向はエリアとそれに紐づくデバイス（パスコントローラー）の設定により定まります。

入室方向と退室方向の定め方

SPLATSでは一つのデバイス（パスコントローラー）に対して二つのエリアが紐づいています。
エリア取得(全体)APIのレスポンスで各エリアとデバイスの紐づけを確認することができます。

エリア①とエリア②にまたがるデバイス（パスコントローラー）がある下図の状態を考えます。

in out direction

このとき、入室方向と退室方向は以下のように定まります。

エリアの移動方向	入室方向／退室方向
エリア① → エリア②	入室方向
エリア② → エリア①	退室方向

エリアの移動方向

入室方向／退室方向

エリア① → エリア②

入室方向

エリア② → エリア①

退室方向

以上から、エリア①にいるメンバーがエリア②へ移動するためにセキュリティゲートを解錠する場合、「入室方向に開く」パスコントローラー操作リクエストを行います。

セキュリティゲートが開いた方向からセキュリティゲートを通行する（通行方向と逆向きにセキュリティゲートが開く）と、不正と判断されて音声による警告が鳴ります。そのため、セキュリティゲートの開く方向を適切に制御することを推奨します。

ゲートを開く

利用シーン

SPLATSではメンバーやゲストに権限を付与することでカードやQRコードによる認証が可能ですが、「外部サービス内にてメンバーの認証を行ったタイミングでセキュリティゲートを解錠する」など、外部サービス内での操作をトリガーにデバイスの解錠をしたい場合に使用します。

デバイス（パスコントローラー）にはオートロックするまでの秒数が設定されています。この設定はメンバーサイトからのみ変更できます。
SPLATS APIによりセキュリティゲートを解錠した場合も、設定されている秒数が経過するとセキュリティゲートはオートロックされます。
オートロックされる前にセキュリティゲートを施錠したい場合は、セキュリティゲートを施錠するパスコントローラー操作リクエストを行ってください。

リクエスト内容

現在メンバーがいるエリアとメンバーが移動する移動先のエリアから「入室方向に開く」か「退室方向に開く」かを指定してください。

項目内容

項目	内容
操作	ゲートを入室方向に開く
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "in_unlock", "info": "ログに残す文字列" }`

操作

ゲートを入室方向に開く

エンドポイント

https://api-link.splats.jp/v1/devices/passes/{device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "in_unlock",
  "info": "ログに残す文字列"
}

項目内容

項目	内容
操作	ゲートを退室方向に開く
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "out_unlock", "info": "ログに残す文字列" }`

操作

ゲートを退室方向に開く

エンドポイント

https://api-link.splats.jp/v1/devices/passes/{device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "out_unlock",
  "info": "ログに残す文字列"
}

ゲートを開いたままにする・ゲートを閉じる

利用シーン

災害などの緊急時にセキュリティゲートを開いたままにしたい場合などに使用します。

セキュリティゲートを閉じている時間は、通常通り、SPLATS上に登録された権限のあるメンバーやゲストがカードやQRコードを使用して解錠できます。

セキュリティゲートに「ゲートを開いたままにする」操作を行った場合、セキュリティゲートのフラップが開いたままになります。
※ 開く方向は、セキュリティゲートの設定に従います。
※ 自動ドアのように自動で閉じることはありません。セキュリティゲートを閉じたい場合はSPLATS APIによりセキュリティゲートを閉じてください。

リクエスト内容
項目	内容
操作	ゲートを開いたままにする
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "cont_unlock", "info": "ログに残す文字列" }`

項目内容

項目	内容
操作	ゲートを施錠する
エンドポイント	https://api-link.splats.jp/v1/devices/passes/{device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "lock", "info": "ログに残す文字列" }`

操作

ゲートを施錠する

エンドポイント

https://api-link.splats.jp/v1/devices/passes/{device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "lock",
  "info": "ログに残す文字列"
}

キーボックスの施解錠を制御

キーボックス操作リクエストによりキーボックスの扉やカギの施解錠を制御することができます。
キーボックス操作リクエストでは、以下の操作をすることができます。

カギを解錠する
カギを施錠する

それぞれの操作の利用シーンとリクエスト内容について説明します。

指定したカギを取り出す

利用シーン

施設管理サービスや車両管理サービスなど、物理的な「カギ」が必要なサービスにおいて、そのカギをSPLATS KEYに保管し、「外部サービス内にてメンバーが利用開始をリクエストしたタイミングで鍵を解錠する」など、外部サービス内でカギの取り出しを制御したい場合に使用します。

デバイス（キーボックス）にはカギを取り出せる時間が設定されています。この設定はメンバーサイトからのみ変更できます。
SPLATS APIによりカギを解錠した場合も、設定されている秒数が経過するとカギは自動で施錠されます。
自動で施錠される前にカギを施錠したい場合は、カギを施錠するキーボックス操作リクエストを行ってください。

リクエスト内容

カギを解錠する操作では、解錠するカギの番号をリストで指定することで、指定したカギを取り出すことができます。
1番と2番のカギを解錠する例を以下に示します。

項目内容

項目	内容
操作	カギを解錠する
エンドポイント	https://api-link.splats.jp/v1/devices/keys/{key_device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "unlock", "targets": ["01", "02"], "info": "ログに残す文字列" }`

操作

カギを解錠する

エンドポイント

https://api-link.splats.jp/v1/devices/keys/{key_device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "unlock",
  "targets": ["01", "02"],
  "info": "ログに残す文字列"
}

カギの返却のために解錠する

利用シーン

指定したカギを取り出す操作で取り出したカギを返却するときに使用します。

リクエスト内容

カギの返却のために解錠する場合、キーボックスと個別キーボックスでリクエスト内容が異なります。
キーボックスでは、キーボックスの扉を解錠することでカギの返却が可能になります。一方、個別キーボックスでは、取り出し時と同様に各カギを解錠することでカギの返却が可能になります。

キーボックス
キーボックスの場合は targets を空リストにしてリクエストしてください。
targets を空リストにしたとき、キーボックスの扉のみが解錠されます。保管されているカギは解錠されません。

項目内容

項目	内容
操作	カギの返却のために解錠する（キーボックス）
エンドポイント	https://api-link.splats.jp/v1/devices/keys/{key_device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "unlock", "targets": [], "info": "ログに残す文字列" }`

操作

カギの返却のために解錠する（キーボックス）

エンドポイント

https://api-link.splats.jp/v1/devices/keys/{key_device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "unlock",
  "targets": [],
  "info": "ログに残す文字列"
}

個別キーボックス
個別キーボックスの場合は targets を返却するカギ番号のリストにしてリクエストしてください。
6番と12番のカギを返却する例を以下に示します。

項目内容

項目	内容
操作	カギの返却のために解錠する（個別キーボックス）
エンドポイント	https://api-link.splats.jp/v1/devices/keys/{key_device_id}/requests
HTTPメソッド	POST
リクエストヘッダー	`Content-Type: application/json Authorization: Bearer YOUR_ACCESS_TOKEN License-Key: YOUR_LICENSE_KEY`
リクエストボディ	`{ "tag": "lock_operation", "control": "unlock", "targets": ["06", "12"], "info": "ログに残す文字列" }`

操作

カギの返却のために解錠する（個別キーボックス）

エンドポイント

https://api-link.splats.jp/v1/devices/keys/{key_device_id}/requests

HTTPメソッド

POST

リクエストヘッダー

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
License-Key: YOUR_LICENSE_KEY

リクエストボディ

{
  "tag": "lock_operation",
  "control": "unlock",
  "targets": ["06", "12"],
  "info": "ログに残す文字列"
}

拡張版SPLATS API注意事項

デバイスを操作をする

パスコントローラー情報取得(全体)APIやキーボックス情報取得(全体)APIでテナントに紐づくデバイス情報を取得します。取得したデバイス情報から特定のデバイスIDを指定してデバイス操作リクエストを行います。

デバイスを操作するにはデバイスがSPLATSクラウドと通信できることが必要です。開発段階でデバイスが存在しない場合や、本番運用中であるがデバイスが通信エラーまたは電源OFFとなっている場合は、デバイス操作リクエストに失敗します。

デバイスの操作に失敗する条件

デバイス操作リクエストに失敗する状態とそのときのレスポンス内容（ステータスコード）を以下の表に示します。
エラーコードを確認することでリクエストに失敗した原因が分かるので、必要に応じてエラーハンドリングをしてください。

状態	ステータスコード	エラーコード
デバイスの電源がOFFである	400	40091
デバイスとクラウド間で通信エラーが発生している	400	40092
デバイスとクラウドが紐づいていない	404	40481
デバイスが30秒以内に処理を受け付けられなかった（タイムアウト）	408	-

以下の場合、デバイス操作リクエストはタイムアウトとなります。

デバイスがリクエストの受け取りに失敗した
デバイスがリクエストを受け取ったが解錠や施錠に失敗した

デバイス操作の理由をログに記録する

SPLATSではドアの開閉やカギの取り出し・返却、及びそれらの操作者の情報をログに記録しています。SPLATS APIを使用したデバイス操作では、システムによる操作であるため、実際の利用者情報や操作の詳細情報はSPLATS上のログに自動的には記録されません。

SPLATS上のログに詳細情報を記録するには、リクエスト時に info パラメータで付加情報を指定する必要があります。必要に応じて適切な情報をログに記録してください。

拡張版SPLATS APIの実装ガイド

デバイス操作リクエストの結果を取得する

デバイス操作リクエストAPIではリクエストを受け付けたかどうかのみをレスポンスします。リクエストが受け付けられた場合は、レスポンスにリクエストIDが含まれます。そのリクエストIDを使用してリクエスト結果取得APIを呼び出すことでリクエスト結果を取得することができます。

デバイス操作リクエストのフロー例は以下の図の通りとなります。

デバイス操作リクエストにおけるリクエスト進捗 status の succeeded という値は、デバイスがリクエストを受け取ったことを意味します。
デバイス操作リクエストが成功しても、実際にドアが開かれたり、カギが取り出されたりしたかまでは分かりません。物理的な動作の有無は、別途デバイス状態取得API や Webhook 等で確認する必要があります。

モックデバイスを操作する

モックデバイスは、実際のパスコントローラーやキーボックスがクラウドに接続されていない開発段階でも、デバイスへの操作リクエストAPIをテストできる機能です。特定の device_id や key_device_id を指定することで、実際のデバイスが動作しているかのようなレスポンスを受け取ることができます。モックデバイスを活用することで、実際のデバイスを用意することなく、アプリケーションの開発・テストを効率的に進めることができます。

モックデバイスへのAPIリクエストも他のAPIリクエストと同様にレート制限の対象となります。
また、アクセストークンやライセンスキーも同様に必要です。

モックデバイスID

device_id 動作内容

`device_id`	動作内容
`mock_succeeded`	リクエストが即時に成功します
`mock_succeeded_5`	リクエストが5秒後に成功します ※ リクエスト結果取得APIでレスポンスされる `status` が5秒後に `progress` から `succeeded` に変わります
`mock_timeout`	リクエストがタイムアウトします

mock_succeeded

リクエストが即時に成功します

mock_succeeded_5

リクエストが5秒後に成功します
※ リクエスト結果取得APIでレスポンスされる status が5秒後に progress から succeeded に変わります

mock_timeout

リクエストがタイムアウトします

使用例

リクエスト結果取得APIのリトライ処理をテストする

デバイス操作リクエストを行ってデバイスが実際に動作するまでに多少の時間を要することがあります。
そのため、リクエスト結果を取得してリクエストが成功したかを確認するためにはリトライ処理が必要になります。

リクエスト結果取得APIのリトライ処理は、モックデバイスIDに mock_succeeded_5 を指定することでテストを行うことができます。
その際のフローは以下の図の通りとなります。

※ リトライ間隔は適切に設定してください。