参考资料 运营

API、Webhook 和集成

API 员工登录的密钥,API 的作用,Webhooks 及其事件、有效负载、签名和重试,以及现成的集成:Poster、Toast、SmartKasa、Make 和 Zapier。

快速阅读

更新时间: 2026年11月19日

API & 集成

API 键位于 API & 集成

设置 → API & 集成有三个标签:API 密钥、网络钩子和集成。

每个方案中的API和API键都是免费的,包括Free Forever;没有API附加组件。通过API给予的印章与其他印章一样是Card Operations,所以当方案的Card Operations用完时它们会停止。Webhooks 是付费部分,见下文。

API需要额外付费吗?

不。API 和 API 键在每个计划中都是免费的,包括 Free Forever。通过它提供的印章与其他一样是 Card Operations。

我可以在Free Forever上使用API吗?

是的。当计划的Card Operations用完时,通过API的印章就像其他任何情况一样停止。

API 设置在哪里?

在 设置 → API 和集成中,有三个选项卡 — API 密钥、Webhooks 和集成。

API 键

为员工登录生成API密钥

在API键下创建了一个API键 → 为一个员工登录添加API键。一个员工登录最多有一个API键,并且无法选择已关闭的员工登录。如果没有可选择的员工登录,生成API键窗口会提供在此处创建一个新的员工登录;新的员工登录需要一个空闲的Staff Seat,在计划已满的情况下,窗口会提供添加席位或选择计划的选项。

使用API密钥进行的每次呼叫都相当于其员工登录:它仅到达该员工登录的业务,按照自动盖章为其选择的盖章卡盖章,并且其盖章计数算作该员工登录的Card Operations。

该密钥可以随时从API密钥列表中查看和复制。它也可以显示为QR代码,以便扫描到终端,并可以打印出员工登录的姓名。

我如何创建一个 API 密钥?

在 设置 → API 和 集成 → API 键中,选择 添加 API 键并选择一个员工登录。每个员工登录最多有一个 API 键。

我丢了我的API钥匙。我需要一个新的吗?

不可以。密钥可以随时在 API 密钥列表中查看和复制,或者显示为 QR 代码。

API把哪张印花卡称为印花卡?

被选中用于钥匙的员工登录自动盖章。其盖章计入该员工登录的Card Operations。

为什么我不能为新钥匙选择员工登录?

已关闭的员工登录无法被选取,而已经有钥匙的员工登录无法获得第二把钥匙。当没有可以选取的对象时,窗口会提供创建一个员工登录。

当 API 键停止工作时

API 密钥不会过期。它仅在被重新生成或删除,或其员工登录被关闭或删除时才会停止工作。员工登录的新密码或登录不会影响它。

  • Regenerate 会给员工登录一个新的 API 密钥;旧的密钥会立即停止工作。
  • 删除会立即停止密钥。工作人员登录本身在7Stamp Scanner中仍然可以使用,并且可以稍后获取新的密钥。
  • 关闭员工登录不会更改其密钥:当员工登录重新开启时,相同的密钥仍然有效。

API 密钥会过期吗?

不。它只有在被重新生成或删除,或其员工登录被关闭或删除时才会停止工作。

我更改了员工登录的密码。我需要新的API钥匙吗?

不。新密码或登录不会影响API密钥。

我重新开启了员工登录。它以前的API密钥还有效吗?

是的。关闭员工登录会保留其密钥,一旦再次开启,相同的密钥再次生效。

API 做什么

通过API,系统可以:

  • 以链接或QR发放印花卡;
  • 添加印章;
  • 读取带有印章、目标和凭证的卡片;
  • 直接向卡片发放代金券;
  • 通过其优惠券代码兑换优惠券;
  • 给顾客发消息。

API通过商家的自有标识(例如 CRM ID、电话或电子邮件,作为 external_id 发送)找到顾客的卡片。该标识存储在卡片上,并且会在每个关于它的 Webhook 中返回。API没有列出商家顾客的调用:整个顾客群只能通过管理员导出获取。

应用程序可以使用员工登录的用户名和密码登录——用于收银员登录的设备,而不是 API 密钥。API 密钥适用于无人值守运行的设备。Webhooks 仅在管理员中添加;API 无需调用来订阅事件或列出事件。

API 不设请求速率限制:调用不会按次数或频率受限制,同一张卡可以立即再次扫描。限制通过它盖章的是计划的 Card Operations。

我们可以添加自己CRM或POS的邮票吗?

是的,通过API。它可以发放印花卡、添加印花、读取卡片并兑换代金券。要让系统了解事件,需要添加一个Webhook——这需要Webhooks & Events附加组件。

我们可以导出数据吗?

通过API,你可以按照自己的标识读取卡片,而 Webhooks 会在事件发生时发送通知。API没有所有顾客的列表——整个顾客群是通过管理员导出获取的。

API 如何找到顾客的卡?

通过您自己的标识符——一个CRM ID,电话或电子邮件——作为external_id发送。它存储在卡片上,并在关于它的每个Webhook中返回。

我可以通过API订阅 Webhooks 吗?

不。Webhooks 只能在管理员中添加。

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 密钥和 Webhooks 工作方式相同。

API 的文档在哪里?

Swagger 网址为 https://api.7loc.com/cards-api/docs, 公开,无需登录。 OpenAPI 文件位于 https://api.7loc.com/cards-api/openapi.json.

API调用的基地址是什么?

https://api.7loc.com/cards-api. 呼叫需要 API 密钥或员工登录。

我们的White Label管理员没有API文档链接。API对我们有用吗?

是的。White Label 企业看不到与参考的关联,但其 API 密钥和 Webhooks 的工作方式相同。

网络钩子

API中的 Webhooks 与集成

在API和集成 → Webhooks → 添加 Webhook下添加了一个 Webhook,并使用接收事件的URL。在7Stamp为集章卡事件创建了一个 Webhook。企业可以添加多个 Webhook,每个都有自己的URL。

Webhooks 需要 Webhooks & Events 插件,$19 每月,仅在付费计划中提供。添加第一个 Webhook 时会提示购买它;没有它,无法创建或重新开启 Webhook。一个插件只能保持一个 Webhook 处于开启状态:可以添加更多,但订阅的每次账单更新都会关闭除最旧的 Webhook 之外的所有 Webhook。

Webhook 会在被添加后立即发送事件。之前的事件不会被发送。

Webhooks 是免费的吗?

不。他们需要 Webhooks & Events 插件,$19 每月,仅在付费计划中提供。API 本身是免费的。

我添加了第二个Webhook,但它被关闭了。为什么?

一个 Webhooks & Events 插件会保持一个 Webhook 开启。订阅的每次计费更新都会关闭除最早的一个之外的所有 Webhook。

新的 Webhook 会发送过去的事件吗?

不。事件是从添加 Webhook 的那一刻起发送的。

Webhook 事件

Webhook 获得 15 个 Stamp 卡事件,以 event_type 命名: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。最后两种情况是当通行证被添加到钱包或从钱包中删除时,无论是苹果还是谷歌。

没有加贴纸的扫描,例如低于贴纸价格的购买,仍然会发送 SCAN,但不会增加任何贴纸。轮盘中奖在轮盘旋转时由一个 LOTTERY_WIN 公告,而不是 REWARD_EARNED 或 VOUCHER_ISSUED;等待旋转的轮盘暂时不会发送任何消息。

顾客评论不是集章卡活动。每条新评论都会发送一个事件,实体为review,动作为created,发送到在 Webhook 页面上对象中勾选了“Reviews”的 Webhooks。这里添加的 Webhook 仅用于集章卡活动,因此只有在勾选“Reviews”后才会接收评论。

当扫描未添加任何标记时,会发送 Webhook 吗?

是的。没有增加印章的扫描,例如低于印章价格的购买,仍然会发送 SCAN,新增印章为零。

哪个事件告诉我顾客在转盘上获胜了?

LOTTERY_WIN,当轮盘被旋转时发送一次。等待旋转的轮盘尚未发送任何内容。

我能知道顾客何时从他们的钱包中取出卡片吗?

是的。将通行证添加到钱包和移除通行证会发送 CARD_ADDED_TO_WALLET 和 CARD_REMOVED_FROM_WALLET,适用于钱包、Apple 或 Google。

我如何通过 Webhook 获取新的顾客评价?

打开 Webhook 页面并在其对象中勾选评论。每条新评论都会随实体评论和创建动作到达;在此之前,添加在 API & 集成下的 Webhook 仅会获取集章卡事件。

当每个事件被发送时

事件发送时间
SCAN员工登录扫描卡片:在7Stamp Scanner,通过API或从POS(例如Toast)。在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一张新卡获得印花卡的代金券包,在一次活动中获得它的所有代金券
ADMIN_VOUCHER_ISSUE凭证直接发放到卡上,可以在管理员中或通过API
VOUCHER_REDEEMED卡上的代金券可通过以下方式兑换:在7Stamp Scanner,通过API,在Toast POS或由顾客兑换
CARD_CAMPAIGN一次活动使用活动的凭证时,每张卡片只能到达一次该卡片,如果它有凭证的话
BIRTHDAY_GREETING生日的祝福写在卡片上,如果发放了生日代金券,也附上代金券
AUTO_MESSAGE_VOUCHER自动消息触发器会在卡上放置一个优惠券,无论之后是否有渠道与顾客联系
CARD_ADDED_TO_WALLET该通行证已添加到Apple Wallet或Google Wallet
CARD_REMOVED_FROM_WALLET通行证从钱包中移除

每一个被扫描达到的目标都会在扫描本身的事件之后发送自己的事件,如果一个扫描在卡片的两轮中两次达到同一个目标,则会发送两个事件。开始新一轮的完整卡片是同一张卡片,并不会发送 CARD_JOINED;如果管理员删除旧卡后再次发放该卡,则会发送。加入带有兑换券包和印章时,首先发送 CARD_JOINED,然后是 VOUCHER_PACK,之后是 DELIVERY_INSERT。

没有印章的集章码不会发送任何 DELIVERY_INSERT,在管理端生成但没有卡的凭证不会发送任何 ADMIN_VOUCHER_ISSUE,对已兑换的凭证重复调用 API 不会发送第二个 VOUCHER_REDEEMED。

哪个事件告诉我顾客达到了目标?

REWARD_EARNED 用于 Award 目标,VOUCHER_ISSUED 用于代金券目标,LOTTERY_WIN 用于 Lottery,每个都在扫描自身事件之后发送。

当印章被移除时,会发送Webhook吗?

是的。在 7Stamp Scanner 中删除的邮票以 SCAN 形式到达,并带有负的 stamps_added。

VOUCHER_ISSUED和ADMIN_VOUCHER_ISSUE有什么区别?

当扫描达到代金券目标时,会出现 VOUCHER_ISSUED。ADMIN_VOUCHER_ISSUE 则是在代金券直接发到卡上、通过管理员手动操作或通过 API 发放时出现。

使用集章码加入的顾客会发送一个事件还是多个事件?

有几个。首先是 CARD_JOINED,然后是 VOUCHER_PACK(如果集章卡有优惠券包),最后是带有印章的 DELIVERY_INSERT。

我会为每条活动信息获得一个事件吗?

CARD_CAMPAIGN 会在活动到达每张卡时发送一次,如果活动附带优惠券,也会随之发送。

Webhook 接收的内容

每个事件都有相同的JSON主体:事件ID、商家,以及带有其类型的事件、集章卡、印章的前后变化、购买金额、订单ID和external_id发送的集成、提供服务的员工登录、提供的代金券和奖励,以及顾客的姓名、电子邮件、Telegram、WhatsApp电话和出生日期。

amount 是以次单位(分)表示的购买金额:扫描发送的 12.50 元会显示为 1250。当事件没有金额时,该字段为空。

事件 ID 位于正文中以及 X-Webhook-Event-Id 头部中。同一事件的重试会保留其 ID,因此接收方可以丢弃重复事件。对于 Make 或 Zapier URL,事件位于 card_event 键下,而不是 data。

Webhook携带了哪些关于顾客的数据?

姓名、电子邮件、Telegram、WhatsApp 电话和出生日期,以及集章卡、前后的印章,以及提供的代金券和奖励。

数量的单位是什么?

以最小单位(分)计。通过扫描发送的金额12.50会显示为1250;如果事件没有金额,则显示为空。

我如何避免同一个事件被处理两次?

在正文和 X-Webhook-Event-Id 头中使用事件 ID。重试会保留相同的 ID。

为什么事件在Make中的 card_event 下?

对于 Make 或 Zapier URL,事件位于 card_event 键下而不是 data 下,因此它们的应用程序可以区分它们。

签名

每次交付都有签名。X-Webhook-Signature 头部包含一个时间戳以及该时间戳和原始正文的 HMAC-SHA256,使用 Webhook 的密钥进行加密。密钥会显示并可在 Webhook 页面上重新生成。也可以添加基本身份验证的登录名和密码。

我如何检查一个 Webhook 是否真的来自 7Stamp?

使用 Webhook 的密钥计算时间戳和原始主体的 HMAC-SHA256,并将其与 X-Webhook-Signature 头进行比较。

我在哪里可以找到Webhook的密钥?

在 Webhook 的页面上,也可以重新生成它。

我可以用密码保护我的终端吗?

是的。除了签名之外,还可以向 Webhook 添加基本身份验证的用户名和密码。

未成功的投递

在三十秒内没有收到 2xx 响应的投递会最多重试十次,每次等待时间比上一次长四秒,因此重试将在大约四分钟内结束。带有 Retry-After 的 429 响应将在该时间后重试。事件的第一次失败会在管理员中放置一条通知。

在连续一百次投递失败后,Webhook 会被系统阻止,不再接收任何事件。其页面会提前发出警告,并有一个解锁按钮;一次成功的投递会重置计数。

每个 Webhook 的页面都有一个其传递记录的日志,其中包含发送的请求和收到的回应。“重新发送”会再次发送相同的事件,仅发送到此 Webhook。

我的服务器宕机了。事件丢失了吗?

每次传送会在大约四分钟内最多重试十次。之后,请打开 Webhook 的日志,并对你需要的事件使用重新发送。

为什么我的 Webhook 停止接收事件了?

在连续一百次投递失败后,它会被系统阻止。修复端点,然后在Webhook页面上点击取消阻止。

我可以查看发送到我的 Webhook 的内容吗?

是的。每个 Webhook 的页面都有一个传递日志,其中记录了发送的请求和收到的回复。

集成选项卡

集成标签

集成标签按组列出了可用的方法:

  • 在结账时盖章 — Poster,Toast,你自己的 POS 或 CRM,并且没有看到你的 POS?;
  • 财政收入 — SmartKasa;
  • 自动化 — Make、Zapier 和公共 Swagger。

每张卡片都说明是否需要API钥匙。该选项卡在每个国家提供相同的卡片;只有财政收据受限于国家。

您自己的 POS 或 CRM

White Label 商户看不到 Make、Zapier 或 Public Swagger 卡,也不会获得 Poster 或 7stamp.com 上的设置指南。

哪些 POS 系统已准备好连接?

Poster,以及 Toast 一旦为平台启动——在此之前显示“即将推出”。其他系统通过 API 连接,使用您自己的 POS 或 CRM。

集成是否受国家限制?

不。这个标签在每个国家提供相同的卡片。只有财政收据受国家限制。

为什么我看不到Make和Zapier?

它们不会显示给 White Label 企业。它的 API 密钥和 Webhooks 的工作方式相同。

Poster

Poster 是我们在 Poster 市场的应用程序。在 Poster 安装会打开其列表,并且应用程序使用员工登录的 API 密钥进行设置。它的印章计入该员工登录的 Card Operations。

我如何连接Poster?

打开集成 → Poster 并在 Poster 中选择安装。该应用已使用员工登录的 API 密钥进行设置。

Poster 邮票使用谁的Card Operations?

那些工作人员登录中,应用使用其 API 键的。

Poster 是否需要 API 密钥?

是的,这是工作人员登录的API键。

Toast

Toast 在每个业务上显示“即将推出”,直到平台上设置了 Toast 访问。这是平台的一个开关,不是业务的设置;一旦开启,Toast 卡片本身就包含了设置。

每个Toast地点都通过其GUID连接到一个员工登录,并且没有API密钥:该员工登录的业务、集章卡和计划适用于来自该地点的每个Toast请求。一个地点只能连接到一个员工登录,而一个员工登录持有一个地点。一旦地点断开连接,或其员工登录被关闭或删除,来自该地点的请求将被拒绝。

每张代金券可以分配一个Toast菜单产品:在Toast POS上,它随后成为该产品的折扣。没有指定产品的代金券作为零折扣应用于账单,收银员通过手递方式交付礼品。代金券在Toast POS处兑换,通过付费账单获得的旋转轮会立即旋转。当Toast撤销一笔交易时,其印章被收回或已兑换的代金券被恢复。

客人可以使用电话号码或电子邮件在Toast自助终端或面向客人的屏幕上加入。集章卡会立即发放;客人在用同一电话或电子邮件打开之前,无法从7Stamp获得任何东西。

为什么Toast说即将推出?

Toast 访问是整个平台的一个开关,而不是你业务的一个设置。在它开启之前,没有任何东西可以连接。

Toast位置是如何连接的?

通过其 GUID 登录一个员工账号,无需 API 密钥。该员工账号的打卡和计划适用于该地点的每个请求。

当Toast作废支票时,印章会发生什么情况?

当 Toast 撤销一笔交易时,其印章会被收回或其已兑换的代金券会被恢复。

SmartKasa

在“集成”选项卡上的SmartKasa

SmartKasa不需要API键。它是收据扫描中的收据来源,由SmartKasa商店ID或由公司代码添加,以覆盖每个商店。顾客在企业的聊天机器人中扫描SmartKasa收据,印章将进入该收据来源的员工登录。

SmartKasa是乌克兰的,财政收据只在乌克兰、斯洛伐克、哈萨克斯坦和乌兹别克斯坦有效。

SmartKasa 是否需要 API 密钥?

编号SmartKasa是收据扫描中的收据来源,由商店ID或公司代码添加。

顾客在哪里扫描 SmartKasa 收据?

在你们企业的聊天机器人中。这些印章会进入该收据来源的员工登录。

财政收据在哪些国家适用?

在乌克兰、斯洛伐克、哈萨克斯坦和乌兹别克斯坦。

Make 和 Zapier

在“集成”选项卡上的Make

适用于 Make 的 7Stamp 应用位于 Make 的公共应用库中:在任意 Make 场景中搜索 7Stamp,或在集成选项卡上使用“在Make中打开”。我们的 Zapier 应用不在 Zapier 的公共目录中:“在Zapier中打开”是一个邀请,会将应用添加到企业自己的 Zapier 账户中。两个应用都使用员工登录的 API 密钥。

Make 场景和 Zaps 是由 7Stamp Webhooks 启动的,因此触发器需要 Webhooks & Events 插件。像添加印章或发行代金券这样的操作只需要一个 API 密钥。Make 和 Zapier 不提供给 White Label 商业用户。

在 Make 和 Zapier 中哪里可以找到 7Stamp 应用?

在 Make 中,在任意场景里搜索 7Stamp 即可 — 该应用位于 Make 的公共应用库中。在 Zapier 中它尚未公开,因此请在集成选项卡上使用“在Zapier中打开” — 邀请会将应用添加到你自己的账户中。

Make和Zapier需要Webhooks & Events附加组件吗?

触发器确实会触发,因为场景和 Zaps 是由7Stamp网络钩子启动的。诸如添加印章或发放凭证等操作只需要一个API密钥。

我需要为Make或Zapier准备一个API钥匙吗?

是的。这些应用程序可以与员工登录的API密钥一起使用。

参考资料
运营 2026年10月28日

套餐与计费

三种计划,什么是 Card Operation,什么是计费的,什么是免费的,附加项,来自 Access Code 的 Packages,以及付款失败时会发生什么。

更新时间: 2026年10月28日

打开文章
参考资料
运营 2026年10月28日

员工通道

什么是员工登录,如何创建、更改、关闭和删除一个,员工如何登录 7Stamp Scanner,他们在那里可以做什么,以及谁使用管理面板。

更新时间: 2026年10月28日

打开文章
参考资料
运营 2026年10月28日

顾客与历史记录

顾客的集章卡列表、顾客的卡片页面、删除卡片、事件日志、7Stamp对顾客的记录以及顾客数据是如何被删除的。

更新时间: 2026年10月28日

打开文章