factorial-api-sdks

Factorial API SDK

ドメイン別の名前空間を持つクライアント、ページネーション用ヘルパー、シンプルな認証機能を備え、Factorial の公開 API をラップする公式 SDK です。このスキルでは、その使い方と Factorial の Webhook の扱い方を説明します。生成されたリファレンスデータは reference/ にあります（リファレンスを参照）。

• TypeScript：@factorialco/api-client（npm）
• Python：factorial-api-client（PyPI）
• Ruby：factorial_api（RubyGems）

インストール

npm install @factorialco/api-client     # TypeScript
pip install factorial-api-client          # Python
gem install factorial_api                 # Ruby

認証

API キーまたは OAuth トークン（あるいは両方）を指定します。

オプション	送信されるヘッダー
apiKey	x-api-key: <value>
token	Authorization: Bearer <value>

Factorial API キーは JWT 形式ですが、ベアラートークンではなく x-api-key として送信します。

認証情報は明示的に渡すか、環境変数（FACTORIAL_API_KEY、FACTORIAL_TOKEN、任意の FACTORIAL_BASE_URL）から読み込めます。

import { FactorialClient } from "@factorialco/api-client";
const client = new FactorialClient({ apiKey: process.env.FACTORIAL_API_KEY });

from factorial_api_client import FactorialClient
client = FactorialClient(api_key="YOUR_KEY")   # or token="...", or from env

require "factorial_api"
api = F::Api.new(api_key: ENV["FACTORIAL_API_KEY"])   # or token:, or from env

エンドポイントの呼び出し

クライアントは client.<namespace>.<resource>.<method> の形式で構成されています。名前空間とリソースは、REST パス /api/<version>/resources/<namespace>/<resource> に対応しています。

メソッド名は次の規則に従います。

HTTP／形式	SDK メソッド
GET コレクション	list() / paginate() / all()
GET ID 指定	get(id)
POST コレクション	create(body)
PUT／PATCH ID 指定	update(id, body)
DELETE ID 指定	delete(id)
カスタムアクション（例：apply）	camelCase のアクション名（例：apply()）

const { data } = await client.employees.employees.list();
const created = await client.apiPublic.webhookSubscriptions.create({ /* body */ });

employees = client.employees.employee.list()
sub = client.api_public.webhook_subscription.create(body={...})

Ruby では同じ形式を snake_case で使用します。パス、クエリ、フォームを問わず必須パラメーターは名前付きキーワードとして指定し、任意のクエリパラメーターは query_params: ハッシュに、リクエスト本文は *_request キーワードに指定します。（api.employees_employee.employees_employees_get(true, false) などの低レベルアクセサーも、引き続き内部で使用できます。）

employees = api.employees.employee.list(only_active: true, only_managers: false).data
team = api.teams.team.create(teams_teams_post_request: { name: "Platform" })

任意のエンドポイントに対応する正確な名前空間／リソース／メソッドを確認するには、reference/sdk-methods.md（各エンドポイントの TS および Ruby の呼び出しをグループ別に掲載）またはオンライン API リファレンスを参照してください。

ページネーション

リストエンドポイントは { data: T[], meta: { end_cursor?, has_next_page, ... } } を返します。

• list() — 生のページを 1 件返します
• paginate() — 非同期イテレーター（TS）／同期または非同期ジェネレーター（Python）
• all()（TS）／collect_all()（Python）— すべてのページを取得して 1 つの配列／リストにまとめます
• Ruby：すべてのリスト対応リソースで paginate（遅延評価の Enumerator。limit:／max_items: で上限を設定）および all を使用できます。F::Api.paginate { |page| ... } は生の呼び出しをラップします

for await (const emp of client.employees.employees.paginate()) { /* ... */ }
const everyone = await client.employees.employees.all({ maxItems: 500 });

for emp in client.employees.employee.paginate(max_items=50): ...
everyone = client.employees.employee.all()

大量データの取得

ページあたりの上限は 100 件 です。これはデフォルト値ではなく、サーバー側のハード上限です （ページネーションのドキュメントを参照）。 より大きな limit を指定しても効果はありません。カーソルページネーションは順次処理されるため（ページ N+1 にはページ N の end_cursor が必要です）、大規模なデータセットでの all()（たとえば、会社全体の 1 か月分の attendance/worked_times）では、数十件のリクエストが順次発生します。リクエスト数とレイテンシーを適切に抑えるには、次の方法を利用してください。

• まず絞り込む。 データをすべて取得してローカルで絞り込むのではなく、エンドポイントのクエリパラメーター（日付範囲、ids、employee_ids など）を使用してください。
• 段階的に同期する。 エンドポイントが updated_at 形式のフィルターに対応している場合は、前回の実行以降に変更されたデータだけを取得してローカルにキャッシュしてください。レポートを作成するたびにデータセット全体を再取得するのは避けてください。
• 大規模な取得を分割する。 1 つの大きなクエリを、フィルターを適用した複数のサブクエリ（日付範囲または ID のチャンクごと）に分割して並行実行してください。各サブクエリ内のページネーションは引き続き順次処理されますが、全体の所要時間は短縮されます。リクエストの総数は変わらないため、レート制限に注意してください。
• 上限を設ける。 バグや予期しないデータ量によって、クロールが無制限に続くことを防ぐため、max_items / maxItems を渡してください。

サーバー側の集計エンドポイントはありません。合計値（たとえば、期間ごとの従業員別勤務時間）は、生のレコードからクライアント側で計算する必要があります。

エラー

どの SDK も、2xx 以外のレスポンス（無効または期限切れのトークン、誤ったベース URL、サーバーエラーなど）を受け取ると、空のデータを返して黙って処理を続けるのではなく、明示的にエラーを発生させます。それぞれ、ステータスとレスポンス本文を保持する型付きエラーを発生させます。

SDK	クラス	ステータス	本文
TypeScript	FactorialApiError（Error を拡張）	status	body（解析済み）、さらに method、url
Python	UnexpectedStatus	status_code	content（バイト列）
Ruby	F::Api::ApiError	code	response_body

// TypeScript — results have no `error` field; failures throw.
import { FactorialApiError } from "@factorialco/api-client";
try {
  const { data } = await client.employees.employees.get({ path: { id: "42" } });
} catch (err) {
  if (err instanceof FactorialApiError) console.error(err.status, err.url, err.body);
  else throw err; // transport failure (DNS/connection), not an HTTP response
}

# Python
from factorial_api_client.generated.errors import UnexpectedStatus
try:
    employees = client.employees.employees.list()
except UnexpectedStatus as e:
    print(e.status_code, e.content)

# Ruby
begin
  api.employees.employee.list
rescue F::Api::ApiError => e
  puts e.code, e.response_body
end

API のバージョニング

SDK は、SDK のメジャーバージョンに固定された特定の日付バージョンの Factorial API（例：2026-04-01）を対象とします。新しい API バージョンは、新しい SDK のメジャーバージョンとして提供されます。

Webhook

Webhook は、イベント発生時に Factorial が target_url へ送信する HTTP POST です。

配信の仕組み

• company_id とともに、target_url を指定して、subscription_type（例：ats/application/create）の Webhook サブスクリプション を作成します。
• イベントが発生すると、Factorial は target_url に POST を送信します。ペイロードは最上位にあるリソースオブジェクトです。{ type, data } のエンベロープにはラップされません。イベントを簡単に区別する必要がある場合は、イベントごとに異なる URL を使用してください。
• サブスクリプション時に challenge を設定すると、Factorial はリクエストヘッダー x-factorial-wh-challenge でその値を返します。これにより、送信元を検証できます。
• オプションの作成者ヘッダー x-factorial-author-id / x-factorial-author-type（employee または company）は、安全に公開できる場合に、イベントを発生させたユーザーを識別します。
• 再試行ポリシー：48 時間で最大 20 回再試行されます。その後、サブスクリプションは無効になり、メールで通知されます。PUT { enabled: true } で再度有効にできます。

SDK を使ったサブスクリプションの管理

await client.apiPublic.webhookSubscriptions.create({
  subscription_type: "ats/application/create",
  target_url: "https://example.com/webhooks/factorial",
  challenge: "a-secret-you-choose",
  company_id: 55,
});

client.api_public.webhook_subscription.create(body={
    "subscription_type": "ats/application/create",
    "target_url": "https://example.com/webhooks/factorial",
    "challenge": "a-secret-you-choose",
    "company_id": 55,
})

エクスポートされた Webhook 型を使って、ハンドラーのペイロードに型を指定します。

import type { AtsApplicationCreateWebhook, WebhookPayloadMap, WebhookSubscriptionType }
  from "@factorialco/api-client";

// Direct alias
function onApplicationCreated(payload: AtsApplicationCreateWebhook) { /* ... */ }

// Typed dispatch keyed on the runtime subscription_type
function handle<T extends WebhookSubscriptionType>(type: T, payload: WebhookPayloadMap[T]) { /* ... */ }

from factorial_api_client import AtsApplicationCreateWebhook, WEBHOOK_PAYLOAD_TYPES

def on_application_created(payload: AtsApplicationCreateWebhook) -> None: ...

# Runtime lookup of the model class for a subscription_type
model_cls = WEBHOOK_PAYLOAD_TYPES["ats/application/create"]

イベントの全一覧、各イベントの subscription_type、およびペイロードのフィールドについては、 reference/webhooks.md を参照してください。

参考資料

生成された SDK 固有の参照テーブルです。正確な名前や構造を確認する際に参照してください。

• reference/webhooks.md — 各 Webhook イベント、subscription_type、ペイロードのフィールド。
• reference/sdk-methods.md — 名前空間／リソース別にまとめた各 REST エンドポイントと、対応する SDK 呼び出し。

OAuth フロー、API キー、バージョニング、Webhook ポリシーなどの解説については、常に最新のライブドキュメントを使用してください。ここには同梱されていません。

• はじめに：https://apidoc.factorialhr.com/docs/getting-started
• API リファレンス全文：https://apidoc.factorialhr.com/reference