‹ 고객12 / 12
‹ 이전

배송주소·쿠폰

v1 API 상세: 회원·배송지, 쿠폰

고객 배송주소 생성

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 은 생략하지 않고 보냅니다(예: 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의 일치 검사도 적용됩니다.

쿠폰 적용 미리보기 API(POST /v1/coupon/preview)는 없고, cart/order-preview 도 쿠폰 ID·배송지·적립금을 반영하지 않습니다. 쿠폰함에 보이는 쿠폰이 실제 주문에 적용되는지는 따로 검증해야 합니다.

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

함께 보기