파트너 API 경로 분리로 결제·정산 연동 구조 정비

파트너 API 경로 분리하면서 정리한 것

오늘 한 일은 파트너 전용 API 경로를 새로 따고, 연동 문서를 거기 맞춰 갱신한 것. 기존엔 내부 운영용 호출이랑 파트너 호출이 같은 prefix 아래 섞여 있어서 권한 분기랑 로깅 분리가 계속 애매했음.

경로 분리 기준

• 내부 운영/대시보드용: /internal/**
• 파트너(외부 연동)용: /partner/v1/**
• 정적/뷰 리소스: 기존 그대로

prefix 자체를 분리해두면 이후에 인증 필터, rate limit, 감사 로그 정책을 묶기 훨씬 쉬워짐. 라우팅 룰 한 군데만 손대면 되는 구조로 가는 게 목적이었음.

라우팅 설정에서 손본 부분

MVC 설정 쪽에서 핸들 등록 순서랑 prefix 매핑을 같이 정리했음.

/partner/v1/charges      → 충전 요청
/partner/v1/charges/{id} → 단건 조회
/partner/v1/settlements  → 정산 내역

화면에서 쓰던 객체를 그대로 외부에 던지면, 나중에 필드 하나 바꿀 때 결제대행사 연동이 같이 깨짐. 그래서 외부 응답은 별도 DTO로 강제했음. 처음엔 귀찮아 보여도 호환성 사고 한 번 터지면 본전 뽑힘.

문서 갱신 포인트

• 엔드포인트 표 새 prefix로 일괄 치환
• 기존 경로는 한동안 살려두되 "deprecated, 6월까지 유지" 명시
• 파트너 쪽에 보낼 변경 노트 초안까지 같이 작성

문서랑 코드 prefix가 한 글자라도 어긋나면 파트너가 통합 테스트에서 바로 막힘. 예전에 슬래시 하나 빠뜨려서 하루 통째로 날린 적 있어서, 이번엔 코드 → 문서 → 샘플 요청이 동일한 소스에서 추출되도록 끼워뒀음.

다음에 이어서 할 것

• 구버전 prefix 호출 비중 모니터링 붙이기
• 파트너 쪽 마이그레이션 스케줄 컨펌
• 인증 필터 분리(별도 PR로)

경로 prefix 하나 바꾸는 작업처럼 보여도, 실제론 이커머스/결제 플랫폼 쪽에서 권한·로깅·외부 계약 라인을 한꺼번에 다시 그리는 일이라 시간이 꽤 걸렸음.

다음