共通仕様¶

ベースURL¶

http://[IPアドレスまたはホスト名]:[ポート番号]/XFV20/api/

ベースURLに続けてアクセスしたいリソース名を指定して必要な操作を呼び出します。指定可能なリソース名についてはリファレンスを参照ください。

ヒント

ユーザー情報の一覧を取得する場合は次のようにベースURLに続けてusersを指定してアクセスします。
```
http://[IPアドレスまたはホスト名]:[ポート番号]/XFV20/api/users
```

APIトークンによる認証¶

REST APIへの不正アクセスを防止するため、各種リソースへアクセスするためには APIトークンによる認証が必須となります。 APIトークンは[システム設定]画面から事前に生成し、リクエストヘッダーまたはパラメーターに指定する必要があります。

APIトークンの発行手順

ログイン画面から[すべての管理権限]または[システム設定の変更権限]の管理権限が付与されたユーザーでワークフローシステムへログインします。
ヘッダーメニューの[管理]をクリック後、[システム設定]をクリックします。
[システム設定]画面の[オプション]メニューをクリックし、[APIオプション]タブの[認証]を表示します。
REST APIの[接続を許可する]を有効にし、APIトークンの[生成]ボタンをクリックしてAPIトークンを生成します。
生成されたAPIトークンをクリップボードなどへコピーします。
[保存]ボタンをクリックして設定を保存します。
ワークフローシステム(アプリケーションサーバー)を再起動します。
REST APIへアクセスする際にリクエストヘッダーまたはパラメータへ生成したAPIトークンを指定します。

種別名前

ヘッダー X-CWF-API-Token

パラメーター api_token
http://[IPアドレスまたはホスト名]:[ポート番号]/XFV20/api/users?api_token=ZU3fHY0LuH0izt2ytqisp3lcKzKfv8a2XDLGK80t

ヒント

APIトークンは自動生成のほか、任意の英数字を使用して指定することもできます。
APIトークンをヘッダーまたはパラメーターに指定していない場合や正しくない場合、エラーレスポンスが返されます。
ヘッダーとパラメーターを同時に指定した場合はパラメーターの値が優先されます。

文字コードとフォーマット¶

文字コードはUTF-8を使用し、JSONフォーマットでデータをやり取りします。文字コードやフォーマットを変更することはできません。
レスポンスで取得される日時の文字列は、UTC（協定世界時）でフォーマットされます。

ページネーション¶

一覧を返すリソースへアクセスする場合、先頭から読み飛ばすレコード数と取得する最大レコード数をパラメーターから指定することで、ページネーション(ページ切り替え)を実現することができます。指定を省略した場合は初期値が使用されます。

種別	名前	指定可能な値	初期値	説明
パラメーター	offset	0以上の整数	0	先頭から読み飛ばすレコードの数を指定します。
パラメーター	limit	1以上100以下の整数	20	取得する最大レコード数を指定します。

ヒント

ユーザーの一覧の30件目から40件目の範囲のレコードを取得する場合、パラメーターは次のように指定します。
```
http://[IPアドレスまたはホスト名]:[ポート番号]/XFV20/api/users?offset=30&limit=10
```

レスポンスには取得可能なレコードの総件数を表すtotal_countが返されます。このtotal_countを使用することでページネーションの有効範囲を判断することができます。

{
   "users": [...],
   "total_count": 50
}

入力データ¶

申請・承認フォームの入力データには、オブジェクト名をキーとして設定します。オブジェクト名は、処理対象のフォームがマルチフォームを使用しているかにより、指定方法が異なります。

ヒント

マルチフォームでは、申請内容にあわせて、申請時に手動でページを追加して申請することができます。 REST APIにおいても、ページを追加した時と同じようにページを指定して申請することができます。
マルチフォームの設定はFormエディターで行います。マルチフォームの設定についての詳細はFormエディターのマニュアルを参照ください。

マルチフォーム設定なし
form_dataの子要素として、フォーム上のオブジェクトと同じ名前のキーを定義し、オブジェクトへの入力内容を設定します。

◇記載例
{
  "form_data":{
    "BUMON_ID": "001",
    "KINGAKU": "20000",
    "NAIYOU": "名刺入れ"
  }
}
マルチフォーム設定あり
Formエディターの[マルチフォーム] - [フォーム設定] - [マルチフォーム設定]がチェックされている状態、かつ、オブジェクトの[HTMLタブ] - [マルチフォームでオブジェクトをページごとに区別する]がチェックされている場合、以下のキーを定義してform_dataの子要素として配置します。
[オブジェクト名] + _ + [フォーム識別子] + _ + [ページ番号] - 1
注釈

[オブジェクト名] [フォーム識別子]は、Formエディターで設定した値です。

[ページ番号]は、フォーム識別子ごとのページ番号です。（全体を通してのページ番号ではありません。）

◇記載例

[フォーム識別子]が「FORM02」のページを2ページ追加し、追加したページのオブジェクトを指定する場合。
ページ番号オブジェクトリクエストで指定するオブジェクト名

1 KINGAKU KINGAKU_FORM02_0

1 NAIYOU NAIYOU_FORM02_0

2 KINGAKU KINGAKU_FORM02_1

2 NAIYOU NAIYOU_FORM02_1
{
  "form_data":{
    "BUMON_ID": "001",
    "KINGAKU_FORM02_0": "20000",
    "NAIYOU_FORM02_0": "名刺入れ",
    "KINGAKU_FORM02_1": "50000",
    "NAIYOU_FORM02_1": "モニター"
  }
}
ヒント

指定したページが、マルチフォーム設定の[最小・最大ページ数]の最小ページ数未満となる場合は、最小ページ数まで空欄のページが追加されます。

マルチフォーム設定の[最小・最大ページ数]の最大ページ数を超えたページ指定は無視されます。

申請データに指定したオブジェクトに未指定のページがある場合、未指定のページについては空欄となります。
例えば、1ページと3ページのオブジェクトが指定されている場合、オブジェクトが指定されていない2ページの値は空欄になります。
ヒント

[HTMLタブ] - [マルチフォームでオブジェクトをページごとに区別する]にチェックのないオブジェクトについては、マルチフォームを使用しない場合と同様の方法で設定してください。

ファイルの取り扱い¶

案件に添付ファイルを添付する場合やExcelなどの申請ファイルを使用して申請する場合、ファイルはBase64フォーマットに変換する必要があります。変換したBase64フォーマットのデータは次のようにnameとdataのキーを使用して指定します。

案件に添付ファイルを添付する

{
   "options": {
      "attached_files": [
         {
            "name": "添付ファイル名",
            "data": "Base64フォーマットのデータ"
         }
      ]
   }
}

申請ファイルを使用して申請する

{
   "form_data": {
      "name": "申請ファイル名",
      "data": "Base64フォーマットのデータ"
   }
}

ヒント

添付ファイルのポリシーやファイルサイズの上限の設定によってエラーレスポンスが返されることがあります。その場合は[システム設定]画面の[ファイル設定]から設定を変更してください。

エスケープシーケンス¶

HTTPメソッドのPOSTやPUTを使用したリクエストで円記号やダブルクォートを含む場合は\(0x5C)でエスケープする必要があります。また、改行とタブ文字を表す場合はそれぞれ\n(0x0A)と\t(0x09)を使用します。