← Partner API 가이드

Changelog

Partner API 변경 이력. deprecation 일정은 본문에서 명시.

PARKING 24 Partner API Changelog

외부 제휴사 통합에 영향을 주는 변경사항을 시간 역순으로 기록합니다. breaking change, 신규 응답 필드, 새 엔드포인트, deprecation 등이 대상입니다. 내부 implementation detail(성능 최적화 RPC, 인덱스, dead code 정리 등)은 기록하지 않습니다.

표기

  • 🚨 Breaking — 즉시 또는 deprecation 기간 후 기존 동작이 변경되는 변경
  • ✨ New — 신규 엔드포인트 / 응답 필드 / 헤더
  • 🛡 Security — 인증 / IP allowlist / 서명 등 보안 영향 변경
  • 📝 Docs — 가이드 보강 (정책 명시, 예시 추가 등)
  • 🩹 Fix — 응답 데이터 정합성 / 누락된 처리 보완

2026-05-14

✨ /v1/ URL prefix 도입 (Phase D-2)

  • 신규 권장 prefix: /api/partner-api/v1/.... 기존 무버전 경로는 alias로 동일 동작하지만 2026-11-14 이후 deprecation 예정 (6개월 윈도우).
  • 모든 응답 형식·인증·rate limit·헤더 동일. 라우팅 차이만.
  • 외부 제휴사 신규 통합은 /v1/ 권장.

✨ 응답에 error_code 필드 추가 (Phase C-3)

  • 모든 partner-api 실패 응답에 error_code enum 필드가 함께 반환됩니다. 사람 가독 error 메시지 대신 stable code로 자동화 분기/알람을 작성하세요.
  • enum 종류 30+ — 자세한 표: docs/partner-api.md ### error_code enum
  • 호환: 기존 error 텍스트 필드는 그대로 유지됩니다.
  • 예시: 
    { "success": false, "data": null, "error": "...", "error_code": "MISSING_FIELD" }

✨ API Changelog 페이지 (Phase C-2)

  • 본 페이지가 추가되었습니다. /partner/api-guide의 "변경 이력" 탭에서 동일 내용 조회 가능.

📝 응답 헤더 X-P24-Timing 안내 추가

  • 모든 partner-api 응답에 단계별 처리 시간을 담은 X-P24-Timing 헤더가 노출됩니다. 형식은 W3C Server-Timing 사양 (name;dur=ms CSV) 호환.
  • 클라이언트측 SLO 모니터링·디버깅·외부 알람 연동에 활용 가능.
  • 자세한 내용: docs/partner-api.md ### 응답 헤더 X-P24-Timing

🩹 is_electric_vehicle 인터페이스 명세화

  • PartnerReservationRequest에 is_electric_vehicle?: boolean 명시. 기존 동작 동일(EV 제한 plan 시 400 반환).
  • 예약 생성 시 is_electric_vehicle 값이 reservations DB에 저장됩니다 (이전엔 검증만 하고 저장 안 됨).

📝 parking24_cost 응답 노출 정책 확정

  • 쿠폰 검증/적용 응답의 parking24_cost 필드를 유지합니다. 파트너 포털 UI와 동일한 transparency 정책. (GitHub issue #80)

2026-05-13

✨ Idempotency-Key 헤더 지원

  • mutation 엔드포인트(POST /reservations, PATCH /reservations, POST /coupon/apply)에 Idempotency-Key 헤더 지원. 동일 키로 24시간 내 재호출 시 첫 응답 재생.
  • 네트워크 오류·timeout 후 안전한 재시도 보장.
  • 동시 호출은 409, body mismatch는 422.

🛡 Webhook HMAC-SHA256 서명

  • 모든 webhook 발송에 X-Parking24-Signature 헤더(HMAC-SHA256, ${WEBHOOK_SIGNING_SECRET}:${partner_id}) 추가.
  • 5초 timeout, 1회 발송.

✨ reservation.cancelled 시 자동 REFUND 정산 생성

  • PATCH 취소 시 settlement_adjustments 테이블에 REFUND row 자동 생성. 정산 차감에 반영.

📝 KST / KRW 명세 명시

  • 모든 날짜·시각은 한국 표준시(Asia/Seoul) 기준.
  • 모든 금액은 KRW 정수.

🩹 응답 sanitize — 내부 회계 필드 제거

  • GET /partner-api/reservations 응답에서 partner_commission_amount, commission_direction, partner_id 등 P24 내부 회계 필드 제거.
  • partner_discount_amount는 제휴사 자기 할인이므로 유지.

더 오래된 변경

PR #79 이전의 Partner API 변경은 GitHub PR 기록을 참조하세요: github.com/roacompany/parking24/pulls.