テーマ
API連携のクイックスタート
カスタムアプリで、開始できるモデルの取得、プロセスの開始、提出、承認を行う基本的な実装手順を説明します。
対象読者
開発者
前提
システム管理者から テナントID(authTenantId)と、サインイン方法またはトークンの取得方法を聞いておくこと。例はTypeScriptと @acomo/client(Node 18以上)。
知っておくこと
| ポイント | 内容 |
|---|---|
| 業務利用者向けAPI | /my/models・/my/processes(MyModelApi / MyProcessApi) |
| 管理者向けAPI | /models・/processes(ModelApi / ProcessApi)— Model:read 等が必要 |
| エンジン操作 | EngineApi の start / submit / approve |
| レスポンス取得 | プロセス情報を返す操作は、既知の制限に該当する場合に*Rawを使用します |
| リクエストbody | フラットなJSON(ネストした data ラッパーは不要) |
業務利用者向けのアプリでは、/my/... のAPIを使用します。/models は管理者向けのAPIであるため、Engine:execute だけを持つロールから呼び出すと403エラーになります。
手順
1. 認証ファサードを用意する
typescript
import { createAcomoAuth } from '@acomo/client'
export const acomoAuth = createAcomoAuth({
apiUrl: '', // 同一オリジンなら空。別ホストなら https://your-acomo.example.com
authTenantId: process.env.ACOMO_AUTH_TENANT_ID!,
})ブラウザのSPAではサインイン画面と組み合わせて使い、サーバー側ではClient Credentialsなどの方式を API認証 に従って選びます。
2. クライアントを初期化する
typescript
import { createAcomoConfiguration, EngineApi, MyModelApi } from '@acomo/client'
import { acomoAuth } from './acomoAuth'
const config = createAcomoConfiguration(acomoAuth)
const myModelApi = new MyModelApi(config)
const engineApi = new EngineApi(config)3. 開始できるモデルを一覧する
typescript
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('経費精算モデルが見つかりません')4. プロセスを開始する
typescript
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()5. データを入力して提出する
typescript
const submitRes = await engineApi.submitWorkflowProcessRaw({
processId: process.id,
body: {
name: '東京出張 交通費',
amount: 12800,
date: '2026-06-10',
applicationType: '申請',
comment: '新幹線往復分',
},
})
if (!submitRes.raw.ok) throw new Error(`submit failed: ${submitRes.raw.status}`)body の中にはデータスキーマのキーを トップレベル に並べます。{ data: { ... } } では包みません。
6. 承認者が承認する
承認者のセッション、またはトークンで、同様に EngineApi を初期化して呼び出します。
typescript
const approveRes = await engineApi.approveWorkflowProcessRaw({
processId: process.id,
body: {
approverComment: '内容を確認し承認しました',
},
})
if (!approveRes.raw.ok) throw new Error(`approve failed: ${approveRes.raw.status}`)操作可否はMyProcessApi.getProcessWithNodeActionsRawが返すnodeActionsで確認します。アプリ側で条件式を独自に再評価しないでください。
CORSとオリジン
ブラウザから別オリジンでAPIを直接呼び出す場合、テナントの接続元URL設定にアプリのオリジンを登録します。BFF経由ならサーバー側から呼び出します。
さらに学ぶ
うまくいかないとき
| 症状 | 確認 |
|---|---|
| 401 | トークン期限、x-tenant-id(apiKey / ヘッダー) |
/models で403 | 業務利用者は /my/models を使う |
TypeError | 既知の制限で対象バージョンと回避方法を確認 |
| CORSエラー | 接続元URL設定 |
表にない症状は、既知の制限とトラブルシューティングを確認してください。