주문 상태 흐름

주문의 전체 상태 흐름, 웹훅 이벤트 매핑, 취소 규칙, Sandbox 동작 차이를 안내합니다.

상태 흐름도

주문은 다음과 같은 순서로 상태가 전이됩니다.

PAID

→

PDF_READY

→

CONFIRMED

→

IN_PRODUCTION

→

PRODUCTION_COMPLETE

→

SHIPPED

→

DELIVERED

파트너 취소:

PAID / PDF_READY

→

CANCELLED_REFUND

상태 코드 전체 목록

주문 상태는 문자열 enum(orderStatus)과 한글 표시 문자열(orderStatusDisplay)로 응답에 포함됩니다. 항목 단위 상태도 동일 규칙(itemStatus·itemStatusDisplay)입니다.

`orderStatus`	`orderStatusDisplay`	Scope	설명
`PAID`	결제완료	Order·Item	충전금 차감 완료 (PDF가 아직 준비되지 않은 주문의 초기 상태)
`PDF_READY`	PDF준비완료	Order·Item	출력용 PDF 준비 완료. 주문 시점에 모든 책의 PDF가 준비돼 있으면(PDF 방식 책은 최종화 후 항상) 주문이 이 상태로 생성됨
`CONFIRMED`	제작확정	Order·Item	제작건 확정 (출력일 배정)
`IN_PRODUCTION`	제작중	Order·Item	인쇄·제본·포장 진행 중
`COMPLETED`	제작완료	Item	항목 제작 완료 (개별)
`PRODUCTION_COMPLETE`	전체제작완료	Order	모든 항목 제작 완료 (발송 대기)
`SHIPPED`	발송완료	Order·Item	택배 발송
`DELIVERED`	배송완료	Order	고객 수령 확인
`CANCELLED`	취소	Order·Item	취소 (환불 없음)
`CANCELLED_REFUND`	취소환불	Order	취소 + 충전금 환불 (부분 취소 귀결 포함)
`ERROR`	오류	Order·Item	오류 상태

상태 — Webhook 이벤트 매핑

각 주문 상태 전이 시 발송되는 웹훅 이벤트와 주요 필드입니다.

상태	Webhook Event	주요 필드
`PAID` 또는 `PDF_READY` (주문 생성)	`order.created`	`total_amount`, `item_count`
`CONFIRMED`	`production.confirmed`	`print_day`
`IN_PRODUCTION`	`production.started`	`order_uid`, `order_status`
`PRODUCTION_COMPLETE`	`production.completed`	`order_uid`, `order_status`
`SHIPPED`	`shipping.departed`	`tracking_number`, `tracking_carrier`
`DELIVERED`	`shipping.delivered`	`order_uid`, `order_status`
`CANCELLED` / `CANCELLED_REFUND` (전체 취소)	`order.cancelled`	`cancel_reason`, `refund_amount`
주문 항목 부분 취소 (`orderStatus` 변경 없음)	`order.item_cancelled`	`cancelled_item_uid`, `remaining_item_uids`, `full_cancel`, `refund_amount`
마지막 항목 부분 취소 → `CANCELLED_REFUND` 귀결	`order.item_cancelled` + `order.cancelled` (호환 발송)	`full_cancel: true`, `refund_amount`
`PAID` (복원)	`order.restored`	`restore_reason`, `credit_deducted`

Sandbox 환경 동작

Sandbox 환경에서는 주문이 PAID 또는 PDF_READY(주문 시점에 PDF가 준비된 경우) 상태에서 멈춥니다. 실제 제작이나 배송이 진행되지 않으며, 상태 전이 테스트는 웹훅 테스트 기능을 활용하세요.

Sandbox에서는 PAID·PDF_READY 이후 자동 상태 전이가 발생하지 않습니다. 웹훅 수신 테스트는 POST /webhooks/test를 활용하세요.

취소 규칙

파트너가 API로 직접 취소할 수 있는 상태는 PAID와 PDF_READY뿐입니다. 이후 상태에서는 관리자 승인 절차를 통해서만 취소할 수 있습니다.

주문 전체 취소

엔드포인트: POST /orders/{orderUid}/cancel
취소 가능 상태: PAID, PDF_READY
결과 상태: CANCELLED_REFUND
충전금 환불: 결제 금액 전액(배송비/포장비 포함) 즉시 환불

주문 항목 부분 취소

엔드포인트: POST /orders/{orderUid}/items/{itemUid}/cancel
취소 가능 상태: 주문·항목 모두 PAID / PDF_READY
결과 상태: 항목 CANCELLED_REFUND / 주문 기존 상태 유지
충전금 환불: 남은 항목으로 재계산 → 차액 즉시 환불

부분 취소 누적 → 마지막 항목 취소

엔드포인트: POST /orders/{orderUid}/items/{itemUid}/cancel (마지막 남은 항목 1개에 대해 호출)
취소 가능 상태: 남은 항목이 1개뿐인 상태
결과 상태: 항목·주문 모두 CANCELLED_REFUND, 응답에 fullCancel: true
충전금 환불: 배송비/포장비 포함 잔액 환불

부분 취소 상세 규약·요청/응답 포맷은 Orders API의 주문 항목 부분 취소 섹션을 참조하세요.

제작 및 배송 SLA

단계	소요 기간	비고
제작 (CONFIRMED → PRODUCTION_COMPLETE)	3~4 영업일	공휴일 제외
배송 (SHIPPED → DELIVERED)	1~2일	한진택배