API 連携のクイックスタート

カスタムアプリから、開始できるモデルの取得、プロセスの開始、提出、承認を行う基本的な実装手順を説明します。

対象読者

フロントエンド、BFF、スクリプトから acomo 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. 認証ファサードを用意する

import { createAcomoAuth } from '@acomo/client'

export const acomoAuth = createAcomoAuth({
  apiUrl: '', // 同一オリジンなら空。別ホストなら https://your-acomo.example.com
  authTenantId: process.env.ACOMO_AUTH_TENANT_ID!,
})

ブラウザ SPA ではサインイン UI と組み合わせ、サーバー側では Client Credentials 等の方式を API 認証 に従って選びます。

2. クライアントを初期化する

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. 開始できるモデルを一覧する

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. プロセスを開始する

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. データを入力して提出する

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 の中には dataSchema のキーを トップレベル に並べます。{ data: { ... } } では包みません。

6. 承認者が承認する

承認者のセッション（またはトークン）で同様に EngineApi を初期化し:

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経由ならサーバー側から呼び出します。

さらに学ぶ

• 詳細な API パターン: 代表的な連携例
• 認証統合: API 認証

うまくいかないとき

症状	確認
401	トークン期限、x-tenant-id（apiKey / ヘッダ）
403 on /models	業務ユーザーは /my/models を使う
TypeError	既知の制限で対象バージョンと回避方法を確認
CORS エラー	接続元URL設定

表にない症状は、既知の制限とトラブルシューティングを確認してください。

次に読む

• OpenAPI仕様書