Partner API 가이드

API (v2)

인천공항 주차대행 예약을 파트너사 서비스에서 생성·취소합니다. 모든 요청은 JSON 본문 + Bearer API 키입니다.

``` Authorization: Bearer <발급받은 API 키> Content-Type: application/json ```

발급 후에는 파트너 대시보드 `https://marketplace.parking24.me/partner` 에서 계정(이메일·비밀번호)으로 로그인하십니다(구 주소 `parking24.me/partner` 는 여기로 이동합니다). 이 문서의 API 키는 시스템 연동 전용이며 포털 로그인에는 쓰지 않습니다.

키는 어디에 요청하나요

• 아직 계약 전이라면 — `marketplace.parking24.me` 의 입점 신청으로 접수해 주세요. 계약이 발효되면 계정과 연동 키를 함께 드립니다.
• 이미 계약한 제휴사라면 — 포털의 문의에서 연동 분류로 남겨 주세요. 키를 잃어버리셨다면 포털 설정 › 연동 키 재발급으로 직접 다시 받으실 수 있습니다.

⚠️ 연동 키는 계약이 발효되고 연동 판매를 켠 채널에만 열립니다. 계약이 발효되기 전에는 포털 로그인 자체가 되지 않습니다.

⚠️ API 주소는 바뀌지 않았습니다 — `https://parking24.me/api/partner/*\` 를 그대로 쓰시면 됩니다. `marketplace.parking24.me` 로 부르셔도 동일하게 동작합니다.

1. 견적 — `POST /api/partner/quote`

```json { "planId": "std", "terminal": "T1", "returnTerminal": "T1", "departureAt": "2027-01-10T09:00", "returnAt": "2027-01-13T18:00", "isEV": false } ```

응답 `200`

```json { "ok": true, "planId": "std", "name": "실내주차", "tier": "STANDARD", "days": 4, "total": 60000 } ```

금액은 요금표에 따라 달라집니다 — 위 숫자는 이 요청의 현재 값입니다. 총액을 자체 계산하지 마시고 이 응답의 `total` 을 쓰십시오.

• 🛫 터미널은 둘입니다 — `terminal` 은 나갈 때, `returnTerminal` 은 돌아올 때입니다. 차를 맡기고 찾는 인계가 각각 한 번씩이라 터미널 할증도 다리마다 따로 붙습니다. · 제1로 나가 제2로 돌아오는 손님은 할증이 한 번, 양쪽 다 제2면 두 번 붙습니다. · `returnTerminal` 을 보내지 않으면 `terminal` 과 같은 것으로 봅니다(기존 연동은 그대로 동작합니다). ⚠️ 손님이 두 터미널을 다르게 고를 수 있다면 반드시 함께 보내 주세요 — 안 보내면 금액이 달라지고, 수행사가 차를 가져다 놓는 터미널도 달라집니다.

2. 예약 — `POST /api/partner/book`

견적과 같은 필드 + 손님 정보.

```json { "planId": "std", "terminal": "T1", "returnTerminal": "T1", "departureAt": "2027-01-10T09:00", "returnAt": "2027-01-13T18:00", "plate": "12가 3456", "customerName": "홍길동", "customerPhone": "010-0000-0000", "departureFlightNo": "KE703", "returnFlightNo": "KE704" } ```

응답 `201` — `{ "ok": true, "code": "PK24-3F9A2K", "amount": 60000 }`

• ✈️ `departureFlightNo`(출국편)·`returnFlightNo`(귀국편) — 선택 · 편명 모양 · 수행사가 인계·회수 시각을 맞추는 데 씁니다. 안 보내면 종전과 똑같이 동작합니다. 보내면 편명 모양(예: `KE703` · `7C2104`)만 확인하고 아니면 `400` (`error` 가 어느 칸인지 말합니다 · 예: `departureFlightNo: 편명 모양이 아닙니다(예: KE703)`). 공백·붙임표·소문자는 정리해서 저장합니다.

• 예약번호는 `PK24-` + 영숫자 6자리(총 11자)입니다 — 저장 칸을 이보다 좁게 잡지 마십시오.

• 손님 이름·연락처는 `customerName`·`customerPhone` 입니다(예전 문서의 `name`·`phone` 도 계속 받습니다).

• ⚠️ 연락처를 꼭 넣어 주세요 — 없으면 손님이 스스로 취소할 수 없고(제휴사 CS 로만 처리됩니다), 현장에서 차를 받는 수행사가 손님에게 연락할 방법이 없습니다.

• 금액은 서버가 재계산합니다(요청 값 신뢰 안 함).

• 필수 약관 동의는 파트너 계약으로 갈음해 서버가 대행 기록합니다.

• 예약은 파트너 채널로 귀속되어 계약 수수료가 정산에 반영됩니다.

• ⚠️ 확인 메일은 발송하지 않습니다 — 손님 접점이 파트너 쪽이므로 통지도 파트너가 합니다.

3. 예약 조회 — `GET /api/partner/booking?code=PK24-3F9A2K`

자기 채널 예약만 조회합니다. 손님이 취소하거나 파킹24가 일정을 바꾸면 이 조회로 맞추세요.

응답 `200`

```json { "ok": true, "code": "PK24-3F9A2K", "status": "confirmed", "stage": "await_checkin", "stageLabel": "받을 차", "planName": "실내주차", "terminal": "T1", "returnTerminal": "T1", "departureAt": "2027-01-10T09:00", "returnAt": "2027-01-13T18:00", "plate": "12가 3456", "departureFlightNo": "KE703", "returnFlightNo": null, "customerName": "홍길동", "customerPhone": "010-0000-0000", "amount": 60000, "discount": 0, "cancelFee": 0, "commission": 9000, "settlementBasis": "booking", "checkedInAt": null, "checkedOutAt": null, "handover": { "label": "현장 담당자", "name": "김담당", "phone": "010-1111-2222" } } ```

• `status` 만 보지 마세요 — 확정 예약도 `stage` 로 노쇼·지연이 갈립니다. (`await_checkin` 받을 차 · `parked` 보관 중 · `overdue_checkin` 인계 지연 · `overdue_checkout` 반환 지연 · `no_show` 노쇼 · `done` 완료)
• `terminal`(나갈 때)·`returnTerminal`(돌아올 때)은 따로 옵니다 — 손님에게 안내하실 때 둘을 같이 보십시오. 차는 `returnTerminal` 의 단기주차장에 가져다 놓습니다.
• `handover` = 손님이 현장에서 연락할 곳입니다. 배정 주차장 이름은 제공하지 않습니다.
• ✈️ `departureFlightNo`·`returnFlightNo` — 선택 · 편명 모양 · 수행사가 인계·회수 시각을 맞추는 데 씁니다. 예약할 때 보낸 값이 그대로 오고, 그 뒤 손님·수행사·운영자가 등록·변경하면 그 값이 옵니다. 없으면 `null` 입니다.
• `settlementBasis` 가 `booking` 이면 아직 입차 기록 전이라 지급 대상이 아닙니다.
• 자사 예약이 아니거나 없는 예약이면 똑같이 `404` 입니다.

4. 취소 — `POST /api/partner/cancel`

```json { "code": "PK24-3F9A2K" } ```

응답 `200` — `{ "ok": true }` · 자사 예약이 아니면 `404`

오류 형식

⚠️ `429` 를 꼭 처리해 주세요. 응답에 `retry-after` 헤더(초)가 함께 옵니다. 그만큼 기다렸다 재시도하시고, 즉시 반복 재시도는 하지 마십시오(대기 시간이 늘어납니다). 정상 키의 호출은 넉넉히 열려 있고, 잘못된 키로 실패한 시도가 주로 제한 대상입니다.

취소 규정·수수료는 운영 정책을 따르며 변경될 수 있습니다. 지금 값은 사람에게 묻지 마시고 포털의 요금 화면에서 직접 보세요 — 요금표(일수별)·터미널/야간 할증·취소 정책·귀사 수수료가 운영값 그대로 나옵니다.

---

이전 버전(v1)에 대해

구 파트너 API(`/api/partner-api/*`)와 파트너 포털은 2026-07-25 제거되었습니다. 현재 제공되는 연동 경로는 위 v2 뿐입니다. 기존 문서가 필요하면 git 이력을 참고하세요.