hsa-receipt-vault

HSA 領収書保管庫

目次

• 概要
• 重要な理由
• 入力の仕様
• 適格経費のカテゴリ
• ワークフロー
• 出力の仕様
• ガードレール

概要

HSA の「靴箱」戦略です。医療費を自己負担で支払い、領収書を保管し、HSA を数十年にわたって非課税で運用した後、いつでも払い戻しを受けます。HSA の払い戻しには期限がなく、経費が HSA 開設後に発生したものであれば対象となります。このスキルは台帳を管理し、記録を検証して、未払い戻し額の累計を表示します。

重要な理由

この台帳に記録された金額はすべて、将来いつでも HSA から非課税で引き出せる金額です。つまり、医療費相当額について HSA を Roth IRA のように活用でき、現金が必要な場合は退職前に払い戻しを受ける選択肢もあります。

入力の仕様

2 つのモードがあります。

A — 領収書を 1 件追加する：

{
  "date": "2026-03-10",
  "amount_cents": 18500,
  "provider": "Dr. Smith DDS",
  "description": "Dental cleaning",
  "receipt_path": "receipts/2026/2026-03-10-smith-dds.pdf",
  "paid_from_account_id": "acc_chk_001",
  "tx_id": "tx_20260310_004"
}

B — 一括照合（category: health.* の取引をスキャンする）：

{
  "transactions": [...],
  "existing_vault": [...],
  "hsa_open_date": "2018-01-15"
}

一括モードでは、このスキルが category: health.* の取引を確認し、すでに台帳に記録されていないものについて保管庫への登録を提案して、ユーザーに（出力を通じて）1 件ずつ確認を求めます。

適格経費のカテゴリ

HSA の適格経費は IRS Publication 502 に準拠します。このスキルでは、次の大まかなカテゴリに基づいて検証します。

適格	例
医療	診察、入院、手術、救急車
歯科	クリーニング、詰め物、抜歯、矯正
視力	眼科検診、眼鏡、コンタクトレンズ、LASIK
メンタルヘルス	セラピー、精神科、処方された入院治療
処方薬	処方薬、インスリン（2020 年以降は市販のインスリンも対象）
市販薬・生理用品	2020 年の CARES Act 以降、対象
医療機器	松葉杖、補聴器、CPAP、血圧計
介護	保険料（IRS の上限内）および適格な介護サービス
鍼治療、カイロプラクティック	対象
禁煙支援	対象
特定の疾患に対する減量	糖尿病、高血圧などの治療として処方された場合のみ対象

一般に、次のものは対象外です。

• ジムの会費（特定の病状に対して処方され、医療必要性証明書がある場合を除く）。
• 美容処置。
• ビタミンやサプリメント（特定の病状の治療用に処方された場合を除く）。
• 結婚カウンセリング／家族カウンセリング。
• 保険料（限定的な例外あり：COBRA、失業給付の受給中、65 歳以上の Medicare）。

該当するか判断が難しい場合は、qualification: unclear として IRS Pub 502 の参照先を記載し、ユーザーに確認を求めます。

ワークフロー

HSA Vault Progress:
- [ ] Step 1: Validate receipt date is after HSA open date
- [ ] Step 2: Map description to a qualified-expense category
- [ ] Step 3: Confirm receipt_path exists or note it's pending
- [ ] Step 4: Confirm amount paid from a non-HSA account (else not a vault entry)
- [ ] Step 5: Generate id and append to ledger
- [ ] Step 6: Update running unreimbursed_total
- [ ] Step 7: Emit warnings for ambiguous qualifications

ステップ 1 — 日付の確認

HSA 開設前の日付の領収書は、HSA の運用期間にかかわらず、非課税での払い戻しの対象になりません。明確な警告を出して却下します。

ステップ 2 — カテゴリの割り当て

説明と加盟店カテゴリを使って、適格カテゴリに割り当てます。割り当てられない場合は qualification: unclear とし、該当する場合はユーザーに医療必要性証明書の添付を提案します。

ステップ 3 — 領収書のパス

領収書は保管する必要があります。IRS は払い戻し後、時効期間が経過するまで、経費の証明を求める場合があります。使用できる領収書形式：PDF、JPG、PNG。パスは家計管理データのルートからの相対パスとして保存します：receipts/YYYY/YYYY-MM-DD-provider.ext。

receipt_path がない場合でも記録は受け付けますが、receipt_status: pending とし、警告を出します。pending の記録は、領収書が添付されるまでは未払い戻し額の累計（running unreimbursed_total）に含めないでください。領収書が添付されれば、その時点で累計に含めます。

ステップ 4 — 支払い元の口座

領収書を保管庫に登録できるのは、HSA 以外の口座から支払った場合のみです。HSA のデビットカードまたは HSA の請求書支払い機能から直接支払ったものは、すでに非課税の分配として扱われるため、靴箱には入れません。

ステップ 5 — 追記

id: rcpt_<year>_<seq> を生成し、hsa.json.receipt_vault[] に追記します。既存のエントリーは変更しないでください。修正が必要な場合は、correction_of: <prior_id> を含むエントリーを追記します。

ステップ 6 — 合計額

unreimbursed_total_cents = Σ amount_cents WHERE receipt_status = "ok" AND reimbursed = false。

これは目立つ位置に表示する数値です。世帯がいつでも非課税で引き出せる金額を示します。

ステップ 7 — 警告

• qualification: unclear — ユーザーに提示します。
• 追加時点で領収書の日付が 1 年以上前の場合 — 情報として提示します。過去にさかのぼってまとめて入力するユーザーもいますが、問題ありません。
• 1 件の領収書の金額が $1,000 を超える場合 — 情報として提示します。領収書が全額をカバーしていることを確認してください。
• 既存のエントリーと日付、提供元、金額がすべて同じ場合 — 重複の可能性があります。確認を求めてください。

出力仕様

モード A（単一の追加）の場合：

{
  "added": {
    "id": "rcpt_2026_0014",
    "date": "2026-03-10",
    "amount_cents": 18500,
    "provider": "Dr. Smith DDS",
    "description": "Dental cleaning",
    "category": "dental",
    "qualification": "ok",
    "receipt_path": "receipts/2026/2026-03-10-smith-dds.pdf",
    "receipt_status": "ok",
    "paid_from_account_id": "acc_chk_001",
    "tx_id": "tx_20260310_004",
    "reimbursed": false,
    "tax_year": 2026
  },
  "running_totals": {
    "unreimbursed_total_cents": 4435500,
    "by_year_cents": {
      "2024": 1820000,
      "2025": 2150000,
      "2026": 465500
    }
  },
  "warnings": []
}

モード B（一括照合）の場合：

{
  "proposed": [
    {
      "tx_id": "tx_20260118_005",
      "amount_cents": 4500,
      "provider": "CVS Pharmacy",
      "description_raw": "CVS/PHARMACY #04123",
      "suggested_category": "prescription_drugs",
      "qualification": "ok",
      "needs_receipt_upload": true
    },
    {
      "tx_id": "tx_20260201_002",
      "amount_cents": 8500,
      "provider": "Equinox",
      "description_raw": "EQUINOX MONTHLY DUES",
      "suggested_category": null,
      "qualification": "not_qualified",
      "rationale": "Gym memberships are not qualified unless prescribed for a specific medical condition with a Letter of Medical Necessity."
    }
  ],
  "running_totals": {
    "unreimbursed_total_cents": 4435500
  }
}

ガードレール

• HSA の開設日の確認は必須です。 開設前の費用は、非課税で払い戻すことはできません。
• 支払い元口座の確認は必須です。 HSA から直接支払われた領収書は、保管庫に追加しません。
• 領収書の保管はユーザーの責任です。 receipt_path を正確に記録し、領収書がない場合は警告してください。払い戻し前の合計額には含めないでください。
• 台帳への追記のみを許可します。 変更しないでください。修正には correction_of を使用します。
• 払い戻し前の合計額は、実現した金額ではなく、払い戻し可能な金額です。 「いつでも非課税で払い戻し可能」として提示してください。実際に払い戻しが行われるまでは、確定申告書には記載されません。
• 払い戻しのタイミングを提案しないでください。 これは、ユーザーが貯蓄・債務エージェントおよび投資・退職エージェントとともに決定する財務上の判断です（現金の必要性と HSA の継続的な運用成長との比較）。
• 市販薬および生理用品は 2020 年以降、適格な費用です。 反射的に対象外と判断しないでください。