フォローする

スマレジAPIからプラットフォームAPIへの移行手順

dev_b.png
スマレジは外部システムと連携する方法としてAPI連携機能を提供しており、『スマレジAPI』と『プラットフォームAPI』の2種類があります。
スマレジAPIは将来的に廃止を予定しています。
廃止時期が決まりましたら移行期間を設けたうえで事前にお知らせいたします。(2024年5月時点で時期未定です。)
このページでは、両者の違いやプラットフォームAPIの利用方法、移行に際する注意事項などをご案内いたします。

スマレジAPIとは

『スマレジAPI』は従来より提供しているAPIで、スマレジ管理画面にて設定を行ないます。
仕様書のダウンロードや開発・検証を行なうには開発者がスマレジのアカウントを取得する必要があるなど、次のような課題が存在しました。

ユーザーの課題
  • 独自に開発するためのコストがかかる
  • 自社開発が不可だった場合に開発会社を探す必要がある

開発会社の課題
  • 受託開発のため横展開をすることが難しい
  • 広くユーザーを獲得することができない

この課題を解決するための新たな方法が、『スマレジ・デベロッパーズ』です。

スマレジ・デベロッパーズとは

スマレジでは、2020年にスマレジのアプリケーションプラットフォーム『スマレジ・アプリマーケット』を公開しました。
スマレジがプラットフォーマーとなることで、開発者がサービスをスマレジユーザー向けに提供可能になり、ユーザーは自身の運用や利用状況にあわせたサービスを探し、利用・購入することが可能になりました。

開発者はアプリマーケットにサービスを公開するために『プラットフォームAPI』を利用します。
スマレジAPIの仕様書はスマレジ管理画面からしかダウンロードできませんでしたが、プラットフォームAPIの仕様書は誰でも閲覧可能なスマレジ・デベロッパーズのホームページからダウンロードできます。
主な特徴
基本的にアプリマーケットに公開してご利用いただいております。
(公開範囲を設定したり、公開せずに利用することも可能です)
そのため、外部システムと連携するためにはアプリとして登録し、登録したアプリにて連携設定も行ないます。

アプリの登録・設定などはすべて開発者専用のデベロッパーズアカウントで行なうため、スマレジAPIのように設定などをユーザーが行なう必要がなくなります。

ユーザーは、アプリマーケットに公開されたアプリを購入することで利用できるようになります。
開発環境について
スマレジAPIでは、設定や検証はすべて、通常アカウントを作成し、試用期間などで検証する必要がありました。
プラットフォームAPIでは、デベロッパーズアカウントに各プロダクトの管理画面も用意しており、検証用のアカウントとしてご利用いただけます。

デベロッパーズアカウントの環境を開発環境(サンドボックス環境)、ユーザーが利用する環境を本番環境(プロダクション環境)といい、リクエストのエンドポイントなどが開発環境と本番環境で異なります。
詳細については、こちらのヘルプページをご覧ください。

スマレジAPIとプラットフォームAPIの違い

連携設定
スマレジAPIでは、スマレジ管理画面からAPI連携の設定を行なう必要がありましたが、プラットフォームAPIでは、デベロッパーズアカウントにて設定を行ないます。
設定をするために必ず『アプリ』として登録する必要があり、アプリ単位での設定になるため、複数のシステムとの連携も容易になります。
APIで登録した内容の送信機能
スマレジAPIでは、送信機能の利用をONにしてもAPI経由のデータの登録や更新の通知はされませんでしたが、プラットフォームAPIでは、APIでデータの登録や更新を行なうとWebhookにて通知を受け取ることができます。
Webhook
スマレジAPIの送信APIでは、全項目の情報が通知されていましたが、プラットフォームAPIでは、イベント名(商品など)とアクション(登録・更新・削除など)、主キーである項目(商品IDなど)の通知のみです。
通知された情報をもとに、取得APIを利用してデータを取得する必要があります。
具体的な通知内容は仕様書をご確認ください。
スマレジ・タイムカードでは、現在Webhook機能の提供はありません
Webhook送信後『3秒以内』にレスポンスを受信できなければ、エラーとして扱い送信処理を終了します。
スマレジAPIでは、送信履歴を確認でき、再送信も可能でしたが、プラットフォームAPIでは、履歴の確認も再送信も行なうことができません。
エラーが発生しても問題ない仕組みづくりを行なう必要があります。
送信履歴と再送信機能の追加について、現在検討中です

スマレジAPIでできてプラットフォームAPIでできないこと

送信履歴と再送信機能
スマレジAPIとプラットフォームAPIの違いにも記載しましたが、プラットフォームAPIでは、Webhookの送信履歴と再送信機能がありません。
受信ログは必ず残し、エラーにも対応できるように開発する必要があります。
送信URL / ヘッダ情報 / パラメータ情報の個別設定
スマレジAPIでは、送信URL / ヘッダ情報 / パラメータ情報を機能ごとに個別で設定できましたが、プラットフォームAPIでは、アプリ単位での設定となります。
送信URL / ヘッダ情報 / パラメータ情報を機能ごとに設定したい場合は、それぞれ別のアプリとして登録する必要があります。
マスタのID指定
スマレジAPIでは、登録と更新を同じAPIで行っていたため、マスタを新規登録するときに一部項目では、IDを指定して登録することができましたが、プラットフォームAPIでマスタの登録を行なう際はIDを指定することができず、最大値 +1 の値が自動採番されます。
エラーメールの送信
スマレジAPIで連携しているとき、エラーが発生すると指定したメールアドレス宛にエラー内容を送信することができましたが、プラットフォームAPIでは、メールへの送信機能がありません。
レスポンスログからエラー内容を確認する必要があります。
弊社にお問い合わせいただいても回答できない可能性がありますので、必ずログを残してください
スマレジに関する機能について
  • スタッフの登録・更新(取得は可能)
  • 取置き登録APIや仮販売登録APIで『クーポン値引き』の指定
  • 日次締め情報取得APIで客数の取得
スマレジ・ウェイターに関する機能について
  • メニューの登録・更新(取得は可能)
  • テーブルの移動や分割・結合
その他、スマレジAPIでできてプラットフォームAPIでできない機能がありますので、仕様書をご確認いただき、不明点があれば利用したい機能を記載してサポートへお問い合わせください。

スマレジAPIでできなくてプラットフォームAPIでできること

スマレジ・タイムカードAPI
スマレジAPIでは、スマレジ・タイムカードに関するAPIの用意がありませんでしたが、 プラットフォームAPIでは、スマレジ・タイムカードに関するAPIも追加しました。 機能の追加も予定されておりますので、ぜひご利用ください。
お知らせについて
スマレジAPIでは、APIに関するお知らせもユーザーへ送られていましたが、プラットフォームAPIでは、デベロッパーズアカウントにログインすることで、トップ画面からAPIに関するお知らせをご確認いただけます。
スマレジに関する機能について
  • 商品に関するAPI(属性やアイコン画像の登録が可能)
  • 仮販売に関するAPI(仕様書
  • 精算に関するAPI(仕様書
  • その他支払いに関するAPI(仕様書
  • 会員ランクに関するAPI(仕様書
そのほかにも様々な機能を追加しておりますので、ぜひ仕様書をご確認ください。
スマレジ・ウェイターに関する機能について
今後の機能追加はプラットフォームAPIのみになり、上記に記載した通り様々な機能がプラットフォームAPIでのみ追加対応を行なっています。
現在、スマレジAPIでできてプラットフォームAPIでできないことも、プラットフォームAPIで対応予定です。

プラットフォームAPIの利用方法

本文中の画像はクリックすると大きなサイズで表示されます
  1. デベロッパーズアカウントを登録します
    developers_01.png
    developers_01.png
    こちらのURLから、デベロッパーズアカウントの作成を行ないます。
    作成の詳細については、こちらのヘルプページをご覧ください。
  2. アプリを新規登録します
    アプリの登録方法には、パブリックアプリプライベートアプリの2種類があります。
    パブリックアプリは、スマレジ・アプリマーケットで公開され、購入者が誰でも利用できるアプリです。
    ユーザー自身が購入手続きを行なうことで利用可能になります。
    プライベートアプリは、アプリマーケットで公開せずに利用することを目的としたアプリです。
    開発者がアクティベート操作を行なうことで利用可能になります。
    【パブリックアプリの場合】
    developers_17.png
    developers_17.png

    ログインし、『アプリ > パブリックアプリ』をクリックします。

    【アプリを新規登録】をクリックします。
    チュートリアルに沿って、下記の表の項目を設定してアプリを新規登録します。

    項目 説明
    アプリ区分
    必須
    WEBアプリ インターネットを通じてブラウザ上で動作するアプリケーションで、特定のOSに依存せずに利用できます。
    スマレジAPIでは『WEBアプリ』への対応のみだったため、基本的にはこちらをご利用いただければ問題ないかと思います。
    ネイティブアプリ 特定のデバイスやOSに最適化されたアプリケーションで、ユーザーはApp StoreやGoogle Playなどからインストールして利用します。
    ユーザーのログイン認証が必要で、特定のユーザーにのみアクセス権限が与えられるため、WEBアプリと比較してセキュリティが強くなります。
    スマレジ iOS URL
    Schema 連携アプリ
    スマレジ・アプリから外部のアプリへ連携させるために利用します。
    他2つのアプリ区分と挙動が全く異なるため、こちらのヘルプサイトではなく仕様書をご確認いただき、不明点があればサポートまでお問い合わせください。
    サービス種類 『スマレジ iOS URL Schema 連携アプリ』を選択時に設定します。
    現在は決済連携のみが選択可能です。
    アプリ名
    必須
    アプリの名称を登録します。
    (45文字以内)
    バージョン
    必須
    アプリのバージョンを登録します。
    (32文字以内)
    【プライベートアプリの場合】
    developers_18.png
    developers_18.png

    ログインし、『アプリ > プライベートアプリ』をクリックします。

    【プライベートアプリを新規登録】をクリックします。
    下記の表の項目を設定してアプリを新規登録します。

    項目 説明
    アプリ区分
    必須
    WEBアプリ インターネットを通じてブラウザ上で動作するアプリケーションで、特定のOSに依存せずに利用できます。
    スマレジAPIでは『WEBアプリ』への対応のみだったため、基本的にはこちらをご利用いただければ問題ないかと思います。
    ネイティブアプリ 特定のデバイスやOSに最適化されたアプリケーションで、ユーザーはApp StoreやGoogle Playなどからインストールして利用します。
    ユーザーのログイン認証が必要で、特定のユーザーにのみアクセス権限が与えられるため、WEBアプリと比較してセキュリティが強くなります。
    アプリ名
    必須
    アプリの名称を登録します。
    (45文字以内)
    アイコン
    必須
    アプリのアイコン画像を登録します。
    (1MB文字以内)
    推奨サイズは512*512pxです。
  3. 環境設定を行ないます

    developer_plan_002.png

    アプリを新規登録すると、自動で『環境設定』タブが表示されます。


    developer_plan_003.png

    『開発環境』と『本番環境』の項目を入力し、クライアントシークレットをコピーして保管します。
    環境についてはこちらをご覧ください。

    入力完了後、【保存】をクリックします。

    入力項目の詳細については、下の表をご覧ください。
    項目 説明
    アプリのURL
    必須
    アプリのサービスURLです。
    ユーザーはこのURLからアプリを利用します。
    (2,083文字以内)
    サービスURLがない場合も任意のURLを設定する必要があります
    利用者契約通知先URL
    必須
    アクティベートされたとき、契約ID情報を送信する先のURLです。
    (2,083文字以内)
    利用者契約通知については、こちらの仕様書をご確認ください。
    Webhook送信先エンドポイント 各イベントの送信先URLです。
    (2,083文字以内)
    クライアントID アプリを新規登録すると自動採番されます。
    リダイレクトURI
    必須
    API認可に必要です。
    (255文字以内)
    何も指定しない場合は『urn:ietf:wg:oauth:2.0:oob』と入力してください。
    クライアントシークレット 開発環境と本番環境それぞれのクライアントシークレットを保管してください。
    クライアントシークレットは、アプリの作成直後しかコピーできないため、必ずコピーして保管してください。
    再発行は可能ですが、再発行を行なった場合それ以前のものは使用できなくなります

    ネイティブアプリの場合、項目は限られています

    ネイティブアプリでは『アプリURL』『クライアントID』『リダイレクトURI』のみで、その他の項目は存在しません。
  4. スコープの設定を行ないます

    developer_scope_002.png

    タブから『スコープ』をクリックします。

    設定を行なう、連携先のサービス名をクリックします。


    developer_scope_003.png

    スマレジAPIの受信設定(参照APIと更新API)と同じ項目をONにします。

    ほかにも利用したい機能があればONにします。

    設定完了後、【保存】をクリックします

    スコープの設定はユーザーが利用を開始する前であれば、いつでも機能を変更可能です

    必要な機能を一旦ONにしていただき、開発が終了した後に不要な機能をOFFにしてください。
    詳細については、各プロダクトの仕様書をご覧ください。
    (それぞれのAPIで必要な項目は『AUTHORIZATIONS: AppAccessToken』に記載されています)
    ユーザーの利用開始後に変更する場合は、ユーザーの同意が必要です
    詳細はこちらをご覧ください(デベロッパーズアカウントにログインが必要です)
  5. Webhookの設定を行ないます
    ネイティブアプリでは利用できません

    developer_scope_004.png

    タブから『Webhook』をクリックします。

    『基本設定』、『カスタムヘッダー』を設定し、連携先のサービス名を選択します。


    developer_scope_005.png

    WebhookはスマレジAPIの送信APIに該当します。
    送信設定と同じ項目をONにし、その他送信したいイベントもONにします。
    スマレジAPIと挙動が異なるため注意が必要です。
    詳細についてはこちらをご覧ください。


    developer_scope_006.png

    【保存】をクリックします

開発

まずは開発環境にて開発・検証を行ない、完了後本番環境にてリクエストを実行します。
開発環境と本番環境でエンドポイントが異なるのでご注意ください。

APIエンドポイント

仕様書はこちらからご覧ください。
  サンドボックス環境 本番環境
アクセストークンAPI https://id.smaregi.dev https://id.smaregi.jp
プラットフォームAPI https://api.smaregi.dev https://api.smaregi.jp

1. アクセストークンの取得

プラットフォームAPIでは、APIにてアクセストークンを取得する必要があります。
有効期限は3600秒なので、基本的にはAPIを利用するときは都度取得します。
アクセストークンの種類
アクセストークンには『アプリアクセストークン』と『ユーザーアクセストークン』の2種類があります。

『アプリアクセストークン』とは、アプリ単位で利用するスコープを指定して認証する方法です。
ユーザーのログイン認証が不要で、アプリのクライアントIDとクライアントシークレットを使って発行します。
仕様書はこちらからご覧ください。
取得方法はこちらのスマレジ公式note記事をご参照ください。

『ユーザーアクセストークン』とは、ユーザーのログイン認証を行ない、スマレジ管理画面で設定した権限と同等の制御を行なう方法です。
ネイティブアプリでは、ユーザーアクセストークンのみ利用可能です。
仕様書はこちらからご覧ください。

2. APIの実行

取得したアクセストークンを使って、APIの実行を行ないます。
項目などについては、各プロダクトの仕様書をご確認ください。
プラットフォームAPIでは、取得APIと登録API、更新API、削除APIなどに分かれています。
スマレジAPIは参照APIも更新APIもHTTPメソッドが「POST」でしたが、プラットフォームAPIは内容により、HTTPメソッドが異なります。
仕様書にそれぞれHTTPメソッドが記載されているので、確認して開発を行なう必要があります。
developers_03.png
developers_03.png

赤枠の部分がHTTPメソッドです。

取得API
取得APIはスマレジAPIの参照APIに該当し、スマレジのデータを取得したいときに利用します。
HTTPメソッドは『GET』です。
スマレジAPIで指定できた『conditions』項目はなく、QUERY PARAMETERSとして指定されている項目のみ、検索条件として指定することが可能です。
取得件数は最大1000件ですが、『limit』項目を指定しない場合は100件です。
仕様書にリクエストサンプルの用意はなく、レスポンス項目は「Responses >200 取得成功」を開くことで確認できます。
developers_04.png
developers_04.png

赤枠の箇所をクリックでレスポンス項目を確認できます。

developers_05.png
developers_05.png

仕様書にはレスポンスサンプルを用意しており、コピーも可能です。

developers_06.png
developers_06.png

エラーレスポンスのサンプルも用意しているので、エラーが発生した時は参考にしてください。

登録APIと更新API
スマレジAPIでは、新規登録したいときもデータの更新を行ないたいときも更新APIを利用していましたが、プラットフォームAPIは登録APIと更新APIに分かれています。
スマレジにデータを新規登録したいときは登録APIを利用し、HTTPメソッドは『POST』です。
スマレジに登録しているデータの更新を行ないたいときは更新APIを利用し、HTTPメソッドは『PATCH』もしくは『PUT』です。

スマレジAPIと違って1回のリクエストで複数のデータを登録・更新することはできず、1件ずつリクエストを行なう必要があります。
一括登録APIや一括更新APIを用意している機能もあります

登録・更新可能な項目はREQUEST BODY SCHEMAを確認してください。
レスポンス項目は『Responses >200 取得成功』を開くことで確認できて、リクエストサンプルとレスポンスサンプルも右側にあります。
削除API
APIを利用して削除を行なうことも可能で、削除APIのHTTPメソッドは「DELETE」です。
APIを利用して削除した場合は、論理削除です。
削除が成功した場合のレスポンスは200ステータスのみです。
一括登録APIと一括更新API
『登録APIと更新API』にも記載した通り、基本的には1件ずつの登録・更新になります。
ただし、一部機能は一括で登録・更新を行なうことも可能です。
HTTPメソッドは登録API・更新APIと同様に「POST」です。

登録・更新作業は非同期で処理されます。
リクエストを実行するときにコールバックURLを指定し、処理が完了したら指定したURL先に通知します。
一括登録・更新が可能な件数は機能ごとに定められていて、各APIの仕様書に記載されています。
リクエスト内容や件数次第では、処理が完了するまで時間を要する可能性がございますのであらかじめご了承ください
Webhook
WebhookはスマレジAPIの送信APIに該当します。
スマレジでデータが登録・更新されると指定したURLに通知されます。
スマレジAPIと挙動が異なるため注意が必要です。
詳細についてはこちらをご覧ください。 各プロダクトのWebhookに関する仕様書
スマレジ・タイムカードでは、現在Webhook機能の提供はありません
その他仕様書の見方やポイント
リクエスト項目やレスポンス項目の子階層に該当する項目は、折りたたまれています。
項目の説明欄に『Array of objects』と記載されている場合は折りたたまれているので、クリックして展開する必要があります。
developers_07.png
developers_07.png

赤枠の部分をクリックして展開してください。

子階層の項目やレスポンス内容は展開する必要があるため、折りたたまれた状態で『Ctrl + F』などで検索してもヒットしません。
ヒットしないから項目がないと判断しないようにご注意ください。
折りたたまれた状態でも検索できるような対応を検討中です

3. スマレジ・アプリなどにログインしての検証

スマレジ・アプリやウェイター・アプリ、タイムカード・アプリでの検証が必要になることもあるかと思います。
アプリをインストールしてそのままの状態だと、本番環境のアプリになるため、デベロッパーズアカウントでログインすることができません。
開発環境(サンドボックス環境)に切り替えて利用する必要があります。
切り替え方法についてはこちらのヘルプページをご覧ください。

4-1. 【パブリックアプリ】アプリマーケットへの公開

開発が完了したパブリックアプリをアプリマーケットに公開するためには、審査が必要です。
審査には『基本情報』の入力が必要なため、こちらのヘルプページをご参照のうえ設定を行なってください。
公開方法についてはこちらのヘルプページをご覧ください。
審査前に、スコープとWebhookの設定の見直しを行なってください
表示範囲の設定を行なった場合は、該当の契約IDでスマレジ・アプリマーケットにログインすることで作成したアプリが表示されます

アプリの内容を変更した場合は再申請が必要です

承認後にバージョンのアップデートや設定の変更を行なった場合は、再度申請を行なう必要があります。
再申請の場合も、審査には通常5営業日ほどお時間をいただきます。

また、スコープを変更した場合はユーザーの同意も必要です。
審査が完了するとユーザーにも通知され、ユーザーが承認することで設定の変更が適用されます。
詳細については、こちらのFAQをご覧ください(デベロッパーズアカウントにログインが必要です)。

4-2. 【プライベートアプリ】アプリのアクティベート

プライベートアプリでは、アプリマーケットに公開しないため審査などは不要です。
デベロッパーズアカウントにて、契約IDをアクティベートすることで本番環境でも利用が可能になります。
  1. 設定ページを開きます
    developers_11.png
    developers_11.png

    スマレジデベロッパーズにログインし、『アプリ > プライベートアプリ』をクリックします。

    設定を行なう、アプリの【概要を見る】をクリックします。

  2. アプリを利用する契約IDへとアクティベートします
    developers_12.png
    developers_12.png

    アプリを利用する契約IDを入力します。

    【アクティベート】をクリックします。

  3. 承認メールを送信します
    developers_13.png
    developers_13.png

    確認のポップアップが表示されるので、【はい】をクリックします。
    該当の契約IDに登録のメールアドレス宛に『【スマレジ】プライベートアプリアクティベート申請』という件名のメールが届くので、本文内のリンクをクリックします。
    次以降の手順は、メールを受信したユーザー側での操作です。

  4. 内容を確認します
    developers_14.png
    developers_14.png

    メール本文内のリンクをクリックすると左の画面が表示されるので、スクロールして内容を確認します。

  5. 利用規約に同意して申し込みます
    developers_15.png
    developers_15.png

    『利用規約』をクリックして内容を確認し、同意する場合はチェックを入れます。

    【上記の内容を申し込む】をクリックします。

  6. ログアウト/ログインを行ないます
    developers_16.png
    developers_16.png

    左の画面が表示されたら、一度ログアウトを行ない、その後ログインし直すことで、アプリを利用可能になります。

利用時の注意点

リクエストの回数制限
スマレジAPIでもリクエスト回数に制限を設けておりましたが、プラットフォームAPIでも制限を設けております。
制限内容については、こちらの仕様書をご確認ください。
サーバー保護のための制限になりますので、ご協力をお願いいたします。
お問い合わせについて
API連携に関するお問い合わせはメールでのみ受け付けております。
専門的な内容になるため、電話対応やチャット対応は行なっておりませんので、あらかじめご了承ください。
お問い合わせ先:support[アットマーク]smaregi.jp

リクエストやエラーに関するお問い合わせの場合、リクエスト内容やレスポンス内容を確認してご案内いたします。
リクエスト内容やレスポンス内容は開発者さまよりご提供いただいておりますので、ログは残すようにご対応いただければと存じます。
成功時もですが、エラー発生時は必ずご対応ください
この記事は役に立ちましたか?
0人中0人がこの記事が役に立ったと言っています
他にご質問がございましたら、リクエストを送信してください
このページの先頭へ