SPLATS Developers Site

SPLATS API利用シーン

デバイスを利用するメンバーを登録して利用状況を確認する

メンバー登録

エリアの入室やカギを利用できるメンバーを登録します。
メンバー登録APIをリクエストするためには、メンバーグループ情報/エリア情報(SPLATS PASS契約の場合のみ)/キーボックス情報(SPLATS KEY契約の場合のみ)が必要になるので、事前に以下のリクエストをして必要な情報を取得してください。

メンバーグループ取得(全体)

GET
https://api-link.splats.jp/v1/membergroups

リクエストに成功すると、メンバーグループ情報がレスポンスされます。
対象メンバーグループのメンバーグループIDを保持してください。
設定したいグループが存在しない場合はメンバーグループ登録APIで新規作成してください。

エリア取得(全体)

GET
https://api-link.splats.jp/v1/areas

SPLATS PASS契約の場合のみリクエストしてください。
リクエストに成功すると、エリア情報がレスポンスされます。
エリアごとに入室の可否を指定する場合のみ対象エリアのエリアIDを保持してください。

キーボックス情報取得(全体)

GET
https://api-link.splats.jp/v1/devices/keys

SPLATS KEY契約の場合のみリクエストしてください。
リクエストに成功すると、キーボックス情報がレスポンスされます。
キーボックスのカギごとに利用可否を指定する場合のみ対象キーボックスのデバイスIDを保持してください。

各種必要な情報が取得できたらメンバー登録APIをリクエストします。

メンバー登録

POST
https://api-link.splats.jp/v1/members

リクエスト内容についてはメンバー登録設定例を参照してください。
登録に成功するとメンバーIDがレスポンスされるので、必要に応じて連携サービス側で保持してください。

複数のメンバーを登録する場合はメンバー一括登録APIを利用してください。
1回のリクエストで複数メンバーをまとめて登録できるため、複数回のリクエストを送信する必要がなく、リクエスト制限を回避しやすくなります。
詳細についてはメンバーの一括操作の使用例を参照してください。

登録したメンバーの確認

登録したメンバーの登録内容を確認する場合は以下のリクエストをしてください。

GET
https://api-link.splats.jp/v1/members/{メンバーID}

メンバーの利用状況の確認

登録したメンバーのエリアへの入室やカギを利用した状況を確認できます。
ログ情報から確認する場合は以下をリクエストしてください。

GET
https://api-link.splats.jp/v1/histories

1回のリクエストで取得できる件数や、指定した期間のログ情報の取得をパラメータで指定することもできます。
詳細はSPLATS API仕様書を参照してください。

Webhookを利用することでSPLATS APIを定期的に呼び出してログ検出を行う必要がなく、リアルタイムに通知を受け取ることができるようになります。
詳細はWebhook概要を確認してください。

デバイスを利用するゲストを登録して利用状況を確認する

来客や施設の利用者など、SPLATSで管理していない外部の人を一時利用の「ゲスト」として登録できます。
ゲスト登録時に指定したQRコードや自動発行されたQRコードで認証することができます。
登録したゲストは利用終了日時の１週間後に自動で削除されるので、連携サービス側から削除する必要がありません。

永続的な管理が必要な場合は「メンバー」として登録してください。

ゲストを利用するためにはQRオプションの契約が必要です。

ゲスト登録APIをリクエストするためには、エリア情報(SPLATS PASS契約の場合のみ)/キーボックス情報(SPLATS KEY契約の場合のみ)が必要になるので、事前に以下のリクエストをして必要な情報を取得してください。

エリア取得(全体)

GET
https://api-link.splats.jp/v1/areas

キーボックス情報取得(全体)

GET
https://api-link.splats.jp/v1/devices/keys

各種必要な情報が取得できたらゲスト登録APIをリクエストします。

ゲスト登録

POST
https://api-link.splats.jp/v1/guests

リクエスト内容についてはゲスト登録設定例を参照してください。
登録に成功すると、ゲストIDがレスポンスされます。必要に応じて連携サービス側で保持してください。

登録したゲストの確認

登録したゲストの登録内容を確認する場合は以下のリクエストをしてください。

GET
https://api-link.splats.jp/v1/guests/{ゲストID}

ゲストの利用状況の確認

登録したゲストのエリアへの入室やカギを利用した状況を確認できます。
ログ情報から確認する場合は以下をリクエストしてください。

GET
https://api-link.splats.jp/v1/histories

1回のリクエストで取得できる件数や、指定した期間のログ情報をパラメータで指定して取得することもできます。
詳細はSPLATS API仕様書を参照してください。

パスコントローラー状態を確認する

SPLATS PASS契約の場合のみパスコントローラー状態を確認できます。
パスコントローラー状態を取得することで、扉の開閉状況や閉め忘れなどのエラー状態を確認することができます。
状態を取得するためにはパスコントローラー情報が必要になるので、事前に以下のリクエストをして必要な情報を取得してください。

パスコントローラー情報取得(全体)

GET
https://api-link.splats.jp/v1/devices/passes

リクエストに成功すると、パスコントローラー情報がレスポンスされます。
状態を取得したい対象パスコントローラーのデバイスIDを元に以下のリクエストをしてください。

パスコントローラー状態取得

GET
https://api-link.splats.jp/v1/devices/passes/{パスコントローラーのデバイスID}/status

キーボックス状態を確認する

SPLATS KEY契約の場合のみキーボックス状態を確認できます。
キーボックス状態を取得することで、カギの取出/返却状況や閉め忘れなどのエラー状態を確認することができます。
状態を取得するためにはキーボックス情報が必要になるので、事前に以下のリクエストをして必要な情報を取得してください。

キーボックス情報取得(全体)

GET
https://api-link.splats.jp/v1/devices/keys

リクエストに成功すると、キーボックス情報がレスポンスされます。
状態を取得したい対象キーボックスのデバイスIDを元に以下のリクエストをしてください。

キーボックス状態取得

GET
https://api-link.splats.jp/v1/devices/devices/keys/{キーボックスのデバイスID}/status

SPLATS KEYの場合のみ一時利用許可を利用できます。
普段は利用できないカギに対して、指定した時間・メンバーのみカギの取り出し/返却を許可することができます。
例えば、アルコールチェック機器など外部サービスで許可された場合に一時利用許可を与えてカギの取り出し/返却を可能とすることができます。
一時利用許可を与えるためにはメンバー情報とキーボックス情報が必要になるので、事前に以下のリクエストをして必要な情報を取得してください。

利用しないカギとしてデバイス設定の「利用しないカギを設定する」を有効にしておく必要があるので、事前にメンバーサイトから設定をしてください。
一時利用許可を与えるメンバーには対象のカギが利用できる権限が必要です。

メンバー取得(全体)

GET
https://api-link.splats.jp/v1/members

リクエストに成功すると、メンバー情報がレスポンスされます。
一時利用許可を与えるメンバーのIDを保持してください。

キーボックス情報取得(全体)

GET
https://api-link.splats.jp/v1/devices/keys

リクエストに成功すると、キーボックス情報がレスポンスされます。
一時利用許可するキーボックスのデバイスIDを保持してください。

各種必要な情報が取得できたら一時利用許可APIをリクエストします。

一時利用許可

PUT
https://api-link.splats.jp/v1/members/{一時利用許可を与えるメンバーのID}/temporary_use

下記設定はキーボックスAのカギ番号01に対して、リクエストを受け付けてから60秒間取り出し/保管を許可する設定例です。
device_action を true にすることで、情報が反映されたときにデバイスから音とLEDで知らせることができます。
info に任意の文字列を指定すると、どういった目的で一時利用許可を与えたかログに残すことができます。

{
  "target": "key",
  "timer": 60,
  "targets_list": [
    {
      "device_id": "{キーボックスAのID}",
      "unit_no_list": ["01"]
    }
  ],
  "device_action": true,
  "info": "補足情報"
}

定期的に変化するQRコードを使用する

SPLATSではメンバーの認証情報にQRコード（静的QRまたはワンタイムQR）を設定することができます。QRコード情報が変化しない静的なQRコードではなく、定期的に変化するQRコードを使用したい場合は、各メンバーに対してワンタイムQRを設定してください。

ワンタイムQRを使用するメリットは次の通りです。

複製のリスクを低減する：静的QRでは複製による不正リスクがありますが、ワンタイムQRを使用することでリスクを軽減することができます。
認証データ更新による遅延の影響を受けない：静的QRを更新する場合、更新リクエストからデバイスまでの反映に時間が掛かり、実際に認証できるようになるまでに遅延があります。ワンタイムQRでは認証情報が自動で更新されるため、更新によるレイテンシーの影響が発生せず、すぐに認証することができます。

※ デバイスが通信エラー中でも、設定済みのメンバーはワンタイムQRを使って認証が可能です。

ワンタイムQRを使用するためにはメンバー情報が必要になるので、事前に以下のリクエストをして必要な情報を設定および取得してください。

メンバー登録

POST
https://api-link.splats.jp/v1/members

リクエストに成功すると、メンバー情報がレスポンスされます。
ワンタイムQRを使用するメンバーのIDを保持してください。

メンバーIDが取得できたらワンタイムQR取得APIをリクエストします。

ワンタイムQR取得

POST
https://api-link.splats.jp/v1/members/{member_id}/one_time_qr

リクエストに成功すると、ワンタイムQRのQRコードデータがレスポンスされます。
これをQRコード画像に変換することで認証が可能になります。

ワンタイムQRは、ワンタイムQR取得APIをリクエストせずとも、定められたルールに従うことで、自身（連携サービス内）で生成することができます。詳細はワンタイムQRの使用例を参照してください。

SPLATS APIリクエスト例

メンバー登録設定例

メンバーを登録する場合の設定例を記載します。
詳細なパラメーターの内容はSPLATS API仕様書を参照してください。

設定するメンバーグループのIDを指定する必要があります。
メンバーグループ情報取得APIを使用してメンバーグループIDを取得してください。
devices_pass はSPLATS PASSを契約している場合のみ指定します。
詳細は権限設定例(SPLATS PASS)をご確認ください。
keys_pass はSPLATS KEYを契約している場合のみ指定します。
詳細は権限設定例(SPLATS KEY)をご確認ください。

ICカードで認証するメンバーを登録する

認証に使用するICカードの情報が必要となります。
登録するカード情報を事前に取得してください。

{
  "member_name": "サンプル",
  "member_code": "0001",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "card_data": "0123ABCD00000000",
  "devices_pass": {
    ・・・
  },
  "keys_pass": {
    ・・・
  }
}

QRコードで認証するメンバーを登録する

QRコードで認証するためにはQRオプションの契約が必要です。

予め用意されたQRコードを登録する

連携システム側などで生成されたQRコードなど予め用意されたQRコード情報をSPLATSに登録します。

{
  "member_name": "サンプル",
  "member_code": "0001",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "qrcode": {
    "data": "ABCDEF0123456789"
  },
  "devices_pass": {
    ・・・
  },
  "keys_pass": {
    ・・・
  }
}

SPLATSでQRコードを自動発行してメール送信する

SPLATSでQRコードを自動発行して、指定されたメールアドレスに送信します。

{
  "member_name": "サンプル",
  "member_code": "0001",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "qrcode": {
    "email": "xxxx@example.com"
  },
  "devices_pass": {
    ・・・
  },
  "keys_pass": {
    ・・・
  }
}

顔認証するメンバーを登録する

顔認証するためには顔認証オプションの契約が必要です。

登録方法については顔認証関連の使用例を参照してください。

利用期間を指定してメンバーを登録する

利用期間外のメンバーはデバイス、メンバーサイトが利用できなくなります。
期日に合わせたメンバーの設定変更も不要になり、メンバーの利用を事前にコントロールすることができます。
下記設定は2023/04/01～2023/04/10の期間のみ、設定された権限内でデバイスを利用できます。

{
  "member_name": "サンプル",
  "member_code": "0001",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "card_data": "0123ABCD00000000",
  "use_date_start": "2023-04-01T00:00:00+09:00",
  "use_date_end": "2023-04-10T23:59:59+09:00",
  "devices_pass": {
    ・・・
  },
  "keys_pass": {
    ・・・
  }
}

ゲスト登録設定例

ゲストを登録する場合の設定例を記載します。
詳細なパラメーターの内容はSPLATS API仕様書を参照してください。

ゲストを利用するためにはQRオプションの契約が必要です。

指定されたエリアに入室できるゲストを登録する

下記設定はエリアAの入室を2023/04/01 09:00:00～2023/04/10 18:00:00の間許可する設定例です。
設定するエリアのIDを指定する必要があります。
事前にエリア情報取得APIを使用してエリアIDを取得してください。

ゲストの入室権限を設定するにはSPLATS PASSの契約が必要です。

{
  "guest_name": "サンプル",
  "use_date_start": "2023-04-01T09:00:00+09:00",
  "use_date_end": "2023-04-10T18:00:00+09:00",
  "qrcode_issuing_method": {
    "qrcode_data": "ABCDEF0123456789"
  },
  "area_id_list": ["{エリアAのID}"]
}

指定されたカギを利用できるゲストを登録する

下記設定はキーボックスAのカギ番号01を2023/04/01 09:00:00～2023/04/10 18:00:00の間、取り出しを許可し、2023/04/10 19:00:00まで返却をすることができる設定例です。
return_grace_period を指定すると利用終了日時から指定した時間までカギの返却ができます。
設定するキーボックスのデバイスIDを指定する必要があります。
事前にキーボックス情報取得APIを使用してキーボックスのデバイスIDを取得してください。
ゲストが利用するカギとしてデバイス設定の「ゲストが利用するカギを設定する」を有効にしておく必要があるので、事前にメンバーサイトから設定をしてください。

ゲストのカギ利用権限を設定するにはSPLATS KEYの契約が必要です。

{
  "guest_name": "サンプル",
  "use_date_start": "2023-04-01T09:00:00+09:00",
  "use_date_end": "2023-04-10T18:00:00+09:00",
  "return_grace_period": 60,
  "qrcode_issuing_method": {
    "qrcode_data": "ABCDEF0123456789"
  },
  "key_devices_list": [
    {
      "key_device_id": "{キーボックスAのID}",
      "units_no_list": ["01"]
    }
  ]
}

権限設定例(SPLATS PASS)

メンバーの入室権限を設定する場合の設定例を記載します。
詳細なパラメーターの内容はSPLATS API仕様書を参照してください。

メンバーの入室権限を設定するにはSPLATS PASSの契約が必要です。

全てのエリアにいつでも入室できる

SPLATSに登録されている全てのエリアにいつでも入室できるメンバーを登録します。
エリアごとに詳細な権限を設定する必要がない場合に設定します。
この設定をした場合、後から追加されたエリアも入室できる状態となります。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "devices_pass": {
    "default_mode" : "allow_all"
  }
}

全てのエリアの入室を不可にする

SPLATSに登録されている全てのエリアの入室を不可にするメンバーを登録します。
devices_pass のキーを指定しない場合でも deny_all を指定した場合と同じ状態となります。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "devices_pass": {
    "default_mode" : "deny_all"
  }
}

または

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx"
}

エリアごとに入室の可否を指定する

一部のエリアのみいつでも入室できるメンバーを登録します。
エリアごとに入室の可否を変更する必要がある場合に設定します。
下記設定はエリアAのみいつでも入室できるようにする設定例です。
指定されていないエリアは入室不可として扱われます。
設定するエリアのIDを指定する必要があります。
事前にエリア情報取得APIを使用してエリアIDを取得してください。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "devices_pass": {
    "default_mode" : "option",
    "areas_list": [
      {
        "area_id": "{エリアAのID}",
        "pass": {
          "effect": "allow_all"
        }
      }
    ]
  }
}

入室できる曜日や休日を詳細に指定する

エリアごとに入室できる曜日や休日を詳細に設定するメンバーを登録します。
平日の業務時間内のみ入室を許可するなど、曜日や時間帯で入室できる権限が異なる場合に設定します。
下記設定はエリアAの入室を月曜日～金曜日は9:00～18:00、土曜日/日曜日/休日は9:00～13:00を許可する設定例です。
終日を許可する場合は 00:00:00+09:00～23:59:59+09:00 の時間を指定してください。
毎日を許可する場合は "week": ["*"] を指定してください。
※「毎日」は休日を含む全ての日です。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "devices_pass": {
    "default_mode" : "option",
    "areas_list": [
      {
        "area_id": "{エリアAのID}",
        "pass": {
          "effect": "allow",
          "schedule": [
            {
              "mode": "weekly",
              "start": {
                "time": "09:00:00+09:00"
              },
              "end": {
                "time": "18:00:00+09:00"
              },
              "week": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
            },
            {
              "mode": "weekly",
              "start": {
                "time": "09:00:00+09:00"
              },
              "end": {
                "time": "13:00:00+09:00"
              },
              "week": ["Sunday", "Saturday", "Holiday"]
            }
          ]
        }
      }
    ]
  }
}

入室できる時間を範囲で指定する

エリアごとに入室できる時間を範囲で設定するメンバーを登録します。
特定の期間のみ入室を許可したい場合などに設定します。
下記設定はエリアAの入室を2022/04/01 09:00:00～2022/04/10 18:00:00の間許可する設定例です。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "devices_pass": {
    "default_mode" : "option",
    "areas_list": [
      {
        "area_id": "{エリアAのID}",
        "pass": {
          "effect": "allow",
          "schedule": [
            {
              "mode": "range",
              "start": {
                "date": "2022-04-01",
                "time": "09:00:00+09:00"
              },
              "end": {
                "date": "2022-04-10",
                "time": "18:00:00+09:00"
              }
            }
          ]
        }
      }
    ]
  }
}

権限設定例(SPLATS KEY)

メンバーのカギ利用権限を設定する場合の設定例を記載します。
詳細なパラメーターの内容はSPLATS API仕様書を参照してください。

メンバーのカギ利用権限を設定するにはSPLATS KEYの契約が必要です。

全てのカギをいつでも利用できる

SPLATSに登録されている全てのキーボックスのカギをいつでも利用できるメンバーを登録します。
カギごとに詳細な権限を設定する必要がない場合に設定します。
この設定をした場合、後から追加されたキーボックスのカギも利用できる状態となります。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "keys_pass": {
    "default_mode" : "allow_all"
  }
}

全てのカギの利用を不可にする

SPLATSに登録されている全てのキーボックスのカギの利用を不可にするメンバーを登録します。
keys_pass のキーを指定しない場合でも deny_all を指定した場合と同じ状態となります。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "keys_pass": {
    "default_mode" : "deny_all"
  }
}

または

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx"
}

キーボックスごとにカギの利用可否を指定する

一部のキーボックスのカギのみいつでも利用できるメンバーを登録します。
キーボックスごとにカギの利用可否を変更する必要がある場合に設定します。
下記設定はキーボックスAのカギをいつでも利用できる、キーボックスB/キーボックスCのカギの利用を不可にする設定例です。
指定されていないキーボックスは deny_all として扱われます。
下記設定の場合キーボックスBは明示的に許可しない、キーボックスCは指定なしとしていますが、キーボックスB/キーボックスC共にカギの利用を不可にする設定となっています。
設定するキーボックスのデバイスIDを指定する必要があります。
事前にキーボックス情報取得APIを使用してキーボックスのデバイスIDを取得してください。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "keys_pass": {
    "default_mode" : "option",
    "key_devices_list": [
      {
        "key_device_id": "{キーボックスAのID}",
        "default_mode": "allow_all"
      },
      {
        "key_device_id": "{キーボックスBのID}",
        "default_mode": "deny_all"
      }
    ]
  }
}

キーボックスのカギごとに利用可否を指定する

キーボックスの一部のカギのみいつでも利用できるメンバーを登録します。
キーボックスのカギごとに利用可否を変更する必要がある場合に設定します。
下記設定はキーボックスAのカギ番号01～03をいつでも利用可、04と05を利用不可とする設定例です。
キーボックスAは5本タイプとします。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "keys_pass": {
    "default_mode" : "option",
    "key_devices_list": [
      {
        "key_device_id": "{キーボックスAのID}",
        "default_mode": "option",
        "units": [
          {
            "unit_no": "01",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "02",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "03",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "04",
            "pass": {
              "effect": "deny_all"
            }
          },
          {
            "unit_no": "05",
            "pass": {
              "effect": "deny_all"
            }
          }
        ]
      }
    ]
  }
}

カギを利用できる曜日や休日を詳細に指定する

キーボックスのカギごとに利用できる曜日や休日を詳細に設定するメンバーを登録します。
平日の業務時間内のみ利用を許可するなど、曜日や時間帯で利用できる権限が異なる場合に設定します。
下記設定はキーボックスAのカギ番号01を月曜日～金曜日は9:00～18:00、土曜日/日曜日/休日は9:00～13:00で利用可、02～05をいつでも利用可とする設定例です。
キーボックスAは5本タイプとします。
終日を許可する場合は 00:00:00+09:00～23:59:59+09:00 の時間を指定してください。
毎日を許可する場合は "week": ["*"] を指定してください。
※「毎日」は休日を含む全ての日です。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "keys_pass": {
    "default_mode" : "option",
    "key_devices_list": [
      {
        "key_device_id": "{キーボックスAのID}",
        "default_mode": "option",
        "units": [
          {
            "unit_no": "01",
            "pass": {
              "effect": "allow",
              "schedule": [
                {
                  "mode": "weekly",
                  "start": {
                    "time": "09:00:00+09:00"
                  },
                  "end": {
                    "time": "18:00:00+09:00"
                  },
                  "week": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
                },
                {
                  "mode": "weekly",
                  "start": {
                    "time": "09:00:00+09:00"
                  },
                  "end": {
                    "time": "13:00:00+09:00"
                  },
                  "week": ["Sunday", "Saturday", "Holiday"]
                }
              ]
            }
          },
          {
            "unit_no": "02",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "03",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "04",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "05",
            "pass": {
              "effect": "allow_all"
            }
          }
        ]
      }
    ]
  }
}

カギを利用できる時間を範囲で指定する

キーボックスのカギごとに利用できる時間を範囲で設定するメンバーを登録します。
特定の期間のみカギの利用を許可したい場合などに設定します。
下記設定はキーボックスAのカギ番号01を2022/04/01 09:00:00～2022/04/10 18:00:00の範囲で利用可、02～05をいつでも利用可とする設定例です。キーボックスAは5本タイプとします。

{
  "member_name": "サンプル",
  "membergroup_id": "xxxxxx-xxxxxx-xxxxx",
  "keys_pass": {
    "default_mode" : "option",
    "key_devices_list": [
      {
        "key_device_id": "{キーボックスAのID}",
        "default_mode": "option",
        "units": [
          {
            "unit_no": "01",
            "pass": {
              "effect": "allow",
              "schedule": [
                {
                  "mode": "range",
                  "start": {
                    "date": "2022-04-01",
                    "time": "09:00:00+09:00"
                  },
                  "end": {
                    "date": "2022-04-10",
                    "time": "18:00:00+09:00"
                  }
                }
              ]
            }
          },
          {
            "unit_no": "02",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "03",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "04",
            "pass": {
              "effect": "allow_all"
            }
          },
          {
            "unit_no": "05",
            "pass": {
              "effect": "allow_all"
            }
          }
        ]
      }
    ]
  }
}

ページネーション使用例

メンバー取得(全体)APIやログ取得APIなどのデータ一覧取得APIは、クエリパラメーターで指定した limit (未指定の場合は100件)の件数分までのデータがレスポンスされます。指定した件数を超えるデータがある場合、一部のデータとともに last_evaluated_key がレスポンスされます。次のデータを取得したい場合は、この last_evaluated_key をクエリパラメーターに指定して再度APIをリクエストしてください。これを繰り返すことで、すべてのデータを取得できます。

リクエスト例(ログ取得)

〇初回リクエスト

初回リクエスト時は last_evaluated_key を指定せずにリクエストしてください。

GET
https://api-link.splats.jp/v1/histories?limit=1000

上記リクエストでは1000件を超えるデータがある場合に last_evaluated_key がレスポンスされます。

{
  "histories": [
    ・・・
  ],
  "last_evaluated_key": "xxxxxxxxxxxxxxxx"
}

〇2回目以降のリクエスト

続きのデータを取得する場合はクエリパラメーターに last_evaluated_key を指定してください。
※同じ条件でデータを取得する場合は他のクエリパラメーターを変更しないでください。

GET
https://api-link.splats.jp/v1/histories?limit=1000&last_evaluated_key={last_evaluated_key}

最後までデータを取得する場合は last_evaluated_key がレスポンスされなくなるまでリクエストしてください。
条件に一致するすべてのデータが取得されると last_evaluated_key がレスポンスされなくなります。

データ件数によっては、 last_evaluated_key がレスポンスされなくなるまでに何度もリクエストをすることになり、レート制限による影響を受けやすくなります。
特にログ取得APIはデータ件数が多くなりやすいので、取得するログの日時（ since と until ）を調整してリクエストすることを推奨します。

顔認証関連の使用例

顔認証関連のSPLATS APIの使用例を記載します。
詳細なパラメーターの内容はSPLATS API仕様書を参照してください。
※顔認証オプションはSPLATS PASSのみ対応しています。

登録する顔画像について

jpeg画像のみ対応しています。
顔登録に使用する画像が以下の場合、登録できません。
・既に使用されている顔画像
・顔が検出できない
・複数人写っている
・マスクをしている
登録する顔画像が不明瞭な場合、認証精度が低くなります。（眼鏡や帽子着用、横顔、影など）
顔画像は縦長の写真を推奨しています。顔画像を1200×1600にリサイズして送信してください。
リサイズする前の顔画像が高解像度なほど認証精度が高くなります。
顔画像の最大サイズは2MBです。

メンバーの顔画像を登録する

登録済みのメンバーに顔画像を登録します。
顔画像の登録に時間がかかることがあるため、顔画像登録の進捗は「リクエスト結果取得」APIで取得します。リクエスト進捗が「succeeded/failed_○○」になると処理完了です。

＜顔画像の登録フロー例＞

※顔画像の登録結果は「リクエスト結果取得」APIでのみ取得できます。
※顔画像登録に成功してから顔認証できるようになるまで30秒以上かかります。（ネットワーク状況により変動します。）
※登録済みの顔画像はSPLATS APIで取得できません。連携サービス上で顔画像を保持して頂くか、SPLATSメンバーサイト上でご確認ください。

＜顔画像登録の進捗例＞

○顔画像登録中の場合

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "face",
  "status": "progress"
}

○顔画像登録に成功した場合

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "face",
  "status": "succeeded"
}

○「既に使用されている顔画像」のため、登録に失敗した場合

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "face",
  "status": "failed_registered"
}

メンバーの顔画像を削除する

登録済みのメンバーの顔画像を削除します。
「メンバー削除」APIを使用した場合、登録されている顔画像も削除します。

メンバーの顔画像を更新する

登録済みの顔画像を更新する場合、一度顔画像を削除してから再度登録してください。

メンバーに顔画像が登録されていることを確認する

顔画像登録済みの場合、「メンバー取得」APIでメンバーに顔画像が登録されていることを確認できます。
「face_data」があれば顔画像が登録されています。下記は顔画像が登録されていた場合の例です。

{
  "member_id": "xxxxxx-xxxxxx-xxxxx",
  "member_name": "サンプル",
  ～　省略　～
  "face_data": "xxxxxx-xxxxxx-xxxxx",
  ～　省略　～
}

メンバーの一括操作の使用例

メンバーの一括操作（登録/更新/削除）のSPLATS APIの使用例を記載します。
詳細なパラメータの内容はSPLATS API仕様書を参照してください。

リクエストボディについて

一回のリクエストで操作（登録/更新/削除）できるメンバーは最大1000人です。
リクエストボディの最大サイズは4MBです。個々のメンバーに設定する権限の内容によっては、1000人に満たない場合でも最大サイズの4MBを超える可能性があります。その際は、リクエストボディのサイズが4MBに収まるように分割してリクエストをしてください。
リクエストボディの最大サイズ4MBを超えてリクエストした場合、HTTPステータスコード「413 Request Too Long」がレスポンスされます。

メンバーを一括で操作する

SPLATS API仕様書に従ってメンバーを一括で操作（登録/更新/削除）します。
一括操作の結果をリクエスト結果取得APIで取得します。
※メンバーの一括操作（登録/更新/削除）は処理に時間がかかるため、リクエストを受け付けたかどうかのみをレスポンスとして返します。
※リクエストが受け付けられた場合は、レスポンスにリクエストIDが含まれます。リクエスト結果を確認するには、リクエスト結果取得APIをご利用ください。

＜一括登録のフロー例＞

※一括登録の結果は「リクエスト結果取得」APIでのみ取得できます。
※一括更新/削除においても同様のフローで結果を確認できます。

＜一括登録の進捗例＞

※一括更新/削除においても同様のレスポンス形式となります。

○一括登録処理待ちの場合

一括操作を複数リクエストした場合、そのリクエスト順に処理されます。
前のリクエストの処理中で処理が始まっていない場合はリクエスト進捗 pending がレスポンスされます。

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "members_bulk",
  "status": "pending"
}

○一括登録中の場合

一括登録中の全体のメンバー数と処理が完了（成功/失敗に関わらない）したメンバー数がレスポンスされます。
これらの値から処理の進捗割合が算出できます。
処理が完了したメンバーは結果がレスポンスされます。
レスポンスされる配列 members は、リクエスト時に指定したメンバー配列の並び順で対応しています。

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "members_bulk",
  "status": "progress",
  "tag": "create",
  "result": {
    "member_count": 1000,
    "completed_member_count": 287,
    "members": [
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル0001",
        "status": "succeeded"
      },
      ...,
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル1000",
        "status": "succeeded"
      }
    ]
  }
}

○一括登録がすべて成功して完了した場合

登録に成功したメンバーの status は succeeded となります。

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "members_bulk",
  "status": "completed",
  "tag": "create",
  "result": {
    "member_count": 1000,
    "completed_member_count": 1000,
    "members": [
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル0001",
        "status": "succeeded"
      },
      ...,
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル1000",
        "status": "succeeded"
      }
    ]
  }
}

○一括登録が一部失敗して完了した場合

登録に失敗したメンバーの status は failed となります。
登録に失敗したメンバーはメンバーIDがレスポンスされません。
登録に失敗したメンバーには失敗した理由が付与されます。

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "members_bulk",
  "status": "completed_with_errors",
  "tag": "create",
  "result": {
    "member_count": 1000,
    "completed_member_count": 1000,
    "members": [
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル0001",
        "status": "succeeded"
      },
      ...,
      {
        "member_name": "サンプル1000",
        "status": "failed",
        "error": {
            "error_code": "40901",
            "error_detail": "入力されたカード情報はすでに登録されています"
        }
      }
    ]
  }
}

〇予期せぬエラーが発生した場合

リクエスト進捗 failed がレスポンスされます。
正常に終了した場所までの結果がレスポンスされます。

{
  "request_id": "xxxxxx-xxxxxx-xxxxx",
  "request_type": "members_bulk",
  "status": "failed",
  "tag": "create",
  "result": {
    "member_count": 1000,
    "completed_member_count": 500,
    "members": [
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル0001",
        "status": "succeeded"
      },
      ...,
      {
        "member_id": "xxxxxx-xxxxxx-xxxxx",
        "member_name": "サンプル1000",
        "status": "failed",
        "error": {
            "error_code": "40901",
            "error_detail": "入力されたカード情報はすでに登録されています"
        }
      }
    ]
  }
}

ワンタイムQRの使用例

QRオプションをご契約のテナントでは定期的に変化するQRコード（ワンタイムQR）を使用することができます。
ワンタイムQRは各メンバーに対して設定をして使用します。メンバーごとに静的QRを使用するか、ワンタイムQRを使用するかが設定できます。

ワンタイムQRのQRコードデータは、ワンタイムQR取得APIをリクエストして取得する方法と自身（連携サービス内）で生成する方法があります。
それぞれの特徴を以下の表にまとめています。

	ワンタイムQR取得APIで取得する	自身（連携サービス内）でワンタイムQRを生成する
QRコードデータの生成元	SPLATS	連携サービス
実装	QRコードデータの切り替わりに応じた、UI上の表示切り替えが必要になります。	QRコードデータの切り替わりに応じた、UI上の表示切り替えに加えて、ワンタイムQRの詳細仕様に従ってワンタイムQRを生成する実装が必要になります。
遅延	ネットワークによる遅延を受ける可能性があります。 ※ SPLATS APIのレート制限にも影響します。	なし
利用フロー

ワンタイムQR取得APIで取得する

自身（連携サービス内）でワンタイムQRを生成する

QRコードデータの生成元

SPLATS

連携サービス

実装

QRコードデータの切り替わりに応じた、UI上の表示切り替えが必要になります。

QRコードデータの切り替わりに応じた、UI上の表示切り替えに加えて、ワンタイムQRの詳細仕様に従ってワンタイムQRを生成する実装が必要になります。

遅延

ネットワークによる遅延を受ける可能性があります。
※ SPLATS APIのレート制限にも影響します。

なし

利用フロー

ワンタイムQR取得APIで取得する

ワンタイムQRの設定をしたメンバーを登録する

メンバー登録APIでワンタイムQRを有効にしたメンバーをSPLATSに登録します。

{
  ...,
  "qrcode": {
    "data": "ABCDEF0123456789",
    "one_time_qr": {
      "enabled": true,
      "timestep": 30,
      "skew": 2
    }
  },
  ...
}

timestep や skew （タイムステップや許容ずれ）についてはワンタイムQRの詳細仕様を参照してください。

ワンタイムQRのQRコードデータを取得する

ワンタイムQR取得APIをリクエストして、ワンタイムQRのQRコードデータを取得します。
※ リクエストにはメンバーのワンタイムQRの設定を有効にする必要があります。

レスポンスの one_time_qr_data がワンタイムQRのQRコードデータとなるので、これを画像に変換して利用者に表示します。

{
  "member_id": "xxxxxx-xxxxxx-xxxxx",
  "one_time_qr_data": "SL-OTQR?v=1&data=ABCDEF0123456789&totp=123456",
  "version": "1",
  "expiration_in_seconds": 30
}

自身（連携サービス内）でワンタイムQRを生成する

ワンタイムQRの設定をしたメンバーを登録する

ワンタイムQR取得APIで取得する場合と同様にメンバーの設定を行います。

メンバー取得(個別)APIでTOTPシードを取得する

メンバー取得(個別)APIで登録したメンバーのワンタイムQR情報を取得します。
TOTPシードがレスポンスされます。

{
  ...,
  "qrcode": {
    "data": "ABCDEF0123456789",
    "one_time_qr": {
      "enabled": true,
      "totp_seed": "ABCDEFGHIJKLMNOPQRSTUVWXYZ012345",
      "timestep": 30,
      "skew": 2
    }
  },
  ...
}

ワンタイムQRのQRコードデータを生成する

取得したTOTPシードとタイムステップを使用してワンタイムQRを生成します。
詳細はワンタイムQRの詳細仕様を参照してください。

生成したワンタイムQRのQRコードデータを画像に変換して利用者に表示します。