KING OF TIME を接続する

grantry から KING OF TIME（勤怠管理）の WebAPI を使うには、KING OF TIME 側で発行したアクセストークンを、grantry の カスタムプロバイダー として登録します。

KING OF TIME 側で準備するもの

1. KING OF TIME の WebAPI が利用できる契約・オプションになっていること
2. WebAPI 用のアクセストークンを発行する

トークンは自己発行できないことがある

KING OF TIME のアクセストークンは管理画面の設定から発行します。プランやオプション契約によっては WebAPI 自体が無効な場合があるため、取得できないときは KING OF TIME のサポートに WebAPI の利用可否を確認してください。

grantry にカスタムプロバイダーを追加する

app.grantry.ai のカスタムプロバイダー追加画面で、以下のように入力します。

項目	入力値
Provider key	kingoftime
Label	KING OF TIME
API base URL	https://api.kingtime.jp/v1.0
Auth style	Authorization: Bearer token
API key header	空欄
Allowed path prefixes	/
Connection check path	/company
Token settings URL	空欄でOK

API base URL はプレースホルダーのまま保存しない

API base URL を https://example.com/api のような初期表示のままにすると、リクエストが正しいホストに飛ばず失敗します。必ず https://api.kingtime.jp/v1.0 に書き換えてください。バージョン /v1.0 まで含めるのがポイントです。

例:

API base URL:
https://api.kingtime.jp/v1.0

Connection check path:
/company

接続を追加する

カスタムプロバイダーを作成したあと、テナント（スコープ）の接続追加画面で KING OF TIME を選び、発行したアクセストークンを credential 欄に貼り付けます。

KING OF TIME は Bearer token 方式なので、カスタムプロバイダー作成時の API key header には何も入れません。トークン本体は接続追加時の credential 欄に入れます。

接続できたか確認する

接続カードで Recheck を押します。成功すると以下のような表示になります。

active
ok
Connection check: 1 ok

この状態なら、grantry 本番環境から KING OF TIME の /company へ疎通できています。

取得できる主なデータ

kingoftime/request（GET）で以下のエンドポイントを呼び出せます。

path	内容
/company	企業情報（疎通確認にも使う）
/employees	従業員一覧
/divisions	所属（部門）一覧
/daily-workings	日別勤怠（出退勤・労働時間）
/monthly-workings	月次集計
/daily-schedules	勤務予定

レート制限

KING OF TIME API には 5 分あたりのリクエスト上限があります（通常エンドポイントは 5 分 500 リクエスト、打刻系は 5 分 2000 リクエスト）。大量取得時は分割して呼び出してください。

IPアドレス制限を使う場合

KING OF TIME 側で API のアクセス元 IP を制限している場合、許可するのは app.grantry.ai のDNS解決先ではなく、grantry の本番実行環境の outbound IP です。

grantry 本番は Railway の agent-oauth service / production environment で動いています。Railway の Static Outbound IPs を有効化し、表示された IPv4 アドレスを KING OF TIME 側に許可してください。

手順:

1. Railway dashboard で agent-oauth project を開く
2. Environment を production にする
3. Service agent-oauth を開く
4. Settings / Networking で Static Outbound IPs を有効化する
5. 表示された IPv4 アドレスを KING OF TIME の許可IPに追加する
6. Railway で再デプロイする
7. grantry の接続カードで Recheck する

よくある失敗

表示・症状	原因	対処
check failed / 404	API base URL がプレースホルダーのまま、またはバージョン抜け	https://api.kingtime.jp/v1.0 に直す
check failed / 401・403	トークンが無効・失効、または WebAPI 未契約	トークンを再発行し、KING OF TIME 側の WebAPI 利用可否を確認する
429	レート制限超過	呼び出し間隔をあける／分割する

→ 接続の状態を確認する