seam-reservation-automations

用途

Seam Reservation Automations 面向需要将 Seam 预订自动化能力嵌入到物业管理（PMS）或度假租赁平台中的集成场景。其目标是让 PMS 不必自行管理智能门锁的访问码、设备或凭证，只需推送预订数据，由 Seam 自动完成访问码的创建与撤销。

主要能力

• 预订数据推送：PMS 通过 push_data 将预订相关信息（客户、宾客身份、入住与退房时间、单元等）发送给 Seam。
• 自动生成访问码：Seam 在单元的智能门锁上自动创建有时限的访问码。
• 取消预订时撤销：预订被取消时，通过 delete_data 撤销访问码。
• 更新处理：在更新处理器中对同一 reservation_key 再次调用 push_data，Seam 会识别为更新。
• Webhook 事件：提供端点接收并处理 access_code.set_on_device、access_code.failed_to_set_on_device、device.disconnected 等事件。

使用方式

1. 安装 SDK 并初始化

安装命令（文档要求不要锁定到特定版本）：

npm install seam        # Node.js
pip install seam        # Python
bundle add seam         # Ruby

Next.js 中在模块作用域创建 new Seam() 会破坏 next build，应使用懒加载 getter：

import { Seam } from "seam";
let _seam: Seam;
function getSeam() {
  if (!_seam) _seam = new Seam({ apiKey: process.env.SEAM_API_KEY! });
  return _seam;
}

Express / 标准 Node.js 可直接在模块作用域初始化：

import { Seam } from "seam";
const seam = new Seam({ apiKey: process.env.SEAM_API_KEY });

Python：

from seam import Seam
seam = Seam(api_key=os.environ["SEAM_API_KEY"])

2. 在预订创建流程中加入 push_data

调用直接写在创建函数内部，而非辅助函数中：

await seam.customers.pushData({
  customer_key: property.id,           // 你的物业/PM ID，不是 Seam 生成的 ID
  user_identities: [{
    user_identity_key: `guest_${guest.id}`,
    name: guest.name,
    email_address: guest.email          // 每位宾客必须唯一
  }],
  reservations: [{
    reservation_key: `res_${reservation.id}`,
    user_identity_key: `guest_${guest.id}`,
    starts_at: reservation.checkIn,
    ends_at: reservation.checkOut,
    space_keys: [unit.id]               // 单元 ID = space key
  }]
});

Python：

seam.customers.push_data(
    customer_key=property.id,
    user_identities=[{
        "user_identity_key": f"guest_{guest.id}",
        "name": guest.name,
        "email_address": guest.email
    }],
    reservations=[{
        "reservation_key": f"res_{reservation.id}",
        "user_identity_key": f"guest_{guest.id}",
        "starts_at": reservation.check_in,
        "ends_at": reservation.check_out,
        "space_keys": [unit.id]
    }]
)

注意事项：customer_key 应使用数据模型中已有的 ID（物业 ID、PM ID），而非 Seam 生成的 ID；space_keys 必须与在 Seam 中创建该空间时使用的 space_key 一致（通常是单元/房间 ID）；email_address 必须每位宾客唯一，重复会导致静默失败（返回 ok: true 但不创建代码）；delete_data 使用的是复数的 customer_keys 列表，而非 customer_key，与 push_data 不同；所有 Seam 调用应包裹 try/catch，Seam 错误不应中断预订流程。

3. 在预订更新流程中加入 push_data

在更新处理器中使用相同的 reservation_key 调用同一接口，Seam 会识别为更新：

await seam.customers.pushData({
  customer_key: property.id,
  reservations: [{
    reservation_key: `res_${reservation.id}`,
    user_identity_key: `guest_${reservation.guestId}`,
    starts_at: reservation.checkIn,
    ends_at: reservation.checkOut,
    space_keys: [reservation.unitId]
  }]
});

4. 在取消流程中加入 delete_data

await seam.customers.deleteData({
  customer_keys: [property.id],
  reservation_keys: [`res_${reservation.id}`],
  user_identity_keys: [`guest_${reservation.guestId}`]
});

Python：

seam.customers.delete_data(
    customer_keys=[property.id],
    reservation_keys=[f"res_{reservation.id}"],
    user_identity_keys=[f"guest_{reservation.guest_id}"]
)

5. 添加 webhook 端点

找到已有 webhook 处理器，按相同模式添加 Seam 端点：

router.post("/seam", (req, res) => {
  const { event_type, ...data } = req.body;
  switch (event_type) {
    case "access_code.set_on_device":
      console.log("Access code set:", data.access_code_id);
      break;
    case "access_code.failed_to_set_on_device":
      console.log("Access code failed:", data.access_code_id);
      break;
    case "device.disconnected":
      console.log("Device disconnected:", data.device_id);
      break;
  }
  res.json({ received: true });
});

6. 将函数改为异步

将服务函数改为异步，并更新调用方以 await 它们。

适用场景

适用于已具备预订/取消流程的物业管理或度假租赁平台，希望在不自行管理门锁访问码和设备的情况下，为预订自动开通和撤销门锁访问权限。

限制

文档提到若出现问题可阅读 references/troubleshooting.md，若需生产就绪可阅读 references/production-checklist.md。除上述接口、字段要求和注意事项外，其他价格、收费、平台覆盖范围等信息暂未提供。