【スマレジアプリを作ってみた#4】アプリ実装（Webhookを使った取引情報の取得方法）

さて早いもので【スマレジアプリを作ってみた】シリーズも4回目となりました！

[前回](https://qiita.com/JoBins/items/5b3eee45324466b01a64)は、引換券モニターの認証機能と
アクセストークンを使って店舗情報を取得する方法についてお伝えしましたが、
今回はアプリ実装編ということで、webhookを利用して
スマレジから注文取引の詳細を取得する方法について説明します。

## データベース構造

契約、ユーザー、店舗、および注文情報を処理するための引換券モニターの
基本的なデータベース構造は次のようになっています。

![Database Design For Queue Monitor.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/a897c321-7227-0819-d234-f02af48a4772.png)

## Webhook

スマレジPOSシステムで（pos.transactions：read pos.transactions：write）などの特定のイベントが発生すると、
Webhookが引換券モニターに通知します。
このセクションでは、スマレジPOSシステムでのWebhookの動作の概要と、
スマレジPOSシステムの取引情報に関連するwebhookの使い方について具体的に説明します。

また、Webhookの使い方の詳細については[こちら](https://developers.smaregi.dev/apidoc/common/#section/Webhook)もぜひご参照ください。


### Webhookを有効にする
Webhookを利用できるようにするために、
まずはアプリの環境設定ページでWebhook送信先エンドポイントURLがあるかどうか確認します。

![環境設定-Qmonitor-ammar-アプリ-スマレジ・デベロッパーズ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/e9166c94-5334-4285-e104-c088afa2c2cb.png)

Webhook送信先エンドポイントURLを入力した後、「Webhook」タブに移動し、
「Webhookの利用」のボタンをオンにします。
下のスクリーンショットにもあるように、送信するイベントを選択することもできます。


![webhook-enable2.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/e4b7f154-7e86-d710-e247-f86b6f0701ca.png)


### リクエスト
Webhookイベントが発生した際、スマレジサーバーは
下記のリクエストをWebhook送信先エンドポイントに対してPOSTします。


**Header**

| フィールド名                           | 値/説明 |
| ----------------           | ----------------------- |
| `Content-Type`                      | application/json |
| `Smaregi-Contract-Id`             | イベントの発生した契約ID |
| `Smaregi-Event`             | イベント名 |
| Webhook設定画面にてカスタムヘッダーに設定したフィールド名             | 値 |

**Body**

| フィールド名                           | 値/説明 |
| ----------------           | ----------------------- |
| `action`                      | イベントに対して発生したアクション名詳細は各API仕様書の各イベント参照例) created : 登録、edited : 更新 |
| (PK項目)             | PK項目の項目名と値については各API仕様書の各イベント参照<br /> ※一括処理(アクションが bulk〜 )の場合、更新対象のIDは通知されないため、必要に応じて対象リソースの再取得を行ってください。 |

特定のWebhookイベントとそのペイロードの詳細については、[こちら](https://www1.smaregi.dev/apidoc/#tag/Webhook)を参照してください。




```
{
  "contactId": "string",
  "event": "string",
  "action": "created",
  "transactionHeadIds": [
    "1",
    "10",
    "12"
  ]
}
```
上記は、Webhookリクエストのサンプルです。
Webhookから `transactionHeadIds`を受け取った後、
取引情報の全詳細を取得するためスマレジAPIにリクエストを送信することができます。
詳細は[こちら](https://www1.smaregi.dev/apidoc/#operation/getTransactionId)を参照してください。


### 引換券モニター上でWebhookをハンドルする
スマレジAPIから取引情報を取得した後、データベースに詳細を入力し、
アイテムをプッシュして次のスクリーンショットのように
スタッフモニターとカスタマーモニターに表示します。


![staff monitor.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/5c182341-4d4d-4dae-8038-69d05aa70d95.png)

![customer-monitor.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/8509844e-9573-b2d2-9cd1-275ab65be239.png)


開発中Wenhookをコントロールするために、私たちはトンネルツールとしてngrokを使いました。
ローカルでngrokを使う方法については、次で説明します。


## Webhookをローカルでハンドルする

Webhookの開発、テスト、およびデバッグに役立つサードパーティツールを紹介します。



| Tool                       | Description     |
| ----------------           | ----------------------- |
| [ngrok](https://ngrok.com/)                      | ローカルWebサーバーをインターネットに公開出来るサービス |
| [Webhook Tester](https://webhook.site/#/)             | Webhookと他のタイプのHTTPリクエストをブラウザでテストできるサービス |

今回の引換券モニター作成時は、ngrokをWebhookのテストとデバッグのため使用しました。

### ngrok
ngrokは、アプリケーションをローカルでテストする時に、
スマレジサーバーが引換券モニターに送信するWebhookレスポンスを
指定したURLで見れる便利なツールです。
ngrokは、ローカルホストで実行されているアプリケーションにアクセス可能なトンネルURLを作成します。
ngrokを使用すれば、そのローカルのWebインターフェースで
HTTP/HTTPSリクエストの詳細を見ることができます。

ngrokの詳細については、こちらの[公式サイト](https://ngrok.com/docs)をご覧ください。



１. ngrokで `ngrok http 80`をスタートします。

![Screenshot from 2021-01-06 13-34-54.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/655a1506-2236-7789-457f-a63790043df0.png)

上記のコマンドは、ローカルホストのポート80へのトンネリングを開始し、
`https：//{id}.ngrok.io.`といったURLを提供します。
このURLを使用すると、インターネットからローカルホストにアクセスできます。


２. 次のスクリーンショットのように、Webhook送信先エンドポイントURLをngrokから受信したURLに置き換えます。
![環境設定-Qmonitor-ammar-アプリ-スマレジ・デベロッパーズ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/e9166c94-5334-4285-e104-c088afa2c2cb.png)

３. Webhookイベントをトリガーする

取引がスマレジPOSシステムで作成されると、Webhookがトリガーされます。
注文作成エンドポイントへのAPI呼び出しを介して手動で注文を作成することにより、
Webhookをトリガーすることもできます。

a. スマレジPOSシステムで新規取引を作成
b. チェックアウトをクリック

![IMG_0011.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/cb75bda4-a87d-571c-37c5-caa87501c1e8.png)


４. ngrokURLにスマレジサーバーから送信されたWebhookリクエストはローカルホストに繋がります。
　ブラウザでhttp://127.0.0.1.404 を開くと、リクエスト詳細を見ることができます。


![ngrok-Inspect-2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/908996/bf61a9cf-7b92-5cbf-50b0-4e0662b5d0a4.png)


## 注意点

### ページネーション

`GET` のAPIを利用する際はページネーションに気をつけてください。
一覧を取得するAPIでは1回で取得できる件数に上限があり、
上限を超える場合はページまたはカーソルを指定する必要があります。

**ページ**
`page` に1から始まるページ番号を指定してください。

**カーソル**
`cursor` に取得する一覧の先頭にしたいデータの識別子を指定してください。
指定無し、または"-1"を指定して最初の一覧を取得できます。


## まとめ

ということで、今回はWebhookの使い方、受信サーバーのセットアップ方法、
ngrokの使い方などアプリ実装の詳細についてお送りしました。
次回は「Sandboxでの動作確認（テスト）」についてお届けします！