배송주소·쿠폰 | Bootpay 커머스 매뉴얼

고객 배송주소 생성

POST https://api.bootapi.com/v1/users/address — 서버 Basic 인증과 user:user_create scope를 사용해요. 회원은 JWT 또는 가맹점 서버가 보낸 user_id로 정해요.

{
  "user_id": "CUSTOMER_ID",
  "name": "홍길동",
  "phone": "01012345678",
  "zipcode": "06164",
  "address": "서울특별시 강남구 ...",
  "address_detail": "101동 101호",
  "alias_name": "집",
  "address_uid": "external-address-001"
}json

name, phone, zipcode, address, address_detail은 필수예요. JWT가 없을 때 user_id가 필요하며, 회원 ID 또는 가맹점 외부 식별자를 보내요. address_uid는 중복 방지 외부 식별자이며 ex_uid/external_uid/uid도 허용해요. is_default: true로 기본 배송지를 지정할 수 있어요. 본문을 address 객체로 한 번 더 감싸면 안 돼요. 여기서 최상위 address는 주소 문자열이에요.

성공 응답은 {"address_id":"CREATED_ADDRESS_ID"}예요. 같은 회원이 같은 address_uid와 같은 내용으로 재요청하면 기존 ID를 돌려줘요. 내용이 다르거나 다른 회원이 사용한 ID는 409 ADDRESS_ALREADY_EXISTS예요. 필수 누락은 API_PARAM_INVALID예요.

주소록 전체

목록·수정·삭제도 함께 제공해요 (2026-09-14).

메서드·URL	소유자 지정	응답
`GET /v1/users/address`	JWT 또는 `user_id`	`{ list: [...], count }`
`POST /v1/users/address`	JWT 또는 `user_id`	`{ address_id }`
`PUT /v1/users/address/:address_id`	JWT 또는 `user_id`	`{ address_id }`
`DELETE /v1/users/address/:address_id`	JWT 또는 `user_id`	`{ success: true }`

목록 항목은 address_id, address_uid, alias_name, name, phone, zipcode, address, address_detail, is_default예요.

호출 주체는 둘이에요.

구매자 호출 — Bootpay-User-JWT를 보내면 소유자는 그 세션의 회원으로 고정돼요. user_id를 함께 보내도 본인이 아니면 USER_NOT_MATCH(403)예요.
서버 호출 — JWT 없이 user_id(Bootpay ID·external_uid) 또는 login_id를 지정하는 관리·동기화용이에요. 액션별로 user:user_read·user:user_create·user:user_update 권한이 필요해요.

JWT도 회원 지정 값도 없으면 소유자를 정할 수 없어 401이에요. JWT 방식에도 액션별 scope가 필요해요. 다른 회원의 주소 ID는 없는 주소와 같은 404로 응답해요.

BFF에서는 서버 권한으로 임의 user_id를 지정할 수 있으므로, 브라우저가 보낸 값을 그대로 쓰지 말고 로그인 세션에서 확인한 고객 ID를 넣어요.

고객 쿠폰

고객용은 단수 /v1/coupon, 관리용은 복수 /v1/coupons로 구분해요.

메서드·URL	요청	구현상 응답
`GET /v1/coupon`	쿼리 `status`, `page`, `limit`	`coupons`, `total_count`, `available_count`, `used_count`, `expired_count`, `has_more`
`GET /v1/coupon/available`	회원 지정 외 파라미터 없음	사용 기간 내 보유 쿠폰 배열
`POST /v1/coupon/download`	`coupon_template_id`	발급된 쿠폰 객체

page/limit은 생략 시 컨트롤러가 nil을 넘겨 모델에서 1로 보정할 수 있으므로 명시적으로 page=1&limit=20을 보내요. status는 현재 이 경로에서 숫자로 변환해 필터링하므로 문자열 enum 지원을 가정하지 않아요.

세 API 모두 Basic 인증과 회원 지정이 필요해요. Bootpay-User-JWT 또는 쇼핑몰 서버가 확인한 user_id를 보내며, user_id 방식은 secretKey 인증에서만 허용해요. 필요한 scope는 순서대로 user:coupon_list·user:coupon_available·user:coupon_download예요. 회원 JWT의 일치 검사도 적용돼요.

POST /v1/coupon/preview는 현재 라우트에 없어요. cart/order-preview로 통합했다는 주석이 있지만 현재 v1 구현은 쿠폰 ID·배송지·적립금을 읽지 않아요. 쿠폰함 조회 가능 여부와 실제 주문에 할인 적용 가능 여부를 별도로 검증해야 해요.

쿠폰 다운로드와 주소 생성은 데이터를 변경하는 요청이에요. 조회 화면을 연 것만으로 자동 실행하지 않아요.

확인 근거: V1::Users::AddressController, V1::CouponController, Coupon::Query, config/routes.rb.