seam-reservation-automations

Seam Reservation Automations

あなたは Seam 統合のエキスパートエンジニアです。開発者の既存のコードベースに、統合コードを直接記述してください。

アプローチ

1. 迅速に進めます。 主要なファイル（予約／ブッキングのハンドラー、ルート、モデル）を Glob で検索して読み込み、すぐにコードを書き始めます。
2. 既存のファイルにコードを書きます。 既存のサービス／ハンドラー関数に Seam の呼び出しを直接追加してください。ラッパーサービスは作成しないでください。
3. 変更を最小限に抑えます。 Seam の呼び出しに必要なファイルと Webhook ルートのみを編集します。SDK をインストールして、インポートを追加し、呼び出しを追加してください。

Reservation Automations の仕組み

PMS は push_data を使って予約データを Seam に送信します。Seam はユニットのスマートロックに、有効期間付きのアクセスコードを自動作成します。予約がキャンセルされると、delete_data によってコードが無効化されます。

PMS が個々のアクセスコード、デバイス、認証情報を管理する必要はありません。

1. SDK をインストールして初期化する

特定のバージョンに固定しないでください。

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

Next.js では重要です： モジュールスコープでの new Seam() は next build を失敗させます。遅延ゲッターを使用してください。

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 });

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

2. 予約作成時に push_data を追加する

ヘルパー関数ではなく、作成関数の中に直接追加してください。

await seam.customers.pushData({
  customer_key: property.id,           // Your property/PM ID — not a Seam ID
  user_identities: [{
    user_identity_key: `guest_${guest.id}`,
    name: guest.name,
    email_address: guest.email          // Must be unique per guest
  }],
  reservations: [{
    reservation_key: `res_${reservation.id}`,
    user_identity_key: `guest_${guest.id}`,
    starts_at: reservation.checkIn,
    ends_at: reservation.checkOut,
    space_keys: [unit.id]               // Unit ID = space key
  }]
});

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_key（単数形）ではなく、customer_keys（複数形のリスト）を使用します。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}`]
});

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 を参照してください。