スマレジからAPIでデータを取得してみた


# はじめに

こんにちは、すぎもんです:smile:

近年、タブレットを活用した各種SaaSの導入が進んでおり、従来型のPOSシステム以外にもiPhoneやiPadなどの端末を利用したPOSシステムが普及しています。一方で、企業の基幹システムとタブレットのPOSレジシステムを連携させることは、システム間のデータ受け渡しが複雑になるため、簡単ではありません。
そこで、今回はHULFT Squareを使って、タブレットを使ったPOSレジシステムと企業の基幹システムを安全かつ確実に連携させる方法をご紹介します。

# スマレジとは
[スマレジ](https://smaregi.jp/)は、iPhoneやiPadなどの端末に専用のアプリをインストールして利用できるクラウド型のPOSレジシステムです。小売業や飲食・サービス業の店舗運営の効率化を目的としており、基本レジ機能のほか、リアルタイム売上分析や在庫管理、顧客管理などの機能が備わっています。
また、スマレジはAPIを公開しているので他システムと連携出来るようになっています。


# 今回やること
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/a653b3d0-1ee5-74fe-3277-934fd6f93de6.png)
今回はスマレジのAPIを使ってHULFT Squareと連携出来るか試してみます。
実際にスマレジに登録されているデータを汎用的に扱いやすいCSV形式のファイルで出力する処理を作成していきます。

## スマレジとの連携するのに必要な設定
### スマレジ側の設定

1.スマレジのサンプルアプリ登録
2.スマレジのサンプルデータを作成

### HULFT Square側の設定

3.コネクションの設定
4.アクセストークン取得処理
5.会員情報取得
6.実行結果確認



:::note info
今回は[スマレジ Developers](https://developers.smaregi.jp/) アカウントを事前に用意したのでこちらを使用していきます。
:::


## スマレジ側の設定

### 1.スマレジのサンプルアプリ登録
API を利用するのに必要なクライアント ID とクライアントシークレットを払い出すためのサンプルアプリを登録します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/91f1585f-aaa8-0602-ad19-c727a78985a6.png)


「スコープ」タブで利用したい API を有効にします。今回は「すべて」を有効化します。
※利用したい API だけでも大丈夫です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/24a3f202-4747-6667-9435-0d50499df054.png)


「基本設定」のタブで「クライアントID」「クライアントシークレット」を確認することができます。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/82d84cc2-8ece-c0e6-af2e-8222a089570b.png)

:::note info
ここで取得した「クライアントID」「クライアントシークレット」は後にHULFT Squareで設定する際につかいます
:::


### 2.スマレジのサンプルデータを作成
今回は「会員」情報のデータを作成します。

コンソール右上の Bento メニューからサンドボックス環境を開くことができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/7d4df636-9acf-e1a6-a1e2-167a6c0c99d8.png)

POS を選択し、"会員 ＞ 新規登録"　から会員データの登録を行います。データの量が多い場合は CSV でインポートすることも可能ですが、今回は手動で登録を行います。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5dd6083d-7cb7-8c24-385d-e2a43f390492.png)


今回はスマレジの「会員」の項目に
このようにデータを登録したのでこのデータをCSVに出力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5d81895f-e85a-f9ce-ac16-937a84d8738d.png)


## HULFT Square側の設定

### 3.コネクションの設定（トークンと会員情報取得API）

まずはHULFT SquareでURLを実行するのに必要なコネクションの設定をしていきます。
スマレジのAPIは仕様書によると最初にアクセストークンを取得してきて、そのトークンを元に実際に必要なデータを取得します。

:::note info
[仕様書
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/368c1097-6ab2-fc85-944f-6b6b630e24dd.png)](https://developers.smaregi.dev/apidoc/common/#section/%E6%A6%82%E8%A6%81)

:::

そのため、今回実行したいリクエスト URLは2つあります。

**3-1** ➀「[アクセストークン](https://developers.smaregi.dev/apidoc/common/#section/%E6%A6%82%E8%A6%81)」を取得するためのリクエストURL (**アクセストークンAPI** )
**3-2** ➁「[会員情報](https://www1.smaregi.dev/apidoc/#operation/getCustomer)」を取得するためのリクエスト URL  ( **プラットフォームAPI**)



### 3-1 **➀アクセストークン取得するためのリクエストURL**
まずは、[アクセストークン](https://developers.smaregi.dev/apidoc/common/#section/%E6%A6%82%E8%A6%81)を取得するためのURLを設定していきます。

`RESTコネクター`を選択して下記の内容を登録します。
| 設定箇所 | 設定値 |  
|:-|:-:|
| 名前 | `REST接続(スマレジ)アクセストークン取得` | 
| URL | **`https://id.smaregi.dev`** | 


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/ad6e6a47-7b9c-543b-d88e-7a5691ce99a8.png)



:::note warn
スマレジのAPIを使用する場合は、一度APIで取得したアクセストークンを元に、取得したいデータ(会員情報)のAPIを実行する必要があります。
:::


### 3-2 **➁「会員情報」を取得するためのリクエスト URL**
次に、今回取得したい[会員情報](https://www1.smaregi.dev/apidoc/#operation/getCustomer)のデータを取得するためのURLを設定していきます。

`RESTコネクター`を選択して下記の内容を登録します。
| 設定箇所 | 設定値 |  
|:-|:-:|
| 名前 | `REST接続(スマレジ)会員情報` | 
| URL | **`https://api.smaregi.dev`** | 

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/8b0fb292-787c-6fd5-19e5-28e4cfa638fa.png)

以上でコネクションの設定は完了です。


### 4.アクセストークン取得処理
ここからは、HULFT Squareのデザイナー画面を開き実際に作成していきます。


### 4-1 **POST実行処理**

:::note warn
事前にご自身の契約IDを確認しておきましょう。
**契約ID**はスマレジの画面左上で確認出来ます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/98c5341f-9d18-3b63-a43c-7055255fd8c7.png)
:::

ここではアクセストークンを取得するための設定をしていきます
まずは、**POST実行アイコン**を配置します
「ツールパレット > ネットワーク > REST > `POST実行`アイコン」をドラッグ＆ドロップするとポップアップが出てきます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/2965c273-3c0d-0bb2-4e15-0586718c047e.png)


➀「必須設定」タブ
接続先：`REST接続(スマレジ)アクセストークン取得(Personal)`　※「3.コネクションの設定」 ➀で設定したもの
パス：`/app/<契約ID>/token`　※<契約ID>はご自身のIDを設定してください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/65ee5611-4aac-5ca9-81d0-4c5f5f4612e8.png)



➁「リクエスト設定」タブ
データ入力元：`● データ`
データ形式：`フォーム`
フォーム設定：`grant_type` 、 `scope`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/a3f23cfd-6e56-537a-f4cf-54db87650335.png)


➂「ヘッダー設定」タブ
「リクエストヘッダ」で`追加`を押し下記を設定
`Content-Type` : `application/x-www-form-urlencoded`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/cad6a439-5630-59f8-5d59-0c10a9e2ff2f.png)


➃「認証設定」タブ
認証：`ベーシック認証`
ユーザー：`クライアントID`
パスワード：`クライアントシークレット`
※「1.スマレジのサンプルアプリ登録」で取得したクライアントID、クライアントシークレットを指定してください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/8fb3e4d4-ea7d-44e7-1269-34bd3a7950b6.png)



### 4-2 **mapping**(1)アイコン
ここでは、使用可能な権限スコープを指定します。

:::note info
[仕様書
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/3dedf33b-bb68-915d-6709-5b678f636694.png)](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)
:::

"ツールパレット > 変換 > 基本 > `マッピング`"をドラッグ&ドロップします。
`マッピング`アイコンを「`Stat` ➡ `マッピング` ➡ `アクセストークン取得`(POSTアイコン)」にドラッグ&ドロップして線でつなぎます。

**`マッピング`アイコンを開きます。**

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/c36fe2cf-1976-40d6-90d0-25b5a9b528f2.png)






**【➀単一文字列定数】** 
まずは、クライアント・クレデンシャルズ（トークンエンドポイントにクライアントアプリケーションの ID とシークレットを提示することでアクセストークンの発行を受けるフロー）を設定します。

単一文字列定数アイコンを配置します。
"ツールパレット > 文字列 > 基本 > `単一文字列定数`"をドラッグ&ドロップします
コメント：`client_credentials`
一行文字列：`client_credentials`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/334e4219-40dc-abca-80d7-fe7580a776ae.png)


**【➁複数文字列定数】** 
次にスコープ（連携の影響範囲）を設定します。

複数文字列アイコンを配置します。
"ツールパレット > 文字列 > 基本 > `複数文字列定数`"をドラッグ&ドロップします
複数文字列定数ロジックに下記のように登録します。
コメント：`scope`
複数文字列定数：`pos.customers:read` `pos.customers:write`
※「会員/ポイントの参照」、「会員/ポイントの更新」以外の他のscopeを使用出来るように全て入れても大丈夫です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/75eb72f0-507c-3b9b-987e-c2ffa1c98518.png)



:::note info
スコープとは、範囲のことで、有効にしたスコープの対象のAPIのみ使うことができます。
[公式マニュアル
<img width="450" alt="mojikyo45_640-2.gif" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/eb9227d0-b4dd-e9cc-7c50-cf134f7cd9ac.png">](https://www1.smaregi.dev/apidoc/#operation/getItem)
:::


最後に必要な項目を繋いでいきます

**`client_credentials`**  (➀単一文字列定数アイコン)   ➡  **grant_type**の`value`
**`scope`** (➁複数文字列定数アイコン)  ➡  **scope**の`value`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/5c19799c-85ae-096f-46a9-d7dd77360029.png)


### 4-3 **mapping**(2)アイコン
最後に取得したアクセストークンを出力します。
デザイナー画面に戻り、"ツールパレット > 変換 > 基本 > `マッピング`"をドラッグ&ドロップします。
「`アクセストークン取得`(POSTアイコン) ➡ `mapping(2)`」をドラッグ&ドロップで線を繋ぎます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/bde3ad8c-bd70-a331-6852-f16d391a0058.png)


取得したアクセストークンを出力するための変数を作成します。
「スクリプトをクリック > 新規作成 > スクリプト変数」を選択します。
今回は`トークン`という名前のスクリプト変数を作成しました。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/ad40c3b7-fed9-6c6d-2425-c3370fd5ca1d.png)


`mapping(2)`を開いて
「`access_token` ➡ `トークン`」に線でつなぎます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/8bdb6b44-efe8-6701-fade-18868e37973d.png)


:::note warn
ここで取得したアクセストークンを確認したい場合は、`mapping(2)`➡`End`に繋ぎ実行することでログから確認出来ます。
<img width="450" alt="mojikyo45_640-2.gif" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/1ead6b28-b7c0-acaa-316f-67fb41c751cb.png">
:::

### 5.会員情報取得
ここから会員情報を取得する処理を作成していきます。

### 5-1 **GET実行**アイコン

「ツールパレット > ネットワーク > REST > `GET実行`アイコン」をドラッグ＆ドロップするとポップアップが出てきます。

アイコンの名前をわかりやすいように下記のように設定します
**名前：`会員情報取得(GET)`**

➀「必須設定」タブ
接続先：`REST接続(スマレジ)アクセストークン取得(Personal)`
　　※「3.コネクションの設定」 ➁で設定したものです
パス：`/<契約ID>/pos/customers` 
　　※<契約ID>は「4.アクセストークン取得処理」と同様にご自身のIDを設定しましょう


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/cc82c978-f0d2-6c5f-770f-cdc11f7d102f.png)

➁「ヘッダ設定」タブ
リクエストヘッダに下記を登録
`Authorization`：`Bearer ${トークン}`
※「4.トークン取得処理」 mappingで設定したものです

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/69f7c5a9-2f8a-d538-1127-ec542bb542a4.png)




### 5-2 **CSV書き込み**アイコン
今回はこちらのCSVファイルにデータを書き込みます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/d635612b-a672-a732-ade9-2e32ca94e4a0.png)

「ツールパレット > ファイル > CSV > `ファイル書き込み`アイコン」をドラッグ＆ドロップするとポップアップが出てきます。

今回は下記のように設定しました。
**名前：`csv書き込み`**
**ファイル：`/Personal/会員情報書き込み.csv`**　※出力先のファイルパスを指定します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/a0e8b70a-6f20-d331-f15e-4408aa96e0a0.png)
上記のように設定した後、列一覧を指定します。

### 5-3 フローを引く

「”4.トークン取得処理”　　4-3 mapping(2)」で作成したアイコンの後から下記のようにフロー(線)を引いていきます。
「**mapping(2)**」➡ 「**会員情報取得(GET)** アイコン」
「**会員情報取得(GET)** アイコン」➡「**CSV書き込み**アイコン」の形でドラッグ&ドロップし**マッパー**を追加します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/23f582f0-a85b-22a2-044c-7330247c3a0b.png)

### 5-4 mapperの設定
最後にmapperの中を設定します。
入力側(スマレジ側)の項目から、出力側(CSV側)に必要な項目を線でつなぎます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/f039e3cb-1475-50fa-c542-c2b373944aa6.png)

:::note warn
今回は下記のように、スマレジの項目と出力するCSVファイルの項目を紐づけました。
<img width="300" alt="mojikyo45_640-2.gif" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/e8e82712-a870-3d4f-2555-7c39d0f3a617.png">
:::

ここまでで処理の作成は完成です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/23f582f0-a85b-22a2-044c-7330247c3a0b.png)


### 6.実行結果確認

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/62da734a-f992-4a86-dc64-cc48cf500d8d.png)

ログでもデータが挿入されているのが確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/d6ebe73d-dd28-22de-0ebb-83e26b983fee.png)


実際にCSVファイルに正常に書き込み出来ているのが確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/458288/b8e534a2-5b37-6d23-ad01-9e33a4c0d187.png)





# 最後に
いかがでしたでしょうか。今回は、スマレジからHULFT SquareでデータをCSVファイル形式で取得してみましたが、データベースや他のSaaS製品とスマレジを連携させることで活用の幅が広がるのではなでしょうか。
また、HULFT Squareはファイル転送ソフトであるHULFT8と連携してオンプレミス環境にそのままファイルを転送させることも可能です。
[**HULFT Squareについて知りたい方はこちら**](https://www.hulft.com/service/hulft-square)

ここまでお読みいただきありがとうございました。それでは、また！