Appearance
給与ソフト向けエクスポート(freee / マネーフォワード)
KIZAMI の締めの出口である区分別時間数を、freee人事労務 / マネーフォワード クラウド給与の 勤怠インポートに合わせた形で出す機能の設計です(2026-08-27 実装)。
実装: apps/api/src/lib/payroll-export.ts / apps/api/src/routes/exports.ts
原則: 金額は計算しない
KIZAMI の集計の出口は時間区分の算出までです(要件 §1)。 ここで行うのは「KIZAMI の区分 → 各社の勤怠項目」という名前と単位の変換だけで、 割増率・単価・支給額は一切扱いません。手当と同じ線です(手当対象時間の算出)。
エンドポイント
GET /exports/attendance.csv?month=YYYY-MM&format=generic|freee|mf- 権限は従来どおり
export.attendance.run(形式によって変わりません) format未指定 =generic。汎用CSVの列・順序・ファイル名は一切変えていません- 未知の
formatは400 invalid_format(黙って generic に落としません) compare=original(締め後修正の差分列)は generic 専用。給与ソフトのインポートは 決まった列しか受け付けないため、給与ソフト形式と併用すると400 compare_not_supportedになります- 文字コードはすべて UTF-8(BOM付き)・CRLF(generic と同じ)
⚠ 検証状況(これが一番大事)
誤ったマッピングは誤った賃金計算に直結します。調査で確認できたこと・できなかったことを ここに明示します。UI にも「β・要マッピング確認」の注意書きを出しています。
freee人事労務 — 列仕様は公開されている(確認済み)
| 項目 | 確認できた内容 | 出典 |
|---|---|---|
| 列名・列順 | 24列。サンプルCSVのヘッダ行そのまま | 他社サービスの勤怠データを取り込む(インポート) / 【サンプル】勤怠_freee形式.csv |
| 単位 | すべて分単位の整数(「労働時間はすべて分単位で入力します」) | 同上 |
| 従業員識別子 | 従業員番号のみ(メールアドレスの列は無い) | 同上 |
| 粒度 | 1行 = 1従業員 × 1集計期間(勤怠サマリー)。日別ではない | 同上 |
| 日付書式 | 集計開始日 / 集計終了日 は YYYY/MM/DD または YYYY-MM-DD | 同上 |
| 深夜の扱い | 他項目から除外せず重複計上する(KIZAMI と同じ考え方) | 同上 |
| 文字コード | 配布サンプルの実体は BOM 無し UTF-8 / CRLF。freee 自身が文字コードエラー時に「UTF-8(BOM付き)」で保存し直すよう案内しているため、BOM 付きも受理される | CSVファイルの文字コードに問題があります |
| 空欄の扱い | 「実績がない場合は、空欄とせず『0』を入力します」= 空欄は 0 として扱われる | インポート記事 |
参考(一次情報): freee 公式 OpenAPI スキーマ hr/open-api-3/api-schema.json。 PUT /api/v1/employees/{id}/work_record_summaries/{year}/{month} のフィールドは CSV 列とほぼ 1:1 で、 時間系はすべて _mins サフィックス(=分単位)です。将来 API 連携を作るときはこれが土台になります。
確認できなかったこと: 勤怠インポート記事に文字コード・改行コードの明示規定は無い(上記は サンプル実体の検査と汎用のエラー記事から)。ヘッダ行が必須かどうかの明文も無い(サンプルには存在)。 60時間超残業に相当する入力列は存在しない(freee 側で分解される想定と読めるが明文は未確認)。
マネーフォワード クラウド給与 — 固定の列仕様が存在しない(重要)
MF は CSV のタイトル行の文字列 = その事業者が「勤怠項目設定」に登録した勤怠項目名 で 突き合わせる方式です。
他社サービスから出力したCSVファイルのインポートでは、マネーフォワード クラウド給与の勤怠項目と 同一名称の勤怠データを取り込みます。(中略)CSVファイルのタイトル行(1行目)の勤怠項目名を 修正してください。 — 他社ソフトからCSVインポートで勤怠データを取り込む方法
勤怠項目はユーザーが自由に追加・改名できる(「勤怠項目」の設定方法)ため、 同じ製品でもテナントによって正しい列名が違います。単位も事業者設定依存で、 0時間 / 0.0時間 / 0.00時間(10進法) / 000時間00分(60進法) から選ぶ方式です (勤怠項目の単位の違い)。
インポートCSV自体の固定列として公開されているのは A列 Version・B列 従業員識別子・ C列 従業員番号(B/C はどちらか一方が必須)と「J列以降が入力欄」という記述だけで、 D〜I列が何かは公開されていません(支給/控除/勤怠項目をCSV形式でインポートする)。
したがって KIZAMI の format=mf は **「そのまま取り込める公式フォーマット」ではなく、MF の画面から落としたテンプレートへ転記するための 「マッピング確認用CSV」**です。列名は MF の既定の勤怠項目名 (勤怠項目の名称を一致させる方法の対応表)に 合わせられるものだけ合わせています。
確認できなかったこと: 対象年月の列があるか、1行の粒度の明文、文字コード(Shift_JIS 要否・BOM)、 改行コード、ヘッダ行必須の明文、60時間超残業の入力方法。 確認できないものを推測で埋めていません(Shift_JIS 変換の依存も足していません)。
空欄の扱いが両社で真逆
| 空欄でインポートすると | |
|---|---|
| freee | 0 が入る(「実績がない場合は空欄とせず『0』を入力します」) |
| マネーフォワード | 上書きされず既存値が残る(payr07) |
KIZAMI が空欄で出す列(後述の日数系)は、freee では 0 として登録されます。 日割り計算・欠勤控除を誤るため、取り込み前に必ず補完してください。
マッピング表
KIZAMI 側の区分は CategorizedMinutes の5種 + 固定時間制の内訳2種です。 給与ソフト向けにはまず次の粒度へ割り直します(derivePayrollCategories)。
| KIZAMI 内部 | 給与向け区分 | 備考 |
|---|---|---|
fixedWithinScheduled (固定) / totals.statutory (フレックス・シフト) | 所定内労働時間 | フレックスは総枠内の労働がこれに当たる |
fixedExtraWithinStatutory (固定) / 0 (それ以外) | 法定内残業 | 割増なし。フレックスに該当区分は存在しない |
totals.overtime - totals.overtime60h | 法定時間外(60時間以下) | 割増25%以上 |
totals.overtime60h | 法定時間外(60時間超) | 割増50%以上(労基法37条1項ただし書) |
totals.lateNight | 深夜 | 他区分と重複する独立の加算区分 |
totals.statutoryHoliday | 法定休日労働 | 割増35%以上。労働時間には含めない |
60時間超の扱いが両社で逆
totals.overtime は60時間超を含んだ法定時間外の総額です。
- freee: 60時間超の列が無いため、
時間外労働時間（分）に総額を入れる(freee 側で分解) - MF: 60時間超は勤怠項目を追加して分ける運用のため、
残業時間は60時間以下だけにして60時間超残業時間を別列に出す
この非対称性を取り違えると二重払い/払い漏らしになるため、単体テストで固定しています。
freee人事労務(24列・分単位の整数)
| # | 列名 | KIZAMI の値 |
|---|---|---|
| 1 | 従業員番号 | メールアドレス(下記「従業員の識別子」) |
| 2 | 氏名 | 氏名(freee 側は取り込まない参考情報) |
| 3 | 所定労働時間（分） | 所定内労働時間 |
| 4 | 法定内残業時間（分） | 法定内残業 |
| 5 | 時間外労働時間（分） | 法定時間外の総額(60時間超を含む) |
| 6 | 所定休日労働時間（分） | 空欄 — KIZAMI は所定休日(法定休日でない休日)を独立区分として持たず、通常の労働時間・時間外に含めて集計する。ここに値を入れると二重計上になる |
| 7 | 深夜労働時間（分） | 深夜 |
| 8 | 法定休日労働時間（分） | 法定休日労働 |
| 9 | 総労働時間（分） | freee の定義どおり 3+4+5+8 の合計 |
| 10–13 | 総労働日数 / 所定労働出勤日数 / 所定休日出勤日数 / 法定休日出勤日数 | 空欄(下記) |
| 14–15 | 遅刻時間（分） / 早退時間（分） | 空欄(下記) |
| 16–19 | 欠勤日数 / 遅刻日数 / 早退日数 / 有休取得日数 | 空欄(下記) |
| 20–21 | 集計開始日 / 集計終了日 | 対象月の初日 / 末日(YYYY-MM-DD) |
| 22–23 | みなし外の法定内残業時間（分） / みなし外の時間外労働時間（分） | 空欄 — KIZAMI は裁量労働制を扱わない |
| 24 | 不足時間（分） | フレックスの不足分(総枠に足りなかった分。正の数)。フレックス以外は空欄 |
日数系の列は空欄です
KIZAMI は日数(出勤日数・欠勤日数・有休取得日数)と遅刻/早退を集計の出口として持たず、 締めスナップショットにも保存していません。これらは空欄で出力されます。 freee は空欄を 0 として扱うため、そのまま取り込むと日割り計算・欠勤控除を誤ります。 表計算で補完してから取り込んでください。
0 ではなく空欄にしているのは、表計算で開いたときに「未入力」だと人の目で分かるようにするためです (0 は「実績なし」という意思表示に見えてしまう)。
マネーフォワード クラウド給与(時:分・60進法)
| # | 列名 | MF の既定勤怠項目か | KIZAMI の値 |
|---|---|---|---|
| 1 | 従業員番号 | ○(インポートCSVの必須列) | メールアドレス(下記) |
| 2 | 氏名 | ✕(参考) | 氏名 |
| 3 | 対象年月 | ✕(参考) | YYYY-MM |
| 4 | 所定内出勤時間 | ○ | 所定内労働時間 |
| 5 | 法定内残業時間 | ○ | 法定内残業 |
| 6 | 残業時間 | ○(MF の「法定外時間」) | 法定時間外のうち60時間以下 |
| 7 | 60時間超残業時間 | ✕(要追加) | 法定時間外のうち60時間超 |
| 8 | 深夜労働時間 | ✕ | 深夜(合計) |
| 9 | 法定休日労働時間 | ✕ | 法定休日労働(合計) |
2・3列目は転記時の目印で、MF の勤怠項目ではありません。取り込み前に削除してください。
7〜9列目に MF の既定項目が対応しないのは、MF が深夜と法定休日を 「平日 / 所定休日 / 法定休日」×「所定 / 所定外 / 法定外」に細分しているのに対し、KIZAMI は 深夜・法定休日をそれぞれ単一の合計でしか持たないためです(法定の割増計算にはそれで足ります)。 MF 側で同名の勤怠項目を追加するか、転記時に按分してください。
単位を時:分(60進法)にした理由: MF の単位は事業者設定依存で、十進表記は小数第2位までしか 保持されません。1分 = 0.01666…時間は割り切れないため、十進で出すと賃金対象時間に丸め誤差が入ります。 労働時間は1分単位で扱うのが原則(労働時間の端数処理)なので、 誤差の出ない60進法を既定にしました。勤怠項目設定が十進の場合は変換してから取り込んでください。
従業員の識別子(判断メモ)
社員番号のフィールドは users に追加せず、メールアドレスを従業員番号の列に出します。
usersに社員番号に相当する列はありません(id/email/name/hire_date/leave_grant_classのみ — v0.1 データモデル)- 追加しなかった理由: 社員番号は他システム側の識別子であり、給与ソフトが複数あれば 1列では足りません。KIZAMI 本体が使わない値のためにスキーマを膨らませ、 マイグレーションと入力UIと権限を抱えるのは割に合わないと判断しました
- 代わりにメールアドレスを出します。freee・MF ともメールアドレスは従業員に必須の項目なので、 給与ソフト側の従業員番号をメールアドレスに揃えるか、取り込み前に表計算で社員番号へ 差し替える運用を前提にします
- 将来ここが実運用の障害になるなら、
usersへの列追加ではなく 「エクスポート設定(テナント × 連携先ごとの外部ID対応表)」として設計し直すのが筋です
手当の列は出しません
汎用CSVの allowance_<name> 列(手当対象時間の算出)は給与ソフト形式には 含めません。手当は会社ごとに任意の名前で定義される KIZAMI 固有の概念で、給与ソフト側のどの支給項目に 対応するかは支給項目の設定を見ないと決まらないためです(推測すると誤った支給に直結します)。 手当対象時間が必要な場合は汎用CSVを併用してください。
締め済み月・締め後修正
- 締め済み月はスナップショットから、未締め月はオンデマンド計算から値を組み立てます (汎用CSVと同じ経路。給与ソフト形式でも変わりません)
- 締め後修正の差分列(
compare=original)は汎用CSV専用です。差額調整が必要なときは 汎用CSVで差分を確認し、給与ソフト側で調整してください (締め後の修正)
API連携について
freee人事労務は公開 API(work_record_summaries)を持っており、CSV を介さない直接連携も 技術的には可能です。ただし OAuth のアプリ登録・トークン管理・従業員IDの対応表が必要になるため、 v1 では CSV エクスポートまでとし、API 連携はロードマップに置いています。 マネーフォワードは勤怠項目が事業者ごとに可変なため、API 連携でも「出力列名を設定として持つ」 仕組みが先に必要です。