1 / 1

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 認証レコードタイプの種類

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

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

設定が完了したら、保存ボタンをクリックしてください。オープンプラットフォーム画面に戻ります。サブスクリプションサービスステータスが「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するイベントのパラメーター

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

group フィールドの説明

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

通常のレスポンス

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

レスポンスのフィールド

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

概要

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

リクエストアドレスの例

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

リクエスト方法

POST application/json

リクエストパラメーター

認証パラメーター

通常のレスポンス

{
    "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
    }
}

レスポンスのフィールド

dataフィールドの説明

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

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

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

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

レスポンスのフィールド

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

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

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

{
    "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
    }
}

レスポンスのフィールド

dataフィールドの説明

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

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

概要

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

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

{
    "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"
        },
    ]
}

レスポンスのフィールド

dataフィールドの説明

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

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

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

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

レスポンスのフィールド

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

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

2.10.1 概要

2.10.2 利用の開始

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

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

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

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

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

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

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

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

2.10.6 Push失敗の場合

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

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

2.10.7 イベント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するイベントのパラメーター

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

group フィールドの説明

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

通常のレスポンス

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

レスポンスのフィールド

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

概要

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

リクエストアドレスの例

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

リクエスト方法

POST application/json

リクエストパラメーター

認証パラメーター

通常のレスポンス

{
    "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
    }
}

レスポンスのフィールド

dataフィールドの説明

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

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

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

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

レスポンスのフィールド

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

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

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

{
    "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
    }
}

レスポンスのフィールド

dataフィールドの説明

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

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

概要

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

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

{
    "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"
        },
    ]
}

レスポンスのフィールド

dataフィールドの説明

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

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

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

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

レスポンスのフィールド

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