接入指南

调用 Open API 前，需先创建应用并获取 API 客户端的 Key 与 Secret。

创建应用

1. 应用界面在控制台填写申请表。
2. 填写服务名称、英文名（渠道代码）与服务 URL 后提交。
3. 运营团队审核通过后会创建私有渠道，审核结果会通过邮件通知。审核通过后，可在应用详情页按下述流程创建 API 密钥。

颁发 API 客户端

1. 应用详情页的 API 客户端 部分中 [添加客户端] 并点击。
2. 填写 Client ID（自由格式，最多 100 字）并选择所需 scope。
3. 创建后立即显示的 请立即将 Client Secret 安全保存 。此值不会再次显示。

权限（Scope）

• 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 编码后的值。

根据合作方要自行处理的范围，有两种对接方式。 方式 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. 若被驳回，请查看原因并完善后重新申请。

一旦成为公开渠道，无需额外操作即可通过 Open API 查询 plott LIFE 上所有房东的房源。选中要对接的房源并设置渠道映射后，即可按所选对接方式进行运营。

查看全部房源

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/** 下的所有端点
• 限制单位房东账号
• 上限每分钟 300 次请求
• 恢复方式连续恢复（greedy refill）。约每 1 秒补充相当于 5 次请求的令牌。

超限响应

超出限额的请求会被立即拒绝， 429 Too Many Requests 并返回错误响应。

建议的客户端处理方式

• 429 收到响应后 不要立刻重试 等待一段时间再重试。
• 平均约 200 毫秒间隔 即可稳定调用。
• 需要在短时间内发起大量请求的批处理，请增加调用间隔或实现指数回退（exponential backoff）重试。