주문 상태 흐름

주문의 전체 상태 흐름, 웹훅 이벤트 매핑, 취소 규칙, 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_READY`	PDF준비완료	Item	출력용 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`	`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 상태에서 멈춥니다. 실제 제작이나 배송이 진행되지 않으며, 상태 전이 테스트는 웹훅 테스트 기능을 활용하세요.

Sandbox에서는 PAID 이후 자동 상태 전이가 발생하지 않습니다. 웹훅 수신 테스트는 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일	한진택배