自社システムをつなぐ: API、認証、自動化
自社のソフトウェアが Offision に届く道筋 — スコープ付きの API 認証情報、REST リファレンスと OpenAPI ドキュメント、リダイレクト先となるシステム URL、自動化の ためのワークフローモジュール — と、送信 Webhook のように Offision が提供して いないもの。
自社のソフトウェアが Offision に対してできることは、すべて 1 つのページから始まります。マーケットプレイス の API 認証 です。そこにある 1 行が 1 つの連携クライアント — 自社システムが提示する 1 つの認証情報で、触れてよい範囲が決められています。共通のマスターキーはありません。人事連携とサイネージ配信はそれぞれ自分の認証情報を持ちます。
API 認証を開く
「API 認証」— 連携クライアントごとに 1 行。
認証情報とそのスコープ
クライアントは 2 種類のどちらかとして作成し、種類は後から変えられません。 OAuth2 クライアント には クライアントID と クライアントシークレット が発行され、シークレットをトークンエンドポイントでクライアントクレデンシャルグラントにより交換すると、1 日有効な Bearer トークンが得られます。アクセストークン は長期有効な不透明トークンをそのまま送る方式 — より単純で、信頼できる 1 か所から動くスクリプトに向いています。
認証情報に何ができるかは APIスコープ で決まります。モジュールごとに 1 行 — 予約、予約可能リソース、ユーザー、来訪者、センサー、建物など、またはすべてのモジュール — を置き、それぞれに 読み取り専用 か 読み書き を付けます。トークンはクライアントに許された範囲より狭く要求することはできても、広くはできません。同じフォームにはさらに 3 つの守りがあります。IP制限、ブラウザーからの呼び出し向けの CORS 設定、そして 有効期限 です。
失効は即時です。クライアントの削除、スコープの縮小、シークレットの再生成は、発行済みトークンの期限を待たずに、それを使うすべての呼び出しをその場で止めます。
API が扱う範囲
REST API は管理コンソールと同じものに届きます。予約と予約可能リソース（パネル表示内容とアクセスキーを含む）、ユーザーとユーザーグループ、建物、来訪予約と来訪者管理、サービス項目、ロッカー、電子ペーパーコントローラー、環境・在室・ IoT スペースの各センサーと Milesight ゲートウェイ、分析とダッシュボードの数値、緊急状態、そして後述のワークフロー Webhook です。汎用の「デバイス」領域はありません — デバイスへのアクセスは種類ごとです。
完全なリファレンスは、このサイトの External API ページにあります。すべてのエンドポイントとリクエスト／レスポンスの形、そして自社のツールに読み込める OpenAPI ドキュメント のダウンロードがあります。
自社システムからのリダイレクト先
同じく マーケットプレイス にある システムURL には、他のシステムから人を
Offision へ送るのに必要な 5 つのアドレスが並びます。ユーザーポータルURL、管理コンソールURL、ビジターアプリURL、ログインページURL、そして自動ログインページ参照 — {userEmailAddress} をユーザーのメールアドレスに置き換えると、ログイン済みの状態で着地させられるパターンです。その下には、自動ログイン URL を持つ連携クライアントごとの行があります。
「システムURL」— 他のシステムから人を送り込む先のアドレス。
自動化: ワークフローモジュール
単純な API 呼び出しでは足りないとき、プレビュー段階のモジュールワークフロー で、ロジックを Offision の中に組み立てられます。ワークフローはキャンバスです。ちょうど 1 つのトリガー — ドメインイベント、スケジュール、 Webhook、MQTTメッセージ、手動トリガー、ワークフロー呼び出し — が起点になり、アクションノードが仕事をします。任意の URL への HTTPリクエスト、通知を送信、メールを送信、SMSを送信、ハードウェアを制御、来訪者バッジを更新 など。
ワークフロー一覧を開く連携で重要なのは 2 つです。エンドポイント設定 はアドレスと認証情報を一度だけ保存し — HTTP、HTTPS、MQTT、gRPC — すべてのワークフローから再利用します。そして Webhook トリガーは、ワークフローに専用の受信 Webhook URL を与えます。自社システムがそこへ POST するとワークフローが動きます。トリガー自身の注記に「Offision外部API認証ヘッダーが必要：」とあるとおり、呼び出し側には上のページで作った認証情報が要ります。呼び出しがすぐ戻るか、ワークフローの完了を待つかは選べます。
これができないこと
- 送信 Webhook の購読はありません。 Offision は「予約が作成された」を登録した URL へ push しません。外へ呼び出すには、ドメインイベント トリガーに HTTPリクエスト アクションをつないだワークフローを作ります。
- Zapier や Power Automate のコネクタはありません。 それらのツールは REST API を呼んだり Webhook トリガーへ POST したりできますが、インストールするだけの既製アプリはありません。
- 旧 OAuth アプリケーションページはこれではありません。 あのページは Offision 自身のログインページと来訪者 WiFi ポータルに対して Offision をサインインプロバイダーにするもので、いまは 来訪者管理 › 来訪者 WiFi から開きます。自社ユーザーを他システムへサインインさせるものではありません。