SmartHR API完全攻略 2026 — OAuth 2.0・従業員/年末調整エンドポイント、成功率39%の正体とエージェント連携の7つの落とし穴

なぜSmartHRのエージェント連携が難しいのか

SmartHRは従業員のオンボーディング、書類管理、社会保険手続き、年末調整(年末調整)までを網羅する、日本のHR SaaSの代表格だ。サンドボックス環境を備えた包括的なREST APIを公開しており、技術的には十分にエージェント連携可能なプラットフォームである。にもかかわらず、KanseiLink実測のエージェント成功率は約39%・信頼スコア0.6にとどまる(2026-05時点)。

これは「APIが貧弱だから」ではない。むしろAPI自体は整理されている。問題はOAuthスコープの宣言が分かりにくく、誤ると認可エラー(auth_error)で詰まる点にある。KanseiLinkは2026-04-06に「SmartHRのOAuthスコープがドキュメント不足で auth_error 失敗を生んでいる」という観測を受け、スコープガイダンスを追記した。HRデータは個人情報の塊であり、認可設計が一段とシビアになるのも、エージェントが躓きやすい背景だ。

MCPステータス — 公式MCPは未提供、REST APIが入口

2026年5月時点で、SmartHRに公式MCPサーバーは存在しない(KanseiLink上のmcp_statusはapi_only)。これは同じHR領域のfreee人事労務が公式MCP(npx @freee/mcp-server)を提供しているのと対照的だ。SmartHRをエージェントから使うには、(1)HTTPツールでREST APIを直接叩く、(2)社内でSmartHR APIをラップしたMCPサーバーを実装する、のいずれかになる。

認証 — OAuth 2.0 Authorization Codeとスコープの罠

SmartHRの認証はOAuth 2.0 Authorization Codeフロー。手順は以下の通り。

1. developer.smarthr.jp/apps でアプリを登録し、client_id / client_secret を取得
2. redirect_uri を設定
3. ユーザーを認可画面に誘導し、必要なスコープを宣言して authorization code を取得
4. POST https://api.smarthr.jp/oauth/token で code を access_token に交換
5. access_token(公称1時間で失効)を Bearer で送信、失効時は refresh_token で更新

GET /v1/employees HTTP/1.1
Host: api.smarthr.jp
Authorization: Bearer {access_token}
Accept: application/json

Response:
{"data":[{"id":"abc123","last_name":"田中","first_name":"太郎",
          "email":"tanaka@example.com"}],"next_cursor":"xyz789"}

主要エンドポイント — 従業員・書類・年末調整

HRエージェント開発で詰まる7つのポイント

❌ 1. OAuthスコープの宣言ミス

最大の失敗要因。必要なリソース×操作のスコープを正確に宣言し、サンドボックスで通ることを確認してから本番へ。

❌ 2. v1を使い続ける

v1の /employees は一部エッジケースで一貫性のない結果を返す報告があり、v2で修正済み。2026-02-18にレガシー従業員一覧エンドポイントが非推奨化されたため、新規実装はv2系で組む。

❌ 3. マイナンバー(社会保険)のPII軽視

社会保険書類はマイナンバーを要求する特定個人情報。ログ・プロンプト・中間ストレージに残さず、利用目的を法令範囲に限定。マイナンバーを扱うエージェントは documents.read のみの最小権限とPIIマスキングを併用する。

❌ 4. トークンの早期失効

公称1時間だが実際は1〜2時間で失効するケースあり。書き込み前のプロアクティブ更新で401を回避する。

❌ 5. 大規模テナントのオフセット全件取得

単一組織の全従業員エクスポートはタイムアウトしやすい。部署(department)単位でページングすると数秒で完了する、という実務知見が報告されている。

❌ 6. レート制限(600 req/10分)の無視

token単位で600 req/10分が目安。429はRetry-Afterヘッダー付きで返るため、ヘッダー値に従った指数バックオフを実装する。

❌ 7. エラーオブジェクトのパース忘れ

エラーは {"errors":[{"code":"invalid_parameter","field":"email","message":"..."}]} 形式。code と field で分岐し、どのフィールドが原因かをユーザーに伝える設計にする。

freee人事労務・KING OF TIME・jobcanとの比較

『公式MCPがある』ことと『成功率が高い』ことは別問題だ。freee人事労務は公式MCPを持つがKanseiLink実測の成功率は50%、SmartHRは公式MCP未提供で39%、API onlyのカオナビが75%で最も高い。MCPの有無よりも『認可設計の分かりやすさ』『エラーの自己説明性』が成功率を左右する、というのがHR領域の実態である。SmartHRが公式MCPを出し、OAuthスコープを明快にすれば、市場シェアに見合った成功率まで一気に伸びる余地が大きい。

本番投入前チェックリスト

• 必要最小限のOAuthスコープ(例: employees.read + documents.read)を正確に宣言している
• サンドボックス(sandbox.smarthr.jp)でスコープ×エンドポイントの疎通を検証している
• v1ではなくv2系エンドポイントで実装している
• access_tokenのプロアクティブ更新(60分超で先にリフレッシュ)を実装している
• マイナンバー(社会保険書類)をログ・プロンプトに残さないPIIマスキングを入れている
• 大規模テナントの全件取得は部署単位でページングしている
• 429のRetry-Afterヘッダーに従った指数バックオフを実装している
• エラーレスポンスの code / field を分岐ロジックに組み込んでいる
• 従業員名は last_name(姓)先・ISO 8601(JST)の前提で処理している
• 年末調整など季節性ワークフローのリトライ・冪等性を設計している

FAQ

Q1. SmartHRに公式MCPサーバーはありますか?

2026年5月時点で公式MCPは存在しません(mcp_status: api_only)。連携はOAuth 2.0で保護されたREST API経由で行います。エージェントからはHTTPツールで叩くか、社内でラッパーMCPを実装する形になります。freee人事労務が公式MCPを提供しているのと対照的です。

Q2. なぜ成功率が39%と低いのですか?

最大の要因はOAuthスコープのドキュメント不足です。スコープ宣言を誤ると認可エラー(auth_error)が返り、エージェントが原因を特定できずに諦めます。正しいスコープを宣言しサンドボックスで事前検証すれば、成功率は大きく改善します。

Q3. 年末調整(年末調整)をエージェントで自動化できますか?

/year_end_adjustments エンドポイント群でワークフローを開始できます。ただし年末調整は12〜1月に処理が集中する長時間・制度依存ワークフローのため、(1)冪等性の確保、(2)失敗時のリトライ設計、(3)マイナンバー等PIIの厳格な取り扱い、を前提に設計してください。

Q4. マイナンバーを扱うエージェントの最小構成は?

documents.read のみの最小権限スコープに絞り、書き込みは別キー/別フローに分離します。マイナンバーをログ・プロンプト・中間ストレージに残さないPIIマスキングを必須とし、利用目的を社会保険・税手続きに限定します。

Q5. v1とv2、本番ではどちらを使うべきですか?

v2を推奨します。v1の /employees は一部エッジケースで一貫性のない結果を返す報告があり、v2で修正されています。レガシー従業員一覧エンドポイントも非推奨化されているため、実装時は公式ドキュメント(developer.smarthr.jp/api)で最新のv2パスを確認してください。