API の概要

FreeMaint がシステム間連携のために提供する API は 1 つです。/api/v1/graphql の GraphQL です。ブラウザーで見える REST ルートはアプリケーション自身の API で、ユーザーセッションで認証されます。API キーでは到達できません。連携は GraphQL を前提に設計してください。

REST API

/api/v1/{resource} の REST ルートは FreeMaint の Web アプリとモバイルアプリが呼び出すもので、ユーザーセッション（JWT）で認証されます。API キー（fmk_...）ではこれらを認証できません。API キーが受け付けられるのは /api/v1/graphql とエネルギー取り込みエンドポイントだけです。連携を構築する場合は、下の GraphQL のセクションをお読みください。REST のパスをここに記載しているのは、ブラウザーのネットワークタブに表示されるためであり、API キーで呼び出せるからではありません。

例（ユーザーセッション。API キーではありません。fmk_ キーではこのルートを認証できません）: curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL API

GraphQL のエンドポイントは POST /api/v1/graphql です。対象は製品の一部に意図的に限定されており、作業指示・設備・設備停止・部品とその在庫変動・メーター・発注書・ロケーション・仕入先・顧客・フロアプランを扱います。アプリケーション全体ではありません。1 つの画面を組み立てるのに複数のエンドポイントを呼ぶ必要がある場合に GraphQL を使ってください。たとえば、作業指示とその設備の詳細、使用部品、労務費合計をまとめて表示するタイルです。スキーマが届かない範囲は ERP 連携ガイドに列挙しています。

クエリの例: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

認証

どちらの API も Authorization ヘッダーの JWT トークンを受け付けます。トークンは POST /api/v1/auth/login が発行し、有効期間は 2 時間です（リフレッシュトークンで更新）。サーバー間連携では代わりに API キーを使ってください。管理者は「会社の設定 > API」（/company-settings/api）で作成し、ロールで許可されているユーザーは「プロフィール > セキュリティ > APIキー」（/profile/api-keys）で自分用のキーを作成します。送信するのは Authorization: Bearer fmk_... です。キーは所有者として動作します。所有者と同じ権限を持ち、所有者が見られるものだけを見ます。重要：API キーで認証できるのは GraphQL エンドポイント（POST /api/v1/graphql）、エネルギー取り込みエンドポイント、/public-api/{whoami,ping} です。REST のリソースルートは認証できません。そちらはユーザーの JWT が必要です。

階層ごとの提供範囲

レート制限

クォータは会社ごとの日次カウンターで、GraphQL とエネルギー取り込みエンドポイントで共有され、UTC 00:00 にリセットされます。Business は 1 日 5,000 コール、Enterprise は 100,000 コールまでです。すべてのレスポンスに X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が付きます。分単位のウィンドウはなく、Retry-After ヘッダーもありません。REST 側では拒否は HTTP 403 になります。GraphQL では HTTP ステータスは 200 のままで（GraphQL は常に 200 を返します）、拒否は errors[0].extensions.code = FORBIDDEN で示されます。GraphQL では HTTP 403 を待ち受けるのではなく、errors 配列を確認してください。

エラー形式

すべてのエラーには、HTTP ステータス、機械が判定できるコード、人が読めるメッセージが含まれます。4xx はクライアント側のエラー（検証、権限、未検出）で、5xx はサーバー側のエラーです。5xx は指数バックオフで再試行してください。GraphQL ではコードは extensions.code にあり、判定に使える値は BAD_REQUEST、UNAUTHENTICATED、FORBIDDEN、NOT_FOUND、CONFLICT、BAD_USER_INPUT、TOO_MANY_REQUESTS です。入力の検証に失敗した場合、メッセージは問題のある項目を正確に示します（例：「quantity must be a number conforming to the specified constraints」）。どの項目が誤っていたかを推測する必要はありません。検索で何も一致しないことはエラーではありません。part(barcode:) は null を返します。

公式 SDK とツール

現時点では公式のクライアント SDK はありません。GraphQL エンドポイントではイントロスペクションが有効なため、任意の GraphQL クライアント（Apollo、graphql-codegen、Insomnia、Postman）で API キーを付けて POST /api/v1/graphql を指定すれば、スキーマを取得できます。現在、静的な OpenAPI ドキュメントや SDL ファイルを固定 URL で公開することはしていません。

API キーは Core と Starter ではご利用いただけません。