ZUNDA LCM 管理ポータル 外部連携API リファレンス
ZUNDA LCM (デバイスLCM) / サービス概要・管理ポータル
松田 悠 更新
本ページでは、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トークンが必要です。以下の手順で発行してください。 ZUNDA LCMにログインし、画面右上のユーザー名をクリックします。表示されたメニューから「APIトークン」を選択します。「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,id4.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内容400BAD_REQUESTパラメータの形式が不正です400OUT_OF_RANGE指定したページが範囲外です401UNAUTHORIZEDAPIトークンが未指定、無効、失効済み、期限切れ、または組織が無効化されています401API_TOKEN_REISSUE_REQUIREDアカウント情報の変更により、トークンの再発行が必要です403FORBIDDEN権限の条件を満たしていません404NOT_FOUND対象のリソースが存在しない、または公開対象外のエンドポイントです422VALIDATION_ERRORバリデーションエラーです503BACKEND_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シリアル番号・デバイス管理番号・社内管理番号・案件明細番号を検索対象とします（オペレーター権限のトークンでは案件明細番号は検索対象になりません）sortserial_number / created_at / status / id。既定値は -created_atレスポンス項目（抜粋）項目内容sku_nameSKU名sku_codeSKUの商品コード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から継承されたスペック値、個体で上書きした値、継承元の値デバイス状態コードとラベルの対応statusstatus_labelA新品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_completedtrue の場合、完了済みの割当も含めます。未指定の場合はアクティブな割当のみが対象ですq利用者名・デバイスのシリアル番号・社内管理番号・デバイス管理番号を検索対象としますsortoutbound_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レスポンス項目は一覧取得と同じです。