外部連携

外部との接続（Connection の定義）、人事の台帳などからの取り込み、会計へ渡す CSV の出力、接続に使う秘密値（SecretRef）。 秘密値の値は API で返さない。取り込みの接続先を呼ぶのはコネクタの実行（consumer）だけ

説明は公開 API の契約（OpenAPI）から生成しています。

エンドポイント

GET	/v1/integrations/connections
POST	/v1/integrations/connections/{name}/rotate
GET	/v1/integrations/secret-rotations
POST	/v1/integrations/secret-rotations/{rotation_id}/resolve
POST	/v1/integrations/connections/{name}/oauth/start
GET	/v1/integrations/oauth/callback
GET	/v1/integrations/browser-flows
GET	/v1/integrations/sync-jobs
POST	/v1/integrations/sync-jobs
GET	/v1/integrations/exports
POST	/v1/integrations/exports
GET	/v1/integrations/exports/{id}
GET	/v1/integrations/exports/{id}/content
GET	/v1/integrations/secrets
PUT	/v1/integrations/secrets/{name}
POST	/v1/integrations/secrets/{name}/revoke

listConnections

GET/v1/integrations/connections

integrations:read が必要。有効なバージョンの Connection の定義

応答

• 200 — object: Connection の定義
• default — Problem: RFC 9457 Problem Details

rotateConnectionSecret

POST/v1/integrations/connections/{name}/rotate

secrets:write が必要。Connection の rotation の日数を待たずに、接続の秘密値を回す。 進めるのは業務データの DO の alarm なので、受け付けた回の記録を返す。回している途中なら、その回を返す

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

応答

• 202 — SecretRotation: 受け付けた回の記録
• default — Problem: RFC 9457 Problem Details

listSecretRotations

GET/v1/integrations/secret-rotations

secrets:read が必要。秘密値を回した記録を新しい順に返す。値は返さない。 接続先に値が残ったまま片付けていない回は、古くても一覧に含める

応答

• 200 — object: 回した記録（直近の 100 件と、片付けていない回の最大 100 件）
• default — Problem: RFC 9457 Problem Details

resolveSecretRotation

POST/v1/integrations/secret-rotations/{rotation_id}/resolve

secrets:write が必要。接続先に値が残った回（revocation が external_revocation_failed）を人が片付けたことを、 誰が・いつ・どう片付けたかとともに記録する。接続先は呼ばず、回の状態も変えない。片付けは 1 回の記録につき 1 度だけ

パラメーター

名前	場所	型	必須	説明
rotation_id	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
how	RotationResolutionHow	はい
note	string		補足。how が left_in_place のときは必須。秘密値の値を書かない

応答

• 200 — SecretRotation: 片付けを記録した回
• default — Problem: RFC 9457 Problem Details

startConnectionOAuth

POST/v1/integrations/connections/{name}/oauth/start

secrets:write が必要。OAuth で接続する Connection の同意を始める。接続先の同意の画面の URL を返す。 管理者がその画面で許可すると、接続先が /v1/integrations/oauth/callback に戻し、Hane がトークンを秘密値として持つ

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

応答

• 201 — object: 同意の画面の URL（10 分で切れる）
• default — Problem: RFC 9457 Problem Details

oauthCallback

GET/v1/integrations/oauth/callback

接続先の同意の画面から、利用者のブラウザがリダイレクトされて来る口。認証はなく、入口が state の署名と期限を確かめる。 結果は利用者に見せる HTML で返す

パラメーター

名前	場所	型	必須	説明
state	query	string	はい
code	query	string
error	query	string

応答

• 200 — string: 接続した
• 400 — string: 接続先が同意を返さなかった
• 409 — string: 同意の要求が切れたか使い済み、またはトークンに替えられなかった
• default — Problem: RFC 9457 Problem Details

listBrowserFlows

GET/v1/integrations/browser-flows

integrations:read が必要。有効なバージョンのポータルの手順（BrowserFlow）。実行は Agent の browser.run_flow（承認あり）から

応答

• 200 — object: BrowserFlow の定義
• default — Problem: RFC 9457 Problem Details

listSyncJobs

GET/v1/integrations/sync-jobs

integrations:read が必要。新しい順に 50 件

応答

• 200 — object: 取り込みの実行
• default — Problem: RFC 9457 Problem Details

startSyncJob

POST/v1/integrations/sync-jobs

integrations:run が必要。hr の Connection から取り込む。consumer が接続先から読み、CSV の取り込みとして台帳に入れる

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
connection	string	はい

応答

• 202 — SyncJob: 受け付けた取り込み
• default — Problem: RFC 9457 Problem Details

listExports

GET/v1/integrations/exports

integrations:read が必要。新しい順に 50 件

応答

• 200 — object: 出力
• default — Problem: RFC 9457 Problem Details

createExport

POST/v1/integrations/exports

integrations:run が必要。accounting-csv の Connection の列と、いまの時刻を境界として固定して出力を依頼する。 consumer が part に分けて書き、manifest を書いたら completed になる

パラメーター

名前	場所	型	必須	説明
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

名前	型	必須	説明
connection	string	はい

応答

• 202 — ExportJob: 受け付けた出力（queued）
• default — Problem: RFC 9457 Problem Details

getExport

GET/v1/integrations/exports/{id}

integrations:read が必要。出力の状態と manifest。manifest は completed になるまで null

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — object: 出力の状態と manifest
• default — Problem: RFC 9457 Problem Details

getExportContent

GET/v1/integrations/exports/{id}/content

integrations:run が必要。completed の出力の CSV（UTF-8）。x-content-sha256 は manifest の digest。 completed でなければ 409 で、書きかけの part は返さない

パラメーター

名前	場所	型	必須	説明
id	path	string	はい

応答

• 200 — string: CSV
• default — Problem: RFC 9457 Problem Details

listSecrets

GET/v1/integrations/secrets

secrets:read が必要。秘密値のメタデータだけ。値は返さない

応答

• 200 — object: 秘密値のメタデータ
• default — Problem: RFC 9457 Problem Details

putSecret

PUT/v1/integrations/secrets/{name}

secrets:write が必要。登録か、同じ名前なら値を替える（バージョンを上げる）。値は暗号化して持ち、返さない

パラメーター

名前	場所	型	必須	説明
name	path	string	はい

リクエストの本文

application/json

名前	型	必須	説明
purpose	string	はい
value	string	はい

応答

• 200 — SecretMeta: 秘密値のメタデータ
• default — Problem: RFC 9457 Problem Details

revokeSecret

POST/v1/integrations/secrets/{name}/revoke

secrets:write が必要。値を消し、以後の接続に使わせない

パラメーター

名前	場所	型	必須	説明
name	path	string	はい
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

リクエストの本文

application/json

応答

• 200 — SecretMeta: 止めた秘密値のメタデータ
• default — Problem: RFC 9457 Problem Details