ZUNDA LCM 管理ポータル 外部連携API リファレンス

本ページでは、ZUNDA LCM管理ポータルを外部システムと連携する際に利用できる公開APIの仕様を説明します。

1. 概要

• Base URL: https://lcm.zunda.co.jp/api/v1
• データ形式: JSON
• 文字コード: UTF-8
• 公開メソッド: GET のみ

公開しているリソースは以下の4つです。データの作成・更新・削除はできません（参照専用のAPIです）。

• GET /api/v1/devices — デバイス一覧の取得
• GET /api/v1/devices/:id — デバイス詳細の取得
• GET /api/v1/assignments — 割当一覧の取得
• GET /api/v1/assignments/:id — 割当詳細の取得

2. 認証

2.1 APIトークンの発行

外部連携APIをご利用いただくには、専用のAPIトークンが必要です。以下の手順で発行してください。

1.  ZUNDA LCMにログインし、画面右上のユーザー名をクリックします。

   

2. 表示されたメニューから「APIトークン」を選択します。
   
3. 「APIトークン」画面が開きます。未発行の場合は「発行」ボタンからトークンを発行してください。発行済みの場合は状態・権限・発行日時・有効期限などが表示されます。
   

2.2 リクエスト方法

発行したトークンは、各リクエストのヘッダーに指定してください。通常の画面ログインで使われる認証方式とは異なりますのでご注意ください。

Accept: application/json
X-ZUNDA-LCM-Api-Token: kmp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

トークンは kmp_ から始まる文字列です。

2.3 トークンが無効になるケース

以下に該当する場合、トークンは無効として扱われ、リクエストはエラーになります。

• トークンが失効（revoke）されている
• 有効期限が切れている
• トークン発行者のアカウントが削除されている
• トークン発行者の所属組織が無効化されている
• トークン発行後に、発行者の所属組織・権限（ロール）・組織の有効状態が変更されている

特に最後のケースでは、専用のエラーコード（API_TOKEN_REISSUE_REQUIRED）が返却されます。このエラーを受け取った場合は、トークンの再発行が必要です。

3. 取得可能なデータの範囲

APIから取得できるデータの範囲は、トークンを発行したユーザーがWebUIから確認できる範囲と同一です。他の企業の保有デバイスやZUNDAからの貸し出しが終了したデバイスの情報は取得できません。

取得できない対象を指定した場合、403 FORBIDDEN または 404 NOT_FOUND が返却されます。

4. 共通のリクエスト仕様

4.1 ページネーション

一覧取得APIは、以下のパラメータでページングを行います。

4.2 ソート

sort パラメータで並び順を指定できます。カンマ区切りで複数指定可能で、先頭に - を付けると降順になります。指定可能なカラムはエンドポイントごとに異なります（各エンドポイントの説明を参照してください）。

sort=-created_at,id

4.3 フィルタ

filter[カラム名]=値 の形式で絞り込みができます。完全一致のフィルタは、カンマ区切りで複数の値を指定できます（OR条件）。

filter[status]=準備中,出荷済

4.4 フリーテキスト検索

q パラメータにキーワードを指定すると、対象項目に対する部分一致検索ができます。検索対象カラムはエンドポイントごとに異なりますが、該当する項目のWebページの「検索」フィルターと同じ挙動をします。全角・半角の表記ゆれは自動で吸収されます。

5. 共通のレスポンス仕様

5.1 成功時

一覧取得APIは、data に配列、meta.pagination にページング情報を返します。

{
  "data": [],
  "meta": {
    "pagination": {
      "limit": 20,
      "total": null,
      "before": null,
      "after": "opaque-cursor"
    }
  }
}

詳細取得APIは、data にオブジェクトを返します。

{
  "data": {
    "id": 1
  }
}

5.2 エラー時

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "APIトークンが無効です。"
  }
}

5.3 主なエラーコード

6. エンドポイント詳細

6.1 デバイス一覧の取得

GET /api/v1/devices

クエリパラメータ

レスポンス項目（抜粋）

デバイス状態コードとラベルの対応

リクエスト例

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-ZUNDA-LCM-Api-Token: kmp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  'https://example.com/api/v1/devices?filter[status]=A&page[limit]=20'

6.2 デバイス詳細の取得

GET /api/v1/devices/:id

一覧取得のレスポンス項目に加えて、以下が含まれます。

6.3 割当一覧の取得

GET /api/v1/assignments

クエリパラメータ

レスポンス項目（抜粋）

割当ステータス

割当種別

リクエスト例

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-ZUNDA-LCM-Api-Token: kmp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  'https://lcm.zunda.co.jp/api/v1/assignments?filter[status]=出荷済&include_completed=true'

6.4 割当詳細の取得

GET /api/v1/assignments/:id

レスポンス項目は一覧取得と同じです。