Developers

共通仕様

API を利用する際の共通仕様は以下のとおりです。

プロトコル

HTTPS

メディアタイプ

application/json

文字コード

UTF-8

日付・日時

以下の形式をサポートします。

タイプ形式説明
日付yyyy/mm/dd・「yyyy」は西暦4桁、「mm」は月2桁、「dd」は日2桁を表します。
・2025年1月1日は次のように表します。例)「2025/01/01」
・指定桁に満たない場合は0を補完します。例) 「2025/1/1」 -> 「2025/01/01」
・月日を省略した場合は01で補完します。例) 「2025」 -> 「2025/01/01」
「2025/01」 -> 「2025/01/01」
日時yyyy/mm/dd hh:MM
または
yyyy/mm/dd hh:MM:ss		・「hh」は時2桁、「MM」は分2桁、「ss」は秒2桁を表します。
・2025年1月1日1時1分1秒は次のように表せます。例）「2025/01/01 01:01:01」

認証

esm APIではBearer認証形式をサポートします。  HTTPヘッダーに「Authorization」を追加し、"Bearer" とAPIトークンもしくはアクセストークンを半角スペースで結合した値を設定します。

Info

APIトークンはこちらから発行することが可能です。
アクセストークンはこちらから発行することが可能です。

Authorization: Bearer ey....

ヘッダー

Request

No.フィールド必須説明
1Authorization○APIトークン(Bearer) or アクセストークン(Bearer)
2X-ESM-TIMEZONE○タイムゾーンに関しての説明はこちら

Response

サーバから共通して返されるレスポンスヘッダは特にありません。

リソース

esm APIで扱うリソースについて説明します。

sheet

  • businesscard(名刺)
  • customer(顧客)
  • businessplan(案件)
  • activity(活動)
  • employee(社員)
  • product(商品)
  • deal(取引商品)
  • task(タスク)
  • milestone(マイルストーン)
  • department(部署)
  • commongroup(共通グループ)
  • mygroup(マイグループ)
  • appextender(拡張アプリ)

schedule

  • schedule(スケジュール)

ロール（権限）

各アプリに対してCRUDを行うには、それぞれに対応したロール(権限)を付与されたユーザーである必要があります。

ロールの確認、編集はシステム設定>ロール設定にて行います。 拡張アプリのロールの確認、編集はシステム設定>アプリ設定>アプリ変更にて行います。

エラーレスポンス

リソース要求が正常終了でない場合、ステータスコードとともに、以下のエラー応答情報を受け取ります。

[
  {
    "message": "エラー原因の詳細"
  }
]

ドキュメント管理基盤(cms)

ファイルを扱う際、cmsに事前にアップロードする必要があります。 また、cmsにアップロードしたファイルをダウンロード、検索することもできます。

アップロード

cmsへファイルをアップロードします。

Request

URL
https://gateway-esm.softbrain.co.jp/cms/file/content
HTTP Method
POST
Parameter
Request Body
No.パラメータ必須タイプ説明
1file○fileアップロードするファイル

Response

{
  "fileId": "fc6472711a1742b99a6e4ea9288dc33a",
  "s3Key": "cms/{tenant}/fc6472711a1742b99a6e4ea9288dc33a/dummy-images-945x545.jpg",
  "fileName": "dummy-images-945x545.jpg",
  "fileSize": 23190,
  "regDate": "2024-12-24 13:47",
  "updDate": "2024-12-24 13:47",
  "fileVersions": [
    {
      "versionId": 1,
      "fileSize": 23190,
      "regDate": "2024-12-24 13:47"
    }
  ]
}

FILE型項目の登録/更新時の推奨手順

cmsへのアップロードのレスポンスにてアップロードしたファイルのfileIdが取得できるので、そのままFILE型項目のパラメータとして使用することを推奨します。
※ファイル検索APIで改めてfileIdを取得することは可能です。

ダウンロード

cmsへアップロード済みのファイルをダウンロードします。

Request

URL
https://gateway-esm.softbrain.co.jp/cms/fileSummary/content/{fileId}
HTTP Method
GET
Parameter
Path Parameter
No.パラメータ必須タイプ説明
1fileId○stringダウンロードするファイル名

Response

ファイルのバイナリデータが返却されます。

ファイル検索

Request

URL
https://gateway-esm.softbrain.co.jp/cms/file/search
HTTP Method
POST
Parameter
Request Body
No.パラメータ必須タイプ説明
1fileName○stringファイル名
Example
{
    "fileName": "ダウンロード"
}

Response

fileNameに対して、部分一致で検索されます。

Example
{
    "result": [
        {
            "fileId": "73e1c63f6bf2482d8d3f56dfcf035a38",
            "s3Key": "cms/softbrain030/73e1c63f6bf2482d8d3f56dfcf035a38/ダウンロード.jpg",
            "fileName": "ダウンロード.jpg",
            "fileSize": 2820,
            "regDate": "2025-01-24 10:38",
            "updDate": "2025-01-24 10:38",
            "fileVersions": [
                {
                    "versionId": 1,
                    "fileSize": 2820,
                    "regDate": "2025-01-24 10:38"
                }
            ]
        }
    ],
    "count": 1,
    "total": 1
}

リクエスト制限

esm APIには、プランごとに1時間あたりのリクエスト数上限と同時アクセス数上限が設定されています。
プランごとの制限値は下記表を参考にしてください。

プラン1時間あたりのリクエスト数上限同時アクセス数上限
esm appli1,0003
Basic1,0003
Enterprise10,0005