API による自動連携

API キーの管理

アカウント設定から API キーの発行・失効を行います（Business plan が必要）。キーは作成時に一度だけ表示されます。すべてのリクエストで X-API-Key ヘッダーに付与して送信してください。

利用可能な機能

Web アプリと同じエンドポイントを API キーで操作できます。本ガイドでは2つの主要フローを解説します：/api/v1/axis での座標変換、および /api/v1/quality-analysis での品質解析。プラン上限（セッション数、ファイルサイズ）は Web アプリと同様に適用されます。

座標変換 API

POST /api/v1/axis/transform に変換元/先の CRS、座標点列、X-API-Key ヘッダーを送信します。レスポンスは変換経路を含め Axis 画面と同様の構成です。CRS 検索も同プレフィックス下で利用できます。

品質解析の一連のフロー

1. 観測ファイルのアップロード：POST /api/v1/quality-analysis/upload（multipart/form-data、フィールド名 "files"、1回あたり最大20ファイル）を X-API-Key ヘッダー付きで実行。各ファイルのレコードが返却されます。
2. 解析タスクの作成：POST /api/v1/quality-analysis/tasks に JSON {"config": {"tool": "<mode id>"}, "files": [<ステップ1のファイルレコード>]} を送信。モードID: "fast" (Fast Mode), "flash" (Flash Mode), "full" (Full Mode), "teqc" (TEQC Mode)。
3. 完了までのポーリング：ステータスが completed になるまで GET /api/v1/quality-analysis/tasks/{taskId} を取得。完了時に全結果オブジェクトが返却されます。
4. PDF レポートの取得：GET /api/v1/quality-analysis/tasks/{taskId}/report.pdf で詳細な PDF レポートをダウンロードします。

Webhooks による非同期通知

ポーリングの代わりに Webhook を登録すると、処理完了時に PosFlow から通知を受信できます。/api/v1/webhooks で管理：POST で新規作成（url, events、任意の secret, description を含む JSON）、GET で一覧、DELETE /api/v1/webhooks/{id} で削除、POST /api/v1/webhooks/{id}/test でテスト送信。通知先 URL は公開 https である必要があり、プライベート IP は拒絶されます。

Webhook イベントとペイロード

現在3つのイベントをサポート：品質解析や処理完了時の "analysis.completed"、変換ジョブ終了時の "processing.completed" および "processing.failed"。各通知は event, timestamp、一意な id、ジョブ詳細を含む data オブジェクトから成る JSON POST です。イベント名は X-Webhook-Event ヘッダーにも記載されます。

署名検証と高信頼性配信

シークレット設定時、すべての送信には生の本文の HMAC-SHA256 署名が X-POSFLOW-Signature ヘッダー（"sha256=<hex>" 形式、X-Webhook-Signature は16進数のみ）で付与されます。シークレットで計算した値と照合してください。失敗時は指数バックオフで最大3回再試行されます。連続10回失敗した Webhook は無効化されるため、受信側は速やかに 2xx を返し、重い処理は非同期で行ってください。

適正利用について

リクエストはプランごとにレート制限されています。可能な限りバッチ処理を活用し、エラー時はバックオフを行ってください。大量の継続処理を行う場合は事前にサポート窓口へご相談ください。