integration-capability-analysis

統合機能の分析

Factorial の統合フレームワークは、現在は給与計算と財務というドメインごとに構成されており、各ドメインには一連の機能が定義されています。それぞれに方向と、その機能を実現する Factorial のエンドポイントがあります。このスキルでは、外部システムの仕様をもとに、機能ごとにどのベンダーエンドポイントが対応するか、また両方の API 間で各フィールドがどのように対応するかを明らかにします。

成果物は統合マッピングドキュメントです。このドキュメントは、統合の構築に価値があるかを判断する人と、その後に構築する人の両方を対象としています。前者が必要とするのは判定結果であり、後者が必要とするのはエンドポイントの実行順序とフィールドマッピングです。どちらも同じルールに基づきます。出典を示すか、確度を下げることです。ベンダーの仕様で根拠を示せないマッピングの行、エンドポイント、判定結果は、事実としてドキュメントに記載しません。

カタログは公開ドキュメントです

機能は、ドメインごとに1ページある Factorial の API ドキュメントで定義されています。

• 給与計算 — https://apidoc.factorialhr.com/v2026-10-01/docs/payroll-integrations
• 財務 — https://apidoc.factorialhr.com/v2026-10-01/docs/finance-integrations

分析を始める際に、対象ドメインのページを必ず確認してください。各ページには、そのドメインの機能、各機能の方向、対象範囲、および関連する Factorial のエンドポイントへのリンクが記載されています。これらのページが信頼できる情報源です。掲載されているすべての機能を分析し、記載された方向を使用し、リンク先のエンドポイントリファレンスから Factorial のフィールド名を取得してください。給与計算や財務の統合に通常含まれる内容を記憶に頼って作業しないでください。実際の一覧は直感的に想定されるものと異なるため、誤った機能一覧に基づくマッピングも、正しいものとまったく同じように説得力があるように見えてしまいます。

URL にはバージョンが含まれています。依頼者が指定したバージョンを使用し、指定がなければ上記のバージョンを使用してください。フィールド名や機能はバージョン間で変わる可能性があるため、使用したバージョンをドキュメントのヘッダーに記録してください。

ページを取得できない場合は、機能一覧を推測せずに中断し、その旨を伝えてください。

ステップ 1 — ドメインを分類する

ベンダーがどのドメインに属するかを判断します。給与計算エンジンは給与計算、会計システムまたは ERP は財務です。システムによっては、給与計算モジュールを備えた ERP のように、両方にまたがる場合があります。その場合は各ドメインを分析し、ドメインごとに1つのドキュメントを作成してください。どちらにも該当しない場合は、その旨を伝えて中断してください。無理にドメインに当てはめると、誰も使えないマッピングができてしまいます。

ドキュメントの冒頭に、分類とその理由を1行で記載してください。依頼者の確認を待つ必要はありません。判断が分かれる場合はその旨を記載し、作業を続けてください。

ステップ 2 — ドメインの機能を読み込む

ドメインページから、各機能、その方向、およびリンク先の Factorial エンドポイントをすべて含む作業用リストを作成します。次に、フィールドを確認するため、各エンドポイントのリンク先もたどってください。読んでいない内容はマッピングできません。ドメインページには多くのエンドポイントへのリンクがあり、その大半は1つの機能だけに使われるため、すべてを最初に読むのではなく、各機能に取りかかる際に確認してください。

また、ドメイン全体に適用される制約も引き継いでください。たとえば、順序やセットアップの手順（ほかのレコードを作成する前に存在していなければならないレコード）、書き込み時に Factorial が要求する識別子（Factorial に送信するレコードの external_id など）、差分同期のパラメーターです。これらは個々の行だけでなく、ドキュメント内のエンドポイントの実行順序にも影響します。

ステップ 3 — ベンダー仕様を棚卸しする

何かを対応付ける前に、事実に基づく棚卸しを作成します。機能から考え始めると、想定したエンドポイントを探し、その近くにあるものを見つけることになります。

API 仕様の場合 — OpenAPI／Swagger、開発者ポータル、PDF ガイドなど — 操作ごとに 1 行を記録します。メソッド、パス、処理内容、必須フラグを含むリクエストとレスポンスのフィールド、そして各情報の出典（operationId、セクション、ページ）を記録します。これらの参照情報が引用元になります。

フィールドのドキュメントと例の両方を読みます。 説明からはフィールドの意味が分かりますが、実際にどのような値を受け取るかは、例に記されていることがよくあります。日付形式、実際の列挙値、ネストされたオブジェクトの形、同時に値が設定されるフィールド、スキーマには記載されていないのに例には登場するフィールドなどです。例によってスキーマで明確にされていない動作が補われることも多いため、活用してください。例とスキーマが矛盾する場合は、一方を黙って選ぶのではなく、矛盾を報告します。

スキーマでは、allOf による合成（実際の required リストはすべての分岐の和集合です）と、祖先自身を指す $ref（ID ではなくネストされたオブジェクトとしてモデル化された関係）に注意して確認します。後者は通常使いものにならず、仕様の品質に関する指摘として記録する価値があります。

ファイル仕様の場合は、ファイル形式で同じように棚卸しします。レコードタイプまたはレイアウトがエンドポイントに、各列がフィールドに相当します。必須フラグ、型、長さ、コードリスト、ファイル間でレコードを関連付けるキー、配信方法、確認ファイルやエラーファイルの有無を記録します。

文書全体の確認事項

これらは仕様に「含まれていない」内容についての確認事項であり、仕様に含まれる内容と同じくらい、対応可能な機能を左右します。印象に頼らず、ファイル全体を確認してください。ファイルが長い場合は、件数を数えるか grep を使います。

• メソッドごとの操作数 — GET、POST、PUT、PATCH、DELETE の数。
• 実際に適用されている認証（ルートまたは操作ごとの security ブロック）。securitySchemes で宣言されているだけのものとは区別します。
• エラーレスポンスを宣言している操作の有無。
• 本文を返さない操作 — 作成しても何も返さない場合、保存する ID が得られません。
• ページネーション（page、limit、offset、cursor）と、一覧エンドポイントの増分フィルター（updated_since、modified_since、since）。
• レート制限 — 429、Retry-After、X-RateLimit-*、文書化されたクォータ。
• すべての enum。それぞれが対応付けるコードリストになります。
• 機能が依存するエンドポイントにおける deprecated: true の有無。

何が返されるかを報告します。何も返されない場合も同様です。「増分フィルタリングに対応する一覧エンドポイントはない」も、空欄ではなく調査結果です。

ステップ 4 — 各機能を対応付ける

方向によって、ベンダー側で探すべきものが決まります。

アウトバウンド — データのソースは Factorial です。Factorial のエンドポイントから読み取り、ベンダーに書き込むため、ベンダーには Factorial の読み取りエンドポイントが返すデータを受け付ける書き込みエンドポイント（作成用の POST、更新用の PUT／PATCH）が必要です。

インバウンド — データのソースはベンダーです。ベンダーから読み取り、Factorial に書き込むため、Factorial の書き込みエンドポイントが必要とするデータを返す読み取りエンドポイント（GET。できればページネーションに対応し、変更日で絞り込めるもの）が必要です。

読み取り API が充実していても、アウトバウンド機能には役立ちません。同様に、書き込み API が充実していても、インバウンド機能には役立ちません。この不一致は、一見よく対応しているベンダーが実際には対応できないと判明する最も一般的な原因です。

各機能について、実装で呼び出す順に、対応するベンダーのエンドポイントを特定します。主な処理を可能にする補助的な呼び出しも含めます。たとえば、作成前に法人またはコストセンターの ID を解決する、作成後にベンダー側の識別子を読み戻す、コードリストを参照する、といった処理です。次に、エンドポイントだけでなくフィールドも確認します。ほとんどすべての HR API に POST /employees はありますが、Factorial の新入社員情報を渡せるかどうかは、すべてそのフィールド次第です。

Step 5 — フィールドを対応付ける

ここがドキュメントの要となります。各機能について、2つのシステム間でデータを受け渡すすべてのフィールドを、データの流れる方向に沿って対応付けます。

各行には、送信元フィールドと宛先フィールドを完全なパスで記録します（GET /employees → birth_on、POST /workers → person.date_of_birth）。また、宛先で必須かどうか、変換がある場合はその内容、根拠となるスキーマ、ドキュメントの記述、または例も記録します。

連携が実際に破綻するのは変換部分です。具体的に記述してください。

• 形式 — 日付、タイムスタンプとタイムゾーン、小数点の区切り、通貨をコードまたは記号のどちらで表すか、金額を主要単位または補助単位のどちらで表すか。
• コードリスト — フィールドだけでなく値も対応付けます。両側で列挙値が公開されている場合は、値の対応表を示します。ベンダー側のリストが顧客ごとに設定される場合は、その対応付けが顧客ごとの設定であると記載します。
• 構造 — 1つのフィールドを複数に分割する（住所全体を番地、建物番号、郵便番号に分割するなど）、複数のフィールドを1つにまとめる、フラットなフィールドをネストされたオブジェクトにする、リストをフラット化する。
• 単位 — 労働時間における時間数と割合、月給と年収、休暇における日数と時間数。
• 識別子 — どちら側の ID をどこに保存するか、次の同期でレコードをどのように照合するか。

次に、意味の異なる2種類のギャップを分けて列挙します。

• Factorial にデータソースがない、ベンダー必須フィールド。 これらは機能を妨げるか、デフォルト値または手動操作を必要とします。それぞれに、定数、顧客ごとの設定値、導出値、またはギャップのいずれか、明確な解決方法を指定します。
• ベンダー側に宛先がない Factorial のデータ。 通常は、ベンダーが保持していないデータです。同期されると誤解されないよう、一覧に記載する価値があります。

行を完成させるために、ベンダーのフィールドを決して作り出さないでください。対応付けられていない行は調査結果です。仕様にない、もっともらしいフィールド名を記載することは、ドキュメントの不備です。

Step 6 — 分類する

各機能を3つの判定に分類します。

完全対応 — ベンダーが、機能に必要なすべての操作を適切な方向で提供し、宛先で必須のすべてのフィールドにソースがあり、次回の同期でレコードを再識別できます。仕様にそのすべてが明記されている場合に限り、この判定が可能です。

部分対応 — 操作は存在しますが、必要な要素が不足しています。たとえば、ソースのない宛先必須フィールド、更新または修正の手段がない、次回の同期でレコードを照合する方法がない、時間に依存するデータで有効期間を設定できない、公開された値のないコードリストなどです。部分対応の判定にはすべて、制約と実現可能性の判断（現状のままリリース可能、または先にギャップを解消する必要がある）と、解消に必要なことを明記します。

非対応 — 仕様でカバーされていません。操作またはエンティティが存在しない、仕様に記載がない、あるいはベンダーの UI で手動作業を行う以外の方法がない場合です。結果は同じで、ドキュメントに記載された内容に基づいてしか構築できないため、記載がない場合と仕様で明示的に除外されている場合は同じ判定になります。仕様で除外されているのか、単に記載がないのかを機能のセクションに記載してください。記載がない場合はベンダーへの質問となり、その回答によって判定が変わる可能性があります。

最後の2つの判定の境界は次のとおりです。フィールドの欠落は機能を部分対応にし、操作またはエンティティの欠落は非対応にします。再送信によって置き換えられるのか蓄積されるのか、といった、他の点では機能する機能内の詳細が明記されていない場合は部分対応とし、その詳細を制約として明記します。

ステップ 7 — ドキュメントを作成する

assets/report-template.md に従ってください。すべてのセクションを埋めてください。省略するのではなく「none」と記載し、「報告することがない」のか「分析していない」のかを読者が判断できるようにしてください。

最初に機能の概要を記載します。意思決定者が読むのはここだからです。次に、機能ごとにセクションを設けます。ドメインページに記載されているすべての機能を対象とし、非対応のものも含めて、それぞれを評価したことが分かるようにしてください。各セクションには、エンドポイントの順序、フィールドマッピング、不足点、判定を記載します。フィールドマッピングはエンジニアが実装の基礎にする部分なので、対象範囲内のフィールドを漏れなく記載し、パスと変換を正確に示す必要があります。

最後に、回答によって計画がどの程度変わるかを基準にベンダーへの質問を並べます。1 回のやり取りで解決する質問はまとめてください。

<vendor>-<domain>-integration-mapping.md という名前で保存します。

失敗につながるケース

• ドメインページではなく記憶を頼りにする。 実際の機能一覧はより長く、方向性を含めて直感に反することもあります。必ず毎回ページを確認してください。
• フィールドを照合せず、エンドポイントだけを照合する。 名前が合っていてもフィールドが異なるエンドポイントは、せいぜい部分的な一致です。
• 例を無視する。 フォーマット、列挙値、ドキュメントに記載されていないフィールドは、例にしかないことがよくあります。
• フィールドを捏造する。 マッピングするのは、ベンダーの仕様に記載されているフィールドだけです。
• フィールドをマッピングしても値をマッピングしない。 列挙値が異なる 2 つの status フィールドは、値までマッピングしなければ対応付けたことにはなりません。
• 印象だけで存在しないと断定する。 「更新用エンドポイントはありません」という判断は、判定を左右します。件数を数えるか grep で検索してから、そう述べてください。