Skip to content

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設定

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

次に読む ​

対応製品バージョン: acomo 1.0.0 / 画面・操作の最終確認日: 2026年8月26日