API と連携

「設定 → API と連携」には 3 つのタブがあります:API キー、Webhook、連携。
API と API キーは、Free Forever を含むすべてのプランで無料で、API のアドオンはありません。API で付与したスタンプは他のスタンプと同じく Card Operations なので、プランの Card Operations を使い切ると止まります。有料なのは Webhook で、下記を参照してください。
API は追加料金がかかりますか?
いいえ。API と API キーは、Free Forever を含むすべてのプランで無料です。API で付与したスタンプは、他のスタンプと同じく Card Operations です。
Free Forever で API を使えますか?
はい。プランの Card Operations を使い切ると、API によるスタンプも他のスタンプと同様に止まります。
API の設定はどこにありますか?
「設定 → API と連携」にあり、「API キー」「Webhook」「連携」の 3 つのタブがあります。
API キー

API キーは「API キー → API キーを追加」で 1 つのスタッフログインに対して作成します。スタッフログインが持てる API キーは最大 1 つで、無効化されたスタッフログインは選択できません。選べるスタッフログインがない場合、「API キーを生成」ウィンドウでその場で作成が提案されます。新しいスタッフログインには空きの Staff Seat が必要で、プランに空きがない場合は、ウィンドウで代わりにシートの追加またはプランの選択が提案されます。
API キーで行うすべての呼び出しは、そのスタッフログインとして動作します。そのスタッフログインのビジネスにのみアクセスし、「自動スタンプ」で選ばれたスタンプカードにスタンプを付け、そのスタンプはそのスタッフログインの Card Operations としてカウントされます。
キーは API キーの一覧からいつでも再表示・コピーできます。端末に読み込ませるために QR コードとして表示したり、スタッフログインの名前とともに印刷したりすることもできます。
API キーはどのように作成しますか?
「設定 → API と連携 → API キー」で「API キーを追加」を選び、スタッフログインを選択します。各スタッフログインが持てる API キーは最大 1 つです。
API キーを紛失しました。新しいキーが必要ですか?
いいえ。キーは API キーの一覧からいつでも再表示・コピーでき、QR コードとして表示することもできます。
API 呼び出しはどのスタンプカードにスタンプを付けますか?
キーのスタッフログインに「自動スタンプ」で選ばれているスタンプカードです。そのスタンプは、そのスタッフログインの Card Operations としてカウントされます。
新しいキーにスタッフログインを選べないのはなぜですか?
無効化されたスタッフログインは選択できず、すでにキーを持つスタッフログインは 2 つ目のキーを持てません。選べるものがない場合、ウィンドウでスタッフログインの作成が提案されます。
API キーが使えなくなるとき
API キーに有効期限はありません。使えなくなるのは、再生成または削除された場合か、そのスタッフログインが無効化または削除された場合だけです。スタッフログインのパスワードやログイン名を変更しても影響しません。
- 再生成 はスタッフログインに新しい API キーを発行します。古いキーはすぐに使えなくなります。
- 削除 はキーをすぐに停止します。スタッフログイン自体は 7Stamp Scanner で引き続き使え、後で新しいキーを取得できます。
- スタッフログインを無効にしてもキーは保持されます。スタッフログインを再び有効にすると、同じキーがまた使えます。
API キーに有効期限はありますか?
いいえ。使えなくなるのは、再生成または削除された場合か、そのスタッフログインが無効化または削除された場合だけです。
スタッフログインのパスワードを変更しました。新しい API キーが必要ですか?
いいえ。パスワードやログイン名を変更しても API キーには影響しません。
スタッフログインを再び有効にしました。古い API キーは使えますか?
はい。スタッフログインを無効にしてもキーは保持され、再び有効にすると同じキーがまた使えます。
API でできること
API を通じて、システムは次のことができます:
- スタンプカードをリンクまたは QR として配布する
- スタンプを追加する
- スタンプ、目標、バウチャーを含むカードを読み取る
- カードにバウチャーを直接発行する
- バウチャーコードでバウチャーを引き換える
- 顧客にメッセージを送る
API は、CRM の ID、電話番号、メールアドレスなどのビジネス独自の識別子を external_id として送ることで顧客のカードを見つけます。識別子はカードに保存され、そのカードに関するすべての Webhook で返されます。API にはビジネスの顧客の一覧を返す呼び出しはなく、顧客基盤全体は管理画面のエクスポートでのみ取り出せます。
API キーの代わりに、アプリはスタッフログインのログイン名とパスワードでサインインすることもできます。これはレジ担当がサインインする端末向けです。API キーは無人で動作する端末に適しています。Webhook は管理画面でのみ追加でき、API にはイベントを登録したり一覧表示したりする呼び出しはありません。
API にはリクエストのレート制限はありません。呼び出しは回数や頻度で制限されず、同じカードをすぐに再スキャンできます。API によるスタンプ付与を制限するのはプランの Card Operations です。
自社の CRM や POS からスタンプを追加できますか?
はい、API を通じて可能です。API はスタンプカードの配布、スタンプの追加、カードの読み取り、バウチャーの引き換えを行います。イベントをシステムに通知させるには Webhook を追加します。それには Webhooks & Events アドオンが必要です。
データをエクスポートできますか?
API では独自の識別子でカードを読み取り、Webhook はイベントを発生時に送信します。API には全顧客の一覧はなく、顧客基盤全体は管理画面のエクスポートで取り出します。
API はどのように顧客のカードを見つけますか?
独自の識別子(CRM の ID、電話番号、メールアドレス)を external_id として送ることで見つけます。識別子はカードに保存され、そのカードに関するすべての Webhook で返されます。
API で Webhook を登録できますか?
いいえ。Webhook は管理画面でのみ追加できます。
API にレート制限はありますか?
いいえ。呼び出しは回数や頻度で制限されず、同じカードをすぐに再スキャンできます。スタンプ付与を制限するのはプランの Card Operations だけです。
API リファレンス
API リファレンスは公開されており、サインインは不要です。Swagger:https://api.7loc.com/cards-api/docs, OpenAPI ファイル:https://api.7loc.com/cards-api/openapi.json. 呼び出しは https://api.7loc.com/cards-api に送り、API キーまたはスタッフログインが必要です。
White Label のビジネスには、管理画面に API リファレンスへのリンクは表示されません。API キーと Webhook は同じように動作します。
API のドキュメントはどこにありますか?
公開されている Swagger(サインイン不要):https://api.7loc.com/cards-api/docs, OpenAPI ファイル:https://api.7loc.com/cards-api/openapi.json.
API 呼び出しのベースアドレスは何ですか?
呼び出しには API キーまたはスタッフログインが必要です。ベースアドレス:https://api.7loc.com/cards-api.
White Label の管理画面に API ドキュメントへのリンクがありません。API は使えますか?
はい。White Label のビジネスにはリファレンスへのリンクは表示されませんが、API キーと Webhook は同じように動作します。
Webhook

Webhook は「API と連携 → Webhook → Webhook を追加」で、イベントを受け取る URL を指定して追加します。7Stamp では、Webhook はスタンプカードのイベント用に作成されます。ビジネスは複数の Webhook を、それぞれ独自の URL で追加できます。
Webhook には月額 $19 の Webhooks & Events アドオンが必要で、有料プランでのみ提供されます。最初の Webhook を追加するときに購入が提案され、アドオンがないと Webhook を作成したり再び有効にしたりできません。1 つのアドオンで有効にしておける Webhook は 1 つです。追加はできますが、サブスクリプションの請求が更新されるたびに、最も古いもの以外はすべて無効になります。
Webhook は、追加した時点からイベントを発生時に送信します。それ以前のイベントは送信されません。
Webhook は無料ですか?
いいえ。月額 $19 の Webhooks & Events アドオンが必要で、有料プランでのみ提供されます。API 自体は無料です。
2 つ目の Webhook を追加したら無効になりました。なぜですか?
1 つの Webhooks & Events アドオンで有効にしておける Webhook は 1 つです。サブスクリプションの請求が更新されるたびに、最も古いもの以外はすべて無効になります。
新しい Webhook は過去のイベントも送信しますか?
いいえ。イベントは Webhook を追加した時点から送信されます。
Webhook のイベント
Webhook は、event_type で名前が示される 15 種類のスタンプカードのイベントを受け取ります:SCAN、DELIVERY_INSERT、RECEIPT_SCAN、CARD_JOINED、REWARD_EARNED、VOUCHER_ISSUED、VOUCHER_PACK、ADMIN_VOUCHER_ISSUE、VOUCHER_REDEEMED、LOTTERY_WIN、CARD_CAMPAIGN、BIRTHDAY_GREETING、AUTO_MESSAGE_VOUCHER、CARD_ADDED_TO_WALLET、CARD_REMOVED_FROM_WALLET。最後の 2 つは、パスがウォレットに追加されたとき、またはウォレットから削除されたときに、ウォレット(Apple または Google)とともに届きます。
スタンプ価格に満たない購入など、スタンプが追加されないスキャンでも、追加スタンプ 0 の SCAN が送信されます。ホイールで当たった賞品は、ホイールが回されたときに 1 回の LOTTERY_WIN で通知され、REWARD_EARNED や VOUCHER_ISSUED では通知されません。回されるのを待っているホイールは、まだ何も送信しません。
顧客のレビューはスタンプカードのイベントではありません。すべての新しいレビューは、entity review、action created のイベントを、Webhook のページのオブジェクトで「レビュー」にチェックを入れた Webhook に送信します。ここで追加した Webhook はスタンプカードのイベント専用に設定されているため、「レビュー」にチェックを入れるとレビューを受け取るようになります。
スタンプが追加されないスキャンでも Webhook は送信されますか?
はい。スタンプ価格に満たない購入など、スタンプが追加されないスキャンでも、追加スタンプ 0 の SCAN が送信されます。
顧客がホイールで当選したことは、どのイベントで分かりますか?
LOTTERY_WIN で、ホイールが回されたときに 1 回送信されます。回されるのを待っているホイールは、まだ何も送信しません。
顧客がウォレットからカードを削除したことは分かりますか?
はい。パスをウォレットに追加すると CARD_ADDED_TO_WALLET、削除すると CARD_REMOVED_FROM_WALLET が、ウォレット(Apple または Google)とともに送信されます。
Webhook で新しい顧客のレビューを受け取るにはどうすればよいですか?
Webhook のページを開き、オブジェクトで「レビュー」にチェックを入れます。以降、すべての新しいレビューが entity review、action created で届きます。「API と連携」で追加した Webhook は、それまではスタンプカードのイベントだけを受け取ります。
各イベントが送信されるタイミング
| イベント | 送信されるタイミング |
|---|---|
SCAN | スタッフログインがカードをスキャンしたとき:7Stamp Scanner、API、または Toast などの POS から。7Stamp Scanner で取り消されたスタンプは、stamps_added が負の値の SCAN になります |
DELIVERY_INSERT | 顧客がスタンプを付与するスタンプコード(QR、リンク、コードそのもの、または API で作成した招待)を開いたとき |
RECEIPT_SCAN | 顧客がビジネスのチャットボットで会計レシートをスキャンし、スタンプが付いたとき。amount はレシートの合計金額です |
CARD_JOINED | 顧客が方法を問わず新しいスタンプカードを取得したとき。あなたが渡した external_id とともに送信されます |
REWARD_EARNED | スキャンで Award の目標に到達したとき |
VOUCHER_ISSUED | スキャンでバウチャーの目標に到達したとき |
LOTTERY_WIN | Lottery のホイールが回され、賞品が出たとき |
VOUCHER_PACK | 新しいカードがスタンプカードのバウチャーパックを受け取ったとき。すべてのバウチャーが 1 つのイベントに含まれます |
ADMIN_VOUCHER_ISSUE | 管理画面または API で、バウチャーがカードに直接発行されたとき |
VOUCHER_REDEEMED | カードのバウチャーが引き換えられたとき:7Stamp Scanner、API、Toast の POS、または顧客自身によって |
CARD_CAMPAIGN | キャンペーンがカードに届いたとき。カードごとに 1 回、キャンペーンにバウチャーがあればそれも含まれます |
BIRTHDAY_GREETING | カードに誕生日のお祝いが送られたとき。誕生日バウチャーが発行された場合はそれも含まれます |
AUTO_MESSAGE_VOUCHER | 自動メッセージのトリガーがカードにバウチャーを付与したとき。その後チャンネルが顧客に届くかどうかは問いません |
CARD_ADDED_TO_WALLET | パスが Apple Wallet または Google Wallet に追加されたとき |
CARD_REMOVED_FROM_WALLET | パスがウォレットから削除されたとき |
スキャンで到達した各目標は、スキャンのイベントの後にそれぞれ独自のイベントを送信します。1 回のスキャンでカードの 2 周にわたり目標に 2 回到達した場合は、2 つ送信されます。満杯のカードが新しい周回を始めても同じカードなので CARD_JOINED は送信されませんが、管理者が古いカードを削除した後に再発行されたカードでは送信されます。参加時にバウチャーパックとスタンプがある場合は、CARD_JOINED、VOUCHER_PACK、DELIVERY_INSERT の順に届きます。
スタンプのないスタンプコードは DELIVERY_INSERT を送信せず、カードなしで管理画面で生成したバウチャーは ADMIN_VOUCHER_ISSUE を送信せず、すでに引き換えたバウチャーに対する API の繰り返しの呼び出しは 2 回目の VOUCHER_REDEEMED を送信しません。
顧客が目標に到達したことは、どのイベントで分かりますか?
Award の目標なら REWARD_EARNED、バウチャーの目標なら VOUCHER_ISSUED、Lottery なら LOTTERY_WIN で、いずれもスキャン自体のイベントの後に送信されます。
スタンプが取り消されたときに Webhook は送信されますか?
はい。7Stamp Scanner で取り消されたスタンプは、stamps_added が負の値の SCAN として届きます。
VOUCHER_ISSUED と ADMIN_VOUCHER_ISSUE の違いは何ですか?
VOUCHER_ISSUED は、スキャンでバウチャーの目標に到達したときに届きます。ADMIN_VOUCHER_ISSUE は、管理画面での手動発行や API により、バウチャーがカードに直接発行されたときに届きます。
スタンプコードで参加した顧客は、イベントを 1 つ送りますか、それとも複数ですか?
複数です。最初に CARD_JOINED、スタンプカードにバウチャーパックがあれば次に VOUCHER_PACK、そしてスタンプとともに DELIVERY_INSERT が届きます。
キャンペーンのメッセージごとにイベントが届きますか?
CARD_CAMPAIGN は、キャンペーンが届いたカードごとに 1 回送信され、キャンペーンにバウチャーが含まれる場合はそのバウチャーも含まれます。
Webhook が受け取る内容
すべてのイベントは同じ JSON 本文を持ちます:イベント ID、ビジネス、そしてイベントの内容(種類、スタンプカード、前後のスタンプ数、購入金額、連携が送った注文 ID と external_id、対応したスタッフログイン、付与したバウチャーと特典、顧客の名前、メールアドレス、Telegram、WhatsApp の電話番号、生年月日)。
amount は最小通貨単位(セント)での購入金額です。スキャンとともに送られた 12.50 という金額は 1250 として届きます。イベントに金額がない場合は空です。
イベント ID は本文と X-Webhook-Event-Id ヘッダーにあります。同じイベントの再試行では ID が維持されるため、受信側は重複を破棄できます。Make または Zapier の URL では、イベントは data ではなく card_event キーの下に置かれます。
Webhook には顧客についてどんなデータが含まれますか?
名前、メールアドレス、Telegram、WhatsApp の電話番号、生年月日と、スタンプカード、前後のスタンプ数、付与されたバウチャーと特典です。
amount の単位は何ですか?
最小通貨単位(セント)です。スキャンとともに送られた 12.50 という金額は 1250 として届きます。イベントに金額がない場合は空です。
同じイベントを 2 回処理しないようにするにはどうすればよいですか?
本文と X-Webhook-Event-Id ヘッダーにあるイベント ID を使ってください。再試行でも同じ ID が維持されます。
Make でイベントが card_event の下にあるのはなぜですか?
Make または Zapier の URL では、それぞれのアプリが区別できるように、イベントは data ではなく card_event キーの下に置かれます。
署名
すべての配信には署名が付きます。X-Webhook-Signature ヘッダーには、タイムスタンプと、Webhook のシークレットキーを鍵とした、そのタイムスタンプと生の本文の HMAC-SHA256 が含まれます。シークレットキーは Webhook のページで表示・再生成できます。Basic 認証のログイン名とパスワードを追加することもできます。
Webhook が本当に 7Stamp から来たことを確認するにはどうすればよいですか?
Webhook のシークレットキーを使ってタイムスタンプと生の本文の HMAC-SHA256 を計算し、X-Webhook-Signature ヘッダーと比較します。
Webhook のシークレットキーはどこにありますか?
Webhook のページにあり、そこで再生成することもできます。
エンドポイントをパスワードで保護できますか?
はい。署名に加えて、Basic 認証のログイン名とパスワードを Webhook に追加できます。
失敗した配信
30 秒以内に 2xx の応答がない配信は最大 10 回再試行され、待ち時間は毎回前回より 4 秒ずつ長くなるため、再試行は約 4 分以内に終わります。Retry-After 付きの 429 応答の場合は、その時間が経過してから再試行されます。イベントの最初の失敗時に、管理画面に通知が表示されます。
100 回連続で配信に失敗すると、Webhook はシステムによってブロックされ、それ以上イベントを受け取らなくなります。その前に Webhook のページで警告が表示され、「ブロック解除」ボタンがあります。配信が 1 回成功するとカウントはリセットされます。
各 Webhook のページには、送信したリクエストと受信した応答を含む配信のジャーナルがあります。「再送信」は、同じイベントをこの Webhook にのみ再び送信します。
サーバーが停止していました。イベントは失われましたか?
各配信は約 4 分以内に最大 10 回再試行されます。その後は Webhook のジャーナルを開き、必要なイベントに「再送信」を使ってください。
Webhook がイベントを受け取らなくなったのはなぜですか?
100 回連続で配信に失敗すると、システムによってブロックされます。エンドポイントを修正し、Webhook のページで「ブロック解除」を押してください。
Webhook に送信された内容を確認できますか?
はい。各 Webhook のページには、送信したリクエストと受信した応答を含む配信のジャーナルがあります。
「連携」タブ

「連携」タブには、既製の方法がグループ別に一覧表示されます:
- レジでスタンプ — Poster、Toast、「自社の POS または CRM」、「お使いの POS が見つかりませんか?」
- 会計レシート — SmartKasa
- 自動化 — Make、Zapier、Public Swagger
各カードには API キーが必要かどうかが表示されます。タブにはどの国でも同じカードが表示され、国によって制限されるのは会計レシートだけです。

White Label のビジネスには Make、Zapier、Public Swagger のカードは表示されず、Poster や 7stamp.com のセットアップガイドも案内されません。
すぐに接続できる POS システムはどれですか?
Poster と、プラットフォームで有効になった後の Toast です。それまでは「近日公開」と表示されます。その他のシステムは「自社の POS または CRM」から API で接続します。
連携は国によって制限されますか?
いいえ。タブにはどの国でも同じカードが表示されます。国によって制限されるのは会計レシートだけです。
Make と Zapier が表示されないのはなぜですか?
White Label のビジネスには表示されません。API キーと Webhook は同じように動作します。
Poster
Poster は、Poster マーケットプレイスにある当社のアプリです。「Poster にインストール」で掲載ページが開き、アプリはスタッフログインの API キーで設定します。そのスタンプは、そのスタッフログインの Card Operations としてカウントされます。
Poster はどのように接続しますか?
「連携 → Poster」を開き、「Poster にインストール」を選びます。アプリはスタッフログインの API キーで設定します。
Poster のスタンプは誰の Card Operations を使いますか?
アプリが使う API キーのスタッフログインの Card Operations です。
Poster には API キーが必要ですか?
はい、スタッフログインの API キーが必要です。
Toast
Toast は、プラットフォームで Toast へのアクセスが設定されるまで、すべてのビジネスで「近日公開」と表示されます。これはプラットフォーム全体で 1 つのスイッチであり、ビジネスの設定ではありません。オンになると、Toast のカード自体にセットアップが表示されます。
Toast の各ロケーションは、GUID で 1 つのスタッフログインに接続し、API キーは不要です。そのスタッフログインのビジネス、スタンプカード、プランが、そのロケーションからのすべての Toast リクエストに適用されます。1 つのロケーションは 1 つのスタッフログインにのみ接続でき、1 つのスタッフログインが持てるロケーションは 1 つです。ロケーションの接続を解除した後や、そのスタッフログインが無効化または削除されている間は、ロケーションからのリクエストは拒否されます。
各バウチャーには Toast のメニュー商品を割り当てられ、Toast の POS ではその商品の割引になります。商品が割り当てられていないバウチャーは会計に 0 円の割引として適用され、レジ担当がギフトを手渡しします。バウチャーは Toast の POS で引き換えられ、支払い済みの会計で到達したホイールはすぐに回されます。Toast が取引を取り消すと、そのスタンプは取り消されるか、引き換えられたバウチャーが元に戻ります。
ゲストは Toast のキオスクやゲスト向け画面で、電話番号またはメールアドレスで参加できます。スタンプカードはすぐに発行されますが、ゲストが同じ電話番号またはメールアドレスで開くまで、7Stamp からは何も届きません。
Toast に「近日公開」と表示されるのはなぜですか?
Toast へのアクセスはプラットフォーム全体で 1 つのスイッチであり、ビジネスの設定ではありません。それがオンになるまで、接続するものはありません。
Toast のロケーションはどのように接続しますか?
GUID で 1 つのスタッフログインに接続し、API キーは不要です。そのスタッフログインのスタンプカードとプランが、そのロケーションからのすべてのリクエストに適用されます。
Toast がチェックを無効にすると、スタンプはどうなりますか?
Toast が取引を取り消すと、そのスタンプは取り消されるか、引き換えられたバウチャーが元に戻ります。
SmartKasa

SmartKasa には API キーは不要です。これは「レシートのスキャン」のレシートソースで、SmartKasa の店舗 ID、またはすべての店舗を対象とする会社コードで追加します。顧客はビジネスのチャットボットで SmartKasa のレシートをスキャンし、スタンプはそのレシートソースのスタッフログインに付きます。
SmartKasa はウクライナのサービスで、会計レシートはウクライナ、スロバキア、カザフスタン、ウズベキスタンでのみ使えます。
SmartKasa には API キーが必要ですか?
いいえ。SmartKasa は「レシートのスキャン」のレシートソースで、店舗 ID または会社コードで追加します。
顧客は SmartKasa のレシートをどこでスキャンしますか?
あなたのビジネスのチャットボットでスキャンします。スタンプはそのレシートソースのスタッフログインに付きます。
会計レシートはどの国で使えますか?
ウクライナ、スロバキア、カザフスタン、ウズベキスタンです。
Make と Zapier

Make 向けの 7Stamp アプリは、Make の公開アプリライブラリに掲載されています。任意の Make シナリオで 7Stamp を検索するか、「連携」タブの「Make で開く」を使ってください。当社の Zapier アプリは Zapier の公開ディレクトリには掲載されていません。「Zapier で開く」は、ビジネス自身の Zapier アカウントにアプリを追加する招待です。どちらのアプリもスタッフログインの API キーで動作します。
Make のシナリオと Zap は 7Stamp の Webhook によって開始されるため、トリガーには Webhooks & Events アドオンが必要です。スタンプの追加やバウチャーの発行などのアクションには API キーだけが必要です。White Label のビジネスには Make と Zapier は提供されません。
Make と Zapier で 7Stamp のアプリはどこにありますか?
Make では、任意のシナリオで 7Stamp を検索してください。アプリは Make の公開アプリライブラリに掲載されています。Zapier ではまだ公開されていないため、「連携」タブの「Zapier で開く」を使ってください。招待によって、アプリがあなた自身のアカウントに追加されます。
Make と Zapier には Webhooks & Events アドオンが必要ですか?
トリガーには必要です。シナリオと Zap は 7Stamp の Webhook によって開始されるためです。スタンプの追加やバウチャーの発行などのアクションには API キーだけが必要です。
Make や Zapier には API キーが必要ですか?
はい。アプリはスタッフログインの API キーで動作します。