メインコンテンツへスキップ
ZUNDA株式会社
ご契約者様向けサポート（新しいタブで開きます）

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は、以下のパラメータでページングを行います。
パラメータ
内容
page[limit]
取得件数。既定値は20。指定可能な値は 20 / 50 / 100（範囲外の値を指定した場合はエラーにならず既定値が適用されます）
page[after]
次のページを取得するためのカーソル
page[before]
前のページを取得するためのカーソル

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 主なエラーコード

HTTPステータス
code
内容
400
BAD_REQUEST
パラメータの形式が不正です
400
OUT_OF_RANGE
指定したページが範囲外です
401
UNAUTHORIZED
APIトークンが未指定、無効、失効済み、期限切れ、または組織が無効化されています
401
API_TOKEN_REISSUE_REQUIRED
アカウント情報の変更により、トークンの再発行が必要です
403
FORBIDDEN
権限の条件を満たしていません
404
NOT_FOUND
対象のリソースが存在しない、または公開対象外のエンドポイントです
422
VALIDATION_ERROR
バリデーションエラーです
503
BACKEND_UNAVAILABLE
サーバー内部でエラーが発生しました。時間をおいて再度お試しください

6. エンドポイント詳細

6.1 デバイス一覧の取得

GET /api/v1/devices

クエリパラメータ

パラメータ
内容
filter[sku_id]
SKU IDの完全一致
filter[product_id]
商品IDの完全一致（デバイスに直接指定された商品、またはSKUに紐づく商品が対象）
filter[organization_id]
所有組織または管理組織のいずれかに一致
filter[owner_organization_id]
所有組織IDの完全一致
filter[managing_organization_id]
管理組織IDの完全一致
filter[status]
デバイス状態コードの完全一致（下記「デバイス状態コード」参照）
filter[warehouse_location]
倉庫名の部分一致（オペレーター権限のトークンでは利用できません）
filter[rentable]
true / false（オペレーター権限のトークンでは利用できません）
filter[include_discarded]
true の場合、削除済みのデバイスも含めます（filter[include_deleted] でも同様に指定できます）
filter[settable_category_ids]
セット可能なカテゴリでの絞り込み
filter[exclude_set_child]
true の場合、セット子デバイスを除外
filter[set_parent_device_id]
指定した親デバイスと組み合わせ可能な候補に絞り込み
filter[exclude_assigned]
true の場合、割当中のデバイスを除外
filter[exclude_id]
指定したデバイスIDを除外
q
シリアル番号・デバイス管理番号・社内管理番号・案件明細番号を検索対象とします（オペレーター権限のトークンでは案件明細番号は検索対象になりません）
sort
serial_number / created_at / status / id。既定値は -created_at

レスポンス項目（抜粋）

項目
内容
sku_name
SKU名
sku_code
SKUの商品コード
product_id / product_name
商品ID・商品名
category_id / category_name
カテゴリID・カテゴリ名
owner_organization_name
所有組織の表示名
managing_organization_name
管理組織の表示名
assignment_destination
現在の割当先の表示
status
デバイス状態コード
status_label
デバイス状態のラベル
set_parent_device_id ほか set_parent_*
セット親デバイスの情報（ID・シリアル番号・管理番号・SKUコード・商品名）
discarded
削除済みかどうか
deletable
削除可能かどうか
spec_* / spec_*_override / spec_*_placeholder
商品・SKUから継承されたスペック値、個体で上書きした値、継承元の値

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

status
status_label
A
新品
B
綺麗な中古品（電源ケーブルあり）
C
綺麗な中古品（電源ケーブルなし）
D
使用感のある中古品（電源ケーブルあり）
E
使用感のある中古品（電源ケーブルなし）
F
不具合・故障あり
X
起動不可（大きな損傷・不具合）

リクエスト例

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
一覧取得のレスポンス項目に加えて、以下が含まれます。
項目
内容
assignments_count
紐づく割当の件数
set_child_devices
セット子デバイスの配列（各要素に device_id, device_management_number, serial_number, product_name, sku_name, sku_code を含む）

6.3 割当一覧の取得

GET /api/v1/assignments

クエリパラメータ

パラメータ
内容
filter[device_id]
デバイスIDの完全一致
filter[customer_organization_id]
顧客組織IDの完全一致（filter[organization_id] でも同様に指定できます）
filter[status]
割当ステータスの完全一致（下記「割当ステータス」参照）
include_completed
true の場合、完了済みの割当も含めます。未指定の場合はアクティブな割当のみが対象です
q
利用者名・デバイスのシリアル番号・社内管理番号・デバイス管理番号を検索対象とします
sort
outbound_date / returned_at / created_at / id。既定値は -created_at

レスポンス項目（抜粋）

項目
内容
device_management_number
デバイス管理番号
device_serial_number
デバイスシリアル番号
device_internal_management_number
デバイス社内管理番号
device_product_name
デバイス商品名
device_product_category_name
デバイス商品カテゴリ名
device_sku_name
デバイスSKU名
device_memos
閲覧可能なデバイスメモのうち、新しい順で最大5件（各要素に id, body, created_at, organization_id, organization_name, user_id, user_name, source, deletable を含む）
customer_organization_name
顧客組織の表示名
set_parent_device_id ほか set_parent_*
セット親デバイスの情報（ID・シリアル番号・管理番号・SKUコード・商品名）

割当ステータス

値
準備中
出荷キャンセル
出荷済
利用終了

割当種別

値
出荷時に割当
割当のみ実施

リクエスト例

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
レスポンス項目は一覧取得と同じです。