連携ガイド

Open APIを利用するには、アプリ作成後にAPIクライアントキーとシークレットを発行してください。

アプリ作成

1. アプリ画面で申請フォームを記入します。
2. サービス名・英語名（チャネルコード）・サービスURLを入力して送信
3. 運営チームの審査後に非公開チャネルが作成され、結果はメールで通知されます。承認後、アプリ詳細ページからAPIキーを発行できます。

APIクライアント発行

1. アプリ詳細ページの APIクライアント セクションで [クライアントを追加] をクリックします。
2. Client ID（自由形式、最大100文字）と使用するスコープを選択します。
3. 作成直後に表示される Client Secretをすぐに安全な場所に保存 してください。この値は再表示されません。

スコープ

• buildingUnit:readBUILDING_UNIT_READ部屋参照
• buildingUnit:writeBUILDING_UNIT_WRITE部屋マッピング作成・編集
• booking:readBOOKING_READ予約参照
• booking:writeBOOKING_WRITE予約作成・変更
• contract:readCONTRACT_READ契約参照
• contract:writeCONTRACT_WRITE契約作成・変更（方式B）
• user:writeUSER_WRITEユーザー作成（方式A・ログイン連携）
• userLoginTicket:writeUSER_LOGIN_TICKET_WRITEログインチケット発行（方式A・ログイン連携）
• chat:readCHAT_READチャット参照
• chat:writeCHAT_WRITEチャット作成・送信

APIで契約・予約を登録するには、テスト用の部屋を作成しチャネルマッピングを設定する必要があります。

手順

1. ホスト画面で新しい部屋を登録します。
2. チャネルマッピング画面登録した部屋を選び、部屋単位マッピングと室単位マッピングを設定します。部屋単位は任意ですが、室単位マッピングを設定しないとOpen APIで契約登録できません。外部物件IDには該当チャネルで使用する室のIDを指定してください。
3. ゲストページで登録した部屋を確認するには /rooms/{roomId}にアクセスしてください。

AIコーディングエージェント（Claude Code、Cursorなど）にplott LIFE Open APIのMCPサーバーを登録すると、エージェントがAPI仕様を即座に参照でき、より速く連携できます。

Claude Codeに登録

claude mcp add --transport http plott-life-partner \
  https://life.plott.co.kr/api/open/mcp \
  --header "Authorization: Basic {base64(clientId:clientSecret)}"

{base64(clientId:clientSecret)} はStep 01で発行したClient IDとSecretを clientId:clientSecret の形式で結合してbase64でエンコードした値です。

パートナーサービスがどこまで対応するかにより、連携方式は2種類あります。 方式A・ログイン連携 は部屋一覧とログインのみを連携し、契約・決済はplott LIFEへ引き渡すハンドオフ方式です。 方式B・契約連携 は契約APIまで連携し、パートナーアプリ内で販売を完結する方式です。下のタブで方式を選ぶと、対応する実装・運用ステップが表示されます。

const res = await fetch(
  'https://life.plott.co.kr/api/open/v1/building-unit-type?page=0&size=20&operationStatus=PUBLISHED',
  { headers: { Authorization: `Basic ${credentials}` } },
);
const { items, totalItems, totalPages } = await res.json();

const res = await fetch('https://life.plott.co.kr/api/open/v1/user', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Basic ${credentials}`,
  },
  body: JSON.stringify({
    externalUserId: 'partner-user-001',
    email: 'user@example.com',
    firstName: '길동',
    lastName: '홍',
    phoneCode: '82',
    phoneNumber: '1012345678',
    countryCode: 'KR',
  }),
});

const { id } = await res.json(); // 플라트라이프 회원 ID

const res = await fetch(
  'https://life.plott.co.kr/api/open/v1/userLoginTicket',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Basic ${credentials}`,
    },
    body: JSON.stringify({ externalUserId: 'partner-user-001' }),
  },
);

const { ticket } = await res.json(); // 5분 TTL · 1회용

非公開チャネルで連携を十分に検証したら、公開チャネルへの切替を申請して全ホストの部屋にアクセスできる権限を拡張します。この手順は両方式とも同じです。

申請方法

1. アプリ詳細ページ申請状況カードで [公開チャネル切替申請] をクリックします。
2. 運営チームが審査し、結果をメールで通知します。
3. 却下された場合は理由を確認し、補足のうえ再申請できます。

公開チャネルになると、追加作業なしでplott LIFEに登録された全ホストの部屋をOpen APIで取得できます。取得した部屋から扱う物件を選んでチャネルマッピングを設定すれば、選んだ連携方式のフローでそのまま運用できます。

全物件一覧の取得

const res = await fetch(
  'https://life.plott.co.kr/api/open/v1/building-unit-type?page=0&size=20',
  { headers: { Authorization: `Basic ${credentials}` } },
);
const { items, totalItems, totalPages } = await res.json();

Open APIの全リクエストはHTTP Basic認証を使用します。 アプリ詳細ページで発行された Client ID と Client Secret をコロンでつなぎbase64でエンコードして Authorization ヘッダーに入れて送信してください。

const credentials = Buffer.from(
  `${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`,
).toString('base64');

const res = await fetch('https://life.plott.co.kr/api/open/v1/contract-channel', {
  headers: {
    Authorization: `Basic ${credentials}`,
  },
});

エラー発生時 RFC 9457 Problem Detail の形式で応答します。

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "예약 매핑을 찾을 수 없습니다.",
  "instance": "/open/v1/booking"
}

• typeエラータイプURI
• titleHTTPステータステキスト
• statusHTTPステータスコード
• detailエラー詳細メッセージ
• instanceリクエストパス

サービス安定性とパートナーの公平利用のため、Open APIに呼び出し制限を設けています。

• 適用範囲/open/** の全エンドポイント
• 制限単位ホストアカウント
• 上限1分あたり300リクエスト
• 回復方式連続回復（greedy refill）。約1秒ごとに5リクエスト分のトークンが補充されます。

上限超過応答

上限を超えたリクエストは即時拒否され、 429 Too Many Requests が返されます。

推奨クライアント処理

• 429 応答を受けたら すぐに再試行せず 一定時間待ってから再試行してください。
• 平均で約 200ms間隔 なら安定して呼び出せます。
• 短時間で多数リクエストが必要なバッチは、間隔を開けるか指数バックオフで再試行してください。