마켓플레이스 Open API

마켓플레이스 앱이 VPMS 데이터에 접근하는 외부 REST 평면이다. GraphQL 과 별개의 평면이며, OAuth2 bearer 토큰으로 인증되고 설치(Installation)의 승인된 scope 로 인가된다. 내부 API 의 raw mirror 가 아닌 public contract 로 설계된다. Base URL 은 API 게이트웨이 도메인의 /marketplace namespace 다 (예: https://staging-api.vpms.io/marketplace). 게이트웨이가 prefix 를 벗겨 marketplace-svc 로 프록시하므로, 이 문서의 모든 경로는 base URL 뒤에 그대로 붙인다 — 예: 토큰 발급은 POST {baseUrl}/oauth/token.

1. 인증 (OAuth2 client_credentials)

앱은 설치별 access token 을 발급받는다. 표준 client_credentials 를 installation_id 파라미터로 확장한 흐름이다 — 토큰은 해당 설치의 accommodation 컨텍스트와 승인 scope 로 한정된다.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=mp_client_xxx
&client_secret=mp_secret_xxx
&installation_id=01KXD...

응답:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "reservations:write folios:write",
  "installation_id": "01KXD..."
}

이후 모든 호출에 Authorization: Bearer <access_token> 를 실는다. scope 는 설치의 AccessGrant.effectiveScopes 기준이며, 부족하면 403 insufficient_scope 다.

OAuth client(client_id/client_secret)는 앱 등록 후 콘솔에서 1회 발급된다. secret 은 그 시점에만 노출되므로 안전하게 보관하라. installation_id 는 테넌트가 앱을 설치·동의한 뒤 installation.activated webhook 으로 전달된다. webhook 외에도, 설치 완료 후 앱의 redirect URI 로 전달되는 handoff query parameter 의 1회용 code 를 POST /oauth/handoff 에 client_id/client_secret 과 함께 교환하면 {installation_id, accommodation_id, app_id} 를 얻는다 (code 는 1회용이며 10분 후 만료). 토큰 검증·폐기는 POST /oauth/introspect / POST /oauth/revoke (둘 다 client_id/client_secret 인증).

2. 멱등성 (명령형 쓰기 필수)

명령형 쓰기(예약·결제 — /api/v1/reservations*·/api/v1/payments* 의 POST/PATCH/DELETE)는 Idempotency-Key 헤더가 필수다. 없으면 400 invalid_request. 같은 키의 재요청은 최초 명령의 결과를 그대로 재응답하므로, 채널 매니저의 네트워크 재시도가 중복 예약/결제를 만들지 않는다. 그 밖의 쓰기 (dataset/document 푸시, setup-ready, action-run/upgrade 완료 보고 등)는 이 헤더를 받지 않는다 — upsert·상태 가드로 자체 멱등인 엔드포인트가 대부분이지만, POST /api/v1/events 는 중복 제거가 없으므로 재시도 시 이벤트가 중복 적재될 수 있다.

POST /api/v1/reservations
Authorization: Bearer <token>
Idempotency-Key: your-app:resv:12345
Content-Type: application/json

키는 의미 있는 자연 키를 쓰라 (예: <app>:resv:<외부예약번호>). 랜덤 UUID 를 매 재시도마다 새로 만들면 멱등성이 깨진다.

명령형 쓰기는 선택적으로 Ordering-Key 헤더(200자 이하, 초과 시 400 invalid_request)를 함께 보낼 수 있다. 같은 키의 지연(outbox) 명령은 설치 내에서 생성 순서대로 직렬 실행되고, 키가 다르면 병렬로 처리된다 (예: 같은 예약에 대한 수정 연쇄). 미지정 시 payload 의 id/reservation_id, 그것도 없으면 Idempotency-Key 기준으로 자동 직렬화된다.

3. 쓰기 모델 — command outbox (동기 확정 + WAL)

쓰기는 hybrid 로 처리된다: 요청을 durable 하게 journaling 한 뒤 인라인으로 내부 백엔드에 시도하고, 실패 시 워커가 at-least-once 로 재시도한다.

결과	HTTP	본문
인라인 성공	`200`/`201`	리소스 envelope + `outbox_id`
인라인 실패(재시도 대기)	`202`	`{ "accepted": true, "outbox_id": "…" }`
정책상 거부(터미널)	`202` 후 `SKIPPED`	webhook 미발행 — `GET /api/v1/commands` 로 확인 (예: `ERR_AUDITTED_DATA` — 마감된 회계 데이터)
검증 실패	`400`	`{ "error": "invalid_request", "error_description": "…" }`
scope 부족	`403`	—
내부 백엔드 오류	`502`	`{ "error": "upstream_error" }`

202 를 받으면 최종 확정은 지연 webhook(예: reservation.created / reservation.failed) 으로 전달되며, 동일 outbox_id 로 요청과 상관관계를 맺는다. 완료 이벤트의 리소스 envelope 는 동기 성공 응답과 동일한 형태다. 단, 백엔드가 명령을 정책상 거부하면 (예: 감사 마감 데이터 수정 — ERR_AUDITTED_DATA) 재시도 없이 SKIPPED 로 종결되며 webhook 이 발행되지 않는다. 202 응답의 최종 상태는 GET /api/v1/commands?prefix=<키 prefix> (prefix 최소 8자)로 조회하라.

PMS 내부 변경 이벤트 (`pms.reservation.*`)

앱 명령 결과(reservation.*)와 별개로, 프런트데스크 등 VPMS 내부에서 발생한 예약 변경은 pms.reservation.* webhook 으로 구독 중인 설치에 전달된다 (채널매니저류 앱의 upstream 동기화용):

이벤트	발생
`pms.reservation.created`	예약 생성
`pms.reservation.updated`	예약 변경
`pms.reservation.cancelled`	예약 취소
`pms.reservation.checked_in` / `.checked_out`	체크인/아웃

payload 는 식별자만 담는다({ reservation_id, actor, reason, occurred_at }) — 앱은 GET /api/v1/reservations/:id 로 전체 상태를 다시 읽는다(read-after-notify). actor 로 자기 쓰기 에코를 억제할 수 있으나, 정밀 억제는 앱이 자기 쓰기 예약 id 를 추적하는 것을 권장한다.

4. 예약 (Reservations)

POST /api/v1/reservations

reservations:write · Idempotency-Key 필수.

필드	필수	설명
`room_type_id`	✓	VPMS 객실 타입 id
`type`	✓	`lodge`(숙박) 또는 `rent`(대실)
`start_date`	✓	체크인 `YYYY-MM-DD`
`end_date`	✓	체크아웃 `YYYY-MM-DD` (rent 는 = start_date)
`check_in_at` / `check_out_at`		실제 입실/퇴실 시각 (ISO datetime). 미지정 시 날짜 기준 생성 — 시각이 있는 원천 데이터는 반드시 함께 보내라
`nightly_rates`		박별 가격 배열. 길이 = 박수(rent 는 1). 지정 시 요금제 자동가격을 우회해 원 단위 패리티
`rate_plan_id`		미지정 시 VPMS 가 자동 해석(최저가 플랜)
`channel_id`		판매 채널(거래처) id. 채널에 거래처가 연결돼 있으면 대외후불 연동
`status`		`INQUIRY`/`TENTATIVE`/`DEFINITE`… (기본 `DEFINITE`)
`sleeps` / `child_sleeps`		인원
`ota_code`		외부 예약번호
`memo`		메모
`guest`		`{ name, phone, email, country, vehicle_number }`

{
  "room_type_id": "01K...",
  "type": "lodge",
  "start_date": "2026-08-02",
  "end_date": "2026-08-04",
  "nightly_rates": [75000, 75000],
  "channel_id": 12,
  "status": "DEFINITE",
  "ota_code": "123944",
  "guest": { "name": "홍길동", "phone": "010-0000-0000" }
}

nightly_rates 지정 시 합계가 예약 총액이 되고, 요금제는 분류(리포팅) 용도로만 쓰인다.

그 밖의 예약 엔드포인트

메서드	경로	scope	비고
`GET`	`/api/v1/reservations`	`reservations:read`	목록 (커서 페이지네이션, createdAt DESC). query: `limit`(≤100) · `cursor` · `created_from`/`created_to`(ISO) · `status`(콤마구분) · `ota_code`(외부 예약번호). 응답: `{reservations, next_cursor, total_count}`. backfill/재조회용 — 실시간 변경은 webhook
`GET`	`/api/v1/reservations/:id`	`reservations:read`	동기 조회
`PATCH`	`/api/v1/reservations/:id`	`reservations:write`	기간 변경 시 요금제 재해석
`DELETE`	`/api/v1/reservations/:id`	`reservations:write`	취소 (`cancel_payment` 옵션)
`POST`	`/api/v1/reservations/:id/purge`	`reservations:write`	물리 삭제 — 예약+folio+청구+결제 행 제거 (취소·soft-delete 아님). 예약 1건짜리 단독 folio 만 허용. 멱등
`POST`	`/api/v1/reservations/bulk-purge`	`reservations:write`	물리 삭제 일괄판 — `reservation_ids`(≤500) 그리고/또는 `channel_ids`(정수 배열) 지정, 둘 중 하나는 필수. 응답 `{purged, skipped, already_gone, failed}` (`skipped`/`failed` 는 `{id, reason}` 배열)
`GET`	`/api/v1/commands`	`reservations:read`	Idempotency-Key prefix(≥8자)로 명령 상태 조회 (부수효과 없음). query: `prefix` · `limit`(≤500, 기본 200) · `cursor`(keyset). 응답: `{commands:[{idempotency_key, type, status, result}], next_cursor}` — `status` 는 `PENDING` `DONE` `FAILED` `SKIPPED`. prefix 8자 미만이면 400

5. 결제 (Payments)

POST /api/v1/payments

folios:write · Idempotency-Key 필수. 결제는 folio 에 귀속되므로 folio_id 또는 reservation_id(→folio 해석) 중 하나가 필요하다.

필드	필수	설명
`reservation_id` 또는 `folio_id`	✓	귀속 folio
`amount`	✓*	금액 — `method: "platform"` 일 때만 생략 가능(전액 대외후불)
`commission_amount`		채널 수수료 금액 (숫자)
`method`	✓	`account` `cash` `creditCard` `easy` `etc` `mileage` `platform`
`status`		결제 상태 (예: `APPROVED`)
`transaction_id` / `approval_id`		거래·승인 번호
`tax_type`		과세 유형
`memo`		메모

method: "platform" 은 VPMS 의 대외후불이다 — 예약에 연결된 채널(거래처)의 미수로 처리된다. 따라서 platform 결제는 예약이 channel_id(거래처 연결 채널)를 가질 때 의미가 있다.

메서드	경로	scope	비고
`PATCH`	`/api/v1/payments/:id`	`folios:write`	body(부분 수정): `amount` · `commission_amount` · `method` · `transaction_id` · `approval_id` · `tax_type`
`DELETE`	`/api/v1/payments/:id`	`folios:write`	query: `amount`(부분 취소 금액, 미지정 시 취소 가능 금액 전액 취소) · `memo`

6. 조회 (Reads)

메서드	경로	scope	설명
`GET`	`/api/v1/accommodation`	(bearer)	설치 숙소 정보
`GET`	`/api/v1/room-types`	`rooms:read`	객실 타입 목록
`GET`	`/api/v1/room-types/:id`	`rooms:read`	객실 타입 상세
`GET`	`/api/v1/rates`	`rates:read`	일별 요금
`GET`	`/api/v1/rate-plans`	`rates:read`	요금제 목록 (query: `is_active`)
`GET`	`/api/v1/channels`	`rooms:read`	판매 채널(거래처) 목록 — 예약 `channel_id` · platform 결제(대외후불)용
`GET`	`/api/v1/availability`	`inventory:read`	재고/가용성

7. UI Surface 데이터 (매핑·문서)

UI surface(manifest.surfaces) 를 뒷받침하는 dataset·매핑·문서 API. 자세한 블록 선언은 UI Kit Manifest 가이드 참조.

메서드	경로	scope	설명
`PUT`	`/api/v1/datasets/{key}`	`marketplace:datasets:write`	매핑 후보 항목 푸시(upsert)
`GET`	`/api/v1/datasets/{key}`	`marketplace:datasets:write`	푸시한 dataset 조회
`GET`	`/api/v1/mappings`	`marketplace:mappings:read`	호텔이 확정한 매핑 조회
`POST`	`/api/v1/installation/setup-ready`	`marketplace:datasets:write`	explicit 준비 신호
`POST`	`/api/v1/action-runs/{run_id}/complete`	(bearer)	action(completion=event) 완료 보고
`PUT`	`/api/v1/documents`	`marketplace:documents:write`	원본 문서(채널 전문 등) 푸시(upsert) — reservation surface 의 document action 에 표시

PUT /api/v1/datasets/

key 는 ^[a-z0-9][a-z0-9_-]{0,63}$. 항목은 최대 5,000개.

{ "items": [ { "id": "AGODA", "label": "아고다", "meta": {} } ] }

GET /api/v1/mappings

?vpms_entity=<entity>&dataset=<key> 로 필터.

{
  "mappings": [
    { "vpms_entity": "roomType", "vpms_entity_id": "01K...",
      "dataset": "ext_room_types", "external_id": "RT-1",
      "external_label": "스탠다드", "updated_at": "…" }
  ]
}

POST /api/v1/action-runs//complete

{ "status": "completed" | "failed", "message": "27건 동기화" } — 이미 종결된 run 은 현재 상태를 멱등 재응답한다.

PUT /api/v1/documents

설치 내 (ref_type, data_id) 기준 upsert. body: ref_type · external_ref · data_id (각 ^[a-zA-Z0-9._:-]{1,128}$), content_type(application/xml | application/json | text/plain), content(UTF-8 최대 65,536 bytes), title(선택, 최대 200자). external_ref 는 키가 아니라 예약 등 대상 리소스를 가리키는 갱신 데이터다. 응답에는 content 가 에코되지 않는다(id, ref_type, external_ref, data_id, size_bytes, updated_at).

8. 설치 업그레이드

메서드	경로	scope	설명
`POST`	`/api/v1/upgrades/{upgrade_id}/complete`	`marketplace:upgrades:write`	`appMigration: "required"` 업그레이드의 앱측 마이그레이션 완료 ack

버전 업그레이드가 실행되면 항상 installation.upgraded webhook ({upgrade_id, from_version, to_version, app_migration, effective_scopes})이 발행된다. manifest 의 upgrade 블록에 appMigration: "required" 인 홉이 포함된 업그레이드는 AWAITING_APP 상태로 유지되며(app_migration: true), 앱이 자체 마이그레이션을 마친 뒤 이 엔드포인트로 ack 해야 완료된다. 대상 업그레이드가 AWAITING_APP 이 아니면(이미 완료됐거나 다른 설치 소유) 404 not_found. upgrade 블록이 없거나 appMigration 이 none 이면 자동 완료된다(app_migration: false).

9. 사용량 / 컨텍스트

메서드	경로	scope	설명
`GET`	`/api/v1/me`	(bearer)	호출 주체(설치·client·scope)
`GET`	`/api/v1/installation`	(bearer)	설치 상세 — `setup_status`, `config`(configForm 값) 포함
`POST`	`/api/v1/installation/uninstall`	(bearer)	앱 자체 설치 해제 — `{id, status, uninstalled_at}` 응답, `installation.uninstalled` webhook 발행; 이미 해제된 설치는 멱등 재응답
`GET`	`/api/v1/usage`	`marketplace:usage:read`	endpoint family 별 호출량
`POST`	`/api/v1/events`	`marketplace:events:write`	Robust 이벤트 적재(202, outbox)

10. 에러 형식

{ "error": "invalid_request", "error_description": "room_type_id is required" }

HTTP	error	의미
400	`invalid_request`	검증 실패 / 필수 헤더 누락
401	`invalid_client` / `invalid_token`	인증 실패
403	`insufficient_scope` / `installation_not_active`	scope 부족 / 설치 비활성(미동의·해제)
404	`not_found`	리소스 없음
502	`upstream_error`	내부 백엔드 오류 (재시도 가능)

API documentation

Core Service

Booking Service

User Service

Subscription Service

Marketplace Service

마켓플레이스 Open API

1. 인증 (OAuth2 client_credentials)

2. 멱등성 (명령형 쓰기 필수)

3. 쓰기 모델 — command outbox (동기 확정 + WAL)

PMS 내부 변경 이벤트 (`pms.reservation.*`)

4. 예약 (Reservations)

POST /api/v1/reservations

그 밖의 예약 엔드포인트

5. 결제 (Payments)

POST /api/v1/payments

6. 조회 (Reads)

7. UI Surface 데이터 (매핑·문서)

PUT /api/v1/datasets/

GET /api/v1/mappings

POST /api/v1/action-runs//complete

PUT /api/v1/documents

8. 설치 업그레이드

9. 사용량 / 컨텍스트

10. 에러 형식

​1. 인증 (OAuth2 client_credentials)

​2. 멱등성 (명령형 쓰기 필수)

​3. 쓰기 모델 — command outbox (동기 확정 + WAL)

​PMS 내부 변경 이벤트 (pms.reservation.*)

​4. 예약 (Reservations)

​POST /api/v1/reservations

​그 밖의 예약 엔드포인트

​5. 결제 (Payments)

​POST /api/v1/payments

​6. 조회 (Reads)

​7. UI Surface 데이터 (매핑·문서)

​PUT /api/v1/datasets/

​GET /api/v1/mappings

​POST /api/v1/action-runs//complete

​PUT /api/v1/documents

​8. 설치 업그레이드

​9. 사용량 / 컨텍스트

​10. 에러 형식

1. 인증 (OAuth2 client_credentials)

2. 멱등성 (명령형 쓰기 필수)

3. 쓰기 모델 — command outbox (동기 확정 + WAL)

PMS 내부 변경 이벤트 (`pms.reservation.*`)

4. 예약 (Reservations)

POST /api/v1/reservations

그 밖의 예약 엔드포인트

5. 결제 (Payments)

POST /api/v1/payments

6. 조회 (Reads)

7. UI Surface 데이터 (매핑·문서)

PUT /api/v1/datasets/

GET /api/v1/mappings

POST /api/v1/action-runs//complete

PUT /api/v1/documents

8. 설치 업그레이드

9. 사용량 / 컨텍스트

10. 에러 형식