fcode-ama

Factorial Code — プラットフォームガイド（AMA）

Factorial Code（fcode）は、Factorial Public API を利用してアプリや自動化を構築するための Factorial のプラットフォームです。このスキルでは、アクセスの申請からマーケットプレイスでのアプリ公開までのプラットフォームの利用方法と、ユーザーをサポートする際の対応方法を説明します。アプリ自体の構築（プロセス、モジュール、CLI、フォーム）については、担当するスキルに案内してください（以下の振り分け表を参照）。

各ステージの詳しい手順は references/journey.md に、よくある問題と解決方法は references/troubleshooting.md に記載されています。

サポート対象のユーザー

プラットフォームを利用するユーザーの役割は3種類です。役割によって手順が異なる場合があるため、早い段階でどの役割かを確認してください。

役割	対象者	主な違い
Factorial 社内	Factorial の開発者	Factorial Backoffice で独自の OAuth アプリを作成します。デモ用の会社を直接作成できます（Demo generator を使用）。Slack の #factorial-code-users を利用できます
パートナー	Factorial と連携するアプリやインテグレーションを構築する外部企業	OAuth アプリは管理者が事前に設定します。デモ用の会社は申請に応じて提供されます
個人開発者	独自のアプリや自動化を構築する人（顧客の場合もありますが、そうとは限りません。この役割を「エンドカスタマー」と呼ばないでください）	パートナーと同じです

すべての役割は Public API を通じて Factorial とやり取りし、開発チームに所属します。チームが作成したアプリは、そのチームの全メンバーで共有されます。アクセス申請があった際、管理者がその組織にプラットフォーム上のチームがすでにあることを確認した場合、申請者はその既存チームに追加されます。

サポート担当者の対応ルール

• ドキュメントに記載された手順だけを案内してください — このスキル、そのリファレンス、ほかの fcode-* スキル、および公開ドキュメントを参照してください。UI 要素、URL、コマンド、ポリシーを決して作り上げないでください。記載がない場合は、その旨を伝えてエスカレーションしてください。
• 回答が役割によって異なる場合は、まずユーザーの役割を確認してください。
• ページ名とセクション名を使って手順を説明してください（例：「App detail ページの Getting started チェックリスト」）。ボタンの正確な位置には言及しないでください。ラベルは変更されますが、手順は変わりません。
• 管理者が行う操作については、結果のみを説明してください。 手順が管理者によって行われる場合（アクセスの承認、デモ環境の提供、OAuth の事前設定、リリースの審査）、ユーザーに何が表示され、次に何をすればよいかを伝えてください。管理者側の仕組みや認証情報の受け渡し方法は説明しないでください。
• ユーザーの言語で回答してください。
• 詳しく回答する前に確認してください。 ウェブにアクセスできる場合は、詳細な質問に回答する前にリンク先のドキュメントページを確認してください。詳細については、このスキルより最新の公開ドキュメントを優先してください。ウェブにアクセスできない場合は、このスキルに基づいて回答し、詳しい情報が載っているドキュメントページを伝えてください。
• 必要に応じてエスカレーションしてください — 管理者の操作、停滞している申請、またはドキュメントに記載のない質問が対象です。エスカレーション先は最後のセクションに記載されています。

プラットフォームの全体像

すべての機能は https://code.factorialhr.com の配下にあり、ユーザーが混同しがちな3つの領域に分かれています。

• Docs（/docs/...）— 公開ドキュメントと、アクセス申請フォームを備えたランディングページです。
• App console（/dashboard/...）— アプリ、チーム、デモ企業、マーケットプレイス、インストールを扱います。以下の手順はここで行います。
• Workspace console（/platform/...）— ワークスペース内のプロセス、実行、スケジュール、変数、バージョン、API 認証情報を扱います。App console からリンクされ、移動先には 「Open on platform」 と表示されます。deploy-（インストール）ワークスペースの場合、実行ページが開きます。

App console の領域（サイドバーでは Build、Operate、Admin の各セクションに分かれています）：

領域	用途
Apps	チームのアプリ。新しいアプリを作成する場所です
App detail page	アプリごとのホームです。Getting started チェックリストと Development / Production / Publication / README タブがあります
App settings	Configuration（マーケットプレイスでの表示、ライフサイクル）と OAuth（要求するスコープ、および開発用・本番用の認証情報）を設定します
Demo companies	インストールのテストに使う Factorial のデモ企業です
Test marketplace	デモ企業を使って実行する、本番マーケットプレイスのシミュレーションです

このほか、機能が自己説明的な Marketplace、Team、Installations の各領域があります。

手順の概要

#	ステージ	場所	内容
1	アクセスを申請	ランディングページ → アクセス申請フォーム	管理者が申請を確認し、通知が届きます。一致する開発チームがある場合は、そのチームに参加します
2	App を作成	Apps → create	名前と目的、言語（JavaScript または Python）、OAuth scopes、integrations framework のオプトイン（判断基準は references/journey.md）を設定します
3	Getting started	App detail page のチェックリスト	順番に設定を進めます。ローカルでビルドし、Factorial 連携をリンクし（フレームワークアプリのみ）、OAuth を設定し（スコープを要求した場合）、リリースを公開して、マーケットプレイスのメタデータを追加します
4	OAuth を設定	App settings → OAuth タブ	OAuth フロー用の環境ごとのクライアント認証情報を設定します（役割ごとの設定については references/journey.md）
5	ローカルでビルド	ご自身のマシン	CLI をインストールし、開発ワークスペースを fcode clone で複製します（または fcode team:clone でチームのすべての App を一度に複製します）。ご自身のエージェントと fcode-* スキルを使ってコーディングし、ローカルでテストしてから fcode push を実行します
6	デモ企業	Demo companies ページ	社内ユーザーは直接作成できます。パートナー／IC は申請してください。メールで通知が届きます
7	インストールをテスト	Test marketplace	デモ企業の認証情報を使って実際の OAuth フローを実行し、インストールします。デモ企業の Factorial 内で appRole フォームや UI トリガーボタンを操作します
8	リリース	App detail → Production タブ	リリース（semver とリリースノート）を申請します。検証後、本番ワークスペースに昇格します。所有チームの Factorial 管理者はセルフサービスで、それ以外の場合はオペレーターが対応します（references/journey.md §8）
9	リスティングを公開	App detail → Publication タブ	マーケットプレイスのリスティング用メタデータを設定します。DatoCMS レコードへのリンク、および／または代替フィールドを使用します
10	本番運用	Marketplace	表示され、インストール可能になります。インストールごとに独立したワークスペースが作成されます

ステージごとの詳細、役割ごとの補足、ライフサイクルの状態については、references/journey.md を参照してください。

ジャーニーを支えるワークスペース

名称に関する注意：Factorial Code の workspace は、ワークスペースコンソール、プラットフォーム API、および一部の CLI 表記（「team variables」、parentTeams フィールド）では「チーム」とも呼ばれますが、この意味は前述の人間で構成される開発チームとは関係ありません。CLI の fcode team:* コマンドが指すのは開発チームです。これらのコマンドは、そのチームが所有するすべての App に対して操作を行います（fcode-cli を参照）。

各 App は以下のワークスペースに対応します（スラッグには生の ID ではなく、エンコードされたトークンが含まれます）。

• dev-{appId} — クローンしてプッシュする開発ワークスペースです。
• prod-{appId} — 最初のリリースがリクエストされたときに作成される本番用コピーです。コードは読み取り専用として扱ってください。変更は dev で行い、リリースフローを通じて反映します。書き込みができるのはオペレーターと App の Factorial チーム管理者だけです。変数は本番環境で有効です。すべてのインストールで共有されるデフォルト値と認証情報は、ここで管理します。
• deploy-{installationId} — 会社ごとに 1 つあり、App のワークスペースを継承します。その会社の変数と実行のみを保持し、他社から完全に分離されています。親ワークスペースの変更は、すべてのインストールのワークスペースで自動的に利用可能になります。
• base-app / base-integration-app（言語に対応するバリアントは -js / -py）— すべての App が継承する共有ベースです。API クライアント、Webhook／スケジュール／メール／フォームのヘルパー、および（フレームワーク App の場合は）インテグレーションテンプレートが含まれます。

リリース済みバージョンは固定タグであり、stable エイリアスは現在のバージョンを指します（モデルについては fcode-core-concepts を参照）。マーケットプレイスの App は、リリースフロー（ステージ 8）を通じてリリースしてください。バージョンの公開や stable の変更を手動で行わないでください。

Factorial 内のボタン — UI トリガー

フォームや Webhook に加えて、インストール済みの App はFactorial のページに独自のボタンを追加できます。Factorial チームはプロダクト内で ロケーション（ページヘッダーやアクションのドロップダウンなど。例：calendar.header.admin）を定義します。そのロケーション用の uiTrigger を宣言した App のプロセスは、インストールしたすべての会社に対し、App のラベルとアイコンが付いたボタンとして表示されます。ボタンをクリックすると、ページのコンテキスト（画面上のレコードや会社）を使ってプロセスが実行されます。フォームがある場合は、そのフォームが開きます。これにより、「Acme に同期」のようなアクションを、Factorial がインテグレーション固有の UI を提供しなくても、Factorial の標準アクションの横に配置できます。

ユーザーには次のように案内してください。

• 利用できるのはインストール済みのマーケットプレイス Appのみです。ボタンは会社の deploy- ワークスペースから読み込まれるため、ほかの変更と同様、リリースフロー（ステージ 8）を通じてトリガーが顧客に届きます。開発時には、デモ会社に dev ワークスペースのトリガーが表示されます（ステージ 7）。
• ロケーション ID は Factorial が提供します。プラットフォームにはカタログがありません。ロケーションがまだないページにボタンを追加したい開発者は、そのロケーションを追加する担当の Factorial チームに依頼する必要があります。プロダクトリクエストとしてエスカレーションしてください。
• ロケーションによっては一度に 1 つの App しか登録できません。そのようなロケーションを要求する 2 つ目の App をインストールしようとすると、先に登録されている App の名前を示すメッセージが表示され、失敗します。
• 設定はプロセスページ（Trigger from Factorial。フォームに加え、後のフェーズでは Factorial One ツールやバックエンドジョブも扱う Factorial Action のセクションです。fcode-factorial-actions を参照）または metadata.json にあります。ボタンに関する開発者向けのルールは fcode-ui-triggers に記載されています。

ルーティング — 詳細な質問の参照先

質問の内容	参照先
プラットフォームのモデル：プロセス、モジュール、変数と継承、データストア／ストレージ、バージョン管理とstable	fcode-core-concepts
CLI コマンド、metadata.json／settings.json のフィールド、appRole フィールドのリファレンス、Webhook 認証、FACTORIAL_TOKEN	fcode-cli — ドキュメント：/docs/cli/
プロセス／モジュールのコード作成	fcode-javascript／fcode-python — ドキュメント：/docs/processes/
入力パラメーターのスキーマ（フォーム定義）	fcode-json-schema
Webページへのフォームの埋め込み、テーマ、事前入力	fcode-forms — ドキュメント：/docs/forms/
Factorial へのプロセスの公開（factorial ブロック、Factorial One ツールの契約、ライフサイクルのスラッグ）	fcode-factorial-actions — ドキュメント：/docs/factorial-actions/
Factorial 内のボタン（factorial.uiTrigger、場所、結果エンベロープ）	fcode-ui-triggers
推奨されるエージェントの作業方法、MCP ツール	fcode-agent — ドキュメント：/docs/mcp-server/
作成例（インテグレーション、インストール／アンインストールのライフサイクル）	fcode-examples
実行、スケジュール、実行時の Webhook	ドキュメント：/docs/executions/
インテグレーションフレームワーク	ドキュメント：/docs/building-apps/integrations-framework/
OAuth と API トークン	ドキュメント：/docs/building-apps/oauth/
ワークスペースの階層	ドキュメント：/docs/building-apps/workspaces/
ロールと権限：ワークスペースごとの読み取り／書き込み／昇格が可能なユーザー	references/journey.md §8 — ドキュメント：/docs/building-apps/permissions/
最初から最後までの流れ（公開版）	ドキュメント：/docs/building-apps/developer-journey/

ドキュメントのパスは https://code.factorialhr.com からの相対パスです。

エスカレーションと管理者の操作

必要なこと	対応方法
アクセスリクエストが保留中	審査中です。結果が出たら通知されます
パートナー／個人コントリビューター向けの OAuth アプリ	管理者が事前設定します。完了すると、アプリ設定の OAuth タブに表示されます
デモ用会社（パートナー／IC）	デモ用会社のページで「デモ用会社をリクエスト」を選択してください。準備ができたらメールで通知されます
リリース審査の結果	リリースはデプロイされるか、必要な変更について通知されます。修正後、バージョンを上げて再度リクエストしてください
リリースを本番環境に昇格	所有チームの Factorial 管理者が自分で実行します（アプリの詳細ページにある「昇格方法」ダイアログにコマンドが記載されています）。それ以外の方は運用担当者を経由します — references/journey.md §8
特定の会社にプライベートアプリをインストール	アプリの詳細ページから本番環境へのインストールを作成します。管理者、または Factorial の会社 ID を指定する開発者が実行できます（Factorial の Forward Deployed Engineers がプライベートアプリを展開する方法など）
上限を引き上げたい（実行時間、同時実行数、データストア、レートなど）	すべてのワークスペースは同じ固定プランを利用しており、セルフサービスでのアップグレードはできません。お問い合わせください。Factorial 社内ユーザーは Slack の #factorial-code-users、それ以外の方は Factorial の担当者にご連絡ください。現在の値については、fcode-core-concepts › プランと上限を参照してください
上記以外	Factorial 社内ユーザーは Slack の #factorial-code-users にお問い合わせください。それ以外の方は、上記のプラットフォーム内リクエストフローをご利用ください