TROCCO®のHTTPコネクタを活用して、スマレジの取引データを取得する

#
::: note warn
TROCCO®のコネクタがアップデートされ、2025年5月20日に転送元スマレジがリリースされました！今後はスマレジコネクタをご利用ください。

https://documents.trocco.io/docs/release-notes

https://x.com/trocco_jp/status/1924791053670088771

:::


# はじめに
スマレジとは、小売の店舗運営で活用されているクラウド型のPOSレジです。

店舗運営をする中で、スマレジに蓄積された商品の取引データを活用し、売上状況や消費者の動向を把握したい方も多いと思います。
また、客層データ、商品データや商品カテゴリーと紐づければ、客層別、商品別、カテゴリー別の売上状況も把握することができます。
さらに、外部データの気象情報を取得すれば、天気による販売状況の分析も可能になります。

このようにスマレジの取引データを活用することで、売上や消費者動向に関するさまざまな分析が可能です。
今回の記事では、スマレジの取引データをTROCCO®のHTTP(・HTTPS)コネクタを活用して、データ基盤に取得する方法を紹介します。

# 対象とする読者
- スマレジの取引データを活用して、店舗運営に活かしたいと考えている方
- スマレジでデータを取得する際に、TROCCO®の活用を検討している方

# そもそもHTTPとは？
「HTTPって何？」という読者の方もいると思うので、簡単な用語解説を行いたいと思います。

HTTPとはWebブラウザ上でリクエストを投げると、取りたい情報が返ってくる仕組みです。
TROCCO®には[転送元のコネクタの1つとしてHTTP（・HTTPS）](https://documents.trocco.io/docs/data-source-http)が存在し、TROCCO®でデータを取得することができます。

![about-http.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/94a77ae3-78e8-56c5-2b89-29b5a3ce9d3f.png)
引用元: 『HTTPとは？HTTPSとの違いをサイト移行で実施するリダイレクト設定などをもとに解説』 [アイティーエムHPより](https://www.itmanage.co.jp/column/about-http-https/)

# 事前準備
### TROCCO®アカウントの作成
まずはTROCCO®のアカウント作成から始めましょう。
TROCCO®では無料で利用開始できるフリープランがあります。

https://trocco.io/lp/index.html

### スマレジアカウントの作成
スマレジのアカウントの作成も行いましょう。こちらも無料で作成することが可能です。

:::note warn
本記事ではスマレジのアカウント上に取引データがあることを前提としています。
:::

https://smaregi.jp/

# スマレジAPIの認証設定
次にスマレジAPIの認証設定を行います。

:::note warn
API(Application Programing Interface)という用語がわからない方は、[こちらの記事](https://www.ntt.com/business/sdpf/knowledge/archive_10.html)などを参考にしてください。
:::

認証設定には以下2つのステップで行なっていきます。

- スマレジ・デベロッパーズの作成
- TROCCO®でのOAuth2.0認証・認可の設定


なお、今回APIの認証方法として、OAuth2.0という方式を採用します。

OAuth2.0とは、ユーザーが直接情報を入力することなく、WEBサーバーが間接的に発行したユーザー情報を認証する方法になります。
そのため、セキュリティ的に優れた認証・認可の仕組みになります。

OAuth2.0の詳しい仕組みを知りたい方は、Google Cloud [OAuth2.0の概要](https://cloud.google.com/apigee/docs/api-platform/security/oauth/oauth-introduction?hl=ja)などを参照してください。

また、今回は実際にスマレジにある取引データを取得するため、本番環境を想定した設定を行います。

開発環境と本番環境の詳細に関しては、スマレジ・アプリマーケット公式noteの下記サイトから確認ください。

https://note.com/smaregi_devtaro/n/nac3b9b7e1b3a
### スマレジ・デベロッパーズの作成
スマレジAPIを利用するにあたって、スマレジ・デベロッパーズを利用します。
まずアカウントを作成します。
スマレジ・デベロッパーズのサイトから、「無料でアカウントを作成」を押し、氏名・メールアドレス・住所等の情報を設定し、「アカウントを作成する」を押します。

https://developers.smaregi.jp/

![スクリーンショット 2024-07-08 19.38.19 2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/3ba87280-d73e-66dc-f5d1-9b7b425820d1.png)

アカウント作成後、登録したメールに「ログイン情報、パスワード、契約ID、ログインURL」の記載されたものが送られてきます。

![スマレジアカウント作成.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/93c5e12d-6eb9-cbd9-35fb-8babd5ae29d2.png)

ログイン後、アプリの登録を行います。
今回は自社の店舗情報を取得するためだけにAPIを使うため、「プライベートアプリケーション」の登録を行います。
プライベートアプリケーションの詳細は下記記事を参考にしてください。

https://note.com/smaregi_devtaro/n/ne44d7bafb316

スマレジデベロッパーズの画面から、「アプリ」を選択し、「プライベートアプリを新規登録」のボタンを押します。

![スクリーンショット 2024-07-04 16.16.42 2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/efea0702-e033-b0da-21c0-662bfb692498.png)

基本情報として、アプリ名とアイコンを記入し、登録ボタンを押します。

![スマレジプライベートアプリ登録.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/5908b5c8-0b71-3861-c550-d8d1c8b7130b.png)

登録終了後、ご契約中のスマレジとの紐付けを行います。

利用状況から、利用契約IDにご契約中のスマレジIDを記載し、アクティベートボタンを押します。

![1_スマレジ_アクティベート.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/00dec230-cdf1-1471-5a61-4a4f2d52df62.png)

![2_スマレジ_アクティベート承認メール確認.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/513c834b-ac7b-8381-6a37-e5cb03713ce0.png)

送信されたメールのURLから、契約IDとプライベートアプリとの紐付けを行います。

![3_アクティベート承認メール.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/e1c42070-7925-105e-382b-d8d273b11860.png)

利用開始にあたり、契約内容の確認が求められ、問題ないかを確認したのち、「上記内容で申し込む」を押します。

![4_スマレジ申込画面.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/33bf6743-0e16-4af0-44e6-8ae03f889c19.png)

![5_スマレジ申込画面2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/61600c37-bd5b-96b4-01f3-5309277a1f61.png)

申し込み終了後、申請が反映され、メールでも変更内容のお知らせがきます。
こちらで、契約IDとプライベートアプリとの紐付けが完了となります。

![7_スマレジ_アクティベート承認メール.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/587ddb05-eef2-feb3-e227-dd633a236f14.png)

紐付け終了後、環境設定を行なっていきます。
リダイレクトURIについて、TROCCO®側で認証できるような設定にする必要があります。
TROCCO®ヘルプセンター[「HTTP・HTTPSの接続情報」](https://documents.trocco.io/docs/connection-configuration-http-https)の「入力項目>クライアントアプリ設定情報」をもとに、以下のように設定します。

```
https://trocco.io/connections/http/callback
```

また、後の章で出てくる`スマレジ・デベロッパーズ上のクライアントID`と`スマレジ・デベロッパーズ上のクライアントシークレット`はこの画面から確認してください。

![スマレジアプリ側の設定.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/5402669a-6ead-992c-6fd4-17f13c12dc90.png)

最後に「スコープ」の設定を行います。
今回は取引で用いる`pos.transactions.read`にチェックボックスをつけて、保存ボタンを押下して、スマレジ・デベロッパーズの作成・設定が完了です。

![スマレジスコープ設定.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/c15da156-e93a-0581-7ac8-fd93b720f8da.png)

### TROCCO®でのOAuth2.0認証・認可の設定
次に作成したスマレジ・デベロッパーズの情報を元に、TROCCO®上でスマレジAPIの認証設定を行なっていきます。

まず、TROCCO®のホーム画面の「接続情報一覧」から「接続情報の新規作成（サービスの選択）」>「HTTP・HTTPS」を選択します。

![スクリーンショット 2024-07-22 17.28.05 2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/c27407d8-e9ca-cc02-ed17-02f573cea35f.png)

「HTTP・HTTPS」選択後、「接続情報の作成・設定」画面に遷移し、「作成したアプリ情報の入力へ」ボタンを押下します。

![スクリーンショット 2024-07-22 17.26.44 2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/b2e228c3-b882-4c66-9b05-ec7f1ed12c3c.png)

画面遷移後、スマレジアプリの認証情報を入力していきます。

TROCCO®ヘルプセンター[「HTTP・HTTPSの接続情報」](https://documents.trocco.io/docs/connection-configuration-http-https)とスマレジAPI公式の[「ログイン」](https://developers.smaregi.dev/apidoc/common/#section/%E3%83%AD%E3%82%B0%E3%82%A4%E3%83%B3)を参考に、以下の表のように設定していきます。
表にない設定項目は、初期設定のまま変更なしで問題ありません。

|設定項目|内容|
|:-|:-|
|グラントタイプ|認可コード|
|クライアントID|`スマレジ・デベロッパーズ上のクライアントID`|
|クライアントシークレット|`スマレジ・デベロッパーズ上のクライアントシークレット`|
|認可URL|`https://id.smaregi.jp/authorize`|
|アクセストークンURL|`https://id.smaregi.jp/authorize/token`|
|スコープ|pos.transactions.read offline_access|

![trocco接続情報.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/b0aca4de-d18b-689e-e2a6-0e5d7c2570f1.png)

設定終了後、認証の確認ができれば完了です。

これで、「スマレジAPIの認証設定」の全工程が終了となります。

# 転送設定の実装
最後にTROCCO®でデータを取得していきます。
今回の記事では、転送先にはデータウェアハウスの[Google BigQuery](https://cloud.google.com/bigquery?hl=ja)を採用しました。

では、実際の転送設定に移っていきます。
TROCCO®にログインし、転送設定の新規作成に進み、以下を選択します。
- 転送元 HTTP・HTTPS
- 転送先 BigQuery

![スクリーンショット 2024-07-24 14.36.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/1f627f3e-d4c5-0017-7be8-74f0163c62bd.png)

### 転送元設定
初めに、「TROCCO®上のOAuth2.0の認証・認可の設定」の章で設定した「HTTP・HTTPS」接続情報を選択します。

カスタム変数機能についても設定を行います。
今回はスマレジAPIのパラメータで使用する、`$transaction_date_time-from$`と`$transaction_date_time-to$`を設定します。

[スマレジAPIの公式ページ](https://www1.smaregi.dev/apidoc/#operation/getTransaction)を参考に、TROCCO®の日付フォーマット上は`%Y-%m-%dT%H:%M:%S±TZD`と設定します。
なお、TZDのところは日本時間の`+09:00`で今回は設定しています。

![転送元設定1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/b1fd1baf-c856-d01e-03ff-dea0ad1fb092.png)

TROCCO®で設定する際は以下表の通りとなります。
表にない設定項目は、初期設定のまま変更なしで問題ありません。

|設定項目名|設定内容|
|:-|:-|
|URL |`https://api.smaregi.jp/{契約ID}/pos/transactions` |  
|HTTPメソッド |GET|
|文字エンコーディング  |UTF-8|
|ファイル入力形式|JSONPath|
|JSONPath|$|
|パラメータ`transaction_date_time-from` |`$transaction_date_time-from$`|
|パラメータ`transaction_date_time-to` |`$transaction_date_time-to$`|
|HTTPヘッダ`Content-Type`|application/x-www-form-urlencoded　|

![転送元設定.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/fc24b365-a347-8e7b-ecbe-ca135c977c64.png)

URLの`{契約id}`については、スマレジ・デベロッパーズ登録時に送られてきたメールから確認できるほか、スマレジ・デベロッパーズの画面左上からも確認できます。

![スクリーンショット 2024-07-09 11.12.31 2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/9e5a170e-fafb-c840-554f-c8faa0efe55e.png)

パラメータ`transaction_date_time-from`と`transaction_date_time-to`は、「取得する取引データの開始日時」と「取得する取引データの開始日時」をそれぞれ指します。

今回は例として、10日前からその時点までのデータを想定した設定にしました。
パラメータの詳細は、スマレジAPI公式の[「取引一覧取得」のQUERY PARAMETERS](https://www1.smaregi.dev/apidoc/#operation/getTransaction)をご確認ください。

### 転送先設定
転送先設定にて、Google BigQuery接続情報、データセット、テーブル、データセットのロケーション、転送モードを設定します。

![転送先設定.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/93f3f840-bfce-04a5-2144-d768a85b1025.png)

STEP2の画面に進むと、転送するデータのプレビューを確認することができます。

![プレビュー.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/58b9a72b-36c5-1971-cd3b-31534ce05a96.png)

取得できる項目はスマレジAPI公式の[「取引一覧取得」のResponse samples](https://www1.smaregi.dev/apidoc/#operation/getTransaction)からご確認ください。

テーブル定義やデータ型などは自動設定のままで問題ないので、確認・保存と進みます。

# 実行結果
転送実行後、BigQueryのプレビュー画面で、転送したデータが入っていることを確認できました。

![BQプレビュー.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2725527/31bc2f9f-6b61-2f3c-e3a6-8256057fd06e.png)

# まとめ
今回は、TROCCO®のHTTPコネクタを活用して、スマレジの取引データをBigQueryに転送する方法を紹介しました。

取引のデータを活用すれば、売上や消費者動向にまつわる様々なユースケースの分析が可能になります。スマレジを活用して店舗運営されている方は、ぜひ活用してみてください！