CareLinker 加算チェッカー 組込ガイド（INTEGRATION GUIDE）

version: v2026.06.11-alpha.9 date: 2026-06-11 対象読者: 介護ソフト・業務システムに本エンジンを組み込む開発者（自社プロダクト／他社ベンダー） 参照: reports/internal/alpha9/alpha9_design.md（設計正本）/ docs/RELEASE_PLAN.md / docs/SALES_READINESS_GATE.md

免責（組込先プロダクトにも転載必須） 本出力は算定可否を法的に保証するものではありません。算定判断は必ず法令・告示原文と保険者への確認に基づいて行ってください。

0. 本ガイドの前提

• 本ガイドのコード例はすべて DEMO データ（架空・synthetic）前提です。例示の dataset_id / office_code は DEMO- 接頭辞の架空IDのみを使います。
• エンジンの判定対象は regulatory_master/service_registry.json に登録されたサービスのみです。status が draft / planned のサービスは算定可能性の判定を行わず、要確認リストの生成までに限定されます（§5参照）。
• 実テナントデータ（実在の職員・利用者に由来する集計値）の投入は、現行の安全ゲート（§1-3）により facts 化されません。解除は社長判断キュー項目です（docs/SALES_READINESS_GATE.md J-new4）。

1. 組込の3形態

1-1. ① in-process SDK（Python 製ソフト向け）

ファサードは scripts/engine_api.py の 2 関数のみ。内部実装（judge_kasan / requirement_dsl / r1_pilot_run）には直接依存しないでください。

import sys
sys.path.insert(0, r"<kasan-manager>/scripts")  # 製品ルート配下の scripts/
from engine_api import check, list_services

# 対応サービスの列挙（service_registry.json と同期）
services = list_services()

# 判定リクエスト（dict in / dict out）
response = check({
    "service_key": "tsusho_kaigo",          # 必須: registry の service_key
    "dataset_id": "DEMO-R1-TSUSHO",         # 必須: 匿名 dataset_id（DEMO- 接頭辞推奨）
    "month": "202604",                       # 任意: 対象月 YYYYMM
    "evidence": None,                        # 任意: レセプトPDF抽出 evidence JSON（集計値のみ）
    "tenant_status": None,                   # 任意: 体制届出状況（集計値のみ）
    "staff_data": None,                      # 任意: 職員集計 staff.json（集計値のみ）
    "user_summary": None,                    # 任意: 利用者集計 JSON（集計値のみ）
    "options": {
        "include_report_markdown": True,     # Markdown レポートを response に含める
        "apply_evidence": False,             # evidence を判定に反映するか
    },
})

if response["ok"]:
    print(response["summary"])               # 件数サマリ
    print(response["disclaimer"])            # 免責文（UI 転載必須）
else:
    print(response["error"])                 # 入力不正・未対応サービス等

request のキー一覧

response のキー一覧

スキーマの正本は schemas/check_request.schema.json / schemas/check_response.schema.json です（手動の構造アサーションで検証。jsonschema ライブラリ非依存）。

1-2. ② REST API（言語非依存）

server/app.py（FastAPI）。SDK check() の薄いラッパーであり、エンドポイントとレスポンス構造は SDK と同一契約です。OpenAPI 定義は docs/openapi.json。

# 死活確認
curl -s http://localhost:8000/v1/health

# サービス一覧
curl -s -H "X-API-Key: <your-key>" http://localhost:8000/v1/services

# 判定実行
curl -s -X POST http://localhost:8000/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-key>" \
  -d '{
        "service_key": "tsusho_kaigo",
        "dataset_id": "DEMO-R1-TSUSHO",
        "month": "202604",
        "options": {"include_report_markdown": false, "apply_evidence": false}
      }'

POST /v1/extract（alpha10・PDFアップロードのワンショット）

明細書PDFを multipart でアップロードし、抽出→（既定で）checkまで一括実行します。アップロードPDFはサーバに保存されません。

curl -s -X POST http://127.0.0.1:8787/v1/extract   -F "file=@meisaisho.pdf;type=application/pdf"   -F "service_key=tsusho_kaigo" -F "dataset_id=DEMO-API-01" -F "run_check=true"
# 応答: {ok, error, extraction: {extraction_summary, evidence, ...}, check: <check_response>, disclaimer}

alpha11: check_response に gap_analysis が追加されました（数値要件の「現在値・基準値・あと何人」。rows[].status = cleared / near / not_met / no_data）。組込先は要件カタログの羅列ではなく ギャップ（現在→基準→残り）を第一に表示してください。no_data は「書類の不足」ではなく「データ未投入」の意味です（誤表示は禁止）。

alpha12: ① /v1/extract に staff_file（職員CSV・任意 multipart）を追加。templates/staff_intake_template.csv 形式（匿名ID・資格・常勤換算・勤続年数・勤務_月〜日）を渡すと、応答の staff_report に体制比率（介護福祉士/常勤/勤続・2種類の分母併記）と曜日×時間帯の資格在席表が返ります（実データはJ-23ゲートにより判定facts化はされず、事実整理として返る）。② check_response.unit_impact を追加（取れた場合の月◯単位・年◯単位概算。/日系は算定中加算の月間回数から延べ日数を推定し根拠を basis に明記。/回・率系は式のみ）。

alpha13: ① 試作UIに職員入力フォームを内蔵（行追加式・資格はチェック選択で表記ゆれゼロ・各資格にどの加算に効くかのヒント表示・曜日×時間帯は候補選択・ブラウザlocalStorageにのみ自動保存・既存CSVテンプレと相互変換）。② POST /v1/staff-report（職員CSVのみ・PDF不要）で体制レポート（比率・曜日×時間帯在席）を即時取得可能。

試作Web UI（GET /）も同じAPIを使用しています（uvicorn 起動後にブラウザで開けます）。

認証は現状スタブです。 環境変数 KASAN_API_KEY を設定した場合のみ X-API-Key ヘッダを照合します。未設定時は認証なしの開発モード（ループバック想定）です。マルチテナント認可は未実装で、R-3 前の必須ゲート項目です（docs/SALES_READINESS_GATE.md 参照）。インターネット公開・複数事業者同居での運用は現段階では行わないでください。

1-3. ③ データブリッジ（CSV → 集計JSON → check）

介護ソフトが出力する利用者・職員 CSV を集計 JSON（user_summary / staff_data）に変換してから check() に渡す経路です。

• alpha10 で第1号変換器を実装済み: ケアプランデータ連携システム標準仕様（厚労省・UP1KYO 第1表）→ 要介護度集計 → user_summary JSON。

  python scripts/import_careplan_csv.py     --csv UP1KYO_xxxx.CSV --service houmon_kaigo --dataset-id DEMO-CP-01 --month 202605
  # 出力: user_summary JSON（被保険者番号・氏名・フリーテキストは読み捨て・集計値のみ）
  # → check() の user_summary / r1_pilot_run --user-summary に渡せる
  

  訪問介護・訪問看護（介護）は請求帳票PDFに要介護度が構造的に載らないため、この経路が要介護度依存加算の判定材料になります。スキーマ正本は schemas/user_summary.schema.json。
• 他社ソフト独自形式の CSV 変換器は R-2 スコープ（未実装）。
• さらに重要な制約として、現行エンジンには sample_policy == "public_demo_synthetic" の安全ゲートがあり、synthetic（架空）と宣言された集計 JSON 以外は facts 化されません。実テナント由来の集計値を渡しても判定材料にならず、安全側で空扱いになります。
• このゲートの変更（実テナントデータの通し）はセキュリティ設計を伴う社長判断項目（J-23）であり、本ガイドの手順では解除できません。変換器は実データ由来の出力に sample_policy: "real_aggregate_pending_gate" を自動付与し、ゲート通過まで判定に流れない設計です。
• ブリッジ設計の原則: CSV の個票は変換器の外に出さない。check() に渡るのは件数・比率・常勤換算合計などの集計値のみ。

2. 接続パターン例（一般化した3類型）

実在のソフト名・事業所名ではなく、一般化した類型で示します。

2-1. ケアプラン作成支援ソフト

2-2. 訪問スケジュール管理ソフト

2-3. 請求ソフト

3. 組込先プロダクトの義務

組込先（自社・他社を問わず）は以下を遵守してください。違反構成での提供は許諾しません。

1. disclaimer の転載必須 — response["disclaimer"] をエンドユーザーの見える位置に必ず表示する。最低限、次の文言を含むこと: 「本出力は算定可否を法的に保証するものではありません。算定判断は必ず法令・告示原文と保険者への確認に基づいて行ってください。」
2. 算定可否を断定・確約する表現の禁止 — 取得を確約する文言、判定結果を断定として見せる UI（例: 緑チェックのみで注記なし）を使わない。「取得可能性」「要確認」の表現を維持する。
3. PII を request に入れない — 氏名・被保険者番号・生年月日・住所・電話番号・メールアドレス等の個票は渡さない。渡してよいのは集計値のみ（件数・比率・常勤換算合計等）。エンジン側にも PII 検出時に facts を生成しない安全弁があるが、これは最後の砦であり、組込側で発生源を断つこと。
4. draft サービスの判定結果を「取得可能」と表示しない — service.status が draft の場合、出力は要確認リストの生成までであり、算定可能性の判定ではない。draft_warning を必ず UI に表示する。
5. pii_scan の検出時は表示を中止 — pii_scan に検出ありが返った場合、そのレポートを表示・保存・転送しない。

4. バージョニングと互換性方針

互換性方針:

• response へのキー追加は後方互換として扱う。組込側は未知キーを無視できる実装にすること。
• 既存キーの削除・型変更・意味変更は engine_api_version のメジャー更新を伴う非互換変更として扱い、事前告知する。
• マスタの revision_tag はレポート・response に必ず含まれる。組込側は表示またはログに記録し、「どの改定時点の要件で判定したか」をエンドユーザーが追跡できるようにすること。
• 法令改定時はマスタのみ更新されることがある（API 契約は不変）。revision_tag の変化を改定反映の検知に使える。
• 改定履歴の正本は releases/changelog.md。

5. 対応サービス表（alpha9 時点）

regulatory_master/service_registry.json からの転記（implemented 4 / draft 6 / planned 1）。

• implemented でも、評価されるのは公式根拠確認済み（checked）の要件のみ。未確認要件は not_evaluated_source_required / not_evaluated_logic_unchecked として評価対象外になる安全弁が常時有効。
• draft サービスは judge-only（要確認リスト生成）であり、clear / currently_claimed を返さないことが回帰テストで固定されている。
• 最新の status は必ず list_services() / GET /v1/services で実行時に取得すること（本表は静的転記）。

6. 組込前チェックリスト

• list_services() で対象サービスの status を確認した（draft なら §3-4 の表示制約を実装した）
• disclaimer を UI に転載した
• request に個票（氏名・被保険者番号等）が入らない実装になっている（集計値のみ）
• pii_scan 検出時の表示中止フローがある
• revision_tag / engine_api_version をログまたは画面に記録している
• REST 利用時: KASAN_API_KEY を設定し、インターネット非公開・単一事業者構成で運用している

本出力は算定可否を法的に保証するものではありません。算定判断は必ず法令・告示原文と保険者への確認に基づいて行ってください。