Integrations

Generated from the public API contract (OpenAPI). Descriptions in the contract are written in Japanese.

Endpoints

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 の定義

Responses

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

rotateConnectionSecret

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

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

Parameters

Name	In	Type	Required	Description
name	path	string	yes
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

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

listSecretRotations

GET/v1/integrations/secret-rotations

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

Responses

• 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 度だけ

Parameters

Name	In	Type	Required	Description
rotation_id	path	string	yes
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
how	RotationResolutionHow	yes
note	string		補足。how が left_in_place のときは必須。秘密値の値を書かない

Responses

• 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 がトークンを秘密値として持つ

Parameters

Name	In	Type	Required	Description
name	path	string	yes
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

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

oauthCallback

GET/v1/integrations/oauth/callback

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

Parameters

Name	In	Type	Required	Description
state	query	string	yes
code	query	string
error	query	string

Responses

• 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（承認あり）から

Responses

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

listSyncJobs

GET/v1/integrations/sync-jobs

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

Responses

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

startSyncJob

POST/v1/integrations/sync-jobs

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

Parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
connection	string	yes

Responses

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

listExports

GET/v1/integrations/exports

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

Responses

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

createExport

POST/v1/integrations/exports

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

Parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Name	Type	Required	Description
connection	string	yes

Responses

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

getExport

GET/v1/integrations/exports/{id}

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

Parameters

Name	In	Type	Required	Description
id	path	string	yes

Responses

• 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 は返さない

Parameters

Name	In	Type	Required	Description
id	path	string	yes

Responses

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

listSecrets

GET/v1/integrations/secrets

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

Responses

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

putSecret

PUT/v1/integrations/secrets/{name}

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

Parameters

Name	In	Type	Required	Description
name	path	string	yes

Request body

application/json

Name	Type	Required	Description
purpose	string	yes
value	string	yes

Responses

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

revokeSecret

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

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

Parameters

Name	In	Type	Required	Description
name	path	string	yes
Idempotency-Key	header	string		副作用を伴う POST ではサーバーが必須にする。SDK は無ければ自動で付けるので、型では省略できる

Request body

application/json

Responses

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