スマートエクステリアAPI for Business

スマートエクステリアAPI for Business Edit

スマートエクステリアAPI for Business(以降、本API)は、スマートエクステリアで提供しているデバイスの情報を外部アプリケーションから利用できるAPIです。
スマートエクステリアの詳細については、こちらをご確認ください。
本APIは、HTTPクライアントがAPIのエンドポイントへHTTPSリクエストを行うことで利用できます。レスポンスはJSON形式です。

注釈は下記の意味を示します。

補足事項

警告事項

注意事項

クラウドサービス Edit

スマートエクステリアクラウドサービス（以降、クラウドサービス）は、IoT機能を持つ住宅設備機器にクラウドを使って連携するサービスです。クラウドサービスの設定が完了したデバイスは、あずけるBOXメンバーズサイトを通して操作することができます。 クラウドサービスの詳細については、こちらをご確認ください。

あずけるBOXメンバーズサイトは、デバイスを利用するためのWebアプリケーションです。

本APIと連携するデバイスは、クラウドサービスの設定が完了している必要があります。
設定はユーザーが実施する必要があり、設定が完了していない場合は情報が取得できません。

クラウドサービスの設定状況は、ユーザーのデバイス一覧を取得のstatusの項目で確認してください。

ゲートウェイ Edit

本APIで操作するデバイスはゲートウェイを経由してクラウドと通信します。
提供しているゲートウェイを以下に記します。

Hub

ホームユニット(以降、Hub)は、スマートエクステリアのホームネットワークシステムの全ての機器を制御する機器です。Hubの詳細については、こちらをご確認ください。

Hubはクラウドと接続できる状態である必要があります。
接続できない場合、情報を取得できない、もしくは古い情報を取得してしまいます。

Hubとクラウド間の接続状況は、ユーザーのデバイス一覧を取得のstatusの項目で確認してください。

対応機器 Edit

本APIで利用できる機器に関する情報を記します。

宅配ボックス

宅配ボックスは家にいる時も、いない時も荷物の受け取りに加え、発送もできます。
本APIを利用することで、貴社のユーザーの荷物を宅配ボックスへ配達、集荷することができます。
宅配ボックスの詳細については、こちらをご確認ください。

宅配ボックスとHubは初期設定が完了している必要があります。
設定はユーザーが実施する必要があり、設定が完了していない場合は情報が取得できません。

API概要 Edit

前提

本APIは、サーバー間で連携することを前提としています。

ブラウザから直接実行しないようにしてください。

出来ること

貴社のシステムと本APIを連携し、貴社のユーザーの荷物を宅配ボックス宛に「配達」「集荷」することが出来ます。

配達の流れ

貴社のシステムが本APIと連携し、宅配ボックスを開けるための解錠番号を取得し、配達を行います。

配達の流れを下記に示します。

集荷の流れ

貴社のシステムが本APIと連携し、宅配ボックスを開けるための解錠番号を取得し、集荷を行います。

集荷の流れを下記に示します。

その他

MyLIXILを退会したユーザーは本APIを利用できません。 そのため、認証済のユーザーでもエラーが発生する可能性があります。

不明点がありましたら、お手数ですが弊社までお問い合わせください。

API環境 Edit

本APIでは、下記2種類のAPI環境を提供します。
貴社の開発フェーズに適した環境をご利用ください。
下記にそれぞれの環境について記述します。

APIのエンドポイントについては、弊社担当者よりご確認ください。

どちらのAPIも定義は同一であり、こちらに記載した通りです。

開発・検証環境

開発・検証用の「Hub」や「宅配ボックス」、「仮想データ」にアクセスするためのAPIです。
貴社専用のデバイスやデータになりますので、開発・検証の用途にご利用いただけます。

「Hub」、「宅配ボックス」、「仮想データ」については弊社担当者よりご確認ください

本番環境

ユーザーのデータにアクセスするためのAPIです。
貴社アプリケーションの本番環境でのみご利用ください。

認証 Edit

本APIを利用するためには、MyLIXILユーザーのアクセストークンを発行する必要があります。

手順

アクセストークンの発行は、以下の手順で実施します。

1. ユーザーはOAuth 2.0のAuthorization Code GrantフローでMyLIXILにログインします。
2. ログインに成功すると指定した redirect_url にリダイレクトします。
3. クエリパラメータの code を用いて、トークンを発行します。
4. 発行されたトークンを保存します。
5. APIのリクエストを行う際に、保存したアクセストークンを利用します。

実装方法

OAuth 2.0のAuthorization Code GrantフローでMyLIXILログインを実装します。

/{customerId}/login/authorize

このエンドポイントは、認証エンドポイントから認証コードを要求するために使用します。このリクエストが成功すると、クライアントに認証コードが与えられます。次に、そのコードをトークンエンドポイントに提示し、アクセストークン、リフレッシュトークン、およびIDトークンと交換できます。

承認リクエストが受け入れられると、ユーザーにはサインイン画面が表示され、サイトまたはアプリにログインするように求められます。認証が成功すると、アクセストークン、リフレッシュトークン、およびIDトークンが取得でき、ユーザーは認証リクエストで指定したURLにリダイレクトされます。

customerIdはあらかじめMyLIXILが発行します。

リクエスト

リクエストは次のようになります。

https://accounts.lixil.co.jp/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?client_id=9e7f2429-496d-4437-b516-048472613cf9&redirect_uri=https://example.com/callback&scope=openid email phone&code_challenge=y63Qmobx6ZCSYCZqPNzQ6Qx1rGK0reaxgbb5WSAQR0o&code_challenge_method=S256&response_type=code&state=tbXZO4Fkxy90JvJx0s2sbt-

リクエストで使用できる追加のパラメーターを、以下の表に要約します。

client_idはあらかじめMyLIXILが発行します。

レスポンス

このエンドポイントへのリクエストが成功すると、エンドポイントは次のようなレスポンスを返します。

https://example.com/callback?state=tbXZO4Fkxy90JvJx0s2sbt-&code=K2MzvxY8nIRhNQYe

/{customerId}/login/token

アクセストークン、リフレッシュトークン、およびIDトークンを発行します。

リクエスト

アクセストークンとリフレッシュトークンを発行します。

アクセストークンの有効期限は1時間、リフレッシュトークンの有効期限は90日です。アクセストークンの有効期限が切れた場合、リフレッシュトークンを用いてトークンの更新リクエストを行います。

リクエストは次のようになります。

curl -X POST \
  https://accounts.lixil.co.jp/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=authorization_code' \
    -d 'client_id=9e7f2429-496d-4437-b516-048472613cf9' \
    -d 'redirect_uri=https://example.com/callback' \
    -d 'code=K2MzvxY8nIRhNQYe' \
    -d 'code_verifier=AdleUo9ZVcn0J7HkXOdzeqN6pWrW36K3JgVRwMW8BBQazEPV3kFnHyWIZi2jt9gA'

リクエストで使用できる追加のパラメーターを、以下の表に要約します。

レスポンス

このエンドポイントへのリクエストが成功した場合、エンドポイントはアクセストークン、リフレッシュトークン、およびIDトークンを含むレスポンスを返します。

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vYWNjb3VudHMubGl4aWwuY28uanAvMDI3ZTgyNTQtMjkwMi0zMzQxLTljM2MtNjM3ODQxMDAwMDAwL2xvZ2luL2p3ayIsImtpZCI6ImU0NTA3NTAwYWEwZTIwNzhjNmE2Y2U2NjBiOWJkNGE1MzVmMDkyZDAiLCJ0eXAiOiJKV1QifQ.eyJhY3IiOiJ1cm46YWthbWFpLWljOm5pc3Q6ODAwLTYzLTM6YWFsOjEiLCJhbXIiOlsicHdkIl0sImF1ZCI6WyI4Y2I0OWMwYS1hOTkyLTRmNDMtYjBiYy04Mzg2YjQ4YjExOGIiXSwiYXV0aF90aW1lIjoxNjE4MzYyNzQ2LCJjbGllbnRfaWQiOiI4Y2I0OWMwYS1hOTkyLTRmNDMtYjBiYy04Mzg2YjQ4YjExOGIiLCJleHAiOjE2MTgzNjYzNDcsImdsb2JhbF9zdWIiOiJjYXB0dXJlLXYxOi8vdGstZGV2LmphbnJhaW5jYXB0dXJlLmNvbS9hazU3bmY4Zm16cTd3enhjdjVkeDRqODc0Zi9KUF9VU0VSL2VjZjhhZTBiLWNhZjctNGE5NS05MDQ5LTc3YzBlYzgzMWQ4MiIsImlhdCI6MTYxODM2Mjc0NywiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5saXhpbC5jby5qcC8wMjdlODI1NC0yOTAyLTMzNDEtOWMzYy02Mzc4NDEwMDAwMDAvbG9naW4iLCJqdGkiOiJhMjdhNTNlZC05YjFjLTRmM2ItODI2ZS0yN2QyMTQwY2VlNjMiLCJzY29wZSI6Im9wZW5pZCIsInN1YiI6ImVjZjhhZTBiLWNhZjctNGE5NS05MDQ5LTc3YzBlYzgzMWQ4MiJ9.N-_sNxcPBAWUasM4J-VKMwfeyPyxdp6s8kMJWNnuSiFTc-1KMOmR7EGh59JnoNS1pHFn2bEw_bezgmL0_bxTXkBBgMX2e-qqTSy5spu38odAFyyRyPZNjJHbQMCPtJgooe2zUeSZv56UFQvSWlLUlI76kXs1GkD-GQNNB6DG8rH18MmSPIJ1_6DcC4-KvD7Fu8hiriylzBzbh65bNjtoANvQ3cRVrh8fBaOirFVrDIpBjPkt7E6eqE7bIOtClgUkedKTYVam9NehVbqGgoSE4O_R4aoTEpBsW0OTKSBd1aa114SA8xRtLEKN14aEbEpdzsey-HzQj7LJl6a2lBRgsQ",
  "refresh_token": "iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH_Xk7EzdpGq5GPQcsxCWM2SxdlwU",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "email openid profile",
  "id_token": "kyJhbGciOiJSUzI1NiIsImtpZCI6ImE5NjRhNjE3YTc0YjZjZWNlMDM4NTdkYWExZThlMTQ0ZDExMTMyYTkiLCJ0eXAiOiJKV1QifQ.eyJhdF9oYXNoIjoiV1Y0STlVbjFWSi96Q25iRHVoWndIUSIsImF1ZCYwNC03YjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3MjEzLCJleHAiOjE1NTMwMzA4MzksImdsb2JhbF9zdWIiOiJjYXB0dXJlLXYxOi8vYjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3bm5qZXl6eXJydDJubTVkcmY1bmtuOC91c2VyLzc5OGQ2NTQwLWExYTYtNDFiNS1iZjcxLTg1YjY5NDFkY2E4MCIsImlhdCI6MTU1MzAyNzIzOSwiaXNzIjoiaHR0cHM6Ly9hcGkubXVsdGkuZGV2Lm9yLmphbnJhaW4uY29tLzAwMDAwMDAwLTAwMDAtMzAwYjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI3NDFiNS1iZjcxLTg1YjY5NDFkY2E4MCJ9.TRaDPi2_a0Z2s6MYh3LQEyTU5UkR1el6w_waPFeV2hZgv10pDHu6xVrAZUZwErU0_mSDbe9bJo5I_yuecgXZ_4Q1WNV0Z4zhTJT9ycpNeSwgPQcDGddh8J1ybI0Rg6yM54OOcf6o_shqrQMGiiFirm9GrtPYjI3LTQ2NGYtYmZmNS04M2JhMjI5MzIzYWYiXSwiYXV0aF90aW1lIjoxNTUzMDI319S83qGyLStH5db06iVjFahdNex0w39uQSHlTf7Ay0Acb0JOtMOk7JUC406wT5WT5Jz1qGV2q_ChvxdUCCnd2Vp8lNba3AyznkehABHeISkNYtJ6BKigQ"
}

バージョニング Edit

バージョンはセマンティックバージョニングを採用しています。

バージョンの変更がある場合は事前にAPI利用者へ告知し一定期間後、新しいバージョンをリリースします。リリースした段階で古いバージョンに対するリクエストにはステータスコード 404 を返却します。 各バージョンの有効期限については、下記の表をご確認ください。

現在本番環境へのリリース日は未定です。利用する場合、お手数ですがお問い合わせの程お願い致します。

エラーハンドリング Edit

右記は、リクエストに失敗した際のレスポンスを示します。

ステータスコード Edit

利用前確認資料 Edit

本APIをご利用いただく前にご確認いただきたい内容について記述します。

事前にご連絡いただきたい情報

本APIをご利用いただくに際して、事前にご連絡いただきたい情報について記します。

あずけるBOXメンバーズサイトにおける貴社サービスの表示方法

あずけるBOXメンバーズサイト（以降、メンバーズサイト）は、弊社がユーザー向けに提供している「デバイスを利用するためのWebアプリケーション」です。
ユーザーは、メンバーズサイト上で貴社サービスの利用履歴を確認することができます。
本機能をユーザーに提供するため、下記の情報を事前に弊社担当者までご連絡頂きますようお願いいたします。

• サービスの名前
• サービスのアイコン
• サービスの説明文章
• アプリもしくは説明ページへのリンク

（※画像は実装イメージです）

認証用リダイレクトURI

本APIでは認証フローとしてOAuth 2.0のAuthorization Code Grantフローを採用しています。
このAuthorization Code Grantフローにおける「リダイレクトURL」を下記のように「開発用」、「本番用」それぞれのURLを弊社担当者までご連絡ください。
本内容の詳細については、認証をご確認ください。

開発用：https://localhost:4200/, https://example-stg.smart-ext.io/
本番用：https://example-prd.smart-ext.io/

その他確認事項

その他のご確認いただきたい情報について記します。

デバイスの貸し出し

本APIを利用するサービスの開発のために必要なデバイス（ホームユニット、宅配ボックス）を貸し出しいたします。
デバイスの配送時期や配送場所等について、弊社担当者からご確認させていただきますのでご対応のほどよろしくお願いいたします。
また、配送後に貴社側で設定をしていただく必要がございますので、こちらを参考にご対応のほどよろしくお願いします。

開発・検証用データの提供

ご希望のお客様には開発・検証用のデータをご用意いたします。
必要な場合は弊社担当者までご連絡ください。
開発・検証用データでは利用できる機能に制限があります。公開前に必ずデバイスでの実機検証をお願いいたします。

ユーザーへの公開日時の事前連絡のお願い

メンバーズサイトでは貴社サービスの利用履歴を確認できる機能を提供します。
この機能と貴社サービスのユーザーへの公開状況を統一するため、貴社サービスで本API利用機能を公開する日時、もしくは本API利用機能を終了する日時については、事前に弊社担当者までご連絡頂きますようお願いいたします。

認証用情報の提供について

本APIでの認証時に利用するクライアントIDについては、「開発・検証用」と「本番環境用」で異なるものを利用する必要があります。
「開発・検証用」で利用するクライアントIDは開発・検証用データの提供時にご連絡します。
「本番環境用」で利用するクライアントIDは、「ユーザーへの公開日時の事前連絡のお願い」における「貴社サービスで本API利用機能を公開する日時」をご連絡いただいた後にご提供いたします。

お問い合わせ先

本資料の内容やその他不明点がございましたら、弊社担当者、もしくは下記までご連絡ください。

support-contact@smartexterior.net

更新履歴 Edit

業務イベント通知 Edit

説明

宅配ボックスと連携し集荷・配達業務を行う際に、下記の業務イベントをユーザーへ通知する必要があります。

下記の3つ業務イベント通知機能の実装と、業務フローへの組み込みは必須となります。

リクエスト

URL

# 配達完了通知
curl -X POST https://api.smart-ext.io/v0/devices/smartDeliveryPost_8cf780c0-c134-4fd9-9929-9ec44091c620/events \
  -H "accept: application/json" \
  -H "Authorization: Bearer {アクセストークン}" \
  -d '{ "eventType": "deliveryComplete" }'

# 集荷前通知
curl -X POST https://api.smart-ext.io/v0/devices/smartDeliveryPost_8cf780c0-c134-4fd9-9929-9ec44091c620/events \
  -H "accept: application/json" \
  -H "Authorization: Bearer {アクセストークン}" \
  -d '{ "eventType": "pickupRequest", "pickupDate": "2020-03-01" }'

# 集荷完了通知
curl -X POST https://api.smart-ext.io/v0/devices/smartDeliveryPost_8cf780c0-c134-4fd9-9929-9ec44091c620/events \
  -H "accept: application/json" \
  -H "Authorization: Bearer {アクセストークン}" \
  -d '{ "eventType": "pickupComplete" }'

レスポンス

ユーザーのデバイス一覧を取得 Edit

説明

ユーザーが所持しているデバイスの一覧を取得します。

現在は宅配ボックスの情報のみが取得できます。

リクエスト

※ 今後のアップデートで別デバイスが入る可能性があるため、クエリパラメータは指定することを推奨します

URL

curl -X GET https://api.smart-ext.io/v0/devices?deviceType=smartDeliveryPost \
  -H "accept: application/json" \
  -H "Authorization: Bearer {アクセストークン}"

レスポンス

statusの詳細

※1 … 宅配ボックスの空きに余裕がない場合は配達できません

解錠番号を取得 Edit

説明

宅配ボックスの解錠番号を取得します。
「encodedQrCodeUrl」、「deviceId」のいずれかを指定する必要があります。
「lat」、「lon」は任意のパラメータです。

宅配ボックスは、目的にあった解錠番号を利用しないと開けられません。 配達、集荷のいずれの目的なのかを指定してください。

宅配ボックスの設定次第では、解錠番号を取得できないことがあります。

本APIは実行するたびにユーザーへ実行結果を通知するため、ユーザーに誤解を与えないようにご注意ください。 例えば、本APIの実行と宅配ボックスの解錠作業にタイムラグがある場合、事前にユーザーへ説明が必要です。

リクエスト

URL

curl -X GET https://api.smart-ext.io/v0/delivery-box/unlock-number?purpose=delivery&deviceId=smartDeliveryPost_b7bceb35-c8b5-4c7b-ad16-b51b0d0b800c \
  -H "accept: application/json" \
  -H "Authorization: Bearer {アクセストークン}"

レスポンス

statusの詳細