# エンドポイントの説明

アプリ認証情報をトークンと交換し、認可済みの Team リソース一覧と選択した Work を取得します。

Canonical: https://developer.realsee.ai/ja/docs/open-api/reference
Source: https://developer.realsee.ai/ja/docs/open-api/reference.md
Language: ja

# OpenAPI エンドポイントの説明

トークン交換、Team 一覧、選択リソース取得の順に進めます。全メソッド・引数・応答は [API Reference](https://developer.realsee.ai/api-reference) を参照してください。

<span id="exchange-app-credentials" class="docs-anchor-alias" aria-hidden="true"></span>

## アプリ認証情報を交換する

`POST https://app-gateway.realsee.ai/auth/access_token`

バックエンドから AK と SK をフォーム項目で送ります：

```bash
curl --request POST 'https://app-gateway.realsee.ai/auth/access_token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "app_key=$REALSEE_APP_KEY" \
  --data-urlencode "app_secret=$REALSEE_APP_SECRET"
```

成功時は業務結果と共に `data.access_token` と秒単位の Unix 時刻 `data.expire_at` を返します。HTTP 200 だけで認証成功と判断せず業務結果を確認します。期限に従いサーバーでキャッシュし、AK/SK・トークンをログやブラウザーに含めないでください。

以後の `/open` は `Bearer` を付けず `Authorization: YOUR_ACCESS_TOKEN` に生のトークンを渡します。

<span id="discover-team-resources" class="docs-anchor-alias" aria-hidden="true"></span>

## Team リソースを探す

`POST https://app-gateway.realsee.ai/open/v3/custom/search`

HTTP POST ですが読み取り専用です。JSON に所有 Team の `source`、`page`、`page_size` を渡します。アクセスを許可された Team を使い、source の代わりに UserCode や AK を使わないでください。

```bash
curl --request POST 'https://app-gateway.realsee.ai/open/v3/custom/search' \
  --header "Authorization: $REALSEE_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"source\":\"$REALSEE_TEAM_SOURCE\",\"page\":1,\"page_size\":10}"
```

応答は `data.list` と `page`、`page_size`、`total`、`total_pages` を含みます。項目には `name`、`resource_code`、`picture_url` などがあり、実際の有無はスキーマと応答を確認します。

対象 VR がなければ空一覧も正常結果です。業務結果を確認し、認証・認可失敗と区別します。Team に適切な VR がなくても公開デモは利用できます。

<span id="read-a-selected-resource" class="docs-anchor-alias" aria-hidden="true"></span>

## 選択したリソースを読む

| メソッド | パス | 用途と前提 |
| --- | --- | --- |
| `GET` | `/open/v3/vr/info` | VR 基本データ。resource_code とトークンヘッダーが必要。 |
| `GET` | `/open/v3/hot/list` | API のリソース引数に従ってホットスポットを取得。 |
| `GET` | `/open/v3/floorplan/plugins` | 文書化されたリソース引数で間取り図プラグイン情報を取得。 |

認可済み Team データの識別子を使い、バックエンドでアクセスを検証します。[API Reference](https://developer.realsee.ai/api-reference) の個別スキーマに従ってください。フロントから渡された ID だけでは認可の証明にならず、読み取り API の JSON が必ずブラウザー用や有効な Work とは限りません。

`GET /open/v3/vr/info` の `data` にある Work を使います。Team 一覧から選択したリソースを認可し、`await five.load(parseWork(workJSON))` で読みます。環境とビューアーは [Team API スターター](https://developer.realsee.ai/ja/docs/open-api/quickstart) を参照してください。VR 一覧は Work ではないため直接渡せません。

ルーム操作は [Live](https://developer.realsee.ai/ja/docs/live)、再構成結果は [Argus](https://developer.realsee.ai/ja/docs/argus)、SaaS VR 生成は [Pano-to-VR](https://developer.realsee.ai/ja/docs/pano-to-vr) を使います。入力と結果は各操作で異なります。

<span id="errors-and-continued-use" class="docs-anchor-alias" aria-hidden="true"></span>

## エラーと継続利用

HTTP と `code`、`status` などの業務項目を確認し、トークン期限切れ、アプリ状態、リソースアクセス、レート制限、タスク失敗を別々に処理します。

連携や継続利用の相談は [Realsee Discord コミュニティ](https://discord.gg/JvxBZJkbNZ) へ。

<span id="see-also" class="docs-anchor-alias" aria-hidden="true"></span>

## 関連情報

- [OpenAPI 概要](https://developer.realsee.ai/ja/docs/open-api)：サーバー連携と操作。
- [認証](https://developer.realsee.ai/ja/docs/authentication)：認証情報、トークン、サーバーの安全性。
- [Team とアプリ管理](https://developer.realsee.ai/ja/docs/team-app-management)：作成、所有権、利用状態。
- [Five SDK クイックスタート](https://developer.realsee.ai/ja/docs/five-sdk/quickstart)：有効な Work の描画。