API 与集成

14. API 与集成

[截图：0601_Apikey.png]

API 和集成 部分包含用于将7stamp 与外部系统（CRM、POS、ERP、分析、消息机器人）进行编程集成的工具。

API Keys

该部分的主页是API键列表。栏目：

• 名称 — 键名称（通常与链接的员工名称匹配）。
• 登录 — 密钥所绑定的员工登录名。
• API Key — 密钥本身（以 7loc_sc_... 开头，默认隐藏，一键复制）。
• 状态 —“活动”。
• 🔄 — 重新生成密钥。
• 🗑️ — 删除密钥。

创建 API 密钥

[截图：0602_Apikey.png]

点击 + ADD API KEY — 将打开 Generate API Key 弹出窗口：

• 扫描仪 — 下拉菜单中选择密钥将绑定到的Staff Login（一名员工可以拥有一把密钥）。
• 按钮 取消 / 生成。

GENERATE 之后，密钥将被创建并显示在列表中。立即复制 — 完整密钥可能不会再次显示。

您可以通过API做什么

• 通过电子邮件/电话向客户发行卡。
• 向特定客户添加印花。
• 签发凭证（模板或自定义，带有Redeem Code）。
• 兑换优惠券（如果您通过自己的POS工作）。
• 读取卡片的状态、进度、历史记录。
• 订阅 Webhooks 以实时接收事件。

网络钩子

Webhook 将卡片事件发送到外部系统。支持（参见事件词汇表）：

• SCAN, DELIVERY_INSERT。
• REWARD_EARNED, LOTTERY_WIN。
• VOUCHER_ISSUED, ADMIN_VOUCHER_ISSUE, VOUCHER_REDEEMED。
• CARD_JOINED, CARD_ADDED_TO_WALLET, CARD_REMOVED_FROM_WALLET。
• CARD_CAMPAIGN, BIRTHDAY_GREETING。

Webhook 负载示例

{
  "entity": "card_event",
  "action": "created",
  "entity_id": 707,
  "event_id": "8f05e58decec48e09d328f0edebbacf6",
  "profile_id": 2,
  "profile_name": "Your Business",
  "profile_lang": "en",
  "data": {
    "event_type": "SCAN",
    "scanned_at": "2026-10-01T09:19:24.179424",
    "user_card_id": 10,
    "card_template_id": 14,
    "card_template_name": "Collect your stamps!",
    "stamps_added": 3,
    "stamps_before": 1,
    "stamps_after": 4,
    "amount": null,
    "external_order_id": "ORDER-1001",
    "workplace": { "id": 4, "name": "Bar Counter" },
    "device_type": null,
    "external_id": "odoo_contact_8821",
    "external_source": "odoo",
    "issued_vouchers": [
      {
        "id": 174,
        "unique_code": "100425813507",
        "stamp_number": 4,
        "issued_at": "2026-10-01T09:19:24.191836",
        "expires_at": "2027-01-01T23:59:59",
        "status": "ACTIVE",
        "voucher_template_id": 58,
        "voucher_description": "Free coffee",
        "voucher_image_url": "https://..."
      }
    ],
    "achieved_goals": [],
    "user": {
      "id": 2,
      "name": "Anna",
      "full_name": "Anna Smith",
      "email": "anna@example.com",
      "telegram_chat_id": null,
      "telegram_username": null,
      "whatsapp_phone": null,
      "birth_date": null
    }
  }
}

现成的 POS 集成

• Poster — 现成的集成，只需点击几下即可连接。
• 服务——现成的集成。
• 其他收银机 — 根据要求制作。 如果技术上可行，则免费（即，您的收银机公开开放的 API 或 Webhooks）。

Messenger 通过 7loc.com 进行广播

对于 WhatsApp、Telegram、Viber 广播，已连接 7loc.com 集成。一旦激活，“messengers”通道将在“PUSH”和Email 旁边的“Campaigns”中可用。

无代码场景：Zapier 和 Make

7Stamp API + Webhook 与 Zapier 和 Make (Integromat) 配合使用，让您无需编码即可构建场景：

• “当VOUCHER_REDEEMED时——在Mailchimp中添加一个标签”。
• “当REWARD_EARNED时——发送通知到Slack”。
• “当BIRTHDAY_GREETING时——在CRM中创建一个任务”。

---