연동 가이드

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 등)에 플라트라이프 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 · 로그인 연동 은 방 목록과 로그인까지만 연동하고 계약·결제는 플라트라이프로 넘기는 핸드오프 방식이며, 방식 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로 조회할 수 있습니다. 조회한 방 중 다룰 방을 선택해 채널 매핑을 설정하면, 선택한 연동 방식의 흐름으로 그대로 운영할 수 있습니다.

방 전체 목록 조회

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 응답을 받으면 즉시 재시도하지 말고 일정 시간 대기 후 재시도하세요.
• 평균 약 200ms 간격 이면 안정적으로 호출할 수 있습니다.
• 짧은 시간 안에 다수 요청이 필요한 배치 작업은 호출 간격을 두거나 지수 백오프(exponential backoff) 재시도를 구현하세요.