Orders API

주문 생성 및 주문 관리 API 문서입니다.

모든 Orders API는 인증이 필요합니다. API Key를 Authorization: Bearer <API_KEY> 헤더로 제공하세요.

주문 상태 코드

코드	키	설명
20	PAID	결제 완료 (충전금 차감)
25	PDF_READY	PDF 생성 완료
30	CONFIRMED	제작 확정 (출력일 배정)
40	IN_PRODUCTION	제작 진행 중
45	COMPLETED	항목 제작 완료 (개별)
50	PRODUCTION_COMPLETE	전체 제작 완료
60	SHIPPED	발송 완료
70	DELIVERED	배송 완료
80	CANCELLED	취소
81	CANCELLED_REFUND	환불 완료
90	ERROR	오류

상태 전이 (State Transitions)

주문 상태는 다음과 같은 흐름으로 전이됩니다. 파트너 관점에서의 전이 주체를 함께 표기합니다.

From	To	주체	비고
PAID	PDF_READY	자동	PDF 생성 완료 시
PDF_READY	CONFIRMED	관리자	제작 확정
CONFIRMED	IN_PRODUCTION	관리자	제작 시작
IN_PRODUCTION	COMPLETED	관리자	개별 항목 제작 완료
COMPLETED	PRODUCTION_COMPLETE	관리자	전체 제작 완료
PRODUCTION_COMPLETE	SHIPPED	관리자	운송장 번호 포함
SHIPPED	DELIVERED	관리자	배송 완료 확인
PAID	CANCELLED_REFUND	파트너	파트너 취소, 자동 환불

파트너 가능 액션

액션	가능 상태	설명
주문 취소	`PAID`	PAID 상태에서만 취소 가능, 자동 환불 처리
배송지 변경	`PAID`, `PDF_READY`, `CONFIRMED`	발송 전까지만 배송지 변경 가능

주문 생성

POST/v1/orders

FINALIZED 상태의 책을 대상으로 주문을 생성합니다. 충전금이 즉시 차감됩니다.

Request Body

json

{
  "items": [
    { "bookUid": "bk_abc123", "quantity": 1 },
    { "bookUid": "bk_def456", "quantity": 2 }
  ],
  "shipping": {
    "recipientName": "홍길동",
    "recipientPhone": "010-1234-5678",
    "postalCode": "06101",
    "address1": "서울시 강남구 테헤란로 123",
    "address2": "4층 401호",
    "memo": "부재시 경비실"
  },
  "externalRef": "PARTNER-ORDER-001"
}

Request 필드 설명

필드	타입	필수	설명
items	array	O	주문 항목 목록 (최소 1개)
items[].bookUid	string	O	책 UID (FINALIZED 상태여야 함)
items[].quantity	int	O	수량 (1~100)
shipping	object	O	배송지 정보
shipping.recipientName	string	O	수령인 (최대 100자)
shipping.recipientPhone	string	O	연락처 (최대 20자)
shipping.postalCode	string	O	우편번호 (최대 10자)
shipping.address1	string	O	주소 (최대 200자)
shipping.address2	string	-	상세주소 (최대 200자)
shipping.memo	string	-	배송 메모 (최대 200자)
externalRef	string	-	파트너 외부 참조 식별자 (최대 100자)

Response (201 Created)

json

{
  "success": true,
  "message": "주문이 생성되었습니다",
  "data": {
    "orderUid": "or_3eAx1IQiGByu",
    "orderType": "NORMAL",
    "orderStatus": 20,
    "orderStatusDisplay": "결제완료",
    "isTest": true,
    "totalProductAmount": 60400.00,
    "totalShippingFee": 3500.00,
    "totalPackagingFee": 500.00,
    "totalAmount": 64400.00,
    "paidCreditAmount": 64400.00,
    "creditBalanceAfter": 935600.00,
    "recipientName": "홍길동",
    "recipientPhone": "010-1234-5678",
    "postalCode": "06101",
    "address1": "서울시 강남구 테헤란로 123",
    "address2": "4층 401호",
    "shippingMemo": "부재시 경비실",
    "orderedAt": "2026-02-19T01:10:47Z",
    "paidAt": "2026-02-19T01:10:47Z",
    "items": [
      {
        "itemUid": "oi_aB3cD4eF5gH6",
        "bookUid": "bk_abc123",
        "bookTitle": "우리 아이 성장앨범",
        "bookSpecUid": "bs_spec001",
        "bookSpecName": "포토북 A4",
        "quantity": 1,
        "pageCount": 24,
        "unitPrice": 60400.00,
        "itemAmount": 60400.00,
        "itemStatus": 20,
        "itemStatusDisplay": "결제완료"
      }
    ]
  }
}

잔액 부족 시 (402 Payment Required)

json

{
  "success": false,
  "message": "Insufficient Credit",
  "data": {
    "required": 64400.00,
    "balance": 10000.00,
    "currency": "KRW"
  },
  "errors": ["잔액이 부족합니다. 필요: 64400.00, 잔액: 10000.00"]
}

처리 로직

각 bookUid 유효성 검증 (존재, 파트너 소유, FINALIZED 상태)
각 책의 bookSpecUid로 가격 계산
배송비(3,500원) + 포장비(500원/수량) + 상품금액 합산
충전금 잔액 확인 후 차감
주문/항목 레코드 생성

HTTP 상태 코드

상태 코드	설명
201 Created	주문 생성 성공
400 Bad Request	유효성 검증 실패 (Book 미존재, 미FINALIZED 등)
401 Unauthorized	인증 실패
402 Payment Required	충전금 잔액 부족
500 Internal Server Error	서버 오류

주문 취소

POST/v1/orders/{orderUid}/cancel

PAID 상태의 주문을 취소합니다. 결제된 충전금은 전액 환불됩니다.

Request Body

json

{
  "cancelReason": "고객 변심"
}

취소 조건

PAID 상태이고 NORMAL 유형의 주문만 취소 가능합니다
제작이 시작된 주문(CONFIRMED 이후)은 취소할 수 없습니다
취소 시 결제 금액이 충전금으로 전액 환불됩니다

Response (200 OK): 변경된 주문 상세 정보가 반환됩니다.

배송지 변경

PATCH/v1/orders/{orderUid}/shipping

PAID ~ CONFIRMED 상태에서 배송지를 변경할 수 있습니다. 발송(SHIPPED) 이후에는 변경이 불가합니다. 변경할 필드만 전달합니다.

Request Body

json

{
  "recipientName": "김영희",
  "address1": "서울시 서초구 반포대로 100"
}

지원 필드: recipientName, recipientPhone, postalCode, address1, address2, shippingMemo