API docs by Redocly

KEYVOX API | 開発者ポータル

Download OpenAPI specification:

KEYVOXアクセス管理サービスは、対応するロックやロッカーを導入することで、 宿泊施設、レンタルスペースやコワーキングスペース等の空間管理ビジネスを簡単に始められるソリューションです （サービスサイト https://keyvox.co）。KEYVOX APIはそのような空間管理ビジネスに必要な業務をAPIとして外部に提供することで、ユーザーの予約システム、管理システム、モバイルアプリなどに簡単に接続することを可能にします。 またWebhookを利用することで自社サービス等への解錠／施錠に関する通知も行えます。KEYVOX APIを利用してKEYVOXサービスを更に活用しましょう。
ご質問はDiscordコミュニティまでお寄せください。
※APIコール数には制限があります。

サンプルソースとして、Java、 PHP、JS(Postman用)を提供しています。

  1. 事前準備
    • KEYVOXのロックを利用する場合
      - ロックを購入します
      - KEYVOX管理画面（BACS - Blockchainlock Access Control Service）右上の①組織＞②開発者メニュー＞③APIキーを生成　からAPIキーを生成します
      - 生成したAPIキーとシークレットキーは④コピーで保存してください。


      - ⑤⑥でAPIを呼び出すサーバの公開IPアドレスを登録します。連携パートナーからAPIを呼び出す場合は、パートナーにIPアドレスをご確認ください。IPアドレスはレンジで指定することもできます。登録されているIPアドレス（レンジ）からのみAPIを呼び出すことができます。
      - KEYVOX Basicでデバイスのペアリングをします
      - KEYVOX 管理画面（BACS）で場所、ドア、デバイスの関係を設定します
    • 他社ロックを利用する場合（L!NKEY, OPELO, igloohome）
      - 各販売店よりデバイスを購入します
      - KEYVOX管理画面（BACS - Blockchainlock Access Control Service）右上の①組織＞②開発者メニュー＞③APIキーを生成　からAPIキーを生成し、公開IPアドレスを登録します。
      - (KEYVOXのロックを利用する場合を参照ください。)
      - BACSの設定＞デバイス＞デバイス追加で該当ロックを追加します
      - KEYVOX 管理画面（BACS）で場所、ドア、デバイスの関係を設定します
    • ロッカーを利用する場合
      - 販売店からロッカーを購入します
      - KEYVOX管理画面（BACS - Blockchainlock Access Control Service）右上の①組織＞②開発者メニュー＞③APIキーを生成　からAPIキーを生成し、公開IPアドレスを登録します。
      - (KEYVOXのロックを利用する場合を参照ください。)
      - ロッカーのMACアドレスをKEYVOX管理画面（BACS）に設定し、口数等必要な設定を済ませます（設定方法は納品時にご確認ください）

  2. Java、PHPでAPIを呼び出す場合
    - Java、PHPのサンプルソースをダウンロードします
    - 上記で取得したAPIキーに入れ替えて実行してみます
  3. postmanでAPIを呼び出す場合
    - postmanに使われるサンプルファイルpostman_collectionをダウンロードします
    - 参照：  Youtubeハンズオン

共通ヘッダ

Parameter Description Example
x-target-host

default.pms固定

 "default.pms"
date Client time. A difference of 5 seconds or more from the server time will deny access Mon, 29 Oct 2018 13:16:39 GMT
digest Sha256 summary of the body part (base64 encoding) SHA-256=2LJ53DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
authorization  Hmac256 authentication header. Contains 5 parts. hmac username="an9y4AidwJ3hsxfltlX7XXXXXXfGh", algorithm="hmac-sha256", headers="date request-line digest", signature="Mk0EOHf2ljFkltwPJBBvj5XXXXXNnCBnHs=" 
   Authentication header type "hmac" 
  username Issued apikey 
  algorithm Signature method. Fixed to "HMAC-SHA256"
  headers The data to be signed is composed. Fixed as "date request-line digest" 
  signature The value obtained by concatenating the data to be signed into a string in a specific way and then signing the string with apisecret.※ 

スマートロック

部屋リスト取得

WEB管理画面「BACS」で設定したドア(部屋)、ドアに紐づいているスマートロックまたはスマートロッカーの情報を取得します。カギの発行はドア(部屋)に対して行います。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Responses

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

部屋暗証番号リスト取得

WEB管理画面「BACS」で設定したドア(部屋)に発行されている暗証番号を取得します。
デバイスに対し、未発行(利用開始から72時間以上前)の暗証番号も取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

unitId
required
string

ドア（部屋）を識別するユニークID

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

position
string

取得レコードの位置を示すポインタID

records
string

取得レコード数、未指定の場合50

Responses

Request samples

Content type
application/json
{
  • "unitId": "000D6F0014A6F0B2",
  • "sTime": "1633359600",
  • "eTime": "1633532340",
  • "position": "11256",
  • "records": "10"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

QRコード・暗証番号発行

ドア(部屋)に対し暗証番号を新規発行します。発行された暗証番号は、ドア(部屋)に紐づけられたすべてのスマートロックに対して配信されます。スマートロックによって仕様が異なるため、異なる機種のスマートロックには同じドア(部屋)からのQRコード・暗証番号発行ができません。詳細はgetLockStatusのレスポンスを参照してください。

スマートロックの機種によって、発行できる暗証番号の桁数やタイミングが異なります。ご利用になるスマートロックの機種が特定できない場合、あらかじめgetLockStatusでスマートロックの種別を確認したうえで処理を変えていただくか、一律以下の処理を行うことを推奨します。

・クライアント側での暗証番号の指定は行わず、自動発行とする
・暗証番号の桁数をクライアント側で指定しない(スマートロック機種によって異なります)。
・createLockPinのおよそ5分後以降に、getLockPinStatusで暗証番号を取得する。
※getLockPinStatusのstatusに3X(30,31,32)が返却されるまで、定期的に取得を繰り返してください。
※暗証番号の発行は利用開始日時の72時間前から、となります。getLockPinStatusでの結果取得も「利用開始日時の72時間前」を過ぎてから行ってください。

QR1が発行するQRコードに関して
QR1が発行するQRコードには「オンラインQRコード」と「オフラインQRコード」の２種類があります。

オンラインQRコード：
サーバ側で発行したQRコードをQR1デバイスに配信します。配信後解錠できるまで数分の時間がかかります。

オフラインQRコード：
サーバ側のアルゴリズムで作成したQRコードを、QR1デバイスと通信することなく発行されたQRコードで即時に解錠できます。

/createLockPinにて「オンラインQRコード」もしくは「オフラインQRコード」のどちらを受け取るかは、KEYVOX管理画面、BACSの 設定＞デバイス＞デバイス詳細 で指定できます。
https://keyvox.notion.site/0834db2a7e6b4b19809448112ef68fa3?pvs=4

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

unitId
required
string

WEB管理画面「BACS」で設定したドア(部屋)ごとに割り当てられるユニークIDです。getUnitsで取得可能です。

pinCode
string

スマートロックに配信する暗証番号に任意の数字を指定する場合に使用します。4桁から8桁を指定できます。指定がなければ6桁が自動発番されまる。自動発番は6桁固定になります。オンラインQRコードは4桁から6桁のみの対応となります。

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "unitId": "5de092a8ef16f9512c1f1fff",
  • "pinCode": "123456",
  • "sTime": "1633305600",
  • "eTime": "1633316400",
  • "targetName": "BCL 太郎"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

QRコード・暗証番号変更

発行したQRコード・暗証番号を変更します。変更を行う際には、createLockPinのレスポンスに含まれるpinIdを指定する必要があります。一部のスマートロックは仕様が異なるため、変更、削除ができません。(※)

※スマートロック igloohome、OPELO をご利用されている場合、発行済みの暗証番号を変更、削除することはできません。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

pinId
required
string

暗証番号を識別するユニークID

pinCode
string

スマートロックに配信する暗証番号に任意の数字を指定する場合に使用します。4桁から8桁を指定できます。指定がなければ6桁が自動発番されまる。自動発番は6桁固定になります。オンラインQRコードは4桁から6桁のみの対応となります。

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "pinId": "c62325518edc528e24492ee8",
  • "pinCode": "123456",
  • "sTime": "1633305600",
  • "eTime": "1633316400",
  • "targetName": "XXXで利用"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

QRコード・暗証番号削除

発行したQRコード・暗証番号を削除します。削除を行う際には、createLockPinのレスポンスに含まれるpinIdを指定する必要があります。一部のスマートロックは仕様が異なるため、変更、削除ができません。(※)

※スマートロック igloohome、OPELO をご利用されている場合、発行済みの暗証番号を変更、削除することはできません。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

pinId
required
string

暗証番号を識別するユニークID

Responses

Request samples

Content type
application/json
{
  • "pinId": "c62325518edc528e24492ee8"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

暗証番号ステータス取得

pinIdを指定して、発行した暗証番号のスマートロックへの配信状況を確認します。スマートロックが複数ある場合、最も遅いステータスが返却されます。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

pinId
required
string

暗証番号を識別するユニークID

Responses

Request samples

Content type
application/json
{
  • "pinId": "c62325518edc528e24492ee8"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

デバイス暗証番号リスト取得

lockIdを指定して、スマートロックごとに発行済みの暗証番号を取得します。取得できるのはデバイスに配信済みの暗証番号のみです。
未来の暗証番号について、利用開始予定時間が72時間以内であれば、すぐ配信しますが、72間後以降の場合、72時間以内になってから配信を行います。
このAPIで取得できるのは配信済(利用開始予定時間が72時間以内）の暗証番号だけであり、それ以降のものについては取得できません。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

lockId
required
string

スマートロックを識別するユニークID

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

position
string

取得レコードが全体で何番目かの位置を示す情報

records
string

取得レコード数、未指定の場合50

Responses

Request samples

Content type
application/json
{
  • "lockId": "000D6F0014A6F0B2",
  • "sTime": "1633359600",
  • "eTime": "1633532340",
  • "position": "200",
  • "records": "10"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

ロック状態取得

lockIdを指定して、ロックの開閉状態、バッテリー残量、Wi-Fi接続状況を取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

lockId
required
string

スマートロックを識別するユニークID

Responses

Request samples

Content type
application/json
{
  • "lockId": "000D6F0014A6F0B2"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

ロック解錠履歴取得

デバイスのID（lockId）を指定して、ロックの開閉履歴を取得します。新しいAPIであるロックイベント履歴 /eventの利用を推奨します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

lockId
required
string

スマートロックを識別するユニークID

position
string

取得レコードの位置を示すポインタID
※初回で「position」を指定せず、履歴を取得したレスポンスの「position」を次回のパラメータとして使う

records
string

取得レコード数、未指定の場合50

Responses

Request samples

Content type
application/json
{
  • "lockId": "000D6F0014A6F0B2",
  • "position": "62fbba54a5ec72404000c962",
  • "records": "10"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

ロックイベント履歴取得

既存の/getLockHistoryに代わる新しいインターフェースで、QR1やその他のスマートロックの開錠、施錠などの操作・イベント履歴を条件指定で検索します。
header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

actionType
string

絞り込み条件（操作種別）

keyType
string

絞り込み条件（開錠方法）

keyWord
string

任意のキーワード（デバイス名等に一致）

sTime
required
string

検索範囲の開始日時
UNIX時間（秒）

eTime
required
string

検索範囲の終了日時
UNIX時間（秒）

sortWord
string

並び替え対象のフィールド

sequence
integer

0:降順 / 1:昇順

page
integer

1ページ目から指定

count
integer

表示件数（最大100前後）

Responses

Request samples

Content type
application/json
{
  • "actionType": "switch",
  • "keyType": "pin",
  • "keyWord": "QR1",
  • "sTime": "1745078400",
  • "eTime": "1745769540",
  • "sortWord": "createtime",
  • "sequence": 0,
  • "page": 1,
  • "count": 10
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

ロック開閉

lockIdを指定して、直接解錠、施錠を行います。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

lockId
required
string

スマートロックを識別するユニークID

flag
required
string
Enum: "0" "1"

鍵の開閉操作、0:施錠,1:解錠

Responses

Request samples

Content type
application/json
{
  • "lockId": "000D6F0014A6F0B2",
  • "flag": "0"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

カード配信

ドアに対しICカードを新規発行

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

unitId
required
string

WEB管理画面「BACS」で設定したドア(部屋)ごとに割り当てられるユニークIDです。getUnitsで取得可能です。

cardCode
required
string

Mifereの場合は、UIDを、Felicaの場合はIDmの値を指定します。

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "unitId": "5de092a8ef16f9512c1f1fff",
  • "cardCode": "C3AD47FC",
  • "sTime": "1633305600",
  • "eTime": "1633532340",
  • "targetName": "XXXで利用"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

カード更新

発行したICカードの利用期間、名前を変更します。変更を行う際には、setCardのレスポンスに含まれるcardIdを指定する必要があります。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

cardId
required
string

カードを識別するユニークID

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "cardId": "c62325518edc5224492ee8",
  • "sTime": "1633305600",
  • "eTime": "1633532340",
  • "targetName": "XXXで利用"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

カード削除

発行したICカードを削除します。削除を行う際には、setCardのレスポンスに含まれるcardIdを指定する必要があります。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

cardId
required
string

カードを識別するユニークID

Responses

Request samples

Content type
application/json
{
  • "cardId": "c62325518edc5224492ee8"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

カードステータス取得

accessIdを指定して、発行したICカードのスマートロックへの配信状況を確認します。スマートロックが複数ある場合、最も遅いステータスが返却されます。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

cardId
string

setLockerCardでアクセス権を設定した際に返却される、アクセス権ごとのユニークIDです。アクセス権を更新する際に指定します。

Responses

Request samples

Content type
application/json
{
  • "cardId": "5f7e9dba0cc45444a0b3a895"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

カードリスト取得

lockIdを指定して、スマートロックごとに発行済みのICカード情報を取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

lockId
required
string

スマートロックを識別するユニークID

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

position
string

取得レコードが全体で何番目かの位置を示す情報

records
string

取得レコード数、未指定の場合50

Responses

Request samples

Content type
application/json
{
  • "lockId": "000D6F0014A6F0B2",
  • "sTime": "1633305600",
  • "eTime": "1633532340",
  • "position": "200",
  • "records": "10"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

スマートロッカー

部屋リスト取得

WEB管理画面「BACS」で設定したドア(部屋)、ドアに紐づいているスマートロックまたはスマートロッカーの情報を取得します。カギの発行はドア(部屋)に対して行います。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Responses

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

ロッカー取得

WEB管理画面「BACS」に登録されているロッカー本体の情報を取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Responses

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

ロッカーステータス取得

deviceIdを指定し、ロッカー本体ごとの各ボックスの利用状況を取得します。ボックス番号(boxNum)はWEB管理画面「BACS」にて確認できます。
※boxNumは数字でxx-yyの形式となり、xxは副キャビネット番号、yyはBOX番号です。それぞれの番号は固定ではなくロッカー毎に違います。BACSの設定＞ロッカー＞ボックス設定画面で確認の上、指定してください。
詳しくはこちら

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

スマートロッカーを識別するユニークID

boxNum
string

ボックスの番号情報を"00-01"のような書式で指定します。00は副キャビネット番号、01はBOX番号を表します。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "5bceb8e2076d20135c307916",
  • "boxNum": "00-01"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

ロッカーステータス設定

deviceIdを指定し、ロッカー本体ごとの各ボックスの状況を設定します。ボックス番号(boxNum)はWEB管理画面「BACS」にて確認できます。
※boxNumは数字でxx-yyの形式となり、xxは副キャビネット番号、yyはBOX番号です。それぞれの番号は固定ではなくロッカー毎に違います。BACSの設定＞ロッカー＞ボックス設定画面で確認の上、指定してください。
詳しくはこちら

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

スマートロッカーを識別するユニークID

boxNum
required
string

ボックスの番号情報を"00-01"のような書式で指定します。00は副キャビネット番号、01はBOX番号を表します。

status
required
string
Enum: "0" "3"

ステータス。0：未使用, 3：故障。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "5bceb8e2076d20135c307916",
  • "boxNum": "00-01",
  • "status": "0"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

ロッカー解錠

deviceId、boxNumを指定して、ロッカーの特定のボックスを直接解錠します。
※boxNumは数字でxx-yyの形式となり、xxは副キャビネット番号、yyはBOX番号です。それぞれの番号は固定ではなくロッカー毎に違います。BACSの設定＞ロッカー＞ボックス設定画面で確認の上、指定してください。
詳しくはこちら

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

スマートロッカーを識別するユニークID

boxNum
required
string

ボックスの番号情報を"00-01"のような書式で指定します。00は副キャビネット番号、01はBOX番号を表します。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "A5C8A98B35260000",
  • "boxNum": "00-01"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

ロッカーにカード配信

ロッカーの特定のボックスに対し、ICカードの利用権限を発行します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
string

スマートロッカーを識別するユニークID

boxNum
string

ボックスの番号情報が"00-01"のような書式で返却されます。00は副キャビネット番号、01はBOX番号を表します。
getLockerStatusのレスポンスでboxNumを確認することができます。

cardCode
string

Mifereの場合は、UIDを、Felicaの場合はIDmの値を指定します。

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "A5C8A98B35260000",
  • "boxNum": "00-01",
  • "cardCode": "C3AD47FC",
  • "sTime": "1633305600",
  • "eTime": "1633532340",
  • "targetName": "XXX用ロッカーのカード"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

ロッカーにカード更新

発行したICカードの利用期間、名前を変更します。変更を行う際には、setLockerCardのレスポンスに含まれるaccessIdを指定する必要があります。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

accessId
required
string

setLockerCardでアクセス権を設定した際に返却される、アクセス権ごとのユニークIDです。

sTime
required
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
required
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "accessId": "string",
  • "sTime": "1633305600",
  • "eTime": "1633532340",
  • "targetName": "XXXロッカーのカード"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

ロッカーQRコード・暗証番号発行

ロッカーの特定のボックスに対し、暗証番号を発行します。 暗証番号の他に、レスポンスとしてQRコード生成用URLも取得することができます。 暗証番号の扱いについてはいくつかのオプションがあります。 詳細はインターフェース内容の説明をご確認ください。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

ロッカーを識別するユニークID

boxNum
string

ボックスの番号情報を"00-01"のような書式で指定します。00は副キャビネット番号、01はBOX番号を表します。

checkin
string
Enum: "0" "1"

ボックスのステータスを指定します。
0:「利用中」の状態でボックスを確保します。ロッカーを解錠した際、利用中のボックスを再度開いた扱いとなります。
1:「利用前」の状態でボックスを確保します。ロッカーを解錠した際、新規利用の扱いとなります。他の利用権限ですでにボックスを利用されている場合、利用開始ができません。

mode
string
Enum: "0" "1" "2"

0:once(一度のみ利用可能なモードです。利用開始後、返却したら再度利用開始することはできません。また、利用中のままeTimeを過ぎても自動的に返却扱いとはなりません。)
1:multi(繰り返し利用可能なモードです。sTime - eTimeの間、返却しても再度利用開始することができます。利用中のままeTimeを過ぎても自動的に返却扱いとはなりません。)
2:always(sTime - eTimeの間、何度も解錠可能なモードです。期間中は確保したボックスを占有し、ゲストから返却することはできません。eTimeを過ぎたら自動的に返却扱いとなります。)

reassign
string
Enum: "0" "1"

Reassign. 0:false(指定したボックスが利用中の場合、空きがないエラーをロッカー端末に表示します。)
1:true(指定したボックスが利用中の場合、別のボックスを自動的にアサインします。)

pinCode
string

スマートロッカーに配信する暗証番号に任意の数字を指定する場合に使用します。(6桁)

sTime
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "A5C8A98B35260000",
  • "boxNum": "00-01",
  • "checkin": "1",
  • "mode": "0",
  • "reassign": "0",
  • "pinCode": "123456",
  • "sTime": "1633305600",
  • "eTime": "1633532340",
  • "targetName": "XXX用のロッカー暗証番号"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

ロッカーQRコード・暗証番号更新

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

pinId
required
string

暗証番号を識別するユニークID

pinCode
string

スマートロッカーに配信する暗証番号に任意の数字を指定する場合に使用します。(6桁)

sTime
required
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
required
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

targetName
string

カギを利用する利用者名を指定します。WEB管理画面「BACS」の履歴などに表示されます。

Responses

Request samples

Content type
application/json
{
  • "pinId": "ABACCD0G1",
  • "pinCode": "123456",
  • "sTime": "1633359600",
  • "eTime": "1633532340",
  • "targetName": "XXX用のロッカー"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

ロッカーQRコード・暗証番号削除

発行したQRコード・暗証番号を削除します。削除を行う際には、createLockerPinのレスポンスに含まれるpinIdを指定する必要があります。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

pinId
required
string

暗証番号を識別するユニークID

Responses

Request samples

Content type
application/json
{
  • "pinId": "ABACCD0G1"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

ロッカー権限リスト取得

ロッカーの特定のボックスに対し、登録済みのカギ情報を取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

スマートロッカーを識別するユニークID

boxNum
string

ボックスの番号情報を"00-01"のような書式で指定します。00は副キャビネット番号、01はBOX番号を表します。
getLockerStatusのレスポンスでboxNumを確認することができます。

sTime
required
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
required
string (getLockerOrdersIn)

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "A5C8A98B35260000",
  • "boxNum": "00-01",
  • "sTime": "1633359600",
  • "eTime": "1633532340"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

ロッカー空きボックスリスト取得

ロッカー本体ごとに、空いているボックスを取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

スマートロッカーを識別するユニークID

boxSize
string

WEB管理画面「BACS」で設定したスマートロッカーのサイズ情報を指定するサイズ番号が返却されます。

sTime
required
string

利用開始日時、1970/01/01からの秒数(UNIX時間)で指定します。

eTime
required
string

利用終了日時、1970/01/01からの秒数(UNIX時間)で指定します。

Responses

Request samples

Content type
application/json
{
  • "deviceId": "5bceb8e2076d20135c307916",
  • "boxSize": "1",
  • "sTime": "1633359600",
  • "eTime": "1633532340"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": [
    ]
}

ロッカーLED色指定

ロッカーボックス毎のLED状態を指定します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

deviceId
required
string

スマートロッカーを識別するユニークID

boxNum
required
string

ボックスの番号情報を"00-01"のような書式で指定します。00は副キャビネット番号、01はBOX番号を表します。

boxColor
required
integer

ボックスの色を指定します。
0：消灯、1:点灯(緑)、2:点灯(赤)、3:点灯(青)

Responses

Request samples

Content type
application/json
{
  • "deviceId": "A5C8A98B35260000",
  • "boxNum": "00-01",
  • "boxColor": 0
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

ロッカーイベント履歴取得

ロッカーの開錠、施錠などの操作・イベント履歴を条件指定で検索します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

orgId
string

組織ID

userName
string

ユーザー名

count
integer

表示件数（最大100前後）

page
integer

1ページ目から指定

sTime
required
string

検索範囲の開始日時
UNIX時間（秒）

eTime
required
string

検索範囲の終了日時
UNIX時間（秒）

actionType
string

絞り込み条件（操作種別）

keyType
string

絞り込み条件（開錠方法）

Responses

Request samples

Content type
application/json
{
  • "orgId": "5f35065f968a8874400fb156",
  • "userName": "山田太郎",
  • "count": 10,
  • "page": 1,
  • "sTime": "1745078400",
  • "eTime": "1745769540",
  • "actionType": "switch",
  • "keyType": "pin"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

WEB管理画面「BACS」操作

カード登録

WEB管理画面「BACS」に対し、ICカードの情報を登録します。あらかじめICカードのIDｍ/UIDをご用意いただく必要があります。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

cardCode
required
string

Mifereの場合は、UIDを、Felicaの場合はIDmの値を指定します。

cardName
required
string

カード名

cardDesc
string

カード備考

Responses

Request samples

Content type
application/json
{
  • "cardCode": "C3AD47FC",
  • "cardName": "XXXX用カード",
  • "cardDesc": "XXXXで利用"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

カード削除

WEB管理画面「BACS」に対し、登録したICカードの情報を削除します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

Array of objects (delCard)

Responses

Request samples

Content type
application/json
{
  • "cardList": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success"
}

予約

予約リスト取得

WEB管理画面「BACS」で設定したドア(部屋)に紐づいている、未チェックインの予約情報一覧を取得します。

header Parameters
x-target-host
required
string

default.pms

date
required
string

RFC-1123 Ex: Mon, 20 Sep 2021 13:16:39 GMT

digest
required
string

Sha256 summary of the body part (base64 encoding)

authorization
required
string

Hmac256 authentication header.

Request Body schema: application/json
required

入力パラメータ

unitId
required
string

WEB管理画面「BACS」で設定したドア(部屋)ごとに割り当てられるユニークIDです。getUnitsで取得可能です。

Responses

Request samples

Content type
application/json
{
  • "unitId": "5de092a8ef16f9512c1f1fff"
}

Response samples

Content type
application/json
{
  • "code": "0",
  • "msg": "success",
  • "data": {
    }
}

©2025 KEYVOX