API のローカルテスト
本番環境へ展開する前に、開発マシンで機器のコールバックを受信し、Postman で REST コマンドをテストする方法を説明します。
ローカルでのテスト（サーバーへの展開なし）
本番サーバーに展開せずに、ローカルの開発マシンでコールバック連携をテストするには、Cams Protocol Engine がコールバックデータを POST できるよう、ローカルマシンをインターネットから到達可能にする必要があります。
オプション A：パブリック IP + ポートフォワーディング
インターネット回線にパブリック（固定）IP アドレスがある場合は、外部ポートをローカルのアプリケーションに転送できます。
パブリック IP を確認する
whatismyip.com にアクセスするか、ターミナルで curl ifconfig.me を実行して、パブリック IP アドレスを控えます。
ルーターでポートフォワーディングを設定する
ルーターの管理画面にログインします。外部ポート（例：8080）を、ローカルマシンの内部 IP と、アプリケーションが動作しているポート（例：3000、5000、8080）に転送します。
コールバック URL を設定する
API Monitor で、コールバック URL を次のように設定します：http://YOUR_PUBLIC_IP:8080/callback
テスト
生体認証機器で打刻します。Cams Protocol Engine がコールバックデータをお客様のパブリック IP に POST し、ルーターがそれをローカルのアプリケーションに転送します。
オプション B：トンネリングツール（パブリック IP 不要）
パブリック IP がない場合やポートフォワーディングを設定できない場合は、トンネリングサービスを使ってローカルサーバーをインターネットに公開します。
| ツール | コマンド | 備考 |
|---|---|---|
| ngrok | ngrok http 3000 | 無料プランあり。公開 HTTPS URL がすぐに発行されます。 |
| Cloudflare Tunnel | cloudflared tunnel --url localhost:3000 | 無料。簡易トンネルならアカウント不要。 |
| localhost.run | ssh -R 80:localhost:3000 ssh.localhost.run | インストール不要。SSH 経由で動作します。 |
ローカルのアプリケーションを起動する
コールバックサーバーをローカルで実行します（例：php -S localhost:8080、node server.js、python app.py）。
トンネルを開始する
トンネリングツールを実行します。https://abc123.ngrok-free.app のような公開 URL が出力されます。
コールバック URL を設定する
API Monitor で、コールバック URL をトンネルの URL に設定します：https://abc123.ngrok-free.app/callback
テスト
打刻を実行します。コールバックはトンネル経由でローカルマシンにリアルタイムで届きます。
URL のテスト
本番稼働の前に、Postman でエンドポイントを検証してください。全 27 の RESTful 操作があらかじめ設定された Collection をご用意しています。
Postman Collection
ダウンロードして Postman にインポートします。base_url、stgid、auth_token の各変数を設定すれば、すぐにテストを開始できます。
Collection をインポートする
Postman を開き → Import → ダウンロードした .json ファイルをドラッグ＆ドロップします。全 27 の RESTful 操作がカテゴリ別にまとめて表示されます。
変数を設定する
Collection の Variables タブを開き、次を設定します：
base_url = RESTful エンドポイント URL（API Monitor から取得）
stgid = 機器の Service Tag ID
auth_token = 機器の AuthToken
リクエストを送信する
任意の操作を選択し、JSON ボディをご自身の値に編集して Send を押します。レスポンスが上記に記載された形式と一致することを確認してください。
Postman の例
以下は、Postman で設定したサンプル API リクエストのスクリーンショットです。メソッドを POST に設定し、RESTful エンドポイント URL に ?stgid= を付けて貼り付け、raw JSON ボディを使用します。
{"status":"done"} を返すことを確認します。