# ロカオプ予約 API

> ワークスペース配下の店舗情報と予約情報を外部システムから取得するための API です。

## このファイルについて

このファイルは AI に API 仕様を共有するためのテキスト版リファレンスです。
人間向けの静的 HTML は https://developers.res-app.locaop.jp/ で確認できます。

API を利用する際に共通して必要な Base URL, 認証, レート制限をまとめています。

## Base URL

`https://api.res-app.locaop.jp`

## 認証

すべての API は `Authorization` header に Bearer token を指定します。

```bash
Authorization: Bearer <token>
```

token は管理画面のワークスペース設定にある `API 連携` から発行します。発行直後に表示される token は再表示できないため、利用者側で安全に保管してください。

token はワークスペース単位で管理されます。同じワークスペース配下の店舗であれば、店舗一覧 API で取得した `shopId` を予約一覧 API の path に指定することで取得対象店舗を切り替えられます。

token を失効させた場合, 反映まで最大 60 秒かかる場合があります。

## レート制限

レート制限はワークスペース単位で適用されます。同じワークスペースで複数の API キーを発行している場合でも、制限は合算されます。

- 上限: 1 ワークスペースあたり 1 秒間に 10 リクエストまで

短時間にリクエストが集中した場合も制限されることがあります。レート制限を超えた場合は `429 Too Many Requests` を返します。`429` が返った場合は、少し時間をおいてから再試行してください。

## Endpoints

### 店舗一覧取得

`GET /v1/shops`

summary: 店舗一覧の取得

token に紐づくワークスペース配下の店舗一覧を取得します。

予約一覧 API の `shopId` には、この API のレスポンスに含まれる `shops[].id` を指定します。

#### レスポンス

| Status | 説明 | Schema |
| --- | --- | --- |
| `200` | 店舗一覧を取得しました。 | ListShopsResponse |
| `401` | token が不正、失効済み、期限切れです。 | ErrorResponse |
| `403` | 必要な scope がない、または指定店舗を利用できません。 | ErrorResponse |
| `429` | レート制限を超過しました。少し時間をおいてから再試行してください。 | ErrorResponse |
| `500` | サーバーエラーです。 | ErrorResponse |

#### レスポンス例

##### 200 success

```json
{
  "shops": [
    {
      "id": 2383,
      "uid": "ginza",
      "name": "銀座店"
    },
    {
      "id": 2384,
      "uid": "shibuya",
      "name": "渋谷店"
    }
  ]
}
```

##### 401 unauthorized

```json
{
  "message": "Unauthorized"
}
```

##### 403 forbidden

```json
{
  "message": "必要な scope がありません"
}
```

##### 429 tooManyRequests

```json
{
  "message": "Too Many Requests"
}
```

##### 500 internalServerError

```json
{
  "message": "Internal server error"
}
```

### 予約一覧取得

`GET /v1/shops/{shopId}/reservations`

summary: 指定店舗の予約一覧の取得

指定した店舗の予約一覧を取得します。

`shopId` には、token に紐づくワークスペース配下の店舗 ID を指定します。

`startDate` と `endDate` の期間は最大 13 ヶ月です。

`dateField=canceledAt` の場合、`includingCanceled` の指定に関係なくキャンセル済み予約のみ返します。

### 取得順序

予約は指定した `dateField` の対象日時の昇順で返ります。

- `dateField=reservationDate`: 予約日 (来店日), 予約時刻, 予約作成日時, 予約 ID の昇順
- `dateField=createdAt`: 予約作成日時, 予約 ID の昇順
- `dateField=updatedAt`: 予約更新日時, 予約 ID の昇順
- `dateField=canceledAt`: キャンセル日時, 予約 ID の昇順

### ページネーション

レスポンスの `nextCursor` が `null` でない場合、次ページがあります。次回リクエストでは同じ query 条件に `cursor=<nextCursor>` を追加してください。

`cursor` は `shopId`、`startDate`、`endDate`、`dateField`、`courseIds`、`includingCanceled` の組み合わせに紐づきます。条件を変えた場合は cursor を使わず、最初のページから取得してください。

### formResponse

`formResponse` は予約フォーム回答です。詳細は Response schema を確認してください。

- `formResponse.fields[].uid` はフォーム項目の識別子です。連携先では表示名ではなく `uid` を安定キーとして扱ってください。
- `formResponse.fields[].name`, `type`, `values[].text` は現在のコースフォーム設定から補完されます。そのため, 予約時点の表示内容と異なる場合があります。
- 現在のコースフォーム設定から項目や選択肢を解決できない場合, `name`, `type`, `values[].text` は `null` になる場合があります。
- `formResponse.fields[].type` の有効な値と意味は `FormFieldType` schema を参照してください。
- 初期値がない任意項目などで利用者が入力操作をしていない場合, その項目は `formResponse.fields` に含まれません。
- 初期値がある項目, または利用者が入力操作をした項目は `formResponse.fields` に含まれます。
- 選択を解除した場合など, 項目が含まれていて回答値がない場合は `values` が空配列 (`[]`) になることがあります。
- テキスト入力を空にした場合など, 実際に空文字が保存された場合は `values` に空文字が含まれることがあります。
- `radio` / `checkbox` の値は `uid` と `text` を含む object 形式で返ります。その他の入力値は基本的に文字列で返ります。

#### パラメータ

##### パスパラメータ

| 名前 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `shopId` **必須** | integer | 取得対象店舗の ID。token に紐づくワークスペース配下の店舗 ID を指定します。 | 2383 |

##### クエリパラメータ

| 名前 | 型 | 説明 | 例 |
| --- | --- | --- | --- |
| `startDate` **必須** | string, format: date | 取得開始日。`YYYY-MM-DD` 形式。 | 2026-05-01 |
| `endDate` **必須** | string, format: date | 取得終了日。`YYYY-MM-DD` 形式。 | 2026-05-31 |
| `dateField` | ReservationDateField | 期間条件の対象日。省略時は `reservationDate`。<br>- `reservationDate`: 予約日 (来店日)<br>- `createdAt`: 予約作成日時<br>- `updatedAt`: 予約更新日時<br>- `canceledAt`: キャンセル日時。キャンセル済み予約のみ取得対象になります<br> | reservationDate |
| `courseIds` | string | コース ID のカンマ区切り。例: `1,2,3`。<br>省略時は、指定店舗のすべてのコースの予約を取得します。<br>コース ID は、管理画面のコース編集画面 URL の末尾の数字で確認できます。たとえば `https://res-app.locaop.jp/a/test-workspace/settings/courses/123` の場合、コース ID は `123` です。<br> | 1,2,3 |
| `includingCanceled` | boolean, default: false | キャンセル済み予約を含める場合は `true`。省略時は `false`。 | true |
| `limit` | integer, default: 50 | 1 ページあたりの取得件数。省略時は `50`、最大 `100`。 | 50 |
| `cursor` | string | 次ページ取得用 cursor。前回レスポンスの `nextCursor` をそのまま指定します。 | eyJ2IjoxLCJkYXRlRmllbGQiOiJyZXNlcnZhdGlvbkRhdGUi... |

#### レスポンス

| Status | 説明 | Schema |
| --- | --- | --- |
| `200` | 予約一覧を取得しました。 | ListReservationsResponse |
| `400` | query parameter が不正です。 | ErrorResponse |
| `401` | token が不正、失効済み、期限切れです。 | ErrorResponse |
| `403` | 必要な scope がない、または指定店舗を利用できません。 | ErrorResponse |
| `429` | レート制限を超過しました。少し時間をおいてから再試行してください。 | ErrorResponse |
| `500` | サーバーエラーです。 | ErrorResponse |

#### レスポンス例

##### 200 success

```json
{
  "reservations": [
    {
      "reservationId": 1001,
      "courseId": 20,
      "courseName": "初回カウンセリング",
      "reservationDate": "2026-05-13",
      "reservationHour": 10,
      "reservationMinute": 30,
      "status": "active",
      "customer": {
        "id": 3001,
        "name": "山田 太郎",
        "nameKana": "ヤマダ タロウ",
        "email": "taro@example.com",
        "tel": "09012345678",
        "lineDisplayName": "山田"
      },
      "note": "予約メモ",
      "inflowSource": {
        "uid": "web",
        "name": "Web"
      },
      "labels": [
        {
          "id": 1,
          "name": "重要"
        }
      ],
      "resources": [
        {
          "id": 5,
          "name": "個室 A"
        }
      ],
      "minutesRequired": 60,
      "createdAt": "2026-05-01 09:00:00",
      "updatedAt": "2026-05-01 09:10:00",
      "deletedAt": null,
      "formResponse": {
        "fields": [
          {
            "uid": "2tEOYE",
            "name": "お名前",
            "type": "name",
            "values": [
              "山田 太郎"
            ]
          },
          {
            "uid": "xtJppM",
            "name": "電話番号",
            "type": "tel",
            "values": [
              "09012345678"
            ]
          },
          {
            "uid": "a8KpQ2",
            "name": "メールアドレス",
            "type": "email",
            "values": [
              "taro@example.com"
            ]
          },
          {
            "uid": "Bn72xR",
            "name": "生年月日",
            "type": "birthDate",
            "values": [
              "1990-01-23"
            ]
          },
          {
            "uid": "mQ4zLp",
            "name": "来店理由",
            "type": "text",
            "values": [
              "Web サイトを見て予約しました"
            ]
          },
          {
            "uid": "V7nDk3",
            "name": "相談内容",
            "type": "textarea",
            "values": [
              "肩こりが気になります"
            ]
          },
          {
            "uid": "rT9wXb",
            "name": "希望メニュー",
            "type": "radio",
            "values": [
              {
                "uid": "Lp4Qz9",
                "text": "メニュー A"
              }
            ]
          },
          {
            "uid": "hY8kNc",
            "name": "気になる症状",
            "type": "checkbox",
            "values": [
              {
                "uid": "P0mXa2",
                "text": "肩こり"
              },
              {
                "uid": "zR6tWq",
                "text": "頭痛"
              }
            ]
          },
          {
            "uid": "cE3uHs",
            "name": "来店人数",
            "type": "number",
            "values": [
              "2"
            ]
          },
          {
            "uid": "nK5pVa",
            "name": "希望日",
            "type": "date",
            "values": [
              "2026-05-20"
            ]
          },
          {
            "uid": "X4gTq1",
            "name": "任意メモ",
            "type": "text",
            "values": []
          }
        ]
      }
    }
  ],
  "limit": 50,
  "nextCursor": null
}
```

##### 400 invalidDate

```json
{
  "message": "startDate は YYYY-MM-DD 形式で指定してください"
}
```

##### 401 unauthorized

```json
{
  "message": "Unauthorized"
}
```

##### 403 forbidden

```json
{
  "message": "必要な scope がありません"
}
```

##### 429 tooManyRequests

```json
{
  "message": "Too Many Requests"
}
```

##### 500 internalServerError

```json
{
  "message": "Internal server error"
}
```

## Schema

### ListShopsResponse

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `shops` | array<Shop> | - |

### Shop

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `id` | integer | 店舗 ID。予約一覧 API の `shopId` に指定します。 |
| `uid` | string | 予約フォーム URL などで使われる店舗 UID。 |
| `name` | string | 店舗名。 |

### ListReservationsResponse

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `reservations` | array<Reservation> | - |
| `limit` | integer | - |
| `nextCursor` | string \| null | 次ページがある場合に返る cursor。次回リクエストの `cursor` にそのまま指定します。 |

### Reservation

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `reservationId` | integer | 予約 ID。 |
| `courseId` | integer | 予約コース ID。 |
| `courseName` | string | 取得時点のコース名。 |
| `reservationDate` | string, format: date | 予約日 (来店日)。`YYYY-MM-DD` 形式。 |
| `reservationHour` | integer | 予約時刻 (来店時刻) の時。 |
| `reservationMinute` | integer | 予約時刻 (来店時刻) の分。 |
| `status` | ReservationStatus | - |
| `customer` | ReservationCustomer \| null | 顧客情報。`formResponse` の氏名, メールアドレス, 電話番号の回答とは別の顧客紐づき情報です。顧客が紐づかない場合は `null`。 |
| `note` | string | 管理画面で入力した予約メモ。未入力の場合は空文字。 |
| `inflowSource` | ReservationInflowSource | 予約の流入元。未設定の場合は `uid` が `unknown`, `name` が `不明` になる場合があります。 |
| `labels` | array<ReservationLabel> | 管理画面で付与した予約ラベル。付与されていない場合は空配列。 |
| `resources` | array<ReservationResource> | 予約に割り当てられたリソース。割り当てられていない場合は空配列。 |
| `minutesRequired` | integer \| null | フォーム回答とコースの所要時間設定から計算した所要時間 (分)。計算できない場合は `null`。 |
| `createdAt` | string | 予約作成日時。`YYYY-MM-DD HH:mm:ss` 形式。 |
| `updatedAt` | string | 予約更新日時。`YYYY-MM-DD HH:mm:ss` 形式。 |
| `deletedAt` | string \| null | キャンセル日時。未キャンセルの場合は `null`。 |
| `formResponse` | FormResponse | 予約フォーム回答。 |

### ReservationStatus

予約ステータス。

- `active`: 有効な予約
- `canceled`: キャンセル済み予約

型: `string, enum: active | canceled`

値:

- `active`
- `canceled`

### ReservationDateField

期間条件の対象日。

- `reservationDate`: 予約日 (来店日)
- `createdAt`: 予約作成日時
- `updatedAt`: 予約更新日時
- `canceledAt`: キャンセル日時。キャンセル済み予約のみ取得対象になります

型: `string, enum: reservationDate | createdAt | canceledAt | updatedAt, default: reservationDate`

値:

- `reservationDate`
- `createdAt`
- `canceledAt`
- `updatedAt`

### ReservationCustomer

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `id` | integer | 顧客 ID。 |
| `name` | string \| null | 顧客名。未設定の場合は `null`。 |
| `nameKana` | string \| null | 顧客名かな。未設定の場合は `null`。 |
| `email` | string \| null | メールアドレス。未設定の場合は `null`。 |
| `tel` | string \| null | 電話番号。未設定の場合は `null`。 |
| `lineDisplayName` | string \| null | LINE 表示名。未連携または未取得の場合は `null`。 |

### ReservationInflowSource

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `uid` | string | 流入元 UID。 |
| `name` | string | 流入元名。 |

### ReservationLabel

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `id` | integer | ラベル ID。 |
| `name` | string | ラベル名。 |

### ReservationResource

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `id` | integer | リソース ID。 |
| `name` | string | リソース名。 |

### FormResponse

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `fields` | array<FormResponseField> | - |

### FormResponseField

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `uid` | string | フォーム項目の識別子。通常は英数字 6 文字です。連携先では表示名ではなく `uid` を安定キーとして扱ってください。 |
| `name` | string \| null | 現在のコースフォーム設定から補完した項目名。解決できない場合は `null`。 |
| `type` | FormFieldType \| null | - |
| `values` | array<FormResponseValue> | 回答値の配列。項目が含まれていて回答値がない場合は空配列になります。 |

### FormResponseValue

型: `string | FormResponseOptionValue`

候補:

- `string`
- `FormResponseOptionValue`

### FormResponseOptionValue

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `uid` | string | 選択肢の識別子。通常は英数字 6 文字です。 |
| `text` | string \| null | 現在のコースフォーム設定から補完した選択肢表示名。解決できない場合は `null`。 |

### FormFieldType

フォーム項目の入力種別。

- `tel`: 電話番号
- `email`: メールアドレス
- `name`: 氏名
- `birthDate`: 生年月日
- `text`: 1 行テキスト
- `textarea`: 複数行テキスト
- `radio`: 単一選択
- `checkbox`: 複数選択
- `number`: 数値
- `date`: 日付

型: `string, enum: tel | email | name | birthDate | text | textarea | radio | checkbox | number | date`

値:

- `tel`
- `email`
- `name`
- `birthDate`
- `text`
- `textarea`
- `radio`
- `checkbox`
- `number`
- `date`

### ErrorResponse

型: `object`

| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `message` | string | - |