2.10 イベントサブスクリプション API

2.10.1 概要

外部システムはSenseLinkのサブスクリプションサービスを利用することで、SenseLinkのイベントをサブスクライブすることができます。SenseLinkはデバイスの認証とアラート（以下、「イベント」）をPOSTリクエスト（以下、「Push」）することができます。

2.10.2 利用の開始

当節で記載される手順・設定の他にJCVサポート窓口へ以下の情報を申請してください。申請およびJCVサポート窓口の処理が完了するまで、イベントサブスクリプション機能は利用できません。

イベントを処理するAPIエンドポイント（アプリケーションのURL）
上記エンドポイントのIPアドレス

サブスクリプション申請時に提出する情報は以下のものです

固定IPアドレスとポート番号（必須）
URL（サブスクリプションを受け取るクライアント側URL）（必須）
※注：クライアント側URLとの通信に際し、BASIC認証などの認証技術は対応しておりません。
アカウントID （必須）
テナントID（オプション）

イベントをサブスクライブする外部システムのAPIエンドポイントは、SenseLinkのナビゲーションメニュー [ユーザー名]→[オープンプラットフォーム] 内のサブスクリプションサービスステータス欄のドメイン管理、もしくは本マニュアル内のAPIで設定および更新することができます。

サブスクリプションサービス設定を選択して表示されるイベント処理サーバーアドレスの欄に、連携する外部システムのサーバーアドレスを入力してください。プロトコルはhttp、httpsをサポートしています。https://またはhttps://から入力してください。複数のエンドポイントを設定することができますので、セミコロン（;）で区切ってください。

サブスクリプションイベントタイプ欄で「認証レコード」にチェックを入れ、サブスクライブするイベントのタイプを選んでください。

デバイスで認証が行われた際、認証レコードをPushで受け取るには認証レコード、デバイスアラートが発生した場合にPushで受け取るにはデバイスアラートを選択してください。なお、両方を選択することも可能です。

2.10.4 認証レコードタイプの種類

認証レコードタイプには、以下の種類があります。

パラメーター名

正常な認証レコード

顔＋IDカード不一致

顔＋ICカード不一致

顔＋QRコード不一致

来訪期間外

アクセス時間外

無効なIDカード

無効なICカード

無効なQRコード

温度異常

マスク検知用

認証レコード＋

サブスクリプションを更新した際に、再保存時に認証レコードタイプ/デバイスアラートタイプが「未選定」の状態になる場合があります。その場合は再設定してください。

設定が完了したら、保存ボタンをクリックしてください。オープンプラットフォーム画面に戻ります。サブスクリプションサービスステータスが「Normal」と表示されていれば、イベントがサブスクライブされています。

2.10.5 サブスクリプションサービスの設定の変更と停止

サブスクリプションサービスの設定を変更するには、サブスクリプションサービス欄の詳細ボタンをクリックしてください。

サブスクリプションサービスを停止するには、サブスクリプション停止ボタンをクリックしてください。サービスが停止され、外部システムにイベントがPushされなくなります。

サブスクリプションサービスの設定を修正するには、サブスクリプション更新ボタンをクリックしてください。設定内容を変更できます。変更内容を入力後、保存してください。

2.10.6 Push失敗の場合

イベントのPush後、外部システムは100秒以内にレスポンスを返却するか、リターンコード200を返却する必要があります。

100秒以内にレスポンスが返却されない場合、またはリターンコードが200以外の場合はエラーとみなされ、SenseLinkはそのイベントを再Pushしません。その後SenseLinkは外部システムのサブスクリプションステータスを「異常」に変更し、エラーログとして保存されます。ただし、その後発生した新しいイベントのPushには影響はありません。

なお、レスポンスが100秒以内に返却された、かつリターンコードが200になった場合、サブスクリプションステータスは「正常」に戻ります。

2.10.7 イベントPushログ

オープンプラットフォーム画面のサブスクリプションサービスステータス欄の詳細をクリックし、サブスクリプションサービスの設定画面にあるログボタンをクリックすると、最新のイベントPushの結果（以下、「ログ」）を確認することができます。

ログは最大100件まで保存され、100件を越えると古いものから順に削除されます。各ログの詳細ボタンをクリックすると認証レコードページまたはデバイスアラートページに遷移し、イベントの詳細を確認することができます。イベントタイプまたはステータスで、ログを検索することができます。リセットボタンをクリックすると検索による絞り込みがリセットされ、すべてのログが表示されます。

テストイベント送信ボタンをクリックすると、テストイベントを連携中の外部システムにPush することができます。認証レコードとデバイスアラートが選択されている場合、または認証レコードのみが選択されている場合は認証レコードのテストイベントが送信されます。デバイスアラートのみが選択されている場合、デバイスアラートのテストイベントが送信されます。

2.10.8 イベントPushのプロトコル

リクエスト方法

POST application/json

イベントPushの例

認証レコード

{
    messageId: '75835750-6dd9-4eed-a929-ba1b4c062405',
    eventType: 30000,
    data: { 
        id: 120260,
        userId: 30707,
        name: '次郎',
        type: 1,
        avatar: '5e65c020f54fd90001fe4a33',
        direction: 0,
        verifyScore: 0.94,
        receptionUserId: 0,
        receptionUserName: null,
        groups: [ { id: 1, name: 'Default group', type: 1 } ],
        deviceName: 'SenseTest',
        sn: 'SPS-e33b1811dbd9189c5eeedffd557fd779',
        signDate: '2020-03-09',
        signTime: 1583726625,
        signAvatar: '5e65c021f54fd90001fe4a37',
        signBgAvatar: '5e65c021f54fd90001fe4a38',
        companyId: 1,
        mobile: '18014398265',
        icNumber: '',
        idNumber: '',
        jobNumber: '3867452109',
        remark: 'welcome',
        entryMode: 1,
        signTimeZone: '+09:00',
        docPhoto: '',
        latitude: 0,
        longitude: 0,
        address: '',
        location: 'SZ-40F',
        abnormalType: 40001,
        userIcNumber: '4751283096',
        userIdNumber: '1g2qW2hz5OwbudHe5gekKbZtmUt0Xwfy',
        bodyTemperature: 38,
        mask: 1,
        signTimeStr:'2021-10-28 12:08:53'
        extInfo:"[{\"name\":\"attendance_flag\",\"value\":1}]"
    },
    sendTime: 1583726626015,
}

デバイスアラート

{
    messageId: '5ee92a0e-7c6b-416c-8843-54a154a3a409',
    eventType: 30100,
    data:{
        id: 35569,
        traceId: '1583726800000',
        code: 10001,
        alarmTime: '2020-03-09 12:06:40',
        level: 1,
        deviceId: 204,
        deviceSn: 'SPS-e33b1811dbd9189c5eeedffd557fd779',
        deviceLocation: 'SZ-40F',
        deviceName: 'SenseTest',
        resloveOption: 3,
        alarmPhoto: '5e65c0d1f54fd90001fe4a39',
        companyId: 1,
        description: 'Device removal',
        releaseTime: '',
        status: 3
    },
    sendTime: 1583726801752
}

Pushするイベントのパラメーター

パラメーター名

型

必須

説明

messageId

string

Yes

イベントの固有の識別子

eventType

int

Yes

30000：認証レコード

30100：デバイスアラート

sendTime

long

Yes

イベント発生時刻（デバイス時間）

data

object

Yes

イベントの対象

認証レコードデータの属性

パラメーター名

型

説明

int

レコードID

userId

int

認証されたユーザーのID

name

string

認証されたユーザーの名前

type

int

ユーザーの識別子タイプ

1：従業員

2：ビジター

3：未登録人物

5：拒否リスト

avatar

string

認証用顔写真

direction

int

デバイスのアクセス方向

verifyScore

float

認証スコア

receptionUserId

int

認証されたユーザーの対応者ID

receptionUserName

string

認証されたユーザーの対応者の名前

groups

list<group>

認証されたユーザーのグループ情報

deviceName

string

デバイス名

string

この認証レコードのデバイス LDID番号をアップロードします

signDate

string

認証レコードの日付

signTime

timestamp

認証時刻（秒）

signAvatar

string

認証時写真（サムネイル）

signBgAvatar

string

認証時写真（大）

companyId

long

企業ID

mobile

string

認証されたユーザーの携帯電話番号

icNumber

string

認証されたユーザーのICカード番号

idNumber

string

認証されたユーザーのID番号（利用できません）

jobNumber

string

認証されたユーザーの従業員ID

remark

string

特記事項

entryMode

int

認証モード

1：顔認証

2：QRコード

3：カード

4：顔認証とカード

5：IDカード

6：顔認証とIDカード

signTimeZone

string

認証レコードのタイムゾーン

docPhoto

string

ID写真

latitude

double

緯度

longitude

double

経度

address

string

住所

location

string

デバイスの設置場所

abnormalType

int

認証レコードの異常のタイプ

0：なし

10001：IDカード不一致

10002：認証カード不一致

10003：認証コード不一致

20001：ビジターが有効期限外

20002：アクセス期限内ではない

30001：無効なIDカード

30002：無効なICカード

30003：無効なQRコード

40001：異常な体温

50001：マスク着用なし

userIdNumber

（利用できません）

bodyTemperature

float

体温

mask

int

マスク着用識別子

0：不明

1：着用なし

2：着用あり

signTimeStr

string

認証時刻

extinfo

string

拡張情報

group フィールドの説明

パラメーター名

型

説明

long

グループID

name

string

グループ名

type

int

グループタイプ

1：従業員グループ

2：ビジターグループ

5：拒否リストグループ

デバイスのアラートレコードのデータ属性

パラメーター名

型

説明

long

アラートレコードのID

traceId

string

アラートのシリアル番号。デバイスによって生成されるアラート固有の識別番号です。

code

int

アラートのタイプ

10001：デバイスの盗難アラート

10002：ドア・ゲート強制突破アラート

10003：ドアセンサータイムアウト

10004：パスワードクラッキング

10005 ：（サポートされないアラートです。現在利用できません）

10006：サーモグラフィカメラ接続異常

20001：カメラの汚れ

20002：Non-Living アタック（非生体による認証）

20003：消防アラート

30001：デバイスオフラインアラート

40001：特徴量抽出エラー

alarmTime

string

アラート時間

level

int

アラートレベル

1：アラート

2：異常

deviceId

long

デバイスのID

deviceSn

string

デバイスのLDID

deviceLocation

string

デバイスの設置場所

deviceName

string

デバイス名

resloveOption

int

アラートの解除オプション

0：解除不要

1：デバイスエンドでの解除のみをサポート

2：リモート解除のみをサポート

3：デバイスエンドまたはリモートでの解除

0：解除不要

10004：パスワードクラッキング

20002：Non-Living アタック（非生体による認証）

30001：デバイスオフラインアラート

1：デバイスエンドでの解除のみをサポート

10003：ドアセンサータイムアウト

20001：カメラの汚れ

10005 ：（サポートされないアラートです。現在利用できません）

10006：サーモグラフィカメラ接続異常

3：デバイスエンドまたはリモートでの解除

10001：デバイスの盗難アラート

10002：ドア・ゲート強制突破アラート

20003：消防アラート

alarmPhoto

string

アラート写真

companyID

long

企業ID

description

string

アラートの説明

releaseTime

string

アラートの解除時間

status

int

アラートのステータス

1：アラート作動中

2：解除中

3：解除済み

通常のレスポンス

{
 "code": 200,
 "message": "success",
 "desc": "",
 "data": {}
}

レスポンスのフィールド

パラメーター名

型

必須

説明

code

int

Yes

リターンコード。200 は成功を示し、その他のコードは失敗を示します

message

string

Yes

リターン情報です。インターフェース実行情報を記録します。successは成功の情報を示し、その他は失敗を示します

desc

string

リターンの説明

data

object

データ

2.10.9 サブスクリプション更新API (/api/v4/event/updateSub)

概要

イベントのサブスクリプションを追加または更新します。

リクエストアドレスの例

https://link.japancv.co.jp/api/v4/event/updateSub

リクエスト方法

POST application/json

リクエストパラメーター

パラメーター名

型

必須

説明

recognition_records_types

list<int>

Yes

認証レコードの異常のタイプ

0：正常な認証レコード

10001：IDカード不一致

10002：認証カード不一致 10003：認証コード不一致

20001：ビジターが有効期限外

20002：アクセス期限内ではない

30001：無効な ID カード

30002：無効な IC カード

30003：無効な QR コード

40001：異常な体温

50001：マスク着用なし

device_alarm_types

list<int>

Yes

アラートのタイプ

10001：デバイスの盗難アラート

10002：ドア・ゲート強制突破アラート

10003：ドアセンサータイムアウト

10004：パスワードクラッキング

10005：（サポートされないアラートです。現在利用できません）

10006：サーモグラフィカメラ接続異常

20001：カメラの汚れ

20002：Non-Living アタック（非生体による認証）

20003：消防アラート

30001：デバイスオフラインアラート

40001：特徴量抽出エラー

event_dest

string

Yes

空の値で登録しないでください

認証パラメーター

パラメーター名

型

必須

説明

app_key

string

Yes

Appキー

sign

string

Yes

timestamp

string

Yes

タイムスタンプ

通常のレスポンス

{
    "code":200,
    "message":"OK",
    "data":{
        "recognition_records_types":[
            0,
            10001,
            10002
        ],
        "device_alarm_types":[
            20003,
            30001,
            40001
        ],
        "event_dest":"https://ip:port/eventRcv",
        "sub_status":1
    }
}

レスポンスのフィールド

パラメーター名

型

説明

code

int

リターンコード。200 は成功を示し、その他のコードは失敗を示します

message

string

リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します

desc

string

リターンの説明

data

object

データ

dataフィールドの説明

パラメーター名

型

説明

recognition_records_types

list<int>

認識レコードタイプの配列

device_alarm_types

list<int>

デバイスアラートの配列

event_dest

string

イベントをサブスクライブする外部システムのサーバーアドレス

sub_status

int

サブスクリプションサービスのステータス

0：構成されていません

1：正常

2：異常（最後のPushステータスに基づく）

エラーレスポンスのフィールド

code

メッセージ

説明

60001

openapi status error

OpenAPIステータス異常

30001

Param Invalid

外部システムのサーバーアドレスが不正です

30001

Param Invalid

イベントIDが存在しません

30001

Param Invalid

無効なパラメーターです

30001

Param Invalid

認識レコードタイプが不正です

30001

Param Invalid

デバイスアラートタイプが不正です

2.10.10 サブスクリプション停止API (/api/v3/event/stopSub)

概要

イベントのサブスクリプションを停止します。

リクエストアドレスの例

https://link.japancv.co.jp/api/v3/event/stopSub

リクエスト方法

GET

認証パラメーター

パラメーター名

型

必須

説明

app_key

string

Yes

Appキー

sign

string

Yes

timestamp

string

Yes

タイムスタンプ

通常のレスポンス

{
 "code": 200,
 "message": "success",
 "desc": "",
 "data": {}
}

レスポンスのフィールド

パラメーター名

型

説明

code

int

リターンコード。200 は成功を示し、その他のコードは失敗を示します

message

string

リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します

desc

string

リターンの説明

data

object

データ

エラーレスポンスのフィールド

code

メッセージ

説明

60001

openapi status error

OpenAPIステータス異常

60002

not config event sub

サブスクリプションサービスが構成されていません

2.10.11 サブスクリプション詳細表示API (/api/v4/event/viewSub)

概要

サブスクリプションの詳細を表示します。

リクエストアドレスの例

https://link.japancv.co.jp/api/v4/event/viewSub

リクエスト方法

GET

認証パラメーター

パラメーター名

型

必須

説明

app_key

string

Yes

Appキー

sign

string

Yes

timestamp

string

Yes

タイムスタンプ

通常のレスポンス

{
    "code": 200,
    "message": "success",
    "desc": "",
    "data": {
        "recognition_records_types": [
            50001,
            40001
        ],
        "device_alarm_types": [
            10001,
            10002
        ],
        "event_dest": "https://ip:port/eventRcv",
        "sub_status": 1
    }
}

レスポンスのフィールド

パラメーター名

型

説明

code

int

リターンコード。200 は成功を示し、その他のコードは失敗を示します

message

string

リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します

desc

string

リターンの説明

data

object

データ

dataフィールドの説明

パラメーター名

型

説明

recognition_records_types

list<int>

認証レコードの異常のタイプ

0 ：正常な認証レコード

10001：IDカード不一致

10002：認証カード不一致

10003：認証コード不一致

20001：ビジターが有効期限外

20002：アクセス期限内ではない

30001：無効な ID カード

30002：無効な IC カード

30003：無効な QR コード

40001：異常な体温

50001：マスク着用なし

device_alarm_types

list<int>

アラートのタイプ

10001：デバイスの盗難アラート

10002：ドア・ゲート強制突破アラート

10003：ドアセンサータイムアウト

10004：パスワードクラッキング

10005：（サポートされないアラートです。現在利用できません）

10006：サーモグラフィカメラ接続異常

20001：カメラの汚れ

20002：Non-Living アタック（非生体による認証）

20003：消防アラート

30001：デバイスオフラインアラート

40001：特徴量抽出エラー

event_dest

string

イベントをサブスクライブする外部システムのサーバーアドレス

sub_status

int

サブスクリプションサービスのステータス

0：構成されていません

1：正常

2：異常（最後のPushステータスに基づく）

エラーレスポンスのフィールド

コード

メッセージ

説明

60001

openapi status error

OpenAPIステータス異常

60002

not config event sub

サブスクリプションサービスが構成されていません

2.10.12 イベントPushログの表示 (/api/v3/event/viewLog)

概要

イベントのPushログを表示します。

サブスクリプションサービスが起動されなくても、該当するAPIを使って前に生成されたログを取得できます。

リクエストアドレスの例

https://link.japancv.co.jp/api/v3/event/viewLog

リクエスト方法

GET

認証パラメーター

パラメーター名

型

必須

説明

app_key

string

Yes

Appキー

sign

string

Yes

timestamp

string

Yes

タイムスタンプ

通常のレスポンス

{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": 20816,
            "status": 200,
            "company_id": 1162,
            "event_type_id": 30000,
            "event_message": null,
            "create_at": "2022-03-21T02:14:16.000+0000",
            "message_id": 29767021,
            "push_id": "00000000-0000-0000-0000-000000000000",
            "is_test": null,
            "abnormal_code": 0,
            "event_dest": "https://ip:port/eventRcv"
        },
    ]
}

レスポンスのフィールド

パラメーター名

型

説明

code

int

リターンコード。200 は成功を示し、その他のコードは失敗を示します

message

string

リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します

desc

string

リターンの説明

data

object

リターンデータです。イベントサブスクリプションの詳細です

dataフィールドの説明

パラメーター名

型

説明

int

イベントID

company_id

int

企業ID

event_type_id

int

イベントタイプの ID

30000：認証レコード

30100：アラートPush

event_message

string

Pushメッセージ本体

status

int

リターンステータス

200：成功

404：サーバー応答不可

500 : 内部例外

create_at

string

イベント生成時間

message_id

int

レコードID、またはアラームID

push_id

string

イベントプッシュID

is_test

int

テストイベント：1

非テストイベント：0

abnormal_code

int

イベントメッセージ

event_dest

string

イベント処理サーバーアドレス

エラーレスポンスのフィールド

コード

メッセージ

説明

60001

openapi status error

OpenAPIステータス異常

60002

not config event sub

サブスクリプションサービスが構成されていません

2.10.13 テストイベントの送信 (/api/v3/event/sendTest)

概要

テストイベントをPush送信します。

リクエストアドレスの例

https://link.japancv.co.jp/api/v3/event/sendTest

リクエスト方法

GET

認証パラメーター

パラメーター名

型

必須

説明

app_key

string

Yes

Appキー

sign

string

Yes

timestamp

string

Yes

タイムスタンプ

通常のレスポンス

{
 "code": 200,
 "message": "success",
 "desc": "",
 "data": {}
}

レスポンスのフィールド

パラメーター名

型

説明

code

int

リターンコード。200 は成功を示し、その他のコードは失敗を示します

message

string

リターン情報です。インターフェース実行情報を記録します。success は成功を示し、その他は失敗を示します

desc

string

リターンの説明

data

object

リターンデータ

エラーレスポンスのフィールド

コード

メッセージ

説明

60001

openapi status error

OpenAPIステータス異常

60002

not config event sub

サブスクリプションサービスが構成されていません

前へ2.9 部署の API 次へ2.11 認証レコード+API

最終更新 2 年前