取扱説明書 ＞ 取得API リファレンス

取得API リファレンス

給与計算システムなどの外部システムから取得APIを呼び出す、開発者向けのリファレンスです。取得（読み取り）専用です。キーの発行手順は 取得API連携 を参照してください。

ホスト

• ホスト: https://<Work Handler のドメイン>
• 以下に記載するエンドポイントのパスはすべて /api/v1 から始まります。
• すべてのエンドポイントは HTTP GET です。

認証

• HTTP ヘッダ Authorization: Bearer <APIキー> を付けます。
• APIキーはユーザー編集画面の「取得 API キー」から発行します（wh_api_ で始まる文字列）。
• キーを発行したユーザーの権限で動作します。組織内の役割や、組織のアクセス元ネットワーク制限（CIDR）もそのまま適用されます。
• 認証に失敗した場合は、理由を区別せず一律 HTTP 401 を返します。

レート制限

• APIキー単位で制限します（MCP連携とは別枠）。
• 目安: 1分あたり600回 / 1時間あたり10000回。
• 超過すると HTTP 429 を返します。レスポンスに、超過した時間窓（window）と再試行可能になるおおよその秒数（retryAfterSec）を含みます。

ページング

• 件数が多くなりうる一覧は、クエリ cursor に前ページ末尾の項目IDを渡して次ページを取得します。
• レスポンスの nextCursor が次ページの起点です。返却件数が上限を下回るページでは null になります。上限ちょうどで後続が無いときも起点を返すため、次ページが0件になることがあります。
• 件数が少ない一覧（所属組織一覧・タイムカード設定一覧など）はページングなしで全件返します。
• 一覧に存在しないカーソルを渡すと 400 と識別子 invalid-cursor を返します。起点の項目が削除された場合に起こるため、先頭から取得し直してください。
• 絞り込み（includeRetired など）で一覧に出ないだけの項目は無効なカーソルではありません。指定するとその次の項目から返します。
• ただしタイムカード集計一覧は月ごとに対象メンバーを組み立てるため、退社などでその月の対象から外れたメンバーのIDは無効なカーソルになります。

年月（月度）について

• year（西暦）・month（1〜12）はタイムカードの「月度」で、暦月とは一致しません（タイムカード設定の月の開始日によって変わります）。

エラー

• 400: 入力パラメータが不正（型違い・必須欠落など）
• 401: 認証失敗（キーが不正・失効・期限切れ・未指定）
• 403: 権限不足（対象組織の非メンバー・その組織に在籍していない・役割不足・ネットワーク制限）
• 404: 不明なパス、または対象データが存在しない
• 429: レート制限超過
• 500: サーバー内部エラー
• エラー時のレスポンスは { "error": "..." } 形式です（429 の場合は window・retryAfterSec も含みます）。

エンドポイント一覧

各エンドポイントが返すデータの個々の項目は、画面で見られる内容と同じです。取得対象とパス・パラメータを示します。

ユーザー（組織の指定不要）

• GET /api/v1/me — 自分のユーザー情報
• GET /api/v1/organizations — 所属組織一覧
• GET /api/v1/received-invitations — 受け取った招待一覧（cursor）

組織・グループ・メンバー

メンバーの一覧・検索は、既定では在籍中のメンバーだけを返します。includeRetired=true を付けると、退社者も含みます。個別情報の取得は、指定なしでも退社者を取得できます。

• GET /api/v1/organizations/:oid — 組織情報
• GET /api/v1/organizations/:oid/members — 組織メンバー一覧（cursor・includeRetired）
• GET /api/v1/organizations/:oid/members-search — 組織メンバー検索（search・includeRetired）
• GET /api/v1/organizations/:oid/members/:uid — 組織メンバーの個別情報
• GET /api/v1/organizations/:oid/members/:uid/settings — メンバー設定
• GET /api/v1/organizations/:oid/members/:uid/activity-logs — メンバーのアクティビティログ一覧（cursor）
• GET /api/v1/organizations/:oid/members/:uid/comments — メンバーコメント一覧（cursor）
• GET /api/v1/organizations/:oid/members/:uid/comment-archives — メンバーコメントアーカイブ一覧（cursor）
• GET /api/v1/organizations/:oid/invitations — 組織が送信した招待一覧（cursor）
• GET /api/v1/organizations/:oid/sections — グループ一覧（cursor）
• GET /api/v1/organizations/:oid/sections/:sid — グループ情報
• GET /api/v1/organizations/:oid/sections/:sid/members — グループメンバー一覧（cursor・includeRetired）
• GET /api/v1/organizations/:oid/sections/:sid/members-search — グループ内メンバー検索（search・includeRetired）
• GET /api/v1/organizations/:oid/sections/:sid/members/:uid — グループメンバーの個別情報

タイムカード

• GET /api/v1/organizations/:oid/timecards/:uid/:year/:month — タイムカードデータ
• GET /api/v1/organizations/:oid/timecard-masters/:uid/:year/:month — 承認済みタイムカード
• GET /api/v1/organizations/:oid/timecard-summaries — タイムカード集計一覧（year・month・cursor）
• GET /api/v1/organizations/:oid/timecard-day-minutes/:uid/:year/:month — 指定日の自動計算済み分数データ（dayList に日次入力のJSON配列、nextMonthDayInputList に翌月度日入力（月度の最終日をまたぐ勤務のために入力する、翌月度側の日の情報）のJSON配列、carryoverData に繰越データ（月度の初日を含む週の前月度側の値や清算・年度の累計など、当月度の計算が必要とする前月度以前の情報）のJSONオブジェクト。nextMonthDayInputList と carryoverData は当月度の設定で入力対象になる日・項目を過不足なく指定し、入力対象が無い場合のみ空とする。nextMonthDayInputList に同じ日の行を複数指定することはできない。dayList は計算する日次入力をそのまま渡す）

タイムカード設定

• GET /api/v1/organizations/:oid/timecard-settings — タイムカード設定一覧
• GET /api/v1/organizations/:oid/timecard-setting-by-month — 月指定でのタイムカード設定（year・month）
• GET /api/v1/organizations/:oid/timecard-settings/:tcsid — タイムカード設定の個別取得

有給休暇

• GET /api/v1/organizations/:oid/paid-leave-setting — 組織の有給設定（未設定の組織は paidLeaveSetting: null）
• GET /api/v1/organizations/:oid/leave-status/:uid — 休暇の残量（年次有給休暇・特別休暇の別残高）・付与履歴

ワークフロー

• GET /api/v1/organizations/:oid/workflows — ワークフロー一覧（mineOnly・status・cursor）
• GET /api/v1/organizations/:oid/workflows/:wid — ワークフロー詳細
• GET /api/v1/organizations/:oid/workflows/:wid/timecard — 承認済みワークフロー内のタイムカード
• GET /api/v1/organizations/:oid/workflow-routes — ワークフロー経路一覧（cursor）
• GET /api/v1/organizations/:oid/workflow-routes-search — ワークフロー経路の検索（search）
• GET /api/v1/organizations/:oid/workflow-routes/:wrid — ワークフロー経路情報

休日

• GET /api/v1/organizations/:oid/holidays — 休日一覧（cursor）
• GET /api/v1/organizations/:oid/holidays/:hdid — 休日の個別取得

統計

• GET /api/v1/organizations/:oid/stats/organization — 組織構成統計（人数は在籍中のメンバーだけを数えます）
• GET /api/v1/organizations/:oid/stats/timecard-summary — 勤怠サマリ統計（year・month・sectionId）

パラメータの意味

• :oid＝組織ID（GET /api/v1/organizations で取得）、:uid＝メンバーのユーザーID、:sid＝グループID、:wid＝ワークフローID、:wrid＝ワークフロー経路ID、:tcsid＝タイムカード設定ID、:hdid＝休日ID
• :year・:month＝月度、search＝検索文字列、cursor＝ページングの起点、sectionId＝グループ絞り込み、mineOnly＝自分が関与するワークフローのみ、status＝ワークフローの状態で絞り込み
• includeRetired＝退社者を含めるか。true を指定したときだけ含み、省略時は在籍中のメンバーだけを返します

呼び出し例

curl -H "Authorization: Bearer <APIキー>" \
  "https://<Work Handler のドメイン>/api/v1/organizations/<oid>/timecard-masters/<uid>/2025/6"