スマレジV4連携

目次

1.機能概要
2.受注データ連携(IN)(店舗受注データ)
3.会員データ連携(OUT)
4.ユーザーウェブへのバーコード表示


1.機能概要

本オプションは、スマレジ社が提供するクラウドPOSレジ「スマレジ(v4(プラットフォームAPI))」との連携が可能になる機能です。
「スマレジ」のサービス内容は公式ホームページをご覧ください。
https://smaregi.jp/


オプション導入にあたっての注意事項

・ご利用には、別途スマレジ様へのご利用申し込み手続きが必要です。
受注データ連携(IN)(店舗受注データ)会員データ連携(OUT)のAPI連携にのみ対応しています。
・会員データ連携(OUT)を利用する場合、スマレジの「プレミアムプラス」以上の料金プランを選択する必要があります。
 (スマレジのオプション「外部会員連携」機能を利用する前提のため)
・店舗様ごとの利用オプションとの併用可否については、導入時に影響調査が必要です。



「受注データ連携(IN)(店舗受注データ)」「会員データ連携(OUT)」共通の導入手順
STEP1. 弊社への申込み【店舗様】

本オプション利用の申し込みの旨を、弊社担当営業またはサポート窓口までご連絡ください。導入時の影響調査を行います。

STEP2. スマレジ様への申込み【店舗様】

スマレジ様へ、v4(プラットフォームAPI)の利用をお申し込みください。

STEP3. オプションの適用【弊社】

弊社にて、オプションをONにします。

その後、各連携機能の導入については、それぞれの導入手順をご確認ください。
受注データ連携(IN)(店舗受注データ)
会員データ連携(OUT)



2.受注データ連携(IN)(店舗受注データ)

1.基本動作
2.導入手順


1.基本動作

スマレジにて受注(取引)データが新規登録、更新、取消された際に、ebisumart zeroに対して受注データを連携します。
スマレジから受け取ったデータをもとに、ebisumart zero側の該当受注データ、ポイント履歴を更新します。
「新規受注登録時のみ」の連携とするか、「新規受注登録、更新、取消時」の連携とするかを、店舗様にて選択いただけます。


機能制限事項
・受注の連携タイミングは、 スマレジでの登録、更新、取消時のみです。
 一括更新、一括取り消し、削除、赤伝・返品、返品取消は連携対象外です。

・キャンセルした取引を連携する場合、スマレジ側で取引を「取消」してください。
 返品取消(消込レコード作成)した場合は、ebisumart zeroに連携されません。
 詳細な操作方法は、以下をご参照ください。※外部サイトに遷移します。
 スマレジ・ヘルプ(取引をキャンセルする)

・商品バリエーションは最大2つの掛け合わせ(例:カラー×サイズ)の受注データであることが前提です。

・ebisumart zero側で取消済みの受注については、スマレジ側で更新してもebisumart zeroへ連携されません。
 また、ebisumart zeroで受注を削除しても、スマレジ側の取引は削除されないため、スマレジ側でも取引を削除してください。

・ebisumart zeroの受注データは、スマレジ側へは連携されません。
 ebisumart zeroで受注を編集した場合などは、適宜スマレジ側の取引を手動で更新いただく必要があります。

・金額項目の桁数の上限が、スマレジ(20桁)とebisumart zero(8桁もしくは12桁)とで異なります。
 スマレジにて「8桁もしくは12桁」を超える金額が設定された受注は、ebisumart zeroに連携できません。


その他仕様、運用について
・受注ヘッダ自由項目を2項目利用します。うち1つは任意ですが、1つは必須です。

・スマレジから連携された受注の決済方法は、実際の決済方法にかかわらず「店頭決済」として登録します。

・ebisumart zero上に受注登録するため、売上レポート機能など各種集計データの対象になります。

・キャンセルした取引を連携する場合は、以下を実施してください。
 ・初期設定「スマレジV4連携:受注連携API利用有無」で「利用する(新規登録・更新・取消)」を選択
 (初期値として選択されています。)
 ・初期設定「スマレジV4連携:受注連携項目マッピング」に「cancelDateTime:CANCEL_DATE」を設定

・初期設定「スマレジV4連携:店頭受注でのポイント操作」および
 「スマレジV4連携:店頭受注でのポイント操作(受注更新・取消用)」を用いて、
 受注データ連携時にebisumart zeroのポイントの更新を行う場合に、スマレジから連携される「付与ポイント」について、
 ポイント還元率の設定は反映せず、連携値をそのまま「加算ポイント合計」に設定します。

・受注連携に失敗した場合の対応は、以下の通りです。
 ebisumart zeroへの受注登録、更新、取消の失敗とも、初期設定「スマレジV4連携:連携エラー時メール配信有無」が
 「配信する」の場合(初期値として選択されています)、店舗管理者メールアドレス宛にエラーメールが届きます。

 ▼受注データの[登録]に失敗した場合
 スマレジ管理画面にて取引データをもう一度登録し、再度連携を行ってください。
 または、弊社にてデータメンテナンスを行います。

 ▼受注データの[更新]に失敗した場合
 該当の受注データが存在しなかった場合:「受注データの[登録]に失敗した場合」と同様
 該当の受注データが存在したが、なんらかの理由で失敗した場合:
 エラーメールに記載の取引番号を参考に、スマレジ管理画面にて取引データを更新し、再度連携を行ってください。
 ※値を修正しない更新(空更新)でも、再度連携処理が実行されます。

 ▼受注データの[取消]に失敗した場合
 該当の受注データが存在しなかった場合:更新対象外として扱います。
 該当の受注データが存在したが、すでに取消済みの場合:更新対象外として扱います。
 該当の受注データが存在したが、受注に紐づく商品の在庫が特定できない、または在庫不足の場合
 (初期設定「スマレジV4連携:連携時在庫引当有無」が「引当する」の前提):
 エラーメールに記載の受注番号や商品コードを参考に、商品の在庫を更新後、
 スマレジ管理画面にて取引データを取消し、再度連携を行ってください。

・受注連携時、決済代行会社などへの決済連携は行いません。

・受注連携時、注文確定時送信メール(注文確認メール)は配信しません。


2.導入手順

STEP1. 受注データ連携(IN)(店舗受注データ)の利用に必要な設定【弊社】
STEP2. 受注データ連携(IN)(店舗受注データ)の利用設定の切り替え【店舗様】
STEP3. 受注ヘッダ自由項目の登録【店舗様】
STEP4. 「取引ID」を連携するための設定【弊社】
STEP5. 初期設定の登録【店舗様】
STEP6. スマレジ・デベロッパーズでの設定【店舗様】
STEP7. 連携テストの実施【店舗様】


以下、ebisumart zeroのデモ環境→本番環境の順に対応してください。


STEP1. 受注データ連携(IN)(店舗受注データ)の利用に必要な設定【弊社】

弊社にて、受注データ連携(IN)(店舗受注データ)の利用に必要な設定を行います。


STEP2. 受注データ連携(IN)(店舗受注データ)の利用設定の切り替え【店舗様】

初期設定「スマレジV4連携:受注連携API利用有無」にて、
「利用する(新規登録)」または「利用する(新規登録・更新・取消)」を選択してください。


STEP3. 受注ヘッダ自由項目の登録【店舗様】

スマレジから連携される、取引ID(必須)、店舗ID(任意)を格納するための受注ヘッダ自由項目を、それぞれ登録してください。

スマレジ項目名 必須 自由項目の項目入力形式 自由項目の最大文字数
取引ID(transactionHeadId) 必須 1行テキスト 12
店舗ID(storeId) 任意 1行テキスト 9


STEP4. 「取引ID」を連携するための設定【弊社】

STEP3の完了後、弊社サポート窓口までご連絡ください。
スマレジ側の「取引ID」をebisumart zeroの受注データに連携するための設定を行います。

この際、店舗様との日程調整のうえ、ユーザーウェブを30分~1時間程度メンテナンス状態とさせていただきます。


STEP5. 初期設定の登録【店舗様】

受注データ連携(IN)(店舗受注データ)で使用する各種初期設定を登録してください。

設定する環境 初期設定 設定内容
デモ環境 スマレジV4連携:テスト用アクセストークンAPI接続先URL スマレジ(開発環境)の、アクセストークンAPIの接続先URLを設定します。
※連携テスト用の設定項目です。
スマレジV4連携:テスト用プラットフォームAPI接続先URL スマレジ(開発環境)の、プラットフォームAPIの接続先URLを設定します。
※連携テスト用の設定項目です。
スマレジV4連携:テスト用クライアントID スマレジ(開発環境)のクライアントIDを設定します。
※連携テスト用の設定項目です。
スマレジV4連携:テスト用クライアントシークレット スマレジ(開発環境)のクライアントシークレットを設定します。
※連携テスト用の設定項目です。
スマレジV4連携:テスト用Webhookカスタムヘッダー値 STEP6で、スマレジ管理画面のWebhookカスタムヘッダーに設定する、ヘッダー値を設定します。
※連携テスト用の設定項目です。
本番環境 スマレジV4連携:アクセストークンAPI接続先URL スマレジ(本番環境)の、アクセストークンAPIの接続先URLを設定します。
スマレジV4連携:プラットフォームAPI接続先URL スマレジ(本番環境)の、プラットフォームAPIの接続先URLを設定します。
スマレジV4連携:クライアントID スマレジ(本番環境)のクライアントIDを設定します。
スマレジV4連携:クライアントシークレット スマレジ(本番環境)のクライアントシークレットを設定します。
スマレジV4連携:Webhookカスタムヘッダー値 STEP6で、スマレジ管理画面のWebhookカスタムヘッダーに設定する、ヘッダー値を設定します。
デモ・本番環境 スマレジV4連携:契約ID スマレジの契約IDを設定します。
スマレジV4連携:連携用商品コードマッピング スマレジ連携項目の「productCode(商品コード)」を紐づけるebisumart zeroの項目のマッピングを指定します。
商品マスタ項目、商品バリエーション項目を指定可能です。
スマレジV4連携:受注連携項目マッピング スマレジから取得する店頭受注データについて、スマレジの各項目の割り当て先としてマッピングするebisumart zeroの受注項目を指定します。
スマレジV4連携:連携用バリエーション スマレジから取得する店頭受注データについて、バリエーション(カラー、サイズなど)を紐づけるebisumart zeroのバリエーションを指定します。
スマレジV4連携:店頭受注データ取り込み対象 スマレジから取得する店頭受注データについて、取り込み対象を選択します。
スマレジV4連携:連携時在庫引当有無 スマレジから取得する店頭受注データについて、連携時の在庫引当有無を選択します。
スマレジV4連携:店頭受注でのポイント操作 スマレジから取得する店頭受注データについて、使用ポイント、付与ポイントの指定があった場合のポイント更新の有無を選択します。
※受注データを登録する場合のポイント操作を設定します。
スマレジV4連携:店頭受注でのポイント操作(受注更新・取消用) スマレジから取得する店頭受注データについて、使用ポイント、付与ポイントの指定があった場合のポイント更新の有無を選択します。
※受注データを更新、取消する場合のポイント操作を設定します。
スマレジV4連携:受注連携ショップ商品名利用フラグ スマレジから取得する店頭受注データについて、受注明細の商品名に、スマレジで設定した商品名ではなくショップ管理ツールで設定した商品名を利用するかを選択します。
スマレジV4連携:連携エラー時メール配信有無 スマレジV4連携処理におけるエラー発生時の、システムエラーメールの配信有無を選択します。

STEP6. スマレジ・デベロッパーズでの設定【店舗様】

▼デモ環境へのオプション導入時

(1)スマレジ・デベロッパーズにログイン後、
   [アプリ]>[パブリックアプリ(プライベートアプリ)]から、設定を行うアプリ欄の[概要を見る(利用状況を見る)]を押下してください。
(2)[Webhook]タブを選択し、以下設定してください。
   ・「基本設定」にて「Webhookの利用」を「利用する」に選択
   ・「カスタムヘッダー」にて「ヘッダーキー」に「ebisumart No(小文字)」を、「ヘッダー値」に「任意の半角英数字11文字」を設定する
   ・「送信するイベント」にて「取引」のフラグをONにする

ヘッダーキーには、半角数字・半角小文字アルファベット・ハイフン(-)のみ使用可能です。
ebisumart Noにアンダーバーが含まれている場合は、ハイフンに置き換えて設定してください。



(3)画面上部または下部にある[保存]ボタンを押下してください。

(4)[スコープ]タブを選択し、「pos.transactions:read」のフラグをONにしてください。
(5)画面上部または下部にある[保存]ボタンを押下してください。

(6)[環境設定]タブを選択し、「開発環境」にて以下の内容を設定してください。

アプリURL https://dev.smaregi.jp/app
利用者契約通知先URL https://dev.smaregi.jp/idp
Webhook送信先エンドポイント https://(ebisumart zeroデモ環境のサービスURL)/(ebisumart No)/api_smaregi_v4_platform.html
リダイレクトURI urn:ietf:wg:oauth:2.0:oob


(7)画面上部または下部にある[保存]ボタンを押下してください。



▼本番環境へのオプション導入時

(1)スマレジ・デベロッパーズにログイン後、
   [アプリ]>[パブリックアプリ(プライベートアプリ)]から、設定を行うアプリ欄の[概要を見る(利用状況を見る)]を押下してください。
(2)[環境設定]タブを選択し、「本番環境」にて以下の内容を設定してください。

アプリURL 店舗様ごとに設定
利用者契約通知先URL 店舗様ごとに設定
Webhook送信先エンドポイント https://(ebisumart zero本番環境のサービスURL)/api_smaregi_v4_platform.html
リダイレクトURI 店舗様ごとに設定

本番環境の設定内容は、以下をご参照ください。※外部サイトに遷移します。

スマレジ・ヘルプ(プラットフォームAPIの利用方法>3. 環境設定を行ないます)


(3)画面上部または下部にある[保存]ボタンを押下してください。


STEP7. 連携テストの実施【店舗様】

スマレジアプリ上で注文し、ebisumart zeroの受注一覧と、スマレジ管理画面の取引一覧に受注データが登録されていることを確認してください。



3.会員データ連携(OUT)

1.基本動作
2.導入手順


1.基本動作

スマレジアプリで、会員検索や会員に紐づく取引を選択した際などに、ebisumart zeroから連携した会員データを参照します。


機能制限事項
・スマレジの「プレミアムプラス」以上の料金プランを選択する必要があります。
 (スマレジのオプション「外部会員連携」機能を利用する前提のため)

・スマレジアプリで会員検索した場合、最大100件までしか連携されません。
 探したい会員が101件目以降に存在した場合は連携できないため、なるべく詳細な条件で検索して、
 検索結果が100件未満になるように運用してください。
 ※会員IDでソートして連携されるため、同じ条件で検索した場合は常に同じ会員リストが連携されます。


その他仕様、運用について
・ポイントオプションを利用する前提ですが、利用しない店舗でも連携は可能です。

・スマレジへ連携する会員の保有ポイントは、通常ポイントや期間限定ポイントなどをすべて合算したポイント数です。

・スマレジへ連携するポイント有効期限は、以下の通りです。
 ポイントの有効期限管理がレコード単位/会員単位どちらの場合も、一番期限が近い有効期限
 (現在日時以降で、現在日時に一番近い日時)を連携
 ※会員単位の場合、通常ポイント/期間限定ポイントにかかわらず、一番期限が近い有効期限を連携します。

 【ポイント数、有効期限に関する注意】
 ebisumart zeroでは、複数の有効期限を持つことが可能ですが、スマレジでは1つしか有効期限を管理できません。
 そのため、スマレジ側に表示されるポイント数のすべてがこの有効期限とは限りません。
 例)スマレジ側の表示「500ポイント/有効期限:2025/7/7」
   ebisumart zero側のデータ「100ポイント/有効期限:2025/7/7、400ポイント/有効期限:2025/12/25」



2.導入手順

STEP1. スマレジ側のIPアドレスの連絡【店舗様】
STEP2. IPアドレスの登録【弊社】
STEP3. 初期設定の登録【店舗様】
STEP4. スマレジ管理画面での設定【店舗様】
STEP5. 連携テストの実施【店舗様】


STEP1. スマレジ側のIPアドレスの連絡【店舗様】

会員情報を取得するIPアドレス(スマレジアプリを使用する実店舗のIPアドレス)を、弊社サポート窓口までご連絡ください。


以下、ebisumart zeroのデモ環境→本番環境の順に対応してください。


STEP2. IPアドレスの登録【弊社】

STEP1でご連絡いただいたIPアドレスを、アクセス許可IPアドレスとして登録します。


STEP3. 初期設定の登録【店舗様】

STEP4でスマレジ管理画面で登録予定の、各環境の「アクセストークン(任意の文字列)」を、各種初期設定に登録してください。

設定する環境 初期設定 設定内容
デモ環境 スマレジV4連携:テスト用アクセストークン(会員一覧連携) スマレジ(開発環境)からの会員一覧取得APIで使用されるアクセストークンを設定します。
※連携テスト用の設定項目です。
スマレジV4連携:テスト用アクセストークン(会員情報連携) スマレジ(開発環境)からの会員情報取得APIで使用されるアクセストークンを設定します。
※連携テスト用の設定項目です。
本番環境 スマレジV4連携:アクセストークン(会員一覧連携) スマレジ(本番環境)からの会員一覧取得APIで使用されるアクセストークンを設定します。
スマレジV4連携:アクセストークン(会員情報連携) スマレジ(本番環境)からの会員情報取得APIで使用されるアクセストークンを設定します。


STEP4. スマレジ管理画面での設定【店舗様】

▼デモ環境へのオプション導入時

(1)スマレジ管理画面(開発環境)にログイン後、[設定]>[システム連携]>[外部会員連携] から、以下の通り設定してください。


■会員一覧取得

APIの利用 利用する
URL https://(ebisumart zeroデモ環境のサービスURL)/(ebisumart No)/api_smaregi_v4_member_list.html
アクセストークン STEP3の「スマレジV4連携:テスト用アクセストークン(会員一覧連携)」で設定した値を設定

■会員情報取得

APIの利用 利用する
スマレジ会員マスタの利用 外部サーバーのみ参照する
URL https://(ebisumart zeroデモ環境のサービスURL)/(ebisumart No)/api_smaregi_v4_member.html
アクセストークン STEP3の「スマレジV4連携:テスト用アクセストークン(会員情報連携)」で設定した値を設定

■その他設定

会員取引検索区分 会員コード


(2)画面下部にある「更新」ボタンを押下してください。


▼本番環境へのオプション導入時

(1)スマレジ管理画面(本番環境)にログイン後、[設定]>[システム連携]>[外部会員連携] から、以下の通り設定してください。


■会員一覧取得

APIの利用 利用する
URL https://(ebisumart zero本番環境のサービスURL)/api_smaregi_v4_member_list.html
アクセストークン STEP3の「スマレジV4連携:アクセストークン(会員一覧連携)」で設定した値を設定

■会員情報取得

APIの利用 利用する
スマレジ会員マスタの利用 外部サーバーのみ参照する
URL https://(ebisumart zero本番環境のサービスURL)/api_smaregi_v4_member.html
アクセストークン STEP3の「スマレジV4連携:アクセストークン(会員情報連携)」で設定した値を設定

■その他設定

会員取引検索区分 会員コード


(2)画面下部にある「更新」ボタンを押下してください。


STEP5. 連携テストの実施【店舗様】

スマレジアプリ上で会員を検索し、ebisumart zero上の会員情報が表示されることを確認してください。
操作方法は以下をご参照ください。※外部サイトに遷移します。

スマレジ・ヘルプ(会員情報を確認する)



4.ユーザーウェブへのバーコード表示

基本動作

ユーザーウェブのマイページなどに、スマレジで利用するための会員コード(=ebisumart zero会員ID)を表示可能とします。
会員バーコード画像を表示するために、m:idを組み込む必要があります。

▼対象m:id
common.MEMBER_ID_BARCODE_TAG
※すべてのテンプレートで使用可能です。

▼サンプルコード

		
<span>
            <img m:id='common.MEMBER_ID_BARCODE_TAG' width="300" height="100" m:type="CODE128"/>
</span>
		
	



パラメータ「m:type」で、必ずバーコードの規格を「CODE128」と指定してください。
詳細はm:id「common.MEMBER_ID_BARCODE_TAG」のページをご参照ください。


バーコード画像はショップ管理ツール上に保存されません。