読み込み中
豆知識
一人社長の API は、Express 5 + Prisma 7 で書かれた Backend-for-Frontend です。フロントエンドから叩く全 805 パス (公開エンドポイントを含む) を一箇所でまとめています。
flowchart LR
subgraph Browser
FE[Vite + React 19<br/>port 5174]
Mobile[iOS / Android<br/>Capacitor]
end
subgraph Backend [Express 5.2 + Prisma 7]
API[REST API<br/>port 8080]
Cron[Cron jobs<br/>EventBridge → Lambda]
Queue[非同期キュー<br/>BullMQ 互換 IF]
AI[AI ルーター<br/>OpenAI / Anthropic / Gemini]
end
subgraph Supabase
DB[(PostgreSQL + RLS)]
Auth[Auth / JWT]
Storage[Storage バケット]
end
FE -->|JWT Bearer + camelCase JSON| API
Mobile -->|JWT Bearer| API
API -->|prisma| DB
API -->|service role| Auth
API -->|signed URL| Storage
API --> AI
Cron -->|x-cron-secret| API
API --> Queue
本番 API のオリジンは https://solo-boss.kensaur.us/api（CloudFront → Lambda）です。
API には「読者によって接し方が違う」レイヤーが 4 つあります。一覧で見るとこうなります。
| レイヤー | 例 | 認証 | 用途 |
|---|---|---|---|
| 完全公開 | GET /api/health GET /api/health/live GET /api/health/ready |
なし | 監視・SLA 計測・k8s プローブ |
| 公開デモ (LP) | GET /api/public/demo/stats POST /api/public/demo/classify-journal POST /api/public/demo/parse-receipt ほか 5 本 |
なし (IP 単位レート制限・AI バジェット) | サインアップ前の体験。provision は LPデモ会社 行を保存し、共有の読み取り専用トークンを返す |
| 公開リファレンス (年末調整) | GET /api/year-end-adjustment/health GET /api/year-end-adjustment/checklist GET /api/year-end-adjustment/reference/tax-brackets |
なし | 年末調整の制度リファレンスを公開する目的。書き込みなし |
| 認証付きの業務 API | /api/documents /api/journal-entries /api/tax/* /api/filing-workspace ほか大半 |
Bearer JWT (Supabase) + CSRF (mutating routes) | 会計・税務・申告のすべて |
| 運用専用 | /api/cron/* (x-cron-secret ヘッダ) ・ /api/admin/* (IP allowlist) ・ GET /api/health/detailed (本番は Bearer) |
個別の秘密鍵 / IP allowlist / Bearer | バックグラウンドジョブ実行・管理者操作 |
メモ マルチパート (ファイルアップロード) と SSE ストリームは、リクエスト本文のケース変換と CSRF を意図的にスキップしています。詳細は データの流れ を見てください。
レート制限は 運用 (Cron / レート制限 / セキュリティ) に集約しています。AI 系・公開デモ系には個別の上限があります。
主要な担当ドメインだけ列挙します。
| ドメイン | 役割 |
|---|---|
| Documents / Files | 書類アップロード、OCR・AI 抽出、ロック・電子帳簿保存法 |
| Bank / Reconciliation | 銀行明細取得、消込、AI による自動仕訳マッチング |
| Journals / Accounting | 仕訳エントリ、勘定科目、複式簿記の不変条件、月次・年次クローズ |
| Tax / Compliance | 確定申告、消費税申告、年末調整、e-Tax / eLTAX 用 XTX/XML エクスポート |
| AI / Advisor | OpenAI / Anthropic / Gemini を切り替えて、分類・要約・洞察を返す |
| Public Demos | LP の体験用エンドポイント (認証なし、レート制限あり) |
| Operations | Cron、キュー、整合性チェック、監査ログ、Sentry / Langfuse 連携 |
詳細なエンドポイントの一覧は API リファレンス と エンドポイント早見表 を見てください。
/v1, /v2 などはありません)X-API-Version ヘッダが付きます (package.json の version と一致)deprecated: true を立て、最低 90 日の告知期間を取りますこれは GitHub・Stripe・Slack の API ガイドラインと同じ方針です。
エラーは RFC 9457 Problem Details です。code (機械可読)、title (短い要約)、detail (説明)、guidance (ユーザー向け案内、日本語) を最低限返します。
{
"type": "https://api.soloboss.cloud/errors/ERR_3006",
"title": "Validation Error",
"status": 400,
"detail": "Validation failed",
"code": "ERR_3006",
"retryable": false,
"guidance": "入力内容を確認して再度お試しください",
"requestId": "req_abc123"
}
エラーコードの一覧は エラーコード一覧 に、フロントエンド側の扱い方は API エラーハンドリング にあります。
読み込み中
豆知識