seam-access-codes

Seam Access Codes（低レベル API）

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

アプローチ

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

Access Codes の仕組み

特定のデバイスに、期限付きのアクセスコードを直接作成します。各コードには starts_at と ends_at の期間が設定されています。後で更新または削除できるよう、access_code_id を保存する必要があります。Seam はコードをロックに登録し、有効期限が切れるか削除されるとコードを取り除きます。

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. デバイス ID を取得する

Access Codes は device_id を指定して特定のデバイスを対象にします。各部屋／ドアには、それぞれ固有のデバイス ID を割り当てる必要があります。すべての部屋に単一のグローバルデバイスを使用しないでください。

次の場所でデバイス ID を探します。

• 部屋ごとの環境変数：SEAM_DEVICE_ROOM_A1、SEAM_DEVICE_ID_ROOM_101 など
• アプリのデータモデル（例：room.seamDeviceId、unit.deviceId）

マッピングが見つからない場合は、処理を失敗させてください。グローバルデバイスにフォールバックしないでください。

3. 予約作成時にアクセスコードを作成する

作成関数の中に直接追加します。access_code_id を予約オブジェクトに保存してください。

// Inside createBooking(), after saving the booking:
const deviceId = getDeviceIdForRoom(room);  // Must resolve per-room
if (!deviceId) {
  throw new Error(`No Seam device configured for room ${room.id}`);
}
try {
  const accessCode = await seam.accessCodes.create({
    device_id: deviceId,
    name: `${member.name} - ${room.name}`,
    starts_at: booking.startTime,
    ends_at: booking.endTime
  });
  booking.seamAccessCodeId = accessCode.access_code_id;
  booking.accessCode = accessCode.code;  // The actual PIN
} catch (err) {
  console.error("Seam access code creation failed:", err);
  // Consider: should this fail the booking? If access is required, throw.
}

# Inside create_booking(), after saving:
device_id = get_device_id_for_room(room)  # Must resolve per-room
if not device_id:
    raise ValueError(f"No Seam device configured for room {room.id}")
try:
    access_code = seam.access_codes.create(
        device_id=device_id,
        name=f"{member.name} - {room.name}",
        starts_at=booking.start_time,
        ends_at=booking.end_time
    )
    booking.seam_access_code_id = access_code.access_code_id
    booking.access_code = access_code.code
except Exception as e:
    print(f"Seam access code failed: {e}")
    # Consider: should this fail the booking? If access is required, raise.

注意点

• access_code_id を保存します。更新や削除に必要です。予約モデルにフィールドがない場合は追加してください。値が null／undefined の場合、コードの作成に失敗しており、再試行が必要です。
• グローバルデバイスへのフォールバックは使用しないでください。各部屋には固有のデバイスを割り当てる必要があります。
• device_id は単一の文字列です（コードごとにデバイスは 1 台）。配列ではありません。
• 特定の PIN が必要な場合を除き、code の値をハードコードしないでください。Seam はデフォルトでランダムなコードを生成します。
• name は任意ですが、設定を推奨します。識別用に Seam Console に表示されます。
• コードスロットの上限：ロックによっては、作成できるコード数に上限があります。device.properties.max_active_codes_supported を確認してください。
• 失敗時の処理を決めます。部屋の予約にアクセスコードが必須の場合（例：施錠された会議室）は、Seam の処理が失敗したら例外をスローしてください。アクセスコードが任意の場合は、ログを記録して処理を続行します。

4. 予約変更時にアクセスコードを更新する

if (booking.seamAccessCodeId) {
  await seam.accessCodes.update({
    access_code_id: booking.seamAccessCodeId,
    starts_at: booking.startTime,
    ends_at: booking.endTime
  });
}

if booking.seam_access_code_id:
    seam.access_codes.update(
        access_code_id=booking.seam_access_code_id,
        starts_at=booking.start_time,
        ends_at=booking.end_time
    )

5. キャンセル時にアクセスコードを削除する

if (booking.seamAccessCodeId) {
  await seam.accessCodes.delete({
    access_code_id: booking.seamAccessCodeId
  });
}

if booking.seam_access_code_id:
    seam.access_codes.delete(
        access_code_id=booking.seam_access_code_id
    )

6. Webhook エンドポイントを追加する

コードベース内の既存の Webhook パターンに従ってください。

router.post("/seam", (req, res) => {
  const { event_type, ...data } = req.body;
  switch (event_type) {
    case "access_code.set_on_device":
      // Code is on the lock — safe to share with the user
      console.log("Code set:", data.access_code_id);
      break;
    case "access_code.failed_to_set_on_device":
      console.log("Code failed:", data.access_code_id);
      break;
    case "device.disconnected":
      console.log("Lock offline:", data.device_id);
      break;
  }
  res.json({ received: true });
});

7. 関数を非同期にする

サービス関数を非同期にし、呼び出し元で await を使用するように更新します。

問題が発生した場合は、references/troubleshooting.md を読んでください。本番環境への対応については、references/production-checklist.md を読んでください。