【スマレジアプリを作ってみた#1】アプリの登録とPostman設定

突然ですが、みなさん[スマレジ](https://smaregi.jp/)ってご存じですか？

スマレジは、2019年2月にマザーズ上場を果たした大阪のITベンチャーが
開発・運営を行っているiPhoneやiPadを使用したクラウドPOSレジシステムで、
ショップやレストランなど様々な業態で使用されています。

スマレジには、外部開発パートナーがスマレジのデータを活用して
アプリ開発・販売ができる[アプリマーケット](https://developers.smaregi.jp/)があります。
いろんなアイデアを試してビジネスチャンスを広げるいい機会になると思い、
わたしたちJoBinsは早速**「引換券モニターアプリ」**を作ってみました！

よくファストフード店なんかに行くとありますが、
料理ができたらレシートに書かれている引換番号がモニターに表示される「あれ」です。
あの機能をスマレジに搭載してほしい店舗はごまんといるはず…！（売れるに違いない！）
そう思い、店舗が呼び出した時にカスタマー用のモニターに引換番号が出て音が鳴る、
というシンプルなWebアプリを作りました。

せっかくなので、このアプリ開発のプロセスについて6回に分けてお伝えしていきます！

前置きがだいぶ長くなりましたが。。。
第1回目はアプリの登録・各種設定方法や[Postman](https://www.postman.com/)を使ってスマレジのAPIを利用する方法について説明します。

##アプリの登録・各種設定

スマレジのAPIを使ってアプリ開発するために、まずは[スマレジDevelopers](https://developers.smaregi.jp/)からデベロッパーアカウントを作成します。（ちゃんと利用規約も読みましょう！）


### アプリを新規登録する

デベロッパーアカウントをゲットしたら[ログイン](https://developers.smaregi.dev/)し、
サイドメニューの「アプリ」から新規登録を行います。
![1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/df06da6c-0fa1-3628-c0b7-2bbdc714fccc.png)
![2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/42fce986-1aaf-3e3d-027c-6f504819bb0e.png)



新規登録ボタンから登録フォームにいき、必須項目を入力します。
アプリのアイコンなど、「申請時に必要」な項目もありますが、
これらは後から入力すればOKなのでとりあえず「必須項目」だけ入れて登録しましょう。


### アプリ登録フォームの必須項目

- **アプリ区分**: 今回はWEBアプリを選択。
- **サービス種類**: WEBアプリなので今回は選択不要。
- **アプリ名**: 名前から機能を連想できるようなアプリ名にしましょう。（例：引換券モニター）
- **バージョン**: アプリのバージョンなので、最初は「1.0.0」とでもしましょう。

登録すると、アプリの概要ページにリダイレクトします。
概要ページでは、APIのスコープ、Webhook、認証リダイレクトURLなどの重要な項目を設定できます。

![アプリ新規登録.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/90bf2810-bbab-9132-cd56-6a545d9a3a90.png)




### アプリの削除方法

「間違えて登録しちゃった！」という時は、削除したいアプリの「概要を見る」をクリックし、
アプリの概要ページにいきます。
上の「基本情報」タブを開くと、ページの下の方に「削除ボタン」があります。

![アプリの削除.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/207a922e-e58c-0b39-f880-99420f369f6d.png)


### クライアントIDとクライアントシークレットをチェック

アプリを登録すると、クライアントIDとクライアントシークレットがアプリごとに発行されます。
これらはアプリの概要ページの「環境設定」タブで確認できます。
この2つはスマレジのAPIにアクセスする際に必要になります。


![クライアントIDなど.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/5f8734d3-2c69-7fe8-ffe9-de913e06403d.png)



##Postman設定


では次に[Postman](https://www.postman.com/)を使ってスマレジのAPIにアクセスしてみましょう！

すべてのAPIには認証が必要なので、`access_token`を取得するには「スマレジ契約ID」、「クライアントID」、「クライアントシークレット」が必要になります。
この `access_token`は、他のAPIをリクエストする際に使用します。


[各APIの仕様書](https://developers.smaregi.dev/documents/api_reference)はメニューバーの「ドキュメント」の中の「仕様書」タブにあります。

環境によりエンドポイントURLが異なるので、このドキュメントではSandbox環境を対象に例を記載しています。


|                  | Sandbox環境　　　　　　　　| 本番環境                 |
| ---------------- | ----------------------- | ---------------------- |
| アクセストークンAPI　 | https://id.smaregi.dev  | https://id.smaregi.jp  |
| プラットフォームAPI   | https://api.smaregi.dev | https://api.smaregi.jp |

### アプリアクセストークンを取得する

参照: [スマレジ・プラットフォームAPI 共通仕様書](https://developers.smaregi.dev/apidoc/common/#section/%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3)

アクセストークンを取得するには、次のリクエストパラメータを使用して`POST`リクエストをエンドポイントに送信します。

**エンドポイント**
 `https://id.smaregi.dev/app/{contractID}/token`

**リクエストヘッダー**
Authorization: `Basic {Base64 client_id:client_secret}`
Content-Type: `application/x-www-form-urlencoded`

**リクエストボディ**
grant_type: `client_credentials`
scope: 要求するAPIスコープ。複数の場合は半角スペースで結合して指定します。


要求するAPIスコープは、アプリ概要ページの「スコープ」タブから設定できます。 
有効ではないスコープを要求しても無視され、存在しないスコープを含む場合はエラーを返します。
たとえば、店舗リストを取得したい場合は、`pos.stores：read`を有効にします。

![スコープ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/ec43dc75-7f04-6609-7756-f159cee75e92.png)


### アプリアクセストークンをPostmanを使って取得する

Postmanで環境変数を設定すればアクセストークンを取得するのは超絶カンタンで、
シンプルに`POST`リクエストをエンドポイントURLに送信するだけです。
設定方法は以下の通り。

**Authorization**
「Basic auth」に設定し、Usernameに`client_id`を、Passwordに`client_secret`を入れます。

**Headers**
Content-Type: `application/x-www-form-urlencoded`

**Body**
「x-www-form-urlencoded」にチェックして、以下のように入力します。
grant_type: `client_credentials`
scope: `pos.stores:read pos.stores:write`

![8.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/851d3df3-37ff-cbd8-ae13-e29d62aea8f4.png)

これらが正しく設定されていると、下の画像のように`access_token`を取得できます。


![9.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/434ba541-e741-c3d6-5d83-98237b9f2b43.png)

###Postmanから店舗一覧を取得する
次に、取得したアクセストークンを使って、店舗一覧を取得できるか確認してみましょう。

①「Authorization」タブでTYPEを「Bearer Token」に設定する
②先程取得したアクセストークンをTokenに入力する
③下記のエンドポイントに`GET`リクエストを送信する
　`https://api.smaregi.dev/{contract_id}/pos/stores/` 
　※`{contract_id}`は自分のidに変更すること

店舗一覧取得の詳細については[こちら](https://www1.smaregi.dev/apidoc/#operation/getStores)で確認できます。

![店舗一覧取得.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/f19464f6-3edb-f15a-8a40-8bdade11107e.png)




##Postman環境設定ファイル

つらつらと書きましたが、「めんどくさいわ！」という方は
[Github](https://github.com/JoBinsJP/smaregi-app-env)にファイルをアップしているのでよかったらご利用ください！

---

第１回目は**アプリの登録**と**Postmanの設定**のポイントにについてお送りしました。
次回はアプリの仕様設計についてお届けします！