Hướng dẫn tích hợp

Để gọi Open API, bạn cần tạo ứng dụng và lấy API client key và secret.

Tạo ứng dụng

1. Màn hình app Điền mẫu đăng ký.
2. Nhập tên dịch vụ, tên tiếng Anh (mã kênh) và URL, rồi gửi.
3. Sau xét duyệt, kênh riêng tư sẽ được tạo; kết quả gửi qua email. Nếu được duyệt, bạn có thể tạo API key trực tiếp trên trang app theo hướng dẫn.

Cấp API client

1. Trang chi tiết app của API client trong phần [Thêm client] nhấn vào.
2. Nhập Client ID (tự do, tối đa 100 ký tự) và chọn scope.
3. Hiển thị ngay sau khi tạo Lưu Client Secret ngay vào nơi an toàn Giá trị này sẽ không được hiển thị lại.

Scope

• buildingUnit:readBUILDING_UNIT_READXem phòng
• buildingUnit:writeBUILDING_UNIT_WRITETạo/Sửa mapping phòng
• booking:readBOOKING_READXem đặt chỗ
• booking:writeBOOKING_WRITETạo/Sửa đặt chỗ
• contract:readCONTRACT_READXem hợp đồng
• contract:writeCONTRACT_WRITETạo/Sửa hợp đồng (Phương thức B)
• user:writeUSER_WRITETạo user (Phương thức A · liên kết đăng nhập)
• userLoginTicket:writeUSER_LOGIN_TICKET_WRITECấp ticket đăng nhập (Phương thức A · liên kết đăng nhập)
• chat:readCHAT_READXem chat
• chat:writeCHAT_WRITETạo/Gửi chat

Để đăng hợp đồng/đặt chỗ qua API, tạo phòng test và cấu hình mapping.

Quy trình

1. Màn hình chủ nhà Đăng phòng mới.
2. Màn hình ánh xạ kênh Chọn phòng đã đăng, rồi thiết lập ánh xạ theo loại phòng và theo số phòng. Ánh xạ theo loại phòng là tùy chọn, nhưng bạn phải thiết lập ánh xạ theo số phòng để có thể đăng hợp đồng qua Open API. Đặt ID tin đăng bên ngoài bằng giá trị ID của phòng trên kênh đó.
3. Để kiểm tra phòng trên trang khách, /rooms/{roomId}hãy truy cập vào đó.

Đăng MCP server của plott LIFE Open API vào AI coding agent (Claude Code, Cursor...) để agent có thể đọc spec ngay và hỗ trợ tích hợp nhanh hơn.

Đăng vào 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)} là chuỗi gồm Client ID và Secret lấy ở Step 01 clientId:clientSecret được nối bằng dấu hai chấm rồi mã hóa base64.

Tùy mức dịch vụ đối tác xử lý trực tiếp, có hai phương thức tích hợp Phương thức A · Liên kết đăng nhập là phương thức hand-off: chỉ tích hợp danh sách phòng và đăng nhập, chuyển hợp đồng/ thanh toán sang plott LIFE, Phương thức B · Liên kết hợp đồng là phương thức tích hợp cả API hợp đồng để hoàn tất bán hàng trong app đối tác. Chọn tab bên dưới để xem các bước triển khai và vận hành tương ứng.

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회용

Nếu đã kiểm thử tích hợp kỹ trên kênh riêng, yêu cầu chuyển sang kênh công khai để mở quyền truy cập đến phòng của mọi host. Bước này giống nhau cho cả hai phương thức.

Cách yêu cầu

1. Trang chi tiết app trên thẻ trạng thái đăng ký [Yêu cầu chuyển kênh công khai] Nhấn vào
2. Nhóm vận hành sẽ xem xét và thông báo kết quả qua email.
3. Nếu bị từ chối, xem lý do, chỉnh sửa và nộp lại.

Khi là kênh công khai, bạn có thể truy vấn phòng của mọi host trên plott LIFE qua Open API mà không cần thao tác thêm. Chọn phòng muốn xử lý và thiết lập channel mapping, rồi vận hành theo luồng tích hợp đã chọn.

Xem toàn bộ danh sách phòng

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

Mọi yêu cầu tới Open API đều dùng xác thực HTTP Basic. Trang chi tiết app được cấp từ Client ID và Client Secret nối bằng dấu hai chấm, sau đó mã hóa base64 Authorization đặt vào header rồi gửi.

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

Khi xảy ra lỗi RFC 9457 Problem Detail sẽ trả về theo định dạng sau.

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

• typeURI loại lỗi
• titleThông điệp trạng thái HTTP
• statusMã trạng thái HTTP
• detailThông điệp lỗi chi tiết
• instanceĐường dẫn yêu cầu

Open API giới hạn số lần gọi để đảm bảo ổn định dịch vụ và công bằng cho đối tác.

• Phạm vi áp dụngTất cả endpoint dưới /open/**
• Đơn vị giới hạnTài khoản host
• Giới hạn300 yêu cầu/phút
• Cơ chế phục hồiPhục hồi liên tục (greedy refill). Khoảng 1s nạp lại tương đương 5 lượt.

Phản hồi khi vượt giới hạn

Yêu cầu vượt giới hạn sẽ bị từ chối ngay lập tức và 429 Too Many Requests sẽ trả về phản hồi lỗi.

Cách xử lý khuyến nghị cho client

• 429 Khi nhận phản hồi, không thử lại ngay lập tức, chờ một khoảng rồi thử lại.
• Trung bình khoảng khoảng 200ms là có thể gọi ổn định.
• Với batch cần nhiều request trong thời gian ngắn, tăng khoảng cách giữa các gọi hoặc dùng exponential backoff.