変動データの連携
当資料の位置づけ
カスタムファンクションで利用することができるCombosite連携用のメソッドのパラメータ・レスポンスの定義を説明するための資料です。
Combosite連携用メソッドを利用することで、Combositeのデータの取得・更新などの操作が可能になります。
カスタムファンクション設定方法
カスタムファンクション設定時には、以下のように設定してください。
実行トリガー設定
- 実行トリガー：
Combositeトリガー
- 実行トリガー処理：
変動データ取込（前）：変動データを取り込む場合
変動データ取込（前）トリガーのカスタムファンクションは、有効なものを1件のみ登録できます。
利用可能メソッド一覧
| # | 実行トリガー処理名 | サービス名 | メソッド名 |
|---|---|---|---|
| 1 | 変動データ取込（前） | combositeDataService.hendoData | saveHendoData |
利用可能メソッド詳細
saveHendoData
Combositeの「変動データ取込」処理時に変動データ（当月のみ）の取り込みを行います。
利用例はCombositeHendoDataServiceを参照してください。
従業員ごとに処理を行う場合は、給与計算の対象従業員IDリストを利用してください。
combositeDataService.kyuyoKeisanSettingsData.employeeIdList
テスト実行時は従業員IDのリストは空になります。テストで実行する際には、プログラム上で従業員IDリストを設定してください。
取込できる給与項目とパラメータ
取込可能な給与項目
取込可能な給与項目は、給与項目マスタの 変動支給・変動控除 などの項目や、調整給として表示される項目が対象になります。
正確な一覧はCombositeの「ファイル取込」のフォーマットを参照してください。
必要な項目のみ指定してください。
確認経路はファイル取込のフォーマットを参照してください。
（フォーマットの例）
フォーマットには、この給与計算の計算パターンに含まれる、変動データ取込可能な給与項目が表示されます。
従業員ごとに計算パターンが異なる場合、指定できる給与項目も異なります。
列の見方
フォーマットの給与項目の各列は、次の3つで構成されています。（先頭の従業員ID列は除く）
給与項目名称 ＋ セパレータ ＋ ヘッダー名
例: セパレータが ** のとき
所得税**金額 → 給与項目名称が 所得税、ヘッダー名が 金額
| 部品 | 意味 | 設定場所 |
|---|---|---|
| 給与項目名称 | 給与項目マスタに表示されている名称 | 給与項目マスタ |
| セパレータ | 名称とヘッダー名を区切る文字 | 変動変換マスタ |
| ヘッダー名 | 金額・会社負担など、その列が何を表すかの名称 | 変動変換マスタ |
リクエストへの対応
| 内容 | リクエストでの指定 |
|---|---|
| 給与項目名称 | kyuyoKomokuName |
| ヘッダー名（金額、会社負担金額、子ども・子育て拠出金、変動取込時ヘッダー情報 など） | 内容に応じて amount / corpFutanAmount / kodomoKosodateKyoshutsukinAmount / codes を指定 |
下の対応例は、変動変換マスタの初期値を前提にしています。
各ヘッダー名を変更している場合は、フォーマット右側の実際の文言に合わせて判断してください。
| フォーマット右側（初期値の例） | リクエストでの指定 |
|---|---|
| 金額 | amount |
| 会社負担金額 | corpFutanAmount（詳細は後述の調整給④） |
| 子ども・子育て拠出金 | kodomoKosodateKyoshutsukinAmount（詳細は後述の調整給⑤） |
| 変動取込時ヘッダー情報の名称 | codes の axis（詳細は後述のコード表） |
| 〇で適用 | kyuyoKomokuName のみ（詳細は後述のコード表③） |
給与項目の算出方法区分に合ったパラメータを指定してください。区分と異なる内容を送ると取込できません。
amount/corpFutanAmount/kodomoKosodateKyoshutsukinAmountは整数です。項目名自体は固定です。- 金額のフィールドと
codesを同時に指定することはできません。 kodomoKosodateKyoshutsukinAmountは、厚生年金の調整給取込時に使う会社負担側の項目です（給与項目区分名の「子ども・子育て支援金」と混同しないでください）。
パターン別の指定パラメータ
カスタムファンクション例の全体はCombositeHendoDataServiceも参照してください。
調整給のパラメータは項目によって異なります。下表は代表例です。対象の調整給が給与項目マスタで調整給項目として表示されていることを確認してください。
| パターン | 算出方法区分などの条件 | 指定する主なパラメータ |
|---|---|---|
| 金額直接入力 | 算出方法区分が「金額直接入力」 | kyuyoKomokuName + amount |
| コード表（①ヘッダー1つ） | 算出方法区分が「コード表」 かつ 変動取込時ヘッダー情報が1つ | kyuyoKomokuName + codes: [{ axis, value }] |
| コード表（②ヘッダー複数） | 算出方法区分が「コード表」 かつ 変動取込時ヘッダー情報が複数 | kyuyoKomokuName + codes: [{ axis, value }, ...]（ヘッダーの数だけ） |
| コード表（③ヘッダーなし） | 算出方法区分が「コード表」 かつ 変動取込時ヘッダー情報なし | kyuyoKomokuNameのみ |
| 調整給（④健康保険・介護保険など） | 調整給項目（会社負担があるもの） | kyuyoKomokuName + amount + corpFutanAmount |
| 調整給（⑤厚生年金保険料） | 調整給項目（子ども・子育て拠出金の会社負担欄があるもの） | kyuyoKomokuName + amount + corpFutanAmount + kodomoKosodateKyoshutsukinAmount |
コード表のCombosite画面と実装例
算出方法区分が「コード表」の場合、金額はコード表から算出されます。
codes の指定方法は、変動取込時ヘッダー情報の件数によって変わります（下表・画面例を参照）。
| パラメータ | 内容 |
|---|---|
axis | 変動変換マスタ（または給与項目マスタの式設定）の 変動取込時ヘッダー情報 の名称を指定します。名称の不足・不一致のときは、取込後のエラーCSVで「コード表の値が不足しています」等と表示されることがあります。 |
value | axis に対応する取込値です。給与項目マスタの式設定で定義したコード表の選択肢などと一致させてください。値が空、またはコード表に存在しない値の場合も、同様に「コード表の値が不足しています」等と表示されることがあります。 |
変動取込時ヘッダー情報は、給与項目マスタ（式設定）または変動変換マスタで確認・編集できます。
変動取込時ヘッダー情報の名称を変更した場合は、codesのaxisも同じ文字列に合わせてください。
①変動取込時ヘッダー情報が1つ
例を表示
フォーマット
変動変換マスタ
給与項目マスタ
実装例
const hendoDataList = [
{
employeeId: '100000',
hendoData: [
{
kyuyoKomokuName: '変動支給_コード表',
codes: [{ axis: '変動', value: '区分1' }],
},
],
},
]
②変動取込時ヘッダー情報が複数
例を表示
フォーマット
変動変換マスタ
給与項目マスタ
実装例
const hendoDataList = [
{
employeeId: '100000',
hendoData: [
{
kyuyoKomokuName: '変動支給_2軸手当',
codes: [
{ axis: '変動地域', value: '大阪' },
{ axis: '変動区分', value: '区分2' },
],
},
],
},
]
③変動取込時ヘッダー情報なし（〇で適用）
例を表示
フォーマット
フォーマットの 〇で適用 は 「この従業員にそのコード表を適用する」 という意味です。
カスタムファンクションでは kyuyoKomokuName のみ指定します（amount / codes は不要）。
コード表のキー（どのマスタで金額を引くか）は、給与項目マスタの式設定で指定した コードマスタリスト に従います。
各キーの値は、取込時にその従業員の 発令情報 などから自動取得されます（リクエストで指定しません）。
変動変換マスタ
給与項目マスタ
発令情報
実装例
const hendoDataList = [
{
employeeId: '100000',
hendoData: [
{
// コードマスタリスト（例: 職位）の値は発令情報から取得し、コード表で金額が決まる
kyuyoKomokuName: '変動支給_手入力なしコード表',
},
],
},
]
調整給のCombosite画面と実装例
④調整給（健康保険・介護保険など）
例を表示
フォーマット
給与項目マスタ
実装例
const hendoDataList = [
{
employeeId: '100000',
hendoData: [
{
kyuyoKomokuName: '健康保険_調整',
amount: 1000,
corpFutanAmount: 2000,
},
],
},
]
⑤調整給（厚生年金保険料）
例を表示
フォーマット
給与項目マスタ
実装例
const hendoDataList = [
{
employeeId: '100000',
hendoData: [
{
kyuyoKomokuName: '厚生年金_調整',
amount: 1000,
corpFutanAmount: 2000,
kodomoKosodateKyoshutsukinAmount: 3000,
},
],
},
]
取込の仕様
再取込時の置換
同じ給与計算履歴に対して再度Combosite Functions取込を行うと、前回のCombosite Functions取込分はすべて削除され、置き換わります。前回の取込データを別途削除する必要はありません。
- 例: 従業員Aの取込済データが誤りであったため、従業員Bのデータだけを取り込み直した場合、従業員Aのデータは削除され、従業員Bのデータのみが作成されます。
- 取込中にエラーが発生した場合、前回分は削除され、今回分は登録されていない可能性があります。エラーを確認し、修正した内容で再度取り込んでください。
空のリクエスト
hendoDataList に1件もデータを入れない場合（空配列）は取込できません。
空のまま成功させると前回のCombosite Functions取込分がすべて消えてしまうためです。取り込むデータがないときは、取込自体を実行しないでください。
ファイル取込・共創取込との関係
同じ給与項目を、Combosite-Functions取込とファイル取込・共創取込で併用しないでください。
複数の取込元からの同時運用はサポートしていません。併用した場合、想定外の結果になることがあります。
金額が0の場合
amount などに 0 を指定した給与項目は取り込まれません（スキップされます）。
Combosite Functionsの再取込では前回分が置き換わるため、次のように考えてください。
- 項目自体を送らない: その項目のCombosite Functions分は残りません。
0を送る: 同様に、その項目のCombosite Functions分としては金額が付きません。
従業員ごとに指定する給与項目が異なる場合、送らない項目の列が空欄になると、空白チェック区分が「空白チェックする」だとエラーになることがあります。空欄を避けたい場合は 0 を送る方法もあります（その項目はスキップされます）。
同一リクエスト内の重複
- 同じ従業員を複数回（
UserHendoDataの配列であるhendoDataListに同一の従業員が複数）送った場合は、それぞれ取り込まれ、金額は合算されます（ファイル取込と同様）。意図しない二重計上を避けるため、同一従業員は1回だけ送ってください。
// 合算される例（非推奨）: 同一従業員が2回 → 変動手当Aが合算される
const hendoDataList = [
{
employeeId: '100000',
hendoData: [{ kyuyoKomokuName: '変動手当A', amount: 10000 }],
},
{
employeeId: '100000',
hendoData: [{ kyuyoKomokuName: '変動手当A', amount: 5000 }],
},
]
- 同一従業員の中で同じ給与項目名称を複数書いた場合は、エラーになります。1人あたり同じ給与項目名称は1回だけ指定してください。
// NG例: 同一従業員内で給与項目名称が重複 → エラー
const hendoDataList = [
{
employeeId: '100000',
hendoData: [
{ kyuyoKomokuName: '変動手当A', amount: 10000 },
{ kyuyoKomokuName: '変動手当A', amount: 5000 },
],
},
]
取込件数の上限
1回の取込で扱える量には上限があります。
取込データの行数 × ヘッダー上の給与項目数（全従業員で指定した給与項目の和集合）が30万を超えると取込できません。
- 例: 従業員1.8万人（各1行）× 給与項目16種 ＝ 28.8万 → 可
- 例: 従業員1.8万人（各1行）× 給与項目17種 ＝ 30.6万 → 不可
同一従業員をリクエスト内で複数回送ると行数が増えるため、上限判定の対象も増えます（同一リクエスト内の重複）。
上限を超える場合は、対象の従業員や給与項目を絞り、1回の取込に収まるようにしてください。
複数回に分けて取り込むと、後から取り込んだ内容だけが残り、先に取り込んだ分は置き換わります。
変動コントロールマスタ
確認経路は変動コントロールを参照してください。
変動コントロールマスタの設定により、取込時のエラー扱いなどが変わります。
区切り文字区分・文字コード区分は、いずれを選んでもCombosite Functions側で対応するため、カスタムファンクションの実装は同じで問題ありません。
区切り文字区分
次のいずれでも問題ありません（カスタムファンクションの実装は変わりません）。
- カンマ
- タブ
空白チェック区分
従業員ごとに指定する給与項目が異なる場合、フォーマット上の未指定項目が空とみなされることがあります。
- 空白チェックする: 上記のように項目を出し分けると、取込全体がエラーになることがあります。
- 空白チェックしない: 従業員ごとに項目を出し分ける場合に検討してください。
// 従業員ごとに異なる給与項目を指定する例
const hendoDataList = [
{
employeeId: '100000',
hendoData: [{ kyuyoKomokuName: '変動手当A', amount: 10000 }],
},
{
employeeId: '100001',
hendoData: [{ kyuyoKomokuName: '変動手当B', amount: 20000 }],
},
]
文字コード区分
次のいずれでも問題ありません（カスタムファンクションの実装は変わりません）。
- UTF-8
- Shift-JIS
一部取込区分
「一部取込区分」により、従業員単位のエラー時の挙動が変わります。
- 一部取込する: リクエスト内にエラーとなる従業員が含まれていても、正常な従業員分だけ取り込まれます（エラーとなった従業員分は取り込まれません）。取込結果は一部成功となり、詳細は変動データ取込画面の一覧からエラーCSVをダウンロードして確認できます。取込件数は、正常に取り込まれた従業員数です。
- 一部取込しない: 1件でもエラーがあると今回の取込全体が取り込まれません。
次のような場合は、一部取込区分の設定にかかわらず取込全体がエラーになります。
- リクエストの形が誤っている（必須欠落、型不正、
hendoDataListが空、従業員のhendoDataが空、金額系が整数でないなど） - 給与項目に対するパラメータの組み合わせが正しくない（例:
amount系とcodesの同時指定、社会保険の調整給なのにcorpFutanAmountがない） - 存在しない給与項目名称を指定した
- 取込できない給与項目を指定した（例: 調整給でない法定控除）
codes.axisの名称・件数が、変動取込時ヘッダー情報と一致しない- 給与項目名や
codes.axisに変動変換マスタのセパレータ文字が含まれている - 給与項目マスタ側の設定不備（コード表・コードマスタ未設定、同名項目が複数有効など）
- 変動変換マスタ／変動コントロール／対象の給与計算実行履歴が取得できない
- 従業員ごとに指定する給与項目が異なり、空白チェック区分が「空白チェックする」の場合
画面への経路
| 用途 | 経路 |
|---|---|
| ファイル取込のフォーマット | 月例: Combosite給与 ＞ 月次 ＞ 給与計算 ＞ ②本計算 ＞ 変動データ取込 ＞ ファイル取込 ＞ フォーマット 退職時即時払: Combosite給与 ＞ 随時 ＞ 退職時即時払 ＞ 退職時即時払グループ選択 ＞ 退職時即時払 ＞ ②本計算 ＞ 変動データ取込 ＞ ファイル取込 ＞ フォーマット |
| 変動データ取込 | 月例: Combosite給与 ＞ 月次 ＞ 給与計算 ＞ ②本計算 ＞ 変動データ取込 退職時即時払: Combosite給与 ＞ 随時 ＞ 退職時即時払 ＞ 退職時即時払グループ選択 ＞ 退職時即時払 ＞ ②本計算 ＞ 変動データ取込 |
| 変動コントロール | Combosite給与 ＞ 随時 ＞ 給与設定 ＞ 変動コントロール |
| 給与項目マスタ | Combosite給与 ＞ 随時 ＞ 給与設定 ＞ 給与項目マスタ |
| 給与項目マスタ（式設定） | Combosite給与 ＞ 随時 ＞ 給与設定 ＞ 給与項目マスタ ＞ 編集 ＞ 式設定 |
| 変動変換マスタ | Combosite給与 ＞ 随時 ＞ 給与設定 ＞ 変動変換マスタ ＞ 編集 |
変動データ取込の手順
起動経路は変動データ取込を参照してください。以下の手順は月例を例に説明します。
-
上記の起動経路から「変動データ取込画面」を開きます。
-
【Combosite-Functions】から【データ取込】ボタンを押下します。
-
「取込完了」の文言表示後【完了】ボタンを押下すれば、取込作業は完了となります。
取込データの確認方法
変動データの取込が完了すると、変動データ取込画面に次の内容が表示されます。
| 項目 | 内容 |
|---|---|
| 取込データ | {カスタムファンクション名}_{識別用の文字列}（取込ごとに付くIDの一部） |
| 取込元 | Combosite-Functions |
| 正常取込 | 正常に取り込まれた従業員数 |
| エラー | 取込で検出されたエラーの件数 |
| 取込状況 | 取込結果のステータス（成功／一部成功／失敗 など） |
| 取込日時 | 取込を実施した日時と実行ユーザー |
取込の成功／失敗は実行履歴でも確認できます。実際の反映額は給与計算を実施したときに確定し、同一リクエスト内で従業員を分けて重複させた分も含めて合算されます。
エラー時の確認方法
エラーが発生した場合は、次のいずれかで詳細を確認できます。
- モーダル内に表示されるURLからCombosite Functionsに移動し、実行履歴のログを確認する
- 変動データ取込画面の一覧から、エラー時のCSVをダウンロードしてエラー詳細を確認する
リクエスト型の不一致など、想定外のエラーが発生した場合は、変動データ取込画面の一覧に結果が表示されないことがあります。一覧に結果が表示されないときは、カスタムファンクションの実行履歴からエラー内容を確認してください。