연동 가이드

Open API를 호출하려면 먼저 앱을 만들고 API 클라이언트 키와 시크릿을 발급받아야 합니다.

앱 만들기

1. 앱 화면에서 신청서를 작성합니다.
2. 서비스 이름, 서비스 영문 이름(채널 코드), 서비스 URL을 입력하고 제출합니다.
3. 운영팀 검토 후 비공개 채널이 생성되며, 결과는 이메일로 안내됩니다.

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계약 생성·수정

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-api-docs \
  https://life.plott.co.kr/open/mcp \
  --header "Authorization: Basic {base64(clientId:clientSecret)}"

{base64(clientId:clientSecret)}은 Step 01에서 발급받은 Client ID와 Secret을 clientId:clientSecret 형식으로 이어 붙인 뒤 base64로 인코딩한 값입니다.

파트너 서비스에서 사용자가 계약을 진행할 때, 백엔드에서 Open API를 호출해 플라트라이프에 계약을 등록합니다. 계약 진행 단계마다 상태를 변경해 양쪽 시스템을 동기화합니다. 결제가 완료되기 전에 플라트라이프에 계약을 먼저 등록하여 다른 채널에서 중복 예약이 발생하지 않도록 구현해주세요.

계약 생성

POST /open/v1/contract로 새 계약을 만듭니다. 핵심 필드는 다음과 같습니다.

• externalId필수파트너 서비스의 계약 식별자
• buildingUnitExternalId필수파트너 서비스의 호실 식별자
• startAt / endAt필수 · UTC계약 시작·종료 시간
• currency / deposit필수통화 / 보증금
• rentFeePerWeek / totalRentFee필수주당 임대료 / 총 임대료
• cleaningFee필수청소비
• managementFeePerWeek / totalManagementFee필수주당 관리비 / 총 관리비
• totalPrice필수할인 전 총 금액
• contractStatus필수계약 상태 (보통 REQUESTED)
• guestName / guestEmail / guestPhone…선택입주자 정보

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', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Basic ${credentials}`,
  },
  body: JSON.stringify({
    externalId: 'partner-contract-001',
    buildingUnitExternalId: 'partner-unit-001',
    startAt: '2026-04-16T05:00:00Z',
    endAt: '2026-07-16T05:00:00Z',
    currency: 'KRW',
    deposit: 1_000_000,
    rentFeePerWeek: 500_000,
    totalRentFee: 6_500_000,
    cleaningFee: 100_000,
    managementFeePerWeek: 50_000,
    totalManagementFee: 650_000,
    totalPrice: 8_250_000,
    contractStatus: 'REQUESTED',
    guestEmail: 'guest@example.com',
    guestName: '홍길동',
  }),
});

const contract = await res.json();

계약 상태 변경

결제·승인·취소 등 진행 상태가 바뀔 때마다 PUT /open/v1/contract/{contractId}로 전체 계약을 덮어씁니다. 변경하지 않는 필드도 반드시 함께 보내야 합니다.

# contractStatus만 APPROVED로 바꾸려는 경우에도, 기존 모든 필드를 함께 전송해야 합니다.
PUT /open/v1/contract/18421
{
  ...기존 필드 그대로...,
  "contractStatus": "APPROVED"
}

계약 상태(ContractStatus)

• REQUESTED계약 요청 (승인 대기)
• APPROVED계약 승인 (결제 대기)
• REJECTED계약 거절
• EXPIRED_APPROVAL승인 만료
• EXPIRED결제 만료
• COMPLETED계약 완료 (결제 완료)
• CANCELED_NOPAY결제 전 취소
• CANCELED결제 후 취소
• USING이용 중
• MOVED_OUT퇴거 완료

외부 식별자로 조회

파트너 서비스의 식별자만으로 계약을 다시 찾으려면 GET /open/v1/contract?externalId=…를 사용하세요. 응답으로 플라트라이프 측 계약 ID와 상세 정보를 받을 수 있습니다.

플라트라이프에서 계약·예약 상태가 변경될 때 파트너 서비스가 폴링 없이 즉시 알림을 받을 수 있습니다. 앱 상세 페이지의 웹훅 구독 섹션에서 등록합니다.

지원 이벤트 타입

• CONTRACT_UPDATED계약 생성·수정·상태 변경 시 발송
• BOOKING_UPDATED예약 생성·수정·상태 변경 시 발송
• BUILDING_UNIT_TYPE_UPDATED방 타입 생성·수정 시 발송

구독 등록

1. 앱 상세 페이지의 웹훅 구독 섹션에서 [구독 추가]를 클릭합니다.
2. 계약 채널, Target URL(HTTPS 권장), 수신할 이벤트 타입을 선택해 저장합니다.
3. 생성 직후 표시되는 Secret을 즉시 안전한 곳에 저장하세요. 이 값은 HMAC 서명 검증에 사용되며, 다시 표시되지 않습니다.

수신 엔드포인트 구현

파트너 서비스에는 HTTP POST를 받을 수 있는 공개 엔드포인트가 필요합니다. 요청 본문 페이로드나 서명 검증 방법은 API 문서에서 확인 가능합니다.

파트너 서비스의 자체 재고 시스템과 플라트라이프 사이의 이중 예약을 방지하기 위해, 플라트라이프가 계약을 등록하기 전 파트너 서비스에 미리 재고를 확인할 수 있습니다.

설정

1. 앱 상세 페이지의 재고 조회 API URL 섹션에서 [URL 수정]을 클릭합니다.
2. HTTPS URL(예: https://example.com/api/inventory)을 입력하고 저장합니다.
3. 플라트라이프가 계약 등록 직전에 이 URL을 호출해 예약 가능 여부를 확인합니다.

요청 페이로드

플라트라이프가 등록한 URL을 POST로 호출하며, 본문에는 아래 필드가 포함됩니다.

{
  "buildingUnitId": 1,
  "buildingUnitExternalId": "partner-unit-001",
  "startAt": "2026-04-16T05:00:00Z",
  "endAt": "2026-07-16T05:00:00Z"
}

• buildingUnitId플라트라이프 호실 식별자
• buildingUnitExternalId파트너 서비스에서 사용하는 호실 식별자
• startAtUTC예약 시작 시간
• endAtUTC예약 종료 시간

응답

응답이 2xx면 예약 가능한 상태로 봅니다.

비공개 채널에서 충분히 연동을 검증했다면, 공개 채널 전환을 요청해 모든 호스트의 방에 접근할 수 있도록 권한을 확장합니다.

요청 방법

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

공개 채널로 전환된 뒤에는 조회한 방 중에서 파트너 서비스에서 다룰 방을 선택해 채널 매핑을 설정합니다. 매핑된 방에는 Step 04에서 사용한 동일한 흐름으로 계약을 등록할 수 있습니다.

전체 운영 흐름

1. GET /open/v1/building-unit-type로 방 목록을 가져와 다룰 방을 선택합니다.
2. 채널별 매핑 API로 채널 매핑을 설정합니다.
3. 매핑된 방의 buildingUnitExternalId를 사용해 계약 등록 API로 계약을 등록합니다.

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) 재시도를 구현하세요.