공통 사항

도메인

환경 도메인 주소

개발서버

https://76ztyqn6fe.execute-api.ap-northeast-2.amazonaws.com

운영서버

-

Http Status

Code 메시지 설명

200

OK

Api 호출 성공

400

Bad request

잘못된 요청

403

Forbidden

권한 없음

500

Internal Server Error

서버 오류

개발자 정보

개발자 이름

장현호

최종 업데이트

2024-10-21

개요

이 문서는 커머스 서비스의 주문 관련 API 명세를 제공합니다. 개발 참고 용도로 작성되었습니다.

공통 응답 구조

모든 API 응답은 다음 구조를 따릅니다:

{
  "success": boolean,
  "data": object | null,
  "error": {
    "code": string,
    "message": string
  } | null
}

주문 관련 API

주문 생성

HTTP Request

POST /order/v1/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Content-Length: 671
Host: localhost:8080

{
  "products" : [ {
    "id" : 1,
    "quantity" : 2
  }, {
    "id" : 3,
    "quantity" : 1
  } ],
  "ordererInfo" : {
    "name" : "김오더",
    "phoneNumber" : "01022334455",
    "email" : "test@emaill.com"
  },
  "deliveryInfo" : {
    "recipient" : "홍길동",
    "phoneNumber" : "01012345678",
    "streetAddress" : "서울시 강남구 테헤란로 123",
    "detailAddress" : "104동 1201호",
    "postalCode" : "12345",
    "memo" : "배송메모"
  },
  "paymentInfo" : {
    "method" : "CREDIT_CARD",
    "depositorName" : "홍길동"
  },
  "agreementInfo" : {
    "termsOfService" : true,
    "privacyPolicy" : true,
    "ageVerification" : true
  }
}

Request Fields

필드명 타입 필수값 양식 설명

products

Array

true

주문할 상품 목록

products[].id

Number

true

상품 ID

products[].quantity

Number

true

주문 수량

ordererInfo

Object

true

주문자 정보

ordererInfo.name

String

true

이름

ordererInfo.phoneNumber

String

true

연락처

ordererInfo.email

String

true

이메일

deliveryInfo

Object

true

배송 정보

deliveryInfo.recipient

String

true

수령인

deliveryInfo.phoneNumber

String

true

수령인 전화번호

deliveryInfo.streetAddress

String

true

도로명 주소

deliveryInfo.detailAddress

String

true

상세 주소

deliveryInfo.postalCode

String

true

우편번호

deliveryInfo.memo

String

배송메모

paymentInfo

Object

true

결제 정보

paymentInfo.method

String

true

결제 방법

paymentInfo.depositorName

String

true

입금자 이름

agreementInfo

Object

true

동의 정보

agreementInfo.termsOfService

Boolean

true

이용 약관 동의 여부

agreementInfo.privacyPolicy

Boolean

true

개인정보 처리방침 동의 여부

agreementInfo.ageVerification

Boolean

true

연령 확인 동의 여부

HTTP Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 491

{
  "success" : true,
  "data" : {
    "id" : 1,
    "orderNumber" : "ORD-20240815-001",
    "orderStatus" : "PENDING",
    "orderDate" : "2024-10-21T19:58:19.518629",
    "products" : [ {
      "id" : 1,
      "name" : "Kotlin in Action",
      "quantity" : 2,
      "price" : 20000,
      "discountedPrice" : 19000
    }, {
      "id" : 3,
      "name" : "Spring Boot in Practice",
      "quantity" : 1,
      "price" : 10000,
      "discountedPrice" : 9000
    } ]
  },
  "error" : null
}

Response Fields

필드명 타입 필수값 양식 설명

success

Boolean

true

요청 성공 여부

data

Object

true

응답 데이터

data.id

Number

true

주문 아이디

data.orderNumber

String

true

주문 번호

data.orderStatus

String

true

주문 상태

data.orderDate

String

true

주문 일시

data.products

Array

true

주문한 상품 목록

data.products[].id

Number

true

상품 ID

data.products[].name

String

true

상품 이름

data.products[].quantity

Number

true

주문 수량

data.products[].price

Number

true

상품 가격

data.products[].discountedPrice

Number

true

상품 할인된 가격

error

Null

오류 정보

주문 목록 조회

HTTP Request

GET /order/v1/orders?dateRange=LAST_6_MONTHS&sortBy=RECENT&page=1&size=20 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Host: localhost:8080

Request Parameters

필드명 필수값 양식 설명

dateRange

ENUM (LAST_WEEK, LAST_MONTH, LAST_3_MONTHS, LAST_6_MONTHS, CUSTOM)

LAST_WEEK: 최근 1주일 동안의 주문 LAST_MONTH: 최근 1개월 동안의 주문 LAST_3_MONTHS: 최근 3개월 동안의 주문 LAST_6_MONTHS: 최근 6개월 동안의 주문 CUSTOM: 사용자 지정 기간 (startDate와 endDate 파라미터 필요)

status

COMPLETED : 주문 완료, CANCELLED : 주문 취소, SHIPPING : 배송중, DELIVERED : 배송완료, REFUNDED : 환불

주문 상태

sortBy

ENUM (RECENT, ORDER_STATUS, ALL)

RECENT: 최근 생성된 주문부터 정렬 ORDER_STATUS: 주문 상태별로 정렬 후, 각 상태 내에서 생성 일시로 정렬 ALL: 특별한 정렬 기준 없음 (데이터베이스 기본 순서)

page

NUMBER (양의 정수)

조회하고자 하는 페이지 번호

size

NUMBER (양의 정수)

한 페이지에 표시할 주문의 수

orderStartDate

yyyy-MM-dd

dateRange가 CUSTOM일 때 조회 시작 일자

orderEndDate

yyyy-MM-dd

dateRange가 CUSTOM일 때 조회 종료 일자. orderStartDate보다 미래여야 함

Http Response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 916

{
  "success" : true,
  "data" : {
    "products" : [ {
      "id" : 1,
      "orderNumber" : "ORD-20240815-000001",
      "content" : "해리 포터와 마법사의 돌 외 2권",
      "orderDate" : "2024-08-15T14:30",
      "status" : "SHIPPING",
      "price" : 45000.0,
      "discountedPrice" : 40500.0,
      "memberName" : "김철수",
      "recipient" : "김영희"
    }, {
      "id" : 2,
      "orderNumber" : "ORD-20240815-000002",
      "content" : "코스모스: 가능한 세계들",
      "orderDate" : "2024-08-16T09:45",
      "status" : "COMPLETED",
      "price" : 22000.0,
      "discountedPrice" : 19800.0,
      "memberName" : "이지은",
      "recipient" : "이지은"
    } ],
    "paginationInfo" : {
      "currentPage" : 1,
      "totalPage" : 1,
      "pageSize" : 20,
      "totalCount" : 2,
      "hasNextPage" : false,
      "hasPreviousPage" : false
    }
  },
  "error" : null
}

Response Fields

필드명 타입 필수값 양식 설명

success

Boolean

true

Boolean

요청 성공 여부

data

Object

true

응답 데이터

data.products

Array

true

Array

주문 목록

data.products[].id

Number

true

String (UUID)

주문 ID

data.products[].orderNumber

String

true

String

주문 번호

data.products[].content

String

true

String

주문 내역 요약

data.products[].orderDate

String

true

String (ISO 8601: yyyy-MM-dd’T’HH:mm:ss)

주문 일자

data.products[].status

String

true

COMPLETED : 주문 완료, CANCELLED : 주문 취소, SHIPPING : 배송중, DELIVERED : 배송완료, REFUNDED : 환불

주문 상태

data.products[].price

Number

true

Number (Double)

주문 원가

data.products[].discountedPrice

Number

true

Number (Double)

할인 적용된 최종 가격

data.products[].memberName

String

true

String

주문자 이름

data.products[].recipient

String

true

String

수령인 이름

data.paginationInfo

Object

true

페이지네이션 정보

data.paginationInfo.currentPage

Number

true

Number (Integer)

현재 페이지 번호

data.paginationInfo.totalPage

Number

true

Number (Integer)

전체 페이지 수

data.paginationInfo.pageSize

Number

true

Number (Integer)

페이지 크기

data.paginationInfo.totalCount

Number

true

Number (Long)

전체 주문 수

data.paginationInfo.hasNextPage

Boolean

true

Boolean

다음 페이지 존재 여부

data.paginationInfo.hasPreviousPage

Boolean

true

Boolean

이전 페이지 존재 여부

error

Null

Object (null if success)

오류 정보

주문 상세 조회

Http

GET /order/v1/orders/ORD-20241012-000001 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Host: localhost:8080

Path Variable

필드명 필수값 양식 설명

orderNumber

true

주문 번호

Response

필드명 타입 필수값 양식 설명

success

Boolean

true

요청 성공 여부

data

Object

true

응답 데이터

data.id

Number

true

주문 ID

data.orderNumber

String

true

주문 번호

data.orderDate

String

true

주문 일시

data.orderer

Object

true

주문자 정보

data.orderer.name

String

true

이름

data.orderer.phoneNumber

String

true

연락처

data.orderer.email

String

true

이메일

data.products

Array

true

주문 상품 목록

data.products[].id

Number

true

상품 ID

data.products[].title

String

true

상품 이름

data.products[].author

String

true

상품 저자

data.products[].publisher

String

true

상품 출판사

data.products[].coverImage

String

true

상품 이미지

data.products[].quantity

Number

true

수량

data.products[].price

Number

true

상품 금액

data.products[].discountedPrice

Number

true

상품 할인된 금액

data.deliveryInfo

Object

true

배송 정보

data.deliveryInfo.recipient

String

true

수령인

data.deliveryInfo.phoneNumber

String

true

수령인 전화번호

data.deliveryInfo.streetAddress

String

true

도로명 주소

data.deliveryInfo.detailAddress

String

true

상세 주소

data.deliveryInfo.postalCode

String

true

우편번호

data.deliveryInfo.memo

String

배송메모

data.paymentInfo

Object

true

결제 정보

data.paymentInfo.method

String

true

결제 방법

data.paymentInfo.depositorName

String

true

입금자 이름

data.paymentInfo.price

Number

true

주문 금액

data.paymentInfo.discountedPrice

Number

true

주문 할인된 금액

data.orderStatus

String

true

COMPLETED : 주문 완료, CANCELLED : 주문 취소, SHIPPING : 배송중, DELIVERED : 배송완료, REFUNDED : 환불

주문 상태

error

Null

오류 정보

{
  "success" : true,
  "data" : {
    "id" : 6,
    "orderNumber" : "ORD-20241012-000005",
    "orderDate" : "2024-10-21T19:58:19.246264",
    "orderer" : {
      "name" : "주문자2",
      "phoneNumber" : "01012345002",
      "email" : "chadwick.madden@example.com"
    },
    "products" : [ {
      "id" : 3,
      "title" : "The Challenge of Greatness (The Legacy of Great Teachers)",
      "author" : "Gose, Michael",
      "publisher" : "국내총판도서",
      "coverImage" : "https://shopping-phinf.pstatic.net/main_3247428/32474284194.20220520074619.jpg",
      "quantity" : 1,
      "price" : 31672,
      "discountedPrice" : 28778
    } ],
    "deliveryInfo" : {
      "recipient" : "수령인2",
      "phoneNumber" : "01054321002",
      "postalCode" : "12002",
      "streetAddress" : "서울 종로구 종로3가 2",
      "detailAddress" : "종로아파트 2호",
      "memo" : "배송메모2"
    },
    "paymentInfo" : {
      "method" : "CREDIT_CARD",
      "depositorName" : "예금주2",
      "price" : 31672,
      "discountedPrice" : 28778
    },
    "orderStatus" : "COMPLETED"
  },
  "error" : null
}

장바구니 관련 API

장바구니 목록 조회

Http

GET /order/v1/shopping-carts HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Host: localhost:8080

Response

필드명 타입 필수값 양식 설명

success

Boolean

true

요청 성공 여부

data

Object

true

응답 데이터

data.products

Array

true

상품 목록

data.products[].shoppingCartId

Number

true

장바구니 고유번호

data.products[].productId

Number

true

상품 고유번호

data.products[].title

String

true

상품 이름

data.products[].coverImage

String

true

상품 이미지

data.products[].quantity

Number

true

수량

data.products[].price

Number

true

상품 금액

data.products[].discountedPrice

Number

true

상품 할인된 금액

error

Array

오류 정보

{
  "success" : true,
  "data" : {
    "products" : [ {
      "shoppingCartId" : 3,
      "productId" : 1,
      "title" : "[개발팀]국내도서 테스트 상품 (테스트 상품입니다.)",
      "coverImage" : "https://shopping-phinf.pstatic.net/main_4964421/49644215637.20240806201630.jpg",
      "quantity" : 12,
      "price" : 353700,
      "discountedPrice" : 303804
    } ]
  },
  "error" : null
}

장바구니 상품 등록

Http

POST /order/v1/shopping-carts HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Content-Length: 39
Host: localhost:8080

{
  "productId" : 1,
  "quantity" : 2
}

Request

필드명 타입 필수값 양식 설명

productId

Number

true

상품 고유번호

quantity

Number

true

수량

Response

필드명 타입 필수값 양식 설명

success

Boolean

true

요청 성공 여부

data

Object

응답 데이터

error

Array

오류 정보

{
  "success" : true,
  "data" : null,
  "error" : null
}

장바구니 상품 수량 변경

Http

PATCH /order/v1/shopping-carts/1 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Content-Length: 20
Host: localhost:8080

{
  "quantity" : 2
}

Path Variable

필드명 필수값 양식 설명

shoppingCartId

true

장바구니 ID

Request

필드명 타입 필수값 양식 설명

quantity

Number

true

수량

Response

필드명 타입 필수값 양식 설명

success

Boolean

true

요청 성공 여부

data

Object

응답 데이터

error

Array

오류 정보

{
  "success" : true,
  "data" : null,
  "error" : null
}

장바구니 상품 삭제

Http

DELETE /order/v1/shopping-carts/1 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzI0NTIwNDc5LCJleHAiOjE3MjU3MzAwNzl9.i1WjcNXU2wBYjikGu5u0r41XmciafAfaMF3nNheb9cc7TUpai-tnMZCg3NUcTWP9
Host: localhost:8080

Path Variable

필드명 필수값 양식 설명

shoppingCartId

true

장바구니 ID

Response

필드명 타입 필수값 양식 설명

success

Boolean

true

요청 성공 여부

data

Object

응답 데이터

error

Array

오류 정보

{
  "success" : true,
  "data" : null,
  "error" : null
}