View on GitHub

X-point REST API利用ガイド

X-point Cloud 開発者用公開ドキュメント

REST API利用ガイド

1. REST APIの概要

X-pointの各種機能をブラウザ、スマートデバイス・アプリに表示される画面から利用するのではなく、httpsプロトコルを介した通信で画面を介さず直接利用することを目的とする機能です。

主な機能

  1. 書類の提出
  2. 書類のワークフロー操作／状態の取得
  3. 書類内容の取得（コメント含む）
  4. 添付ファイルの操作
  5. 書類PDFの取得
  6. 自動申請情報の取得
  7. フォーム情報の取得
  8. 代理権限情報の取得
  9. 承認待ち書類情報取得
  10. 書類検索
  11. ユーザ情報の取得、登録、更新、削除
  12. ユーザグループ情報の取得、登録、更新、削除
  13. 役職情報の取得、登録、更新、削除

注意事項

2. 共通仕様

2.1. 基本項目

書類編集・承認操作の REST API の実行ではリクエストを X-point に送信する場合、ログイン ID による認証を必要とする方法、予め登録されたトークンコードを使用する方法の 2 種類があります。接続に使用する情報は http ヘッダに指定する必要があります。 ヘッダに、認証情報、トークンコードいずれかの指定が無い REST API 実行は必ずエラー応答になります。

注意事項

2.2. APIトークン

API トークンを利用する場合、OAuth2 認証のようにユーザー毎の個別認証を行わずに、トークン情報で REST API を実行することができます。 ユーザーID 毎の認証を行わない為、REST API 実行時には実行ユーザー（誰が申請したか、だれが承認したかなど）を記録するためユーザーコードとドメインコードが必要になります。 トークンコードはデータベースへの追加、更新、削除、閲覧の４種類の対する許可を設定する事ができます。REST API の利用者が許可範囲を超えて操作してしまう事を防止する、REST API を実行するプログラムが漏洩する等した場合に、トークンコードに指定された許可を取り消す事でデータの漏洩・破損を防ぐ事ができます。

2.3. 認証

APIトークンを用いないREST APIの利用にはX-pointに登録されているユーザによる認証が必要になります。認証にはOAuth2認証がを利用します。

2.3.1. OAuth2認証(Authorization)

HTTPヘッダAuthorizationに指定されたアクセストークン文字列が示すユーザによる操作としてREST APIが動作し、利用が記録されます。

アクセストークンの発行はOAuth2認証フローを利用して発行する方法とX-point管理者サイトから発行する方法の2種類があります。

【ヘッダ設定形式】

Authorization: Bearer *******
【OAuth2認証フローを利用したアクセストークン発行】

X-pointではOAuth2認証フローの認可コードフローを利用してアクセストークンを発行します。

認可コードフローを利用したアクセストークン発行のために必要な手順は下記の通りです。

認可コードフロー図

  1. X-point管理者サイトでクライアントIDを生成

    認可エンドポイントへリクエストを送信する際、リクエストにクライアントIDを指定する必要があります。

    クライアントIDはX-point管理者サイトで生成でき、ドメイン毎に1つのクライアントIDが生成可能です。

    1. X-point管理者サイトのドメイン管理画面を表示し、認証情報リンクを押下します。

      ドメイン管理画面

    2. 認証情報画面で＋クライアントIDを生成するリンクを押下してクライアントIDを生成します。

      認証情報画面

  2. 認可エンドポイントへリクエストを送信

    認可コードの発行に必要なパラメータをリクエストに指定し、認可エンドポイントへリクエストを送信します。

    リクエストを送信すると認証ページへのリダイレクトが行われ、認証を行うことで認可コードが発行されます。

    認証はパスワード認証、GoogleWorkspace連携による認証、SAML認証のいずれかの方式で可能です。

    • URI

       GET https://{サブドメイン}.atledcloud.jp/xpoint/a/v1/oauth2/auth/{ドメインコード}
      • X-point Cloudに登録されているドメインが1つである場合に限り、ドメインコードの指定を省略することが可能です。ドメインが1つのみであるかは、X-point情報取得APIの応答内容で判断できます。

    • クエリパラメータ

      パラメータ名 型 省略可 説明
      response_type 文字列 - codeを指定します。
      client_id 文字列 - X-point Cloudのドメイン毎に生成したクライアントIDを指定します。クライアントIDの生成方法については本章の1．X-point管理者サイトでクライアントIDを生成を確認してください。
      redirect_uri 文字列 - URLエスケープを行った認証完了後のリダイレクトURIを指定します。
      scope 文字列 ◯ スコープ(未使用)
      state 文字列 ◯ ステート(未使用)
      code_challenge_method 文字列 - code_challengeの暗号化方式(PKCE対応)を指定します。S256(SHA-256で暗号化)、plain(暗号化無し)のいずれかが指定可能です。
      code_challenge 文字列 - 暗号化文字列(PKCE対応)を指定します。 code_challenge_methodにS256を指定した場合は、code_verifierをSHA-256で暗号化しBase64URL形式にエンコードした値を設定します。code_challenge_methodにplainを指定した場合はcode_verifierの値を指定します。

      注意事項

      • code_verifierは半角英数字及び記号(- . _ ~)からなる43文字～128文字のランダムな文字列です。クライアント側でcode_verifierを生成する必要があります。
      • code_challengeはSHA-256で暗号化後、クエリパラメータとして利用できるようにBase64形式の文字列から以下の文字の削除及び置換を行う必要があります。
        • パディング(文字詰めの=)の削除
        • +を-に置換

        • /を_に置換

          例

          Base64形式 code_challenge用に削除・置換
          FJOESijewgaio9+32jffof90uiof/j32hideowjfi== FJOESijewgaio9-32jffof90uiof_j32hideowjfi

    • 応答内容

      X-point未認証の場合は認証ページが表示され、認証後にクエリパラメータに指定したリダイレクト先に遷移します。

      認証済みの場合は認証ページは表示されず、クエリパラメータに指定したリダイレクト先に遷移します。

  3. ユーザ認証

    認可エンドポイントへリクエストを送信すると下図のように認証ページに遷移します。

    ユーザID、パスワードを入力してログインすると、認可エンドポイントへのリクエスト時に指定したリダイレクトURIのページに遷移します。

    GoogleWorkspace連携、もしくはSAML認証サービスを利用する設定を行っている場合、未認証であれば連携先の認証ページに、認証済みであればリダイレクトURIに指定したページに遷移します。

    上記以外の連携を設定している場合は認証済みかどうかを問わず認証ページに遷移しますので、ユーザID、パスワードを入力してログインしてください。

    • X-point認証ページ

      X-point認証ページ

    • 連携先認証ページ例

      連携先認証ページ例

  4. 認可コードの取得

    認証が完了しリダイレクトURIに指定したページへ遷移すると、遷移先URLのクエリパラメータから認可エンドポイントで発行された認可コードが取得できます。

    認可コードはトークンエンドポイントへリクエスト送信する際に指定します。

  5. トークンエンドポイントへリクエストを送信

    アクセストークンの発行に必要な認可コード等をリクエストに指定し、トークンエンドポイントへリクエストを送信します。

    リクエストを送信するとアクセストークン、リフレッシュトークンが発行され、JSON形式で応答が返されます。

    また、アクセストークンの有効期限が切れた場合にリフレッシュトークンを使ってアクセストークンを再発行することが可能です。

    • URI

       POST https://{サブドメイン}.atledcloud.jp/xpoint/a/v1/oauth2/token

    • リクエストヘッダ

       Content-Type: application/x-www-form-urlencoded

    • リクエスト内容

      パラメータ名 型 省略可 説明
      grant_type 文字列 - 認証種別を指定します。authorization_code(認可フロー)、refresh_token(アクセストークン再発行)のいずれかが指定可能です。
      code 文字列 △ 認可コードを指定します。grant_typeにauthorization_codeを指定した場合は必須です。
      refresh_token 文字列 △ リフレッシュトークンを指定します。grant_typeにrefresh_tokenを指定した場合は必須です。
      scope 文字列 ◯ スコープ(未使用)
      redirect_uri 文字列 △ 認可エンドポイントで指定したリダイレクトURIを指定します。grant_typeにauthorization_codeを指定した場合は必須です。
      client_id 文字列 - X-point Cloudのドメイン毎に生成したクライアントIDを指定します。クライアントIDの生成方法については本章の1．X-point管理者サイトでクライアントIDを生成を確認してください。
      code_verifier 文字列 △ 検証文字列(認可エンドポイントでクエリパラメータに指定したcode_challengeの暗号化前文字列)を指定します。grant_typeにauthorization_codeを指定した場合は必須です。

      注意事項

      • 認可コードの有効期間は発行してから10分間です。有効期間外の認可コードでリクエストを行うとエラーが返されます。

    • 応答ヘッダ

       Content-Type: application/json

    • 応答内容

      パラメータ名 型 NULL 説明
      access_token 文字列 No 発行されたアクセストークンです。
      token_type 文字列 No トークン種別bearerが返されます。
      expires_in 長整数 No アクセストークンの有効期限(秒)です。アクセストークンは3600秒(1時間)有効です。
      refresh_token 文字列 No 発行されたリフレッシュトークンです。

      • 応答例

         {
    "access_token": "XXXXXXXXXXXX",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "XXXXXXXXXXXX"
 }

      注意事項

      • リフレッシュトークンの有効期間は発行してから180日間です。有効期間外のリフレッシュトークンでリクエストを行うとエラーが返されます。
      • リフレッシュトークンでアクセストークンの再発行を行うと使用したリフレッシュトークンは無効化されます。次回のアクセストークン再発行には、再発行時に新しく発行されたリフレッシュトークンを使用してください。
【X-point管理者サイトからアクセストークン発行】

X-point管理者サイトのドメイン管理>認証情報からアクセストークンを発行します。

認証情報から発行したアクセストークンは長期間の有効期限が設定されており、有効期限が切れることはありません。

  1. X-point管理者サイトのドメイン管理画面を表示し、認証情報リンクを押下します。

    ドメイン管理画面

  2. 認証情報画面で＋アクセストークンを生成するリンクを押下します。

    認証情報画面

  3. アクセストークンの発行対象ユーザ選択画面が表示されるので、対象ユーザを選択して作成ボタンを押下します。

    アクセストークン発行

2.3.2. 困ったときは

2.4. REST API一覧

API種別 API 認証方法
書類編集・承認操作API 書類作成API、添付ファイル追加API等 APIトークン及びアクセストークンによる認証が可能
システムAPI フォーム定義情報取得API、マスタデータ取得API等 アクセストークンによる認証のみ可能
ユーザー別API 利用可能フォーム一覧取得API、書類検索API等 アクセストークンによる認証のみ可能
SCIM API ユーザ情報取得API、ユーザグループ情報作成API等 アクセストークンによる認証のみ可能
その他API X-point情報取得API 認証情報無しで利用可能

利用可能なAPIの詳細についてはOpenAPI仕様に基づき記述されたOpenAPIドキュメントをご参照ください。

OpenAPIドキュメントには各APIのエンドポイントやリクエスト、レスポンス形式が定義されています。

2.5. リクエストヘッダ

送信するリクエストに指定するリクエストヘッダです。

2.6. リクエストURI

2.6.1. 書類編集・承認操作API

書類編集・承認操作APIのリクエストの送信は3つの基本パターンがあります。

2.6.2. システムAPI／ユーザ別API

システムAPI、ユーザ別APIのリクエストの送信は2つの基本パターンがあります。

2.6.3. SCIM API

SCIM APIのリクエストの送信は2つの基本パターンがあります。

注意事項

2.7 リクエストボディ・レスポンスボディ

リクエストボディ、レスポンスボディの文字コードはそれぞれUTF-8に対応しています。

UTF-8以外の文字コードでリクエストボディを送信した場合、APIで作成した書類が文字化けしますのでご注意ください。

2.8. エラー応答

2.8.1. エラーの種類例

  1. 認証エラー

    HTTPヘッダに指定された認証情報にて認証エラーとなった場合は401 Unauthorizedとしてエラーレスポンスを返します。

  2. APIトークンチェック

    APIトークン未設定の場合は400 BadRequestとしてエラーレスポンスを返します。

    適切な操作権限が付与されていないAPIトークンを指定していた場合は403 Forbiddenとしてエラーレスポンスを返します。

  3. パスパラメータチェック

    パスパラメータに指定された値が不正な場合は400 BadRequestとしてエラーレスポンスを返します。

    ※パスパラメータの期待値が数値であることに対して文字列が指定された 等

  4. パラメータチェック

    以下のチェックでエラーとなった場合に400 BadRequestとしてエラーレスポンスを返します。

    • 必須チェック
    • 範囲チェック
    • 桁数チェック

  5. 書類情報チェック

    書類情報の取得に失敗した場合やその他のエラーが発生した場合は500 InternalServerErrorとしてエラーレスポンスを返します。

2.8.2. レスポンスヘッダ

HTTPステータスコードはレスポンスボディのerror_codeと同じコードが設定されます。

X-point側の処理の結果、エラーとなった場合の応答は全てJSON形式で応答が戻ります。

application/jsonまたはapplication/scim+json以外の応答が戻る場合は、X-point以外の処理で問題が生じていることを示しており、通常のHTTPレスポンスエラーとして取り扱ってください。

API ヘッダ名 設定値
SCIM API以外 Content-Type application/json
SCIM API Content-Type application/scim+json

2.8.3. レスポンスボディ

【SCIM API以外の場合】

項目名 型 NULL 内容 説明
error_code 数値 No エラーコード 後述のエラーコード一覧を参照
error_message 文字列 Yes エラーメッセージ  
reasons 文字列配列 Yes エラー理由 エラーの詳細が文字列の配列形式で返される。reasonsが返されるのは書類作成API、書類のワークフロー操作・編集・更新APIでエラーとなった場合のみ。

【SCIM APIの場合】

項目名 型 NULL 内容 説明
schema 配列 No スキーマ  
scimType 文字列 Yes エラー内容  
detail 文字列 No エラー詳細  
status 文字列 No エラーコード 後述のエラーコード一覧を参照

【エラーコード一覧】

エラーコード 名称 説明
400 BadRequest 構文が無効であるためサーバーがリクエストを理解できないことを示します。
401 Unauthorized 接続が認証されていない(許可されていない)状態です。利用のためには認証が必要です。
403 Forbidden アクセス権が無い。
404 NotFound リクエストされたリソースが無い。
405 MethodNotAllowed ユーザエージェントから与えられた条件に合うコンテンツが見つからない。
500 InternalServerError サーバー内部エラー。
503 ServerUnavailable X-point Cloudが起動中の場合、サーバーがリクエストを処理できない状態。

2.9. 絞り込み条件・並び替え・日付範囲指定

一部のAPIはリクエストに絞り込み条件、並び替え、日付範囲を指定する事が可能です。

2.9.1. 絞り込み条件

パラメータkeywordに絞り込み対象項目、演算子、値を指定する事で条件に一致する情報が取得できます。

2.9.2. 並び替え

パラメータorderに並び替え対象項目を指定する事で指定した項目の並び順で情報が取得できます。

2.9.3. 日付範囲

パラメータfilterに日付範囲条件を指定する事で指定した範囲に合致する情報を取得できます。

2.10. REST APIアクセスログ

REST APIをリクエストするとアクセスログとしてリクエストした情報を記録します。

記録されたアクセスログはX-point管理者サイトで検索・ダウンロードすることが可能です。

詳細は管理者機能マニュアルの4.5. REST APIアクセスログを参照してください。

2.11 自動申請設定の登録

フォーム毎に生成可能なAPIトークンを利用してREST APIをリクエストする場合や、書類作成・書類操作を行うREST APIで自動申請設定を使用する場合は事前に自動申請設定の登録が必要になります。

補足

以下のような場合は自動申請設定を登録する必要はありません。

【REST API用自動申請設定の登録手順】

  1. 管理者サイト＞フォーム管理＞自動申請に遷移し、+作成リンクを押下します。

  2. フォーム情報の各項目を入力して次へボタンを押下します。

    項目名 説明
    自動申請名称 任意の名称を入力します。
    フォーム名（フォームコード） REST APIで使用するフォームを選択します。
    申請ルート（ルートコード） REST APIで使用する承認ルートを選択します。
    取り込みを行うファイル REST APIでのみ使用する場合は、他自動申請設定と重複しない名称を入力します。
    申請後の取込ファイルの処理 REST APIでのみ使用する場合は成功時、失敗時どちらも何もしないを選択します。
    取り込みファイル一行目の処理 REST APIで使用する場合は項目行として無視するを選択します。
    申請書類の切換え判定項目 REST APIで使用する場合は先頭列を書類切換えに利用を選択します。先頭行文字、継続行文字はデフォルトのままにします。
    備考 任意の情報を入力します。

    自動申請設定登録_フォーム情報

  3. CSVフォーマットを設定して次へボタンを押下します。

    書類作成・書類操作を行うREST APIで自動申請設定を使用する時に、この画面でCSVフォーマットに設定したフィールドをリクエストボディに指定します。

  4. 申請ユーザタイプ、キーを指定して次へボタンを押下する。

    • 申請ユーザタイプ

      REST APIで書類の申請を行う場合、リクエストヘッダに指定したアクセストークンやトークン情報に紐づくユーザで申請が行われます。 登録中の自動申請設定がREST APIでのみ使用するものであれば、指定するユーザは任意のユーザで構いません。

    • キー

      CSVフォーマットに表定義を設定した場合はキーを選択します。 REST APIはリクエストボディに指定された書類データで書類の申請が行われます。登録中の自動申請設定がREST APIでのみ使用するものであれば、選択するキーは任意のフィールドで構いません。

  5. 設定内容を確認して完了ボタンを押下する。

2.12. 制限事項

3. 個別仕様

3.1. 書類作成API／書類のワークフロー操作・編集・更新API