공통 사항
도메인
| 환경 | 도메인 주소 |
|---|---|
개발서버 |
|
운영서버 |
- |
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
}