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時間当たり最大10,000件のリクエストが可能です。
また、同時に処理できるリクエスト数は最大10件までとなります。