代表的な連携例

curl と TypeScript の最小例です。ホスト・トークン・テナント ID は環境の値に置き換え、ソースに秘密を直書きしないでください。流れの説明は API 連携のクイックスタート にあります。

Operation ID	メソッド	パス	用途
listMyModels	GET	/my/models	自分が開始できる公開モデル一覧（業務アプリの正）
listMyProcesses	GET	/my/processes	自分が操作できるプロセス一覧
startWorkflowProcess 等	POST	/engine/...	開始・提出・承認（EngineApi）
listWorkflowModels	GET	/models	管理者向け全モデル（Model:read が必要）
listWorkflowProcesses	GET	/processes	管理者向け全プロセス（Process:read が必要）

業務利用者向けのアプリでは、/my/... の API と EngineApi を使用します。/models は管理者向けの API です。

例 1: curl で開始できるモデルを取得する

export ACOMO_HOST="https://YOUR_ACOMO_HOST"
export ACOMO_TOKEN="YOUR_ACCESS_TOKEN"
export ACOMO_AUTH_TENANT_ID="YOUR_AUTH_TENANT_ID"

curl -sS \
  -H "Authorization: Bearer ${ACOMO_TOKEN}" \
  -H "x-tenant-id: ${ACOMO_AUTH_TENANT_ID}" \
  "${ACOMO_HOST}/api/v1/my/models"

成功時はモデルの JSON 配列が返ります。空配列なら、モデルの公開状態と開始ノードのアクションポリシーを確認します。Engine:execute は、一覧取得ではなく開始・提出・承認に必要な権限です。

例 2: TypeScript でプロセスを開始して提出する

import { Configuration, EngineApi, MyModelApi } from '@acomo/client'

const config = new Configuration({
  basePath: process.env.ACOMO_URL,
  accessToken: process.env.ACOMO_TOKEN,
  apiKey: process.env.ACOMO_AUTH_TENANT_ID,
})
const myModelApi = new MyModelApi(config)
const engineApi = new EngineApi(config)

const listRes = await myModelApi.listMyModelsRaw({})
if (!listRes.raw.ok) throw new Error(`listMyModels failed: ${listRes.raw.status}`)
const models = await listRes.raw.json()
const expenseModel = models.find((m: { name: string }) => m.name === '経費精算')
if (!expenseModel) throw new Error('経費精算モデルが見つかりません')

const startRes = await engineApi.startWorkflowProcessRaw({ modelId: expenseModel.id })
if (!startRes.raw.ok) throw new Error(`start failed: ${startRes.raw.status}`)
const process = await startRes.raw.json()

const submitRes = await engineApi.submitWorkflowProcessRaw({
  processId: process.id,
  body: {
    name: '東京出張 交通費',
    amount: 12800,
    date: '2026-06-10',
    applicationType: '申請',
  },
})
if (!submitRes.raw.ok) throw new Error(`submit failed: ${submitRes.raw.status}`)

*Rawを使用する理由は、既知の制限を参照してください。

例 3: 操作可否の取得

import { MyProcessApi } from '@acomo/client'

const myProcessApi = new MyProcessApi(config)
const res = await myProcessApi.getProcessWithNodeActionsRaw({ processId })
if (!res.raw.ok) throw new Error(`getProcessWithNodeActions failed: ${res.raw.status}`)
const { process, nodeActions } = await res.raw.json()
// nodeActions から submit / approve の可否を判定（サーバー評価結果を信頼する）

連携設計の判断材料

• ポータル型申請アプリでは、listMyModels でモデルを取得し、start で開始したプロセスに対して submit または approve を実行します。
• 読み取り専用の監視 — listMyProcesses と履歴 API（管理者は /processes）
• マスタ連携 — ユーザー・グループAPIには、それぞれの対象を管理できる権限が必要です

ブラウザから直接 API を呼び出すとき

別オリジンから呼び出す場合は、接続元URL設定を確認してください。

認証と権限の設定を確認するため、ステージング環境で 401 と 403 の応答をそれぞれ確認してください。業務利用者の権限で管理者向けの /models を呼び出すと、403 エラーになります。

うまくいかないとき

症状	確認
401	トークン期限、x-tenant-id
403 on /models	/my/models に切り替え、または管理者ロール
TypeError	既知の制限で対象バージョンと回避方法を確認
CORS	オリジン登録

認証の付け方は API 認証。トークンの発行画面は アクセストークン。

次に読む

• acomo MCP Server