[電子レシートAPI] 端末の追加、検索、取得、更新

ここではAPIでの端末管理方法を紹介します。

# ここで言う端末とは

ここでいう端末はレジやMPOSなどレシートを発行する元となる端末のことをいいます。
電子レシート発行時には端末IDを指定する必要がありますので、予め少なくても1台は登録しておく必要があります。

端末は店舗単位で紐づける必要があります。（なので、店舗も予め登録しておく必要があります）

# リクエスト/レスポンス
それでは端末に対する各種APIを紹介します。端末に関するAPIは全て指定の権限を持っている必要がありますので、まずはトークンを取得し、ヘッダーに`Bear Token`を指定してください。

- [APIトークンの取得方法](https://qiita.com/syantien/items/5a62acabce99aa81edab)

## 作成

まずは端末データを作成します。

### エンドポイント
`https://api.receiptroller.com/{organizationId}/terminal/create`

### メソッド
`POST`

### リクエスト項目
|フィールド名|必須|指定箇所|備考|
|:--|:--|:--|:--|
|organizationId|必須|Route|組織Id|
|storeId|必須|Body|店舗Id|
|terminalCode|必須|Body|任意の端末ID、通常は端末側でもっており端末ID的なものを入れます|
|Memo||Body|登録した端末に関して備考を入力|

### サンプルリクエスト

```
curl -X 'POST' \
  'https://api.receiptroller.com/{organizationId}/terminal/create' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
  "storeId": "{storeId}",
  "terminalCode": "T8888",
  "memo": "T888のテスト端末"
}'
```

### サンプルレスポンス

```json
{
  "id": "{terminalId}",
  "organizationId": "{organizationId}",
  "storeId": "{storeId}",
  "terminalCode": "T8888",
  "memo": "T888のテスト端末"
}
```

## 一覧

作成された端末があるかどうか確認してみます。

### エンドポイント
`https://api.receiptroller.com/{organizationId}/terminals`

### メソッド
`POST`

### リクエスト項目
|フィールド名|必須|指定箇所|備考|
|:--|:--|:--|:--|
|organizationId|必須|Route|組織Id|
|storeId||Body|店舗Id|
|keyword||Body|terminalCodeでの検索|
|currentPage|必須|Body|現在のページを指定|
|itemsPerPage|必須|Body|1ページに何項目表示するか指定|

### サンプルリクエスト

```
curl -X 'POST' \
  'https://api.receiptroller.com/{organizationId}/terminals' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "currentPage": 1,
  "itemsPerPage": 10
}'
```

### サンプルレスポンス

```json
{
  "terminals": {
    "items": [
      {
        "id": "{terminalId}",
        "organizationId": "{organizationId}",
        "storeId": "{storeId}",
        "terminalCode": "t12346",
        "memo": "テスト2"
      },
      {
        "id": "{terminalId}",
        "organizationId": "{organizationId}",
        "storeId": "{storeId}",
        "terminalCode": "T8888",
        "memo": "T888のテスト端末"
      },
      {
        "id": "{terminalId}",
        "organizationId": "{organizationId}",
        "storeId": "{storeId}",
        "terminalCode": "t12345",
        "memo": "テスト"
      }
    ],
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalItems": 3,
    "totalPages": 1,
    "keyword": null,
    "sort": null
  }
}
```

## 詳細

現段階では利用用途は少ないのですが、将来端末に対する情報が増えてきたときは指定した端末を取得する際に利用するAPIです。

### エンドポイント
`https://api.receiptroller.com/{organizationId}/terminal/{terminalId}`

### メソッド
`GET`

### リクエスト項目
|フィールド名|必須|指定箇所|備考|
|:--|:--|:--|:--|
|organizationId|必須|Route|組織Id|
|id||Route|端末Id|

### サンプルリクエスト

```
curl -X 'GET' \
  'https://api.receiptroller.com/{organizaionId}/terminal/{terminalId}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}'
```

### サンプルレスポンス

```json
{
  "id": "{id}",
  "organizationId": "{organizationId},
  "storeId": "{storeId}",
  "terminalCode": "T8888",
  "memo": "T888のテスト端末"
}
```

## 更新

端末データを登録した後に情報を更新する必要があるときはこのAPIにて行います。

### エンドポイント
`https://api.receiptroller.com/{organizationId}/terminal/upsert`

### メソッド
`POST`

### リクエスト項目
|フィールド名|必須|指定箇所|備考|
|:--|:--|:--|:--|
|organizationId|必須|Route|組織Id|
|id|必須|Body|端末d|
|storeId|必須|Body|店舗Id|
|terminalCode|必須|Body|任意の端末ID、通常は端末側でもっており端末ID的なものを入れます|
|Memo||Body|登録した端末に関して備考を入力|

### サンプルリクエスト

```
curl -X 'POST' \
  'https://api.receiptroller.com/9f81702c-bf05-4fc0-917e-269b1c4d311e/terminal/upsert' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "{id}",
  "storeId": "{storeId}",
  "terminalCode": "T8888",
  "memo": "T8888のメモを更新します。"
}'
```

### サンプルレスポンス

```json
{
  "id": "{id}",
  "organizationId": "{organizationId}",
  "storeId": "{storeId}",
  "terminalCode": "T8888",
  "memo": "T8888のメモを更新します。"
}
```

# 最後に

質問やバグを発見した場合はこちらからIssueをご登録お願いいたします。

https://github.com/Receipt-Roller/RECEIPTROLLER-Dev./issues