CaseFlow Help
埋め込みフォーム（Widget）ヘルプ
外部サイトに埋め込んだ問い合わせフォームで発生する代表的なエラーと対処方法です。
まず確認すること（3つ）
- SITE_KEY が正しいか（管理: /admin/widget-sites または CASEFLOW_WIDGET_SITE_KEYS）
- 埋め込み元 Origin が許可されているか（CASEFLOW_WIDGET_ALLOWED_ORIGINS または Widget Sites の allowedOrigins）
- widget.js の baseUrl が正しい CaseFlow ドメインか（本番/検証/ローカルの取り違え）
このページはログイン不要で参照できます。運用・開発チームにそのまま共有してください。
エラーコード
origin_not_allowed
Origin が許可リストに入っていない
原因:
- CASEFLOW 側で Origin 制限が有効で、埋め込み元の Origin が許可されていない
修正:
- 環境変数 CASEFLOW_WIDGET_ALLOWED_ORIGINS に埋め込み元を追加する
- もしくは /admin/widget-sites で SITE_KEY ごとの allowedOrigins を設定する
例:
- https://example.com
エラーコード
missing_reference_origin
ref が空で Origin を判定できない
原因:
- 埋め込み元URL（ref）が送られていない/取得できない
- ブラウザ設定・埋め込み方式によって referrer が落ちるケースがある
修正:
- 埋め込みスクリプト/iframe が ref を渡せる構成になっているか確認
- まずは /widget-test.html で送信テストして挙動を切り分ける
エラーコード
unknown_site
SITE_KEY が未登録または許可されていない
原因:
- data-site（SITE_KEY）が許可リストにない
修正:
- 環境変数 CASEFLOW_WIDGET_SITE_KEYS に SITE_KEY を追加する
- または /admin/widget-sites に SITE_KEY を登録して運用する
エラーコード
tenant_mismatch
tenantId が一致しない（なりすまし防止）
原因:
- identityToken の tenantId と、SITE_KEY に紐づく tenantId が一致しない
修正:
- SITE_KEY の紐付け（tenant/project）を見直す
- token を発行している側が正しい tenantId を入れているか確認する
エラーコード
network
通信失敗（CORS / CSP / ネットワーク）
原因:
- ネットワーク断
- 埋め込み先サイトの CSP で script-src / frame-src がブロックされている
- （見かけ上）CORS のように見えるブロック
修正:
- ブラウザ DevTools の Console / Network を確認
- 埋め込み先の CSP に CaseFlow ドメインを許可する（docs/api/widget-embed.md の CSP セクション参照）
エラーコード
screenshot_capture_failed
スクリーンショットが撮れない（画面共有の権限/制限）
原因:
- ブラウザ/OSの画面共有（画面収録）権限が未許可
- ブラウザが iframe 内での画面共有を制限している
修正:
- macOS: システム設定 → プライバシーとセキュリティ → 画面収録 でブラウザ（Chrome等）を許可
- 可能なら Chrome/Edge で試す（Safari は制限が強い）
- /widget-test.html を“会社ドメイン”に置いて本番の Origin で試す（プレビュー iframe では制限される場合がある）