こんにちは！エンジニアの君島です。
高機能クラウドPOSレジであるスマレジには、連携用のAPIが用意されています。それらを用いて、開発者が独自に開発したアプリケーションをマーケットに公開して、スマレジを利用しているユーザーに販売することも可能です。
本記事では、スマレジ・プラットフォームAPIを呼び出す手順を記載します。
スマレジ®は、株式会社スマレジの登録商標です。ロゴについてもガイドラインに準拠して使用します。
目次
開発の概要
スタートガイドに沿って進めていきます。
APIを呼び出す手順については、スマレジ・プラットフォームAPI 共通仕様書を参考にします。
各種のAPIを呼び出す際は、個別の仕様書を参考にします。
POSの場合は、スマレジ・プラットフォームAPI POS仕様書を参照します。
また、APIを呼び出すのにPostmanを利用することにします。
開発者アカウントを取得する
スマレジDevelopersからアカウント登録を実施します。
以下スマレジDevelopersのサービスサイトより引用です。
スマレジ・デベロッパーズは、開発したアプリの公開や、利用状況の管理などを行う環境を指します。
ご登録いただくと、充実のAPIとサンドボックス、弊社スタッフによるフォローをすべて無料でご利用いただけます。
とのことなので、まずはアカウント登録してみましょう。
アプリを登録する
アカウント登録が完了したら、ログインしてアプリケーションを新規作成しましょう。
メニューには、パブリックアプリとプライベートアプリがありますが、今回はテストで利用するためスマレジの審査がないプライベートアプリで作成します。
必要な情報を入力して新規作成を行います。
APIを実行するための情報を取得する（WEBアプリの場合）
クライアントIDとクライアントシークレットを確認する
アプリの作成が完了したら、スタートガイド記載の通りに確認しましょう。以下引用です。
アプリを新規登録すると、クライアントIDとクライアントシークレットが発行されます。
アプリの「環境設定」ページにて参照できます。
とのことですので、以下のように新規作成したアプリの環境設定を確認して、記載されているクライアントIDとクライアントシークレットを記録しておきます。
アプリアクセストークンを取得する
さて、今度はスマレジ・プラットフォームAPI 共通仕様書を読みながら進めましょう。
データの参照、更新をAPI経由で行うためには、アプリユーザーのアクセストークンを取得する必要があります。
それでは、実際にPostmanを用いながらサンドボックス環境でのアクセストークンを取得してみましょう。
以下を指定して実行してみましょう。
| 項目 | 値 |
| HTTPメソッド | POST |
| Request URL | https://id.smaregi.dev/app/{契約ID}/token ※1 |
| Authorization>Type | Basic Auth |
| Authorization>Username | クライアントID(上記で記録したもの) |
| Authorization>Password | クライアントシークレット(上記で記録したもの) |
| Headers | Content-Type:application/x-www-form-urlencoded |
| Body | grant_type:client_credentials |
| Body | アクセストークンで有効なスコープリスト※2
例) scope:pos.products:read pos.transactions:write |
※1 {契約会社ID}は、スマレジDevelopersにログインすると左上に表示されていますので、そちらから確認してください。
※2 アクセストークンで有効なスコープリストとは、APIごとにスコープスクリプトが指定されています。
APIごとに実行可能な権限を指定してあげる必要があります。上記の例では、商品/部門の参照と取引/予算の更新ができるように記載しています。
POSのAPIで指定可能なスコープスクリプトの一覧はコチラ。
実行したレスポンスの例は以下となります。
|
1 2 3 4 5 6 |
{ "scope": "{SCOPE_NAME} {SCOPE_NAME} {SCOPE_NAME}", "token_type": "Bearer", "expires_in": 3600, "access_token": "{ACCESS_TOKEN}" } |
{ACCESS_TOKEN}を記録しておきましょう。expires_inは有効期限(秒)ですので、この出力結果の場合は3600秒＝60分間有効なトークンとなります。
ここまで、スタートガイドとスマレジ・プラットフォームAPI 共通仕様書に従って実施していきました。
以降では実際にAPIを呼び出してみましょう。
APIを呼び出す
（取得系）商品取得
スマレジDevelopersにログインした後、POSの画面を開きましょう。画面右上のボタンからPOS、Waiterなどのサービスも選択することができます。
まずはPOSから商品情報を新規作成しておきます。例えば、以下のように設定したとします。
Postmanから商品取得のAPIをコールしてみましょう。
詳細な手順はスマレジ・プラットフォームAPI POS仕様書のコチラから確認してください。
以下をPostmanに指定して実行してみましょう。200 OKのレスポンスと商品一覧のjsonが戻ってきたら成功です。
| 項目 | 値 |
| HTTPメソッド | GET |
| Request URL | https://api.smaregi.dev/{契約ID}/pos/products |
| Authorization>Type | Bearer Token |
| Authorization>Token | {ACCESS_TOKEN} |
（更新系）取引登録
今度はPostmanから取引登録のAPIをコールしてみましょう。
詳細な手順はスマレジ・プラットフォームAPI POS仕様書のコチラから確認してください。
| 項目 | 値 |
| HTTPメソッド | POST |
| Request URL | https://api.smaregi.dev/{契約ID}/pos/transactions |
| Authorization>Type | Bearer Token |
| Authorization>Token | {ACCESS_TOKEN} |
| Body | Request json※3 |
※3 仕様書を確認しながら、最低限必須の項目を含めるようにしてください。なお、取引明細(details)が必須となっていますので、含めておきましょう。
また、json内の各項目については一定の制約が存在しています。違反していた場合はAPIが失敗するので、出力結果をよく見てリクエストを修正しましょう。
例えば、以下のようなBodyを設定して成功することを確認しました。
商品情報は上記で設定したものを流用しています。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ "transactionHeadDivision":"1", "subtotal":100, "taxExclude":10, "total":110, "storeId":1, "terminalId":1, "terminalTranId":"2112270001", "terminalTranDateTime":"2021-12-27T19:27:29Z", "details": [ { "transactionDetailId":"001", "parentTransactionDetailId":"001", "transactionDetailDivision": "1", "productId": "800002", "productName": "YouWire Office", "printReceiptProductName": "YW Office", "taxDivision": "1", "price": "100", "salesPrice": "100", "quantity": "1" } ] } |
API実行結果が200 OKとなれば成功です。
POSから取引一覧を確認してみましょう。以下のようにAPIで登録した取引が追加できていることがわかります。
まとめ
本記事ではスマレジ・プラットフォームAPIをコールする手順についてまとめました。
- CLIでAmazon S3にあるファイル内の文字列検索をしてみる - 2024-02-01
- 不完全なマルチパートアップロードをCLIで確認してS3の無駄コストを無くそう - 2024-01-29
- AlmaLinux9.3にPHP8.3を入れてLaravel9から10にバージョンアップする - 2024-01-12
- AWS CloudShellの表現力を確認してみよう - 2024-01-01
- AWSのアーキテクチャーを学べるAWS Card Clash攻略Wiki - 2023-12-26
【採用情報】一緒に働く仲間を募集しています
