Gnuboard7/modules/_bundled/sirsoft-ecommerce/docs/api/checkout.md

Checkout API 레퍼런스

소유: module sirsoft-ecommerce · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.

---

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Checkout 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

---

DELETE /api/modules/sirsoft-ecommerce/checkout

• 라우트명: api.modules.sirsoft-ecommerce.checkout.destroy
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Public\CheckoutController@destroy
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

요청 파라미터 없음.

요청 예시

DELETE /api/modules/sirsoft-ecommerce/checkout HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

이 엔드포인트는 data 를 반환하지 않습니다 (성공 메시지만) — CheckoutController@destroy 는 ResponseHelper::moduleSuccess('sirsoft-ecommerce', 'messages.checkout.deleted') 를 데이터 인수 없이 호출합니다.

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "주문서가 삭제되었습니다.",
    "data": null
}

에러 응답

상태코드	의미	발생 조건
404	Not Found	삭제할 임시 주문이 없음 (TempOrderService::deleteTempOrder() 가 false 반환 — 이미 만료·미존재). 메시지: 임시 주문 정보를 찾을 수 없습니다.
500	Internal Server Error	삭제 처리 중 예외 발생. 메시지: 주문서 삭제에 실패했습니다.

설명 주문서 페이지를 이탈할 때 현재 회원/비회원의 임시 주문(temp order)을 삭제합니다. optional.sanctum으로 회원은 Auth::id(), 비회원은 cart_key(X-Cart-Key)로 대상을 식별하며, CheckoutController@destroy가 TempOrderService::deleteTempOrder()를 호출합니다. 삭제할 임시 주문이 없으면 404를 반환합니다. 주문 확정 없이 주문서에서 뒤로가기·페이지 이탈 시 미완료 임시 데이터를 정리하는 용도입니다.

GET /api/modules/sirsoft-ecommerce/checkout

• 라우트명: api.modules.sirsoft-ecommerce.checkout.show
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Public\CheckoutController@show
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

이름	위치	타입	필수	허용값	용도
country_code	query	string	아니오	—	국가 코드 (ISO 3166-1 alpha-2)
zipcode	query	string	아니오	max 20	우편번호
region	query	string	아니오	max 100	지역/권역
city	query	string	아니오	max 100	도시명 (배송비 미리보기 산출용 배송 주소)
address	query	string	아니오	max 255	기본 주소

요청 예시

GET /api/modules/sirsoft-ecommerce/checkout?country_code=KR&zipcode=06234&region=%EC%98%88%EC%8B%9C%EA%B0%92&city=%EC%98%88%EC%8B%9C%EA%B0%92&address=%EC%84%9C%EC%9A%B8%ED%8A%B9%EB%B3%84%EC%8B%9C%20%EA%B0%95%EB%82%A8%EA%B5%AC%20%ED%85%8C%ED%97%A4%EB%9E%80%EB%A1%9C%201 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

단건 응답: data 객체의 필드 (CheckoutDataService::buildResponseData() 가 구성).

필드	타입	실측 예시값	용도/설명
temp_order_id	integer	1	임시 주문 ID (주문 확정 시 사용)
items	array	[...]	주문 상품 목록 (CheckoutItemResource — 아래 "items[] 항목" 표)
calculation	object	{...}	주문 계산 결과 (OrderCalculationResult::toArray() — 아래 "calculation" 표)
promotions	object	{"item_coupons":{},"order_coupon_issue_id":null,"shipping_coupon_issue_id":null}	현재 임시 주문에 적용된 쿠폰 선택 상태
use_points	integer	0	현재 사용 설정된 마일리지 포인트
shipping_address	object|null	{"country_code":"KR","zipcode":"06234","region":null,"city":null,"address":null}	배송비 계산에 사용된 배송 주소 (미전달 시 null)
expires_at	string	2026-07-14T12:34:56+09:00	임시 주문 만료 시각 (ISO 8601)
available_coupons	array	[]	주문금액/배송비 대상 사용 가능 쿠폰 목록 (비회원은 빈 배열)
mileage	object|null	{...}	마일리지 잔액 정보 (비회원은 null — 아래 "mileage" 표)
validation_errors	array	[]	조건 위반으로 자동 제외된 쿠폰의 사유 목록 (min_amount / per_user_limit / not_combinable 등)
has_unshippable_items	boolean	false	선택된 배송국가로 배송 불가한 상품이 1개라도 있으면 true (주문하기 차단 플래그)
selected_shipping_country	string	KR	현재 선택된 배송 국가 코드
free_shipping	object	{...}	무료배송 기준액 정보 (아래 "free_shipping" 표)
unavailable_items	array	[]	구매 불가 상품 목록 (존재할 때만 포함)
has_stock_issue	boolean	false	구매 불가 사유에 재고 부족이 포함되면 true (unavailable_items 존재 시에만 포함)
has_status_issue	boolean	false	구매 불가 사유에 판매 상태 문제가 포함되면 true (unavailable_items 존재 시에만 포함)

items[] 항목 (CheckoutItemResource::toArray()):

필드	타입	실측 예시값	용도/설명
id	integer|null	1	장바구니 아이템 ID (바로구매는 null)
product_id	integer	1	상품 ID
product_option_id	integer	1	상품 옵션 ID
quantity	integer	1	주문 수량
additional_options	array	[]	선택한 추가 옵션 (group_name / name / price_adjustment)
additional_options_total	integer	0	추가 옵션 단가 합계
product	object|null	{...}	상품 정보 (이름·썸네일 등)
product_option	object|null	{...}	옵션 정보 (옵션명·판매가 등)
is_shippable_to_selected_country	boolean	true	선택된 배송국가로 이 상품이 배송 가능한지
subtotal	integer	10000	표시 소계 = (옵션 판매가 + 추가옵션 단가 합계) × 수량
subtotal_formatted	string	10,000원	소계 통화 포맷
multi_currency_subtotal	object	{"KRW":{...}}	소계 다통화 환산
unit_price	integer	10000	계산 기준 단가
unit_price_formatted	string	10,000원	단가 통화 포맷
product_coupon_discount_amount	integer	0	상품 쿠폰 할인액
product_coupon_discount_formatted	string	0원	상품 쿠폰 할인액 포맷
code_discount_amount	integer	0	할인코드 할인액
code_discount_formatted	string	0원	할인코드 할인액 포맷
order_coupon_discount_share	integer	0	주문 쿠폰 할인의 이 라인 분담액
order_coupon_discount_share_formatted	string	0원	분담액 포맷
total_discount	integer	0	이 라인의 총 할인액
total_discount_formatted	string	0원	총 할인액 포맷
points_used_share	integer	0	사용 마일리지의 이 라인 분담액
points_used_share_formatted	string	0원	분담액 포맷
points_earning	integer	0	이 라인의 적립 예정 마일리지
final_amount	integer	10000	이 라인의 최종 금액
final_amount_formatted	string	10,000원	최종 금액 포맷
multi_currency_unit_price	object	{"KRW":{"amount":10000,"formatted":"10,000원"}}	단가 다통화 환산
multi_currency_product_coupon_discount	object	{"KRW":{"amount":0,"formatted":"0원"}}	상품 쿠폰 할인 다통화 환산
multi_currency_total_discount	object	{"KRW":{"amount":0,"formatted":"0원"}}	총 할인 다통화 환산
multi_currency_final_amount	object	{"KRW":{"amount":10000,"formatted":"10,000원"}}	최종 금액 다통화 환산
available_coupons	array	[]	이 상품에 적용 가능한 상품 쿠폰 목록
disabled_coupon_ids	array	[]	다른 상품 라인에서 이미 소진되어(per_user_limit) 이 라인에서는 선택 불가한 쿠폰 발급 ID

calculation (OrderCalculationResult::toArray()):

필드	타입	실측 예시값	용도/설명
items	array	[...]	라인별 계산 결과
summary	object	{...}	합계 정보 (Summary::toArray() — 아래 표)
promotions	object	{...}	실제 적용된 프로모션 요약 (상품/주문 프로모션 분리 + coupon_issue_ids / item_coupons / discount_code 평탄 키)
validation_errors	array	[]	쿠폰 검증 오류 목록
metadata	object	{}	플러그인 확장용 메타데이터 (비어 있으면 생략)

calculation.summary (Summary::toArray()):

필드	타입	실측 예시값	용도/설명
subtotal	integer	10000	상품 금액 소계 (할인 전)
subtotal_formatted	string	10,000원	소계 통화 포맷
product_coupon_discount	integer	0	상품/카테고리 쿠폰 할인 합계
product_coupon_discount_formatted	string	0원	상품 쿠폰 할인 포맷
code_discount	integer	0	할인코드 할인 합계
code_discount_formatted	string	0원	할인코드 할인 포맷
order_coupon_discount	integer	0	주문 쿠폰 할인 합계
order_coupon_discount_formatted	string	0원	주문 쿠폰 할인 포맷
total_coupon_discount	integer	0	상품 + 주문 쿠폰 할인 합계
total_coupon_discount_formatted	string	0원	쿠폰 할인 합계 포맷
total_discount	integer	0	총 할인금액
discount_formatted	string	0원	총 할인금액 포맷
base_shipping_total	integer	3000	기본 배송비 합계
extra_shipping_total	integer	0	추가 배송비(도서산간) 합계
total_shipping	integer	3000	총 배송비 (기본 + 추가)
total_shipping_fee	integer	3000	총 배송비 (별칭 키)
shipping_fee_formatted	string	3,000원	총 배송비 포맷
shipping_discount	integer	0	배송비 할인
shipping_discount_formatted	string	0원	배송비 할인 포맷
taxable_amount	integer	10000	과세 금액 합계
tax_free_amount	integer	0	면세 금액 합계
points_earning	integer	0	적립 예정 마일리지 합계
total_mileage	integer	0	적립 예정 마일리지 (별칭 키)
mileage_formatted	string	0P	적립 예정 마일리지 포맷
points_used	integer	0	사용 마일리지 합계
points_used_formatted	string	0원	사용 마일리지 차감액 통화 포맷
payment_amount	integer	13000	결제금액 (마일리지 사용 전)
payment_amount_formatted	string	13,000원	결제금액 포맷
final_amount	integer	13000	최종 지불금액
final_amount_formatted	string	13,000원	최종 지불금액 포맷
selected_payment_currency	string	KRW	선택된 결제 통화 (설정된 경우에만 포함)
multi_currency	object	{"KRW":{...}}	합계 금액의 다통화 환산 (설정된 경우에만 포함)
coupon_discount	integer	0	상품 쿠폰 할인 (deprecated — 하위 호환)
coupon_discount_formatted	string	0원	상품 쿠폰 할인 포맷 (deprecated)
order_discount	integer	0	주문 쿠폰 할인 (deprecated — 하위 호환)
order_discount_formatted	string	0원	주문 쿠폰 할인 포맷 (deprecated)

mileage (UserMileageService::getBalance() + 체크아웃 추가 키, 비회원은 null):

필드	타입	실측 예시값	용도/설명
enabled	boolean	true	마일리지 적립 기능 활성화 여부
available	integer	0	사용 가능 마일리지 잔액
pending	integer	0	적립 대기 중인 마일리지
expiring_soon	integer	0	곧 소멸 예정 마일리지
expiring_date	string|null	2026-08-31	소멸 예정일 (없으면 null)
total_earned	integer	0	누적 적립 마일리지
total_used	integer	0	누적 사용 마일리지
by_currency	object	{}	통화별 마일리지 내역
max_usable	integer	0	이번 주문에서 사용 가능한 최대 마일리지
usable	boolean	true	마일리지 "사용" 가능 여부 (기본 통화 사용 규칙 미설정 시 false)

free_shipping (CheckoutDataService::buildFreeShippingInfo()):

필드	타입	실측 예시값	용도/설명
enabled	boolean	false	무료배송 기준액 기능 활성화 여부
threshold_base	integer	50000	무료배송 기준액 (기본 통화 정수)
threshold_multi_currency	object	{"KRW":{...}}	기준액의 결제통화 환산 (기준액 0 이면 [])
remaining_base	integer	40000	무료배송까지 남은 금액 (기본 통화)
remaining_multi_currency	object	{"KRW":{...}}	남은 금액의 결제통화 환산 (남은 금액 0 이면 [])

응답 예시

{
    "success": true,
    "message": "주문서 정보를 조회했습니다.",
    "data": {
        "temp_order_id": 1,
        "items": [
            {
                "id": 1,
                "product_id": 1,
                "product_option_id": 1,
                "quantity": 1,
                "additional_options": [],
                "additional_options_total": 0,
                "product": { "id": 1, "name": "샘플 상품" },
                "product_option": { "id": 1, "name": "기본 옵션" },
                "is_shippable_to_selected_country": true,
                "subtotal": 10000,
                "subtotal_formatted": "10,000원",
                "multi_currency_subtotal": {},
                "unit_price": 10000,
                "unit_price_formatted": "10,000원",
                "product_coupon_discount_amount": 0,
                "product_coupon_discount_formatted": "0원",
                "code_discount_amount": 0,
                "code_discount_formatted": "0원",
                "order_coupon_discount_share": 0,
                "order_coupon_discount_share_formatted": "0원",
                "total_discount": 0,
                "total_discount_formatted": "0원",
                "points_used_share": 0,
                "points_used_share_formatted": "0원",
                "points_earning": 0,
                "final_amount": 10000,
                "final_amount_formatted": "10,000원",
                "available_coupons": [],
                "disabled_coupon_ids": []
            }
        ],
        "calculation": {
            "items": [],
            "summary": {
                "subtotal": 10000,
                "subtotal_formatted": "10,000원",
                "total_discount": 0,
                "discount_formatted": "0원",
                "base_shipping_total": 3000,
                "extra_shipping_total": 0,
                "total_shipping": 3000,
                "shipping_fee_formatted": "3,000원",
                "points_earning": 0,
                "points_used": 0,
                "points_used_formatted": "0원",
                "payment_amount": 13000,
                "payment_amount_formatted": "13,000원",
                "final_amount": 13000,
                "final_amount_formatted": "13,000원"
            },
            "promotions": {
                "coupon_issue_ids": [],
                "item_coupons": {},
                "discount_code": null
            },
            "validation_errors": []
        },
        "promotions": {
            "item_coupons": {},
            "order_coupon_issue_id": null,
            "shipping_coupon_issue_id": null
        },
        "use_points": 0,
        "shipping_address": {
            "country_code": "KR",
            "zipcode": "06234",
            "region": null,
            "city": null,
            "address": null
        },
        "expires_at": "2026-07-14T12:34:56+09:00",
        "available_coupons": [],
        "mileage": {
            "enabled": true,
            "available": 0,
            "pending": 0,
            "expiring_soon": 0,
            "expiring_date": null,
            "total_earned": 0,
            "total_used": 0,
            "by_currency": {},
            "max_usable": 0,
            "usable": true
        },
        "validation_errors": [],
        "has_unshippable_items": false,
        "selected_shipping_country": "KR",
        "free_shipping": {
            "enabled": false,
            "threshold_base": 0,
            "threshold_multi_currency": [],
            "remaining_base": 0,
            "remaining_multi_currency": []
        }
    }
}

에러 응답

상태코드	의미	발생 조건
404	Not Found	임시 주문이 만료되었거나 존재하지 않음. 메시지: 임시 주문 정보를 찾을 수 없습니다.
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)
500	Internal Server Error	조회/재계산 중 예외 발생

설명 현재 유효한 임시 주문을 조회하면서 최신 가격으로 실시간 재계산해 주문서 페이지 데이터를 반환합니다. optional.sanctum으로 회원/비회원 모두 접근하며, CheckoutController@show가 TempOrderService::getTempOrderWithCalculation()으로 재계산하고 CheckoutDataService::buildResponseData()가 쿠폰·마일리지·상품·구매불가 상품 정보를 포함해 응답을 구성합니다. 쿼리로 country_code/zipcode/region 등 배송 주소를 전달하면 해당 주소 기준 배송비가 계산되며, 우편번호 없이 배송국가만으로도 미리보기 배송비를 산출합니다. 임시 주문이 만료·미존재면 404를 반환합니다.

응답의 mileage_info 에는 잔액(available)·사용 가능 최대(max_usable)·사용 가능 여부(usable)와 함께 사용 정책 usage_policy(min_use_amount, use_unit, max_use_amount)가 포함됩니다. max_usable 과 usage_policy.max_use_amount 는 저장 API 가 판정하는 기준(마일리지 차감 전 결제금액)과 동일한 기준으로 산출되므로, 입력 UI 는 이 값을 그대로 상·하한으로 사용하면 됩니다. 조회는 사용 한도를 초과한 임시 주문이 있어도 200 을 반환합니다(차단은 저장 시점에서만).

POST /api/modules/sirsoft-ecommerce/checkout

• 라우트명: api.modules.sirsoft-ecommerce.checkout.store
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Public\CheckoutController@store
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

이름	위치	타입	필수	허용값	용도
item_ids	body	array	아니오	min 1	item 식별자 배열
direct_items	body	array	아니오	min 1	바로 구매 항목 배열 (장바구니 미경유 — 항목별 product_id/product_option_id/quantity, item_ids와 택일)
coupon_issue_ids	body	array	아니오	—	coupon issue 식별자 배열
use_points	body	integer	아니오	min 0	사용할 마일리지(적립금) 포인트

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (sirsoft-ecommerce.checkout.validation_rules).

요청 예시

POST /api/modules/sirsoft-ecommerce/checkout HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json

{
    "item_ids": [
        "예시값"
    ],
    "direct_items": [
        "예시값"
    ],
    "coupon_issue_ids": [
        "예시값"
    ],
    "use_points": 1
}

응답 필드 (data 내부)

단건 응답: data 객체의 필드 (CheckoutController@store 가 직접 조립 — 성공 시 HTTP 201).

필드	타입	실측 예시값	용도/설명
temp_order_id	integer	1	생성된 임시 주문 ID (이후 조회/수정/주문 확정에 사용)
calculation	object	{...}	주문 계산 결과 (OrderCalculationResult::toArray() — items / summary / promotions / validation_errors. 상세는 GET /checkout 의 calculation 표 참조)
expires_at	string	2026-07-14T12:34:56+09:00	임시 주문 만료 시각 (ISO 8601)

응답 예시

{
    "success": true,
    "message": "주문서가 생성되었습니다.",
    "data": {
        "temp_order_id": 1,
        "calculation": {
            "items": [],
            "summary": {
                "subtotal": 10000,
                "subtotal_formatted": "10,000원",
                "total_discount": 0,
                "total_shipping": 3000,
                "payment_amount": 13000,
                "final_amount": 13000,
                "final_amount_formatted": "13,000원"
            },
            "promotions": {
                "coupon_issue_ids": [],
                "item_coupons": {},
                "discount_code": null
            },
            "validation_errors": []
        },
        "expires_at": "2026-07-14T12:34:56+09:00"
    }
}

에러 응답

상태코드	의미	발생 조건
400	Bad Request	장바구니가 비어 있음. 메시지: 장바구니가 비어있습니다.
422	Unprocessable Entity	보유 잔액을 초과하는 마일리지 사용 요청 (error.code: mileage_exceeds_balance). 메시지: 주문서 생성에 실패했습니다.
500	Internal Server Error	임시 주문 생성 중 예외 발생. 메시지: 주문서 생성에 실패했습니다.

설명 장바구니에서 선택한 아이템으로 임시 주문을 생성해 주문서 작성 단계로 진입합니다. optional.sanctum으로 회원/비회원 모두 접근하며, CheckoutController@store가 direct_items가 있으면 TempOrderService::createTempOrderFromDirectItems()(바로 구매, 장바구니 미경유), 없으면 item_ids로 createTempOrderFromSelectedItems()(장바구니 경유)를 호출합니다. 응답에는 임시 주문 ID·계산 결과·만료 시각(expires_at)이 포함됩니다. 재고 부족·판매 중지·구매 제한 상품이 있으면 400(cart_unavailable), 빈 장바구니는 400을 반환합니다.

마일리지 사용은 보유 잔액뿐 아니라 관리자 설정 사용 정책(최소 사용액 min_use_amount, 사용 단위 use_unit, 최대 한도 max_use_percent/max_use_value)까지 서버에서 강제하며, 위반 시 422 를 반환합니다. 한도 초과 응답 메시지에는 사용 가능한 최대 금액이 함께 안내됩니다. 판정 기준 금액은 마일리지 차감 전 결제금액이며, 비회원의 use_points 는 예외 없이 0 으로 처리됩니다.

PUT /api/modules/sirsoft-ecommerce/checkout

• 라우트명: api.modules.sirsoft-ecommerce.checkout.update
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Public\CheckoutController@update
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

이름	위치	타입	필수	허용값	용도
item_coupons	body	array	아니오	—	상품별 적용 쿠폰 맵 (상품 옵션 ID를 키로, 발급 쿠폰 ID 배열을 값으로 — 상품당 최대 2개)
order_coupon_issue_id	body	integer	아니오	—	order coupon issue 식별자
shipping_coupon_issue_id	body	integer	아니오	—	shipping coupon issue 식별자
use_points	body	integer	아니오	min 0	사용할 마일리지(적립금) 포인트
zipcode	body	string	아니오	max 10	우편번호
country_code	body	string	아니오	—	국가 코드 (ISO 3166-1 alpha-2)
payment_method	body	string	아니오	max 50	결제 수단 코드 (결제수단별 할인/수수료 계산 확장용)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (sirsoft-ecommerce.checkout.update_validation_rules).

요청 예시

PUT /api/modules/sirsoft-ecommerce/checkout HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json

{
    "item_coupons": [
        "예시값"
    ],
    "order_coupon_issue_id": 1,
    "shipping_coupon_issue_id": 1,
    "use_points": 1,
    "zipcode": "06234",
    "country_code": "KR",
    "payment_method": "예시값"
}

응답 필드 (data 내부)

단건 응답: data 객체의 필드. GET /api/modules/sirsoft-ecommerce/checkout 과 동일한 구조입니다 (CheckoutDataService::buildResponseData() 를 그대로 사용).

필드	타입	실측 예시값	용도/설명
temp_order_id	integer	1	임시 주문 ID
items	array	[...]	재계산된 주문 상품 목록 (CheckoutItemResource — GET 문서의 items[] 표와 동일)
calculation	object	{...}	재계산된 주문 계산 결과 (items / summary / promotions / validation_errors)
promotions	object	{"item_coupons":{},"order_coupon_issue_id":null,"shipping_coupon_issue_id":null}	반영된 쿠폰 선택 상태 (미전송 필드는 기존 값 유지)
use_points	integer	0	반영된 마일리지 사용 포인트
shipping_address	object|null	{"country_code":"KR","zipcode":"06234"}	배송비 계산에 사용된 배송 주소
expires_at	string	2026-07-14T12:34:56+09:00	임시 주문 만료 시각 (ISO 8601)
available_coupons	array	[]	주문금액/배송비 대상 사용 가능 쿠폰 (비회원은 빈 배열)
mileage	object|null	{...}	마일리지 잔액 정보 (비회원은 null)
validation_errors	array	[]	조건 위반으로 자동 제외된 쿠폰의 사유 목록
has_unshippable_items	boolean	false	선택된 배송국가로 배송 불가한 상품 존재 여부
selected_shipping_country	string	KR	현재 선택된 배송 국가 코드
free_shipping	object	{...}	무료배송 기준액 정보 (enabled / threshold_base / threshold_multi_currency / remaining_base / remaining_multi_currency)

응답 예시

{
    "success": true,
    "message": "주문서가 수정되었습니다.",
    "data": {
        "temp_order_id": 1,
        "items": [],
        "calculation": {
            "items": [],
            "summary": {
                "subtotal": 10000,
                "subtotal_formatted": "10,000원",
                "total_discount": 1000,
                "discount_formatted": "1,000원",
                "total_shipping": 3000,
                "shipping_fee_formatted": "3,000원",
                "points_used": 0,
                "payment_amount": 12000,
                "final_amount": 12000,
                "final_amount_formatted": "12,000원"
            },
            "promotions": {
                "coupon_issue_ids": [10],
                "item_coupons": {},
                "discount_code": null
            },
            "validation_errors": []
        },
        "promotions": {
            "item_coupons": {},
            "order_coupon_issue_id": 10,
            "shipping_coupon_issue_id": null
        },
        "use_points": 0,
        "shipping_address": {
            "country_code": "KR",
            "zipcode": "06234"
        },
        "expires_at": "2026-07-14T12:34:56+09:00",
        "available_coupons": [],
        "mileage": {
            "enabled": true,
            "available": 0,
            "max_usable": 0,
            "usable": true
        },
        "validation_errors": [],
        "has_unshippable_items": false,
        "selected_shipping_country": "KR",
        "free_shipping": {
            "enabled": false,
            "threshold_base": 0,
            "threshold_multi_currency": [],
            "remaining_base": 0,
            "remaining_multi_currency": []
        }
    }
}

에러 응답

상태코드	의미	발생 조건
404	Not Found	임시 주문이 만료되었거나 존재하지 않음 (TempOrderNotFoundException). 메시지: 임시 주문 정보를 찾을 수 없습니다.
422	Unprocessable Entity	보유 잔액을 초과하는 마일리지 사용 요청 (error.code: mileage_exceeds_balance). 메시지: 주문서 수정에 실패했습니다.
500	Internal Server Error	재계산 중 예외 발생. 메시지: 주문서 수정에 실패했습니다.

설명 주문서 작성 중 쿠폰·마일리지·배송 주소가 변경될 때 임시 주문 금액을 재계산합니다. optional.sanctum으로 회원/비회원 모두 접근하며, CheckoutController@update가 전송된 프로모션 필드(item_coupons·order_coupon_issue_id·shipping_coupon_issue_id)와 use_points만 반영하고 미전송 필드는 TempOrderService::updateTempOrder()에서 기존 값을 유지합니다. zipcode/country_code로 배송 주소를 함께 넘기면 배송비가 다시 계산됩니다. 임시 주문이 만료·미존재면 404, 보유 잔액 초과 또는 사용 정책(최소 사용액·사용 단위·최대 한도) 위반 마일리지는 422를 반환합니다.

POST /api/modules/sirsoft-ecommerce/checkout/extend

• 라우트명: api.modules.sirsoft-ecommerce.checkout.extend
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\Public\CheckoutController@extend
• 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근)

요청 파라미터

요청 파라미터 없음.

요청 예시

POST /api/modules/sirsoft-ecommerce/checkout/extend HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드	타입	실측 예시값	용도/설명
expires_at	string	2026-07-14T13:04:56+09:00	연장된 임시 주문 만료 시각 (ISO 8601)

응답 예시

{
    "success": true,
    "message": "주문서 유효시간이 연장되었습니다.",
    "data": {
        "expires_at": "2026-07-14T13:04:56+09:00"
    }
}

에러 응답

상태코드	의미	발생 조건
404	Not Found	연장할 임시 주문이 이미 만료되었거나 존재하지 않음 (TempOrderService::extendExpiration() 이 null 반환). 메시지: 임시 주문 정보를 찾을 수 없습니다.
500	Internal Server Error	연장 처리 중 예외 발생. 메시지: 주문서 유효시간 연장에 실패했습니다.

설명 임시 주문의 만료 시각을 연장합니다. optional.sanctum으로 회원은 Auth::id(), 비회원은 cart_key로 대상을 식별하며, CheckoutController@extend가 TempOrderService::extendExpiration()을 호출해 갱신된 expires_at을 반환합니다. 주문서 작성이 길어져 임시 주문이 만료되기 전에 세션을 연장하는 용도이며, 연장할 임시 주문이 이미 만료·미존재면 404를 반환합니다.