API契約仕様書 / DRAFT

外部連携のAPI契約
SDX ／ Shachihata Cloud ／ 内部API

実装構成設計書の3層構成を、実際の呼び出し単位に落としたもの。SDXとShachihata Cloudの仕様は未確認のため、こちら側が必要とする契約として先に書き、確認時にこの表と突き合わせる。要確認の印がある項目が、先方仕様に依存して変わりうる箇所。

SDX
案件台帳の読み書き。読み6・書き2の計8呼び出し。
Shachihata Cloud
承認申請と決裁完了の受け取り。Webhookが取れない場合はポーリングに退避。
内部API
10画面が叩くWorkerのエンドポイント。24本。

1. SDX 連携

SDXは案件台帳の正本。こちらは複製せず、参照とオフセットだけを持つ。書き込みは成果物の格納と状態更新の2つに限る。台帳の構造をこちらから変えない設計にすることで、SDXの既存運用に影響を出さない。

向き用途必要な操作呼ぶ画面 / 契機
読案件一覧の取得条件・並び順・件数指定つきの行一覧画面1。更新日時降順、ページング必須
読案件1件の取得_id指定の単行取得画面1〜9すべての起点
読更新差分の検知更新日時での絞り込み、または変更通知取り込みパイプライン1段目。5分間隔のCronを想定
読添付ファイルの取得ファイル列からのバイナリ取得（署名URLでも可）取り込み時にR2へ複製。1案件で10〜40ファイル
読案件種類・業種のマスタ選択肢の一覧画面3の絞り込み条件。取得不可なら固定値で持つ
読担当者一覧ユーザー情報画面8の承認者選択。要確認取得できなければ手入力
書成果物のアップロードファイル列への添付追加画面9。押印済みPDFと申請書一式
書案件状態の更新特定列の値更新画面8・9。「起案中」「承認待ち」「完了」の3値
設計判断 — 書き込みを2つに絞る理由
条項や差分履歴をSDXに書かないのは行数の問題だけでなく、障害時の切り分けのため。SDXへの書き込みが成果物の格納と状態更新だけなら、連携が落ちてもこちら側の作業は続行でき、復旧後に再送すれば整合する。書き込み対象が増えるほど、この再送設計が難しくなる。
確認事項（SDX）
項目こちらの前提外れた場合の影響
認証方式APIキーまたはOAuthクライアント資格情報ユーザー単位のOAuthだと、Cron側の無人実行にサービスアカウントが要る
レート制限毎分60回以上下回るならQueuesで流量制御。取り込みの所要時間が延びる
ファイル列の書き込みAPIから添付を追加できるできない場合、画面9は書き出しのダウンロードのみとし手動で格納
更新差分の取得更新日時での絞り込みが可能不可なら全件取得の差分比較。件数が増えると成立しない
カスタム列の追加状態管理用の列を1つ追加できる不可ならD1側だけで状態を持ち、SDXは成果物の格納先に限定

2. Shachihata Cloud 連携

承認フェーズの入口と出口だけを担当させる。ドラフトの中身は渡さず、書き出し済みPDFと案件IDだけを渡す。決裁完了の受け取り方が実装方式を決めるため、そこを最初に確認する。

向き用途渡す / 受け取る情報備考
出承認申請の作成PDF、申請者、承認者、件名、外部参照ID（draft_id）画面8の「承認に出す」。応答で先方の申請IDを受け取りD1に保存
入決裁完了の通知申請ID、結果（承認／差戻し）、決裁者、日時要確認 Webhookが第1候補。なければ10分間隔のポーリング
入押印済みPDFの取得完了した申請の成果物R2へ保存後、SDXへ格納
入申請状態の照会申請IDから現在の状態画面8の進捗表示。ポーリング方式ならこれが通知手段を兼ねる
出申請の取り下げ申請ID差戻し前に起案側が誤りに気づいた場合。要確認 対応可否
通知方式による分岐
Webhookが使える場合
Workerに受信エンドポイントを1本立てる。署名検証、冪等性キー（申請ID＋結果）、重複配信の無視が必要。反映は即時。
ポーリングになる場合
Cronで承認待ちの申請だけを照会。10分の遅延を許容し、画面8に「最終確認 hh:mm」を表示して待ち時間を可視化する。
設計判断 — 外部参照IDを必ず持たせる
申請にdraft_idを持たせられるかが分かれ目。持たせられれば通知だけでドラフトを特定できる。持たせられない場合は、こちら側で申請IDとの対応表を持ち、件名に案件番号を含めて人が追える状態にしておく（【2026-0431】建設業許可申請書一式 の形式）。

3. 内部API（Worker）

10画面が叩くエンドポイント。すべて/api配下、認証はCloudflare Accessのセッションを前提とする。時間のかかる処理はジョブIDを返して非同期にする。

画面エンドポイント返すもの / 動作
1GET /api/cases案件一覧。SDXの応答にD1の起案状態を合成
1GET /api/cases/:id案件詳細＋紐づくドラフト一覧
2POST /api/cases/:id/ingest取り込み開始。job_idを返す
2GET /api/jobs/:job_id進捗。{ stage, done, total, errors[] }
3GET /api/drafts/:id/references自動選定された参照案件と選定理由・類似度
3PUT /api/drafts/:id/references参照案件の差し替え。以降の生成に反映
3GET /api/search/clauses条項の検索。差し替え時の候補提示に使う
4POST /api/drafts/:id/messagesAI相談。SSEで応答。記録ブロックと助言ブロックを別イベントで送る
4GET /api/drafts/:id/thread相談履歴。引用条項IDを含む
4POST /api/drafts/:id/generate書類セットの生成。job_idを返す
5GET /api/drafts/:id/fields全記載欄。値・出典・確信度・フラグ・未レビュー差分の有無
5PATCH /api/drafts/:id/fields/:key値の更新。revisionを追記（origin: human）
5POST /api/drafts/:id/fields/:key/reviewAI由来差分のレビュー完了。reviewed_atを記録
6GET /api/drafts/:id/compare参照案件との記載欄単位の対照
7GET /api/clauses/:id条項の全文・ページ・bbox・分割方法
7GET /api/documents/:id/page/:n原本PDFのページ画像。R2から署名URLを返す
8GET /api/drafts/:id/gate承認可否と未達項目の一覧
8POST /api/drafts/:id/submitShachihataへ申請。承認者を指定
8POST /api/webhooks/shachihata決裁完了の受信。署名検証と冪等処理
9POST /api/drafts/:id/export様式一式の書き出し。job_idを返す
9POST /api/drafts/:id/deliverSDXへの格納と状態更新
10GET /api/office-standards抽出済み標準の一覧。状態・根拠件数つき
10GET /api/office-standards/:id1件の詳細。根拠案件・一致判定・推定箇所
10POST /api/office-standards/:id/decideapprove / amend / reject。否認も記録に残す
承認ゲートの応答（画面8）
GET /api/drafts/d_8812/gate
{
  "can_submit": false,
  "blockers": [
    { "type": "unreviewed_ai_diff", "count": 3,
      "fields": ["form4.capital", "form2.work_history.3", "form7.role_title"] },
    { "type": "standard_mismatch", "count": 1,
      "standard_id": "os_014", "field": "form4.attachments",
      "expected": "貸借対照表で疎明", "actual": "残高証明を添付",
      "reason_required": true }
  ],
  "warnings": [
    { "type": "low_confidence", "count": 2,
      "fields": ["form2.work_history.5", "form11.branch_office"] }
  ]
}
設計判断 — ブロックと警告を分ける
blockersは承認に進めない項目、warningsは進めるが表示する項目。確信度の低さは人が読んで判断すれば足りるため警告に置く。すべてブロックにすると、ゲートを通すための形式的な操作が増えて実質が失われる。

4. 失敗時の扱い

失敗扱い利用者に見える形
SDXが落ちている読みはD1のキャッシュで代替、書きはQueuesに退避して再送画面1に「案件台帳の同期待ち」。起案作業は続行できる
OCR / 分割の失敗文書単位で失敗を記録し、他の文書の処理は続ける画面2に失敗ファイルを列挙し、個別に再試行
LLMの応答不良3回まで再試行。以降は生成せずフラグを立てる該当欄を空欄＋「自動生成できず」の印で提示。空欄のまま承認には進めない
未同意の案件送信前にconsentを確認しブロック画面4で相談を開始する時点で「同意の記録がありません」を表示
Shachihata通知の欠落申請から24時間状態が変わらない場合はポーリングで補完画面8に「確認中」。人が先方画面を見に行かずに済む
Webhookの重複配信申請ID＋結果を冪等性キーとして2回目以降を無視表示上の変化なし

5. 確認の順番

先方への確認は、依存の深いものから。上2つが決まらないと着手できない範囲が広い。

1
SDXの認証方式とファイル列の書き込み可否
取り込みと引き渡しの両端。ここが決まらないと画面2と画面9の実装方式が決まらない。
2
Shachihataの決裁完了通知と外部参照ID
Webhookかポーリングかで画面8・9の作りが変わる。外部参照IDが持てるかも同時に確認する。
3
SDXのレート制限と更新差分の取得
取り込みの所要時間と同期間隔に影響。方式は変わらないため後でもよい。
4
担当者一覧の取得、申請の取り下げ
いずれも代替手段がある。取得できなければ手入力・手動対応に落とす。
作成 2026年8月28日 / 実装構成設計書の補遺
SDX・Shachihata Cloud の実仕様は未確認。本書は必要とする契約を先に定義したもので、確認結果で改訂する。