HeuJung
42eb21320b
현금영수증/환불계좌 기능(S3)의 감사 보완과, 그 과정에서 발견한 하네스 결함을 같은 세션에서 일괄 처리한다. 지시에 따라 무관 산출물(namuwiki 문서 초안 포함)도 단일 커밋으로 묶는다. - 현금영수증 발급 이력 접기/펼치기(W-3) + 결제행별 독립 토글 + aria 상태 - vendor-bundle manifest 해시 재생성 — composer.json version bump 미반영분 정합 - 시나리오 매니페스트 거짓 경로 정정(A/B) + 미작성 부채 :test-files 정직 표기(C) - layout-* 룰의 resources/extensions 검사 사각 제거 + 확장점 전용 root 스키마 분기 - validate-test-scenario.cjs: 맵형 test_files 크래시 + fallback 파서 covers 오검출 수정 - tosspayments 확장점 setState target 규약 위반 수정
142 KiB
142 KiB
Orders API 레퍼런스
소유: module
sirsoft-ecommerce· 생성:php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Orders 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
GET /api/modules/sirsoft-ecommerce/admin/orders
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.index - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@index - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| search_field | query | string | 아니오 | all, order_number, orderer_name, recipient_name, orderer_phone, recipient_phone, product_name, sku |
검색 대상 필드명 (검색어를 적용할 컬럼) |
| search_keyword | query | string | 아니오 | max 200 | 검색 키워드 (부분 일치) |
| date_type | query | string | 아니오 | — | 기간 필터 기준 일자 종류 (ordered_at 주문일 / paid_at 결제일 / confirmed_at 구매확정일 / delivered_at 배송완료일 / cancelled_at 취소일) |
| start_date | query | date | 아니오 | — | 조회 기간 시작일 (이 날짜 이후 데이터) |
| end_date | query | date | 아니오 | — | 조회 기간 종료일 (이 날짜 이전 데이터) |
| order_status | query | array | 아니오 | — | 주문상태 다중 선택 필터 (OrderStatusEnum 값 배열, 해당 상태의 주문만 조회) |
| option_status | query | array | 아니오 | — | 주문옵션 상태 다중 선택 필터 (OrderStatusEnum 값 배열, 해당 옵션 상태를 가진 주문만 조회) |
| shipping_type | query | array | 아니오 | — | 배송유형 다중 선택 필터 (ShippingType 코드 배열) |
| payment_method | query | array | 아니오 | — | 결제수단 다중 선택 필터. 코어 8종과 PG 플러그인이 등록한 확장 결제수단 ID(예: nhnkcp_naverpay)를 모두 허용 |
| category_id | query | integer | 아니오 | — | category 식별자 |
| min_amount | query | integer | 아니오 | min 0 | 주문금액 범위 필터 하한 (이 금액 이상 주문만 조회) |
| max_amount | query | integer | 아니오 | min 0 | 주문금액 범위 필터 상한 (이 금액 이하 주문만 조회) |
| country_codes | query | array | 아니오 | — | 배송국가 코드 다중 선택 필터 (ISO 3166-1 alpha-2 2자리 코드 배열) |
| order_device | query | array | 아니오 | — | 주문 디바이스 다중 선택 필터 (DeviceTypeEnum 값 배열 — pc/mobile/app 등) |
| min_shipping_amount | query | integer | 아니오 | min 0 | 배송비 범위 필터 하한 (이 배송비 이상 주문만 조회) |
| max_shipping_amount | query | integer | 아니오 | min 0 | 배송비 범위 필터 상한 (이 배송비 이하 주문만 조회) |
| shipping_policy_id | query | integer | 아니오 | — | shipping policy 식별자 |
| user_id | query | integer | 아니오 | — | user 식별자 |
| orderer_uuid | query | uuid | 아니오 | — | 특정 회원의 주문만 조회하는 주문자 UUID 필터 (회원 검색 연동용) |
| member_type | query | string | 아니오 | member, guest |
회원 구분 필터 (member 회원 주문 / guest 비회원 주문) |
| sort_by | query | string | 아니오 | ordered_at, paid_at, total_amount, shipped_at |
정렬 기준 필드명 (그 외 값은 422). shipped_at 은 배송 테이블 기준 — desc 는 주문별 가장 늦은 발송일, asc 는 가장 이른 발송일로 정렬하며 발송 이력이 없는 주문도 목록에 남는다 |
| sort_order | query | string | 아니오 | asc, desc |
정렬 방향 (asc 오름차순 / desc 내림차순) |
| per_page | query | integer | 아니오 | min 10, max 100 | 페이지당 항목 수 |
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
sirsoft-ecommerce.order.list_validation_rules,sirsoft-ecommerce.order.list_validation_messages).
요청 예시
GET /api/modules/sirsoft-ecommerce/admin/orders?search_field=all&search_keyword=%EC%98%88%EC%8B%9C%EA%B0%92&date_type=%EC%98%88%EC%8B%9C%EA%B0%92&start_date=2026-01-01&end_date=2026-01-01&order_status=%EC%98%88%EC%8B%9C%EA%B0%92&option_status=%EC%98%88%EC%8B%9C%EA%B0%92&shipping_type=%EC%98%88%EC%8B%9C%EA%B0%92&payment_method=%EC%98%88%EC%8B%9C%EA%B0%92&category_id=1&min_amount=1&max_amount=1&country_codes=KR&order_device=%EC%98%88%EC%8B%9C%EA%B0%92&min_shipping_amount=1&max_shipping_amount=1&shipping_policy_id=1&user_id=1&orderer_uuid=9f8b2c1a-4d3e-4a2b-8c1d-0e1f2a3b4c5d&member_type=member&sort_by=ordered_at&sort_order=asc&per_page=1&page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
목록 응답: data.data[] 배열 항목의 필드 + data.pagination.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| number | integer | 100 |
목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
| id | integer | 1408 |
기본 키 (내부 식별자) |
| order_number | string | 20260730-1436301187 |
주문번호 (사용자 노출용 고유 식별 코드) |
| order_status | string | pending_payment |
주문상태 (OrderStatusEnum 값 — 결제대기/결제완료/배송중 등) |
| order_status_label | string | 결제대기 |
order_status 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| order_status_variant | string | warning |
order_status 값의 표시 변형 키 (UI 배지 색상/스타일) |
| base_currency | string | JPY |
금액 표기 기준 통화 (모든 *_formatted 필드의 통화, 주문 시점 base_currency 고정) |
| payment_currency | string | JPY |
결제 통화 (유저가 선택·결제한 통화, base_currency 와 다르면 병기 표시) |
| is_cross_currency | boolean | false |
cross currency 여부 |
| is_partially_cancelled | boolean | false |
partially cancelled 여부 |
| total_amount | integer | 125000 |
최종 주문금액 (상품합계 − 할인 + 배송비) |
| total_amount_formatted | string | ¥125,000 |
total_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_shipping_amount | integer | 0 |
총 배송비 |
| total_shipping_amount_formatted | string | ¥0 |
total_shipping_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_paid_amount | integer | 0 |
총 실제 결제금액 (PG 결제된 금액) |
| total_paid_amount_formatted | string | ¥0 |
total_paid_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_unpaid_amount | integer | 125000 |
미결제 잔액 (최종 주문금액 − 실제 결제금액) |
| total_unpaid_amount_formatted | string | ¥125,000 |
total_unpaid_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_cancelled_amount | integer | 0 |
총 취소금액 |
| total_refunded_amount | integer | 0 |
총 환불금액 |
| total_points_used_amount | integer | 0 |
총 포인트(마일리지) 사용액 |
| total_points_used_amount_formatted | string | ¥0 |
total_points_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_earned_points_amount | integer | 1250 |
총 적립 예정 포인트 |
| total_earned_points_amount_formatted | string | ¥1,250 |
total_earned_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| ordered_at | string | 2026-07-30T10:36:30+00:00 |
ordered 일시 |
| ordered_at_formatted | string | 2026-07-30 19:36:30 |
ordered_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| order_device | string | pc |
주문 디바이스 (DeviceTypeEnum 값 — pc/mobile/app) |
| order_device_label | string | PC |
order_device 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_first_order | boolean | false |
first order 여부 |
| user | object | {"uuid":"a26219fc-94a0-4f63-9404-04c2a6ac99e4","name":"최고… |
회원 주문의 주문자 요약 (uuid·name, 비회원 주문이면 미포함) |
| first_option | object | {"product_name":"겨울 패딩 점퍼 #16","product_option_name":"카키\… |
대표 표시용 첫 번째 주문 옵션 요약 (상품명·옵션명·수량·썸네일·추가옵션 요약) |
| options_count | integer | 1 |
options 개수 (집계) |
| address | object | {"orderer_name":"연정훈","recipient_name":"소정훈","recipient_c… |
배송지 요약 (주문자명·수령인명·배송국가 코드/현지화명) |
| payment | object | {"payment_method":"dbank","payment_method_label":"무통장입금"} |
결제 요약 (결제수단 값·현지화 라벨) |
| shipping | object | {"shipping_type":null,"shipping_type_label":null,"shippin… |
배송 요약 (배송유형·배송방법 라벨·택배사명·송장번호, 첫 번째 배송 기준) |
| is_owner | boolean | false |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_update":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "주문 정보를 조회했습니다.",
"data": {
"data": [
{
"number": 100,
"id": 1408,
"order_number": "20260730-1436301187",
"order_status": "pending_payment",
"order_status_label": "결제대기",
"order_status_variant": "warning",
"base_currency": "JPY",
"payment_currency": "JPY",
"is_cross_currency": false,
"is_partially_cancelled": false,
"total_amount": 125000,
"total_amount_formatted": "¥125,000",
"total_shipping_amount": 0,
"total_shipping_amount_formatted": "¥0",
"total_paid_amount": 0,
"total_paid_amount_formatted": "¥0",
"total_unpaid_amount": 125000,
"total_unpaid_amount_formatted": "¥125,000",
"total_cancelled_amount": 0,
"total_refunded_amount": 0,
"total_points_used_amount": 0,
"total_points_used_amount_formatted": "¥0",
"total_earned_points_amount": 1250,
"total_earned_points_amount_formatted": "¥1,250",
"ordered_at": "2026-07-30T10:36:30+00:00",
"ordered_at_formatted": "2026-07-30 19:36:30",
"order_device": "pc",
"order_device_label": "PC",
"is_first_order": false,
"user": null,
"first_option": {
"product_name": "겨울 패딩 점퍼 #16",
"product_option_name": "카키/XL",
"product_code": "5E1WSBY0CHFX7UJU",
"quantity": 1,
"thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/81d10a0b743c",
"additional_options_summary": null
},
"options_count": 1,
"address": {
"orderer_name": "연정훈",
"recipient_name": "소정훈",
"recipient_country_code": "KR",
"recipient_country_name": {
"ko": "한국",
"en": "South Korea"
}
},
"payment": null,
"shipping": {
"shipping_type": null,
"shipping_type_label": null,
"shipping_method_label": null,
"carrier_name": null,
"tracking_number": null
},
"is_owner": false,
"abilities": {
"can_read": true,
"can_update": true
}
},
{
"number": 99,
"id": 1405,
"order_number": "20260730-1436298546",
"order_status": "pending_payment",
"order_status_label": "결제대기",
"order_status_variant": "warning",
"base_currency": "JPY",
"payment_currency": "JPY",
"is_cross_currency": false,
"is_partially_cancelled": true,
"total_amount": 66000,
"total_amount_formatted": "¥66,000",
"total_shipping_amount": 0,
"total_shipping_amount_formatted": "¥0",
"total_paid_amount": 66000,
"total_paid_amount_formatted": "¥66,000",
"total_unpaid_amount": 0,
"total_unpaid_amount_formatted": "¥0",
"total_cancelled_amount": 0,
"total_refunded_amount": 0,
"total_points_used_amount": 0,
"total_points_used_amount_formatted": "¥0",
"total_earned_points_amount": 698,
"total_earned_points_amount_formatted": "¥698",
"ordered_at": "2026-07-30T08:36:29+00:00",
"ordered_at_formatted": "2026-07-30 17:36:29",
"order_device": "pc",
"order_device_label": "PC",
"is_first_order": false,
"user": null,
"first_option": {
"product_name": "기본 양말 5족 #2",
"product_option_name": "그레이/M",
"product_code": "S0SO3A6SJFYLAKSF",
"quantity": 3,
"thumbnail_url": "/api/modules/sirsoft-ecommerce/product-image/8fc3ae669be2",
"additional_options_summary": null
},
"options_count": 3,
"address": {
"orderer_name": "양호민",
"recipient_name": "전종수",
"recipient_country_code": "KR",
"recipient_country_name": {
"ko": "한국",
"en": "South Korea"
}
},
"payment": null,
"shipping": {
"shipping_type": null,
"shipping_type_label": null,
"shipping_method_label": null,
"carrier_name": null,
"tracking_number": null
},
"is_owner": false,
"abilities": {
"can_read": true,
"can_update": true
}
},
"... (총 25건 중 2건 표시)"
],
"abilities": {
"can_update": true
},
"statistics": {
"total": 100,
"status_counts": {
"confirmed": 10,
"delivered": 20,
"cancelled": 5,
"shipping": 13,
"payment_complete": 20,
"preparing": 15,
"shipping_ready": 5,
"shipping_hold": 5,
"pending_payment": 7
},
"today_count": 0,
"today_revenue": 0,
"monthly_revenue": 0
},
"pagination": {
"current_page": 1,
"last_page": 4,
"per_page": 25,
"total": 100,
"from": 1,
"to": 25,
"has_more_pages": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.read)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 관리자가 주문을 다양한 필터·검색·정렬 조건으로 페이지네이션 조회합니다. auth:sanctum + sirsoft-ecommerce.orders.read 권한이 필요하며, Admin\OrderController@index가 OrderService::getList()로 목록을, getStatistics()로 상태별 통계를 함께 가져와 OrderCollection에 담아 반환합니다. 검색 필드(주문번호/주문자명/상품명/SKU 등)·기간·주문상태·결제수단·금액대·회원/비회원 구분 등 폭넓은 필터를 지원합니다. 관리자 주문 목록 화면의 기본 데이터 소스입니다.
PATCH /api/modules/sirsoft-ecommerce/admin/orders/bulk
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.bulk - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@bulkUpdate - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| ids | body | array | 예 | min 1 | 대상 리소스 식별자 배열 (대량 작업 대상) |
| order_status | body | string | 아니오 | — | 일괄 전환할 주문상태 (OrderStatusEnum 값, pending_order 제외 · 전이 규칙 검증) |
| carrier_id | body | integer | 아니오 | — | carrier 식별자 |
| tracking_number | body | string | 아니오 | max 50 | 송장(운송장)번호 (배송 관련 상태로 전환 시 carrier_id 와 함께 필수) |
요청 예시
PATCH /api/modules/sirsoft-ecommerce/admin/orders/bulk HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"ids": [
"예시값"
],
"order_status": "예시값",
"carrier_id": 1,
"tracking_number": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 관리자가 여러 주문(ids)의 주문상태나 배송 정보(택배사·송장번호)를 일괄 변경합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@bulkUpdate가 OrderService::bulkUpdate()로 처리합니다. 주문 목록에서 여러 건을 선택해 "배송 처리"·"상태 일괄 변경" 등을 수행할 때 사용합니다.
DELETE /api/modules/sirsoft-ecommerce/admin/orders/{order}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.destroy - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@destroy - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.delete
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
요청 예시
DELETE /api/modules/sirsoft-ecommerce/admin/orders/1316 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.delete)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)을 소프트 삭제합니다. auth:sanctum + sirsoft-ecommerce.orders.delete 권한이 필요하며, Admin\OrderController@destroy가 OrderService::delete()를 호출합니다. 물리 삭제가 아닌 소프트 삭제(deleted_at 표시)이므로 데이터는 보존되며, 주문 목록/상세에서 제외됩니다.
GET /api/modules/sirsoft-ecommerce/admin/orders/{order}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.show - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@show - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
요청 예시
GET /api/modules/sirsoft-ecommerce/admin/orders/1316 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 1316 |
기본 키 (내부 식별자) |
| order_number | string | 20260730-1436224914 |
주문번호 |
| base_currency | string | JPY |
금액 표기 기준 통화 (모든 *_formatted 필드의 통화, 주문 시점 base_currency 고정) |
| payment_currency | string | JPY |
결제 통화 (유저가 선택·결제한 통화, base_currency 와 다르면 병기 표시) |
| is_cross_currency | boolean | false |
cross currency 여부 |
| order_status | string | payment_complete |
주문상태 (OrderStatusEnum) |
| order_status_label | string | Payment Complete |
order_status 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| order_status_variant | string | info |
order_status 값의 표시 변형 키 (UI 배지 색상/스타일) |
| is_partially_cancelled | boolean | false |
partially cancelled 여부 |
| order_device | string | pc |
주문 디바이스 (pc/mobile/app) |
| order_device_label | string | PC |
order_device 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_first_order | boolean | true |
first order 여부 |
| subtotal_amount | integer | 179000 |
상품 합계 (할인 전, 상품가×수량 합계) |
| subtotal_amount_formatted | string | ¥179,000 |
subtotal_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_discount_amount | integer | 3000 |
총 할인금액 (모든 할인 합계) |
| total_discount_amount_formatted | string | ¥3,000 |
total_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_shipping_amount | integer | 0 |
총 배송비 |
| total_shipping_amount_formatted | string | ¥0 |
total_shipping_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_amount | integer | 176000 |
최종 주문금액 (subtotal - discount + shipping) |
| total_amount_formatted | string | ¥176,000 |
total_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_paid_amount | integer | 176000 |
총 실제 결제금액 (PG 결제액) |
| total_paid_amount_formatted | string | ¥176,000 |
total_paid_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_due_amount | integer | 0 |
총 결제예정금액 (무통장 등) |
| total_due_amount_formatted | string | ¥0 |
total_due_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| depositor_name | null | null |
무통장 입금자명 (입금확인 모달 기본값, payment 관계 로드 시에만 노출) |
| total_cancelled_amount | integer | 0 |
총 취소금액 |
| total_cancelled_amount_formatted | string | ¥0 |
total_cancelled_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_refunded_amount | integer | 0 |
총 환불금액 |
| total_refunded_amount_formatted | string | ¥0 |
total_refunded_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_refunded_points_amount | integer | 0 |
총 환불 포인트 |
| total_refunded_points_amount_formatted | string | ¥0 |
total_refunded_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_product_coupon_discount_amount | integer | 3000 |
상품 쿠폰 할인 합계 |
| total_product_coupon_discount_amount_formatted | string | ¥3,000 |
total_product_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_order_coupon_discount_amount | integer | 0 |
주문 쿠폰 할인 합계 |
| total_order_coupon_discount_amount_formatted | string | ¥0 |
total_order_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_coupon_discount_amount | integer | 3000 |
총 쿠폰 할인금액 |
| total_coupon_discount_amount_formatted | string | ¥3,000 |
total_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_code_discount_amount | integer | 0 |
총 할인코드 할인금액 |
| total_code_discount_amount_formatted | string | ¥0 |
total_code_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_points_used_amount | integer | 0 |
총 포인트 사용액 |
| total_points_used_amount_formatted | string | ¥0 |
total_points_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_deposit_used_amount | integer | 0 |
총 예치금 사용액 |
| total_deposit_used_amount_formatted | string | ¥0 |
total_deposit_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_earned_points_amount | integer | 1760 |
총 적립 예정 포인트 |
| total_earned_points_amount_formatted | string | ¥1,760 |
total_earned_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| mc_subtotal_amount | object | {"KRW":{"amount":179000,"formatted":"179,000원"},"USD":{"a… |
상품합계 다중 통화 |
| mc_total_discount_amount | object | {"KRW":{"amount":3000,"formatted":"3,000원"},"USD":{"amoun… |
총 할인 다중 통화 |
| mc_total_shipping_amount | object | {"KRW":{"amount":0,"formatted":"0원"},"USD":{"amount":0,"f… |
총 배송비 다중 통화 |
| mc_total_amount | object | {"KRW":{"amount":176000,"formatted":"176,000원"},"USD":{"a… |
최종금액 다중 통화 (payment_amount) |
| mc_total_product_coupon_discount_amount | object | {"KRW":{"amount":3000,"formatted":"3,000원"},"USD":{"amoun… |
상품 쿠폰 할인 다중 통화 |
| mc_total_order_coupon_discount_amount | object | {"KRW":{"amount":0,"formatted":"0원"},"USD":{"amount":0,"f… |
주문 쿠폰 할인 다중 통화 |
| mc_total_coupon_discount_amount | object | {"KRW":{"amount":3000,"formatted":"3,000원"},"USD":{"amoun… |
쿠폰 할인 합계 다중 통화 |
| mc_total_code_discount_amount | object | {"KRW":{"amount":0,"formatted":"0원"},"USD":{"amount":0,"f… |
할인코드 할인 다중 통화 |
| mc_total_points_used_amount | object | {"KRW":{"amount":0,"formatted":"0원"},"USD":{"amount":0,"f… |
포인트 사용 다중 통화 |
| mc_total_deposit_used_amount | object | {"KRW":{"amount":0,"formatted":"0원"},"USD":{"amount":0,"f… |
예치금 사용 다중 통화 |
| item_count | integer | 2 |
item 개수 (집계) |
| total_quantity | integer | 5 |
주문 옵션 수량 합계 (options 로드 시) |
| total_list_price | integer | 207000 |
정가 합계 (옵션 스냅샷 정가 × 수량 합계) |
| total_list_price_formatted | string | ¥207,000 |
total_list_price 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| ordered_at | string | 2026-07-27T14:36:22+00:00 |
ordered 일시 |
| ordered_at_formatted | string | 2026-07-27 23:36:22 |
ordered_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| paid_at | string | 2026-07-30T14:36:22+00:00 |
paid 일시 |
| paid_at_formatted | string | 2026-07-30 23:36:22 |
paid_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| confirmed_at | null | null |
confirmed 일시 |
| confirmed_at_formatted | null | null |
confirmed_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| cancelled_at | null | null |
cancelled 일시 |
| cancelled_at_formatted | null | null |
cancelled_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| delivered_at | null | null |
delivered 일시 |
| total_tax_amount | integer | 16000 |
총 과세금액 |
| total_tax_amount_formatted | string | ¥16,000 |
total_tax_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_vat_amount | integer | 1455 |
총 부가세금액 |
| total_vat_amount_formatted | string | ¥1,455 |
total_vat_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_taxable_supply_amount | integer | 14545 |
과세 공급가액 (총 과세금액 − 부가세, 영수증 과세금액 표시 SSoT) |
| total_taxable_supply_amount_formatted | string | ¥14,545 |
total_taxable_supply_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_tax_free_amount | integer | 0 |
총 면세금액 |
| total_tax_free_amount_formatted | string | ¥0 |
total_tax_free_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| user | object | {"uuid":"a26219fc-94a0-4f63-9404-04c2a6ac99e4","name":"최고… |
회원 주문의 주문자 정보 (uuid·name·email, user 관계 로드 시 · 비회원이면 미포함) |
| user_id | string | a26219fc-94a0-4f63-9404-04c2a6ac99e4 |
user 식별자 (연관 리소스 참조) |
| user_login_id | null | null |
회원 로그인 아이디 (login_id, 비회원 주문이면 null) |
| orderer_name | string | 박대수 |
주문자 이름 (배송지에서 플래튼) |
| orderer_phone | string | 010-4416-4675 |
주문자 휴대전화 (배송지에서 플래튼) |
| orderer_tel | null | null |
주문자 일반전화 (배송지에서 플래튼, 미입력 시 null) |
| orderer_email | string | shin.yewon@cheon.biz |
주문자 이메일 (배송지에서 플래튼, 비회원 알림 수신 통로) |
| recipient_name | string | 권강희 |
수령인 이름 (배송지에서 플래튼) |
| recipient_phone | string | 010-6286-6243 |
수령인 휴대전화 (배송지에서 플래튼) |
| recipient_tel | null | null |
수령인 일반전화 (배송지에서 플래튼, 미입력 시 null) |
| recipient_zipcode | string | 25530 |
수령인 우편번호 (배송지에서 플래튼) |
| recipient_address | string | 경상남도 광주시 선릉로 768 |
수령인 기본 주소 (배송지에서 플래튼) |
| recipient_detail_address | null | null |
수령인 상세 주소 (배송지에서 플래튼, 미입력 시 null) |
| delivery_memo | string | parcel_box |
배송 메모 (배송지에서 플래튼, 미입력 시 null) |
| delivery_memo_label | string | 택배함에 넣어주세요 |
delivery_memo 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| options | array | [{"id":1263,"option_status":"payment_complete","option_st… |
주문 옵션(품목) 목록 (OrderOptionResource — 상품·옵션·수량·옵션상태·금액) |
| shipping_address | object | {"id":319,"address_type":"shipping","orderer_name":"박대수",… |
배송지 상세 (OrderAddressResource — 주문자/수령인/국내·해외 주소) |
| billing_address | null | null |
청구지 상세 (OrderAddressResource, 미분리 시 null) |
| payment | object | {"id":1,"payment_status":"paid","payment_status_label":"P… |
대표 결제 정보 (OrderPaymentResource — 결제수단·결제상태·금액) |
| payments | array | [{"id":1,"payment_status":"paid","payment_status_label":"… |
결제 이력 목록 (OrderPaymentResource 배열 — 다회 결제/부분결제 포함) |
| cash_receipt | null | null |
현재 유효한 현금영수증 (CashReceiptResource — 취소되지 않은 발급 건, 없으면 null) |
| cash_receipts | array | [] |
현금영수증 발급·취소 이력 전체 (CashReceiptResource 배열 — 취소된 건 포함) |
| shippings | array | [] |
배송 이력 목록 (OrderShippingResource 배열 — 배송유형·택배사·송장번호) |
| cancels | array | [] |
취소 이력 목록 (OrderCancelResource 배열 — 취소 사유·상세·취소일시, 최근순) |
| promotions_applied_snapshot | object | {"coupon_issue_ids":[7330],"item_coupons":[],"discount_co… |
적용된 프로모션 스냅샷 (재계산용) |
| shipping_policy_applied_snapshot | object | {"items": [], "address": {}} |
적용된 배송정책 스냅샷 (재계산용). items 는 옵션별 적용 정책 목록(각 항목: product_option_id, policy), address 는 주문 시점 배송지 메타(country_code, zipcode). 항목이 없어도 items 는 빈 배열이다 |
| shipping_policy_applied_snapshot (비회원 응답) | object | {"items": [{"product_option_id": 481, "policy": {"policy_name": "국내 무료배송", "standalone_shipping_amount": 0, "standalone_shipping_amount_formatted": "무료배송"}}]} |
비로그인(비회원 조회 토큰) 응답은 표시용 필드만 내보낸다 — policy_name · standalone_shipping_amount(_formatted). 정책 id·계산 근거와 배송지 메타(address)는 제외된다. 비회원 주문 상세 화면이 회원과 같은 partial 로 상품별 정책명·개별 배송비를 그리므로 필드 자체를 빼면 그 줄만 오류 없이 사라진다 |
| admin_memo | null | null |
관리자 메모 (내부 관리용) |
| customer_memo | null | null |
고객 메모 (주문 시 고객이 남긴 메모) |
| created_at | string | 2026-07-30T14:36:22+00:00 |
생성 일시 |
| updated_at | string | 2026-07-30T14:36:22+00:00 |
최종 수정 일시 |
| is_owner | boolean | true |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_update":true,"can_cancel":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "주문 정보를 조회했습니다.",
"data": {
"id": 1316,
"order_number": "20260730-1436224914",
"base_currency": "JPY",
"payment_currency": "JPY",
"is_cross_currency": false,
"...": "(101개 키 생략, 총 106개)"
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.read)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)의 전체 상세를 조회합니다. auth:sanctum + sirsoft-ecommerce.orders.read 권한이 필요하며, Admin\OrderController@show가 OrderService::getDetail()로 옵션·배송·결제·취소 이력·금액 내역(과세/면세/다중통화 포함)까지 풀로드해 OrderResource로 반환합니다. 관리자 주문 상세 화면의 데이터 소스이며, 주문이 없으면 404를 반환합니다.
PATCH /api/modules/sirsoft-ecommerce/admin/orders/{order}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.update - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@update - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| order_status | body | string | 아니오 | — | 변경할 주문상태 (OrderStatusEnum 값, 현재 상태에서 전이 가능한 값만 허용) |
| admin_memo | body | string | 아니오 | max 2000 | 관리자 메모 (내부 관리용, 고객 비노출) |
| recipient_name | body | string | 예 | max 50 | 수령인 이름 |
| recipient_phone | body | string | 아니오 | max 20 | 수령인 연락처 |
| recipient_tel | body | string | 아니오 | max 20 | 수령인 일반전화 (recipient_phone 없을 때 필수) |
| recipient_zipcode | body | string | 아니오 | max 10 | 수령인 우편번호 (국내 주소, 해외 주소 없을 때 필수) |
| recipient_address | body | string | 아니오 | max 255 | 수령인 기본 주소 (국내 주소, 해외 주소 없을 때 필수) |
| recipient_detail_address | body | string | 아니오 | max 255 | 수령인 상세 주소 (recipient_address 입력 시 필수) |
| address_line_1 | body | string | 아니오 | max 255 | 주소 1행 (기본 주소) |
| address_line_2 | body | string | 아니오 | max 255 | 주소 2행 (상세 주소) |
| intl_city | body | string | 아니오 | max 100 | 도시 (국제 주소) |
| intl_state | body | string | 아니오 | max 100 | 주/도 (국제 주소) |
| intl_postal_code | body | string | 아니오 | max 20 | 우편번호 (국제 주소) |
| delivery_memo | body | string | 아니오 | max 500 | 배송 메모 (배송 시 요청사항) |
| recipient_country_code | body | string | 아니오 | — | 수령인 배송국가 코드 (ISO 3166-1 alpha-2 2자리) |
요청 예시
PATCH /api/modules/sirsoft-ecommerce/admin/orders/1316 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"order_status": "예시값",
"admin_memo": "예시값",
"recipient_name": "예시 이름",
"recipient_phone": "010-1234-5678",
"recipient_tel": "예시값",
"recipient_zipcode": "06234",
"recipient_address": "서울특별시 강남구 테헤란로 1",
"recipient_detail_address": "서울특별시 강남구 테헤란로 1",
"address_line_1": "서울특별시 강남구 테헤란로 1",
"address_line_2": "서울특별시 강남구 테헤란로 1",
"intl_city": "예시값",
"intl_state": "예시값",
"intl_postal_code": "06234",
"delivery_memo": "예시값",
"recipient_country_code": "KR"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)의 주문상태·관리자 메모·수취인 배송지(국내/해외 주소 포함)를 수정합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@update가 OrderService::update()로 처리한 뒤 수정된 주문을 OrderResource로 반환합니다. 관리자 주문 상세에서 배송지 정정·메모 기록·상태 변경 등에 사용합니다.
POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/cancel
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.cancel - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@cancelOrder - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| type | body | string | 예 | — | 취소 유형 (full 전체취소 / partial 부분취소 — partial 이면 items 필수) |
| reason | body | string | 예 | — | 취소 사유 코드 (ClaimReason 의 refund·활성 코드) |
| reason_detail | body | string | 아니오 | max 500 | 취소 사유 상세 (관리자 입력 자유 텍스트) |
| items | body | array | 아니오 | min 1 | 처리 대상 항목 배열 |
| cancel_pg | body | boolean | 아니오 | — | PG 결제 취소 동반 여부 (미지정 시 기본 true — 실제 PG 취소 수행) |
| refund_priority | body | string | 아니오 | pg_first, points_first |
환불 배분 우선순위 (pg_first PG 우선 / points_first 포인트 우선, 기본 pg_first) |
| refund_bank.bank_code | body | string | 아니오 | max 10 | 환불 계좌 은행코드. 가상계좌 + 입금완료 건은 필수(주문 시 입력된 계좌가 있으면 생략 가능). 세 필드는 전부 입력하거나 전부 비워야 함 |
| refund_bank.account_number | body | string | 아니오 | max 50 | 환불 계좌번호 |
| refund_bank.holder | body | string | 아니오 | max 50 | 환불 계좌 예금주 |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/orders/1316/cancel HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"type": "예시값",
"reason": "예시값",
"reason_detail": "예시값",
"items": [
"예시값"
],
"cancel_pg": true,
"refund_priority": "pg_first"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)을 전체취소 또는 부분취소합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@cancelOrder가 items 유무에 따라 OrderCancellationService의 cancelOrder()(전체) 또는 cancelOrderOptions()(부분)를 호출합니다. 취소자(cancelledBy)로 관리자 ID가 기록되고, cancel_pg로 PG 결제 취소 동반 여부를, refund_priority로 PG/포인트 환불 우선순위를 지정합니다. 취소 후 갱신된 주문을 OrderResource로 반환하며, 취소 불가 상태 등 실패 시 422를 반환합니다.
DELETE /api/modules/sirsoft-ecommerce/admin/orders/{order}/cash-receipt
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.cash-receipt.cancel - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\CashReceiptController@cancel - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 대상 order의 식별자 |
요청 예시
DELETE /api/modules/sirsoft-ecommerce/admin/orders/1/cash-receipt HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
data 는 항상 null 입니다 — 취소 성공 여부는 success 로 판정합니다. 취소 후의 원장 상태가 필요하면 주문 상세(GET admin/orders/{order})의 cash_receipts 를 다시 조회합니다.
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "현금영수증이 취소되었습니다.",
"data": null
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)에 발급된 현금영수증을 전액 취소합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\CashReceiptController@cancel이 CashReceiptService::cancelAll()로 활성 영수증을 발급 프로바이더(토스페이먼츠 등)에 취소 요청합니다. 부분취소 API 는 사용하지 않습니다 — 금액이 바뀌는 경우는 재발급(/cash-receipt/reissue)이 담당합니다. 취소 이력은 원장에 남아 국세청 신고 근거로 유지되며, 재발급용 식별번호 암호문은 폐기하지 않습니다(관리자가 같은 번호로 다시 발급할 수 있어야 하므로). 발급 취소는 관리자 전용이며 회원·비회원에게는 노출하지 않습니다.
실패 시 사유는 errors.error_code 로 구분합니다 — 활성 영수증이 없으면 NO_ACTIVE_RECEIPT, 프로바이더 취소가 실패하면 CANCEL_FAILED 이며 둘 다 422 입니다.
{
"success": false,
"message": "취소할 현금영수증이 없습니다.",
"errors": {
"error_code": "NO_ACTIVE_RECEIPT"
}
}
POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/cash-receipt
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.cash-receipt.issue - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\CashReceiptController@issue - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 대상 order의 식별자 |
| receipt_type | body | string | 예 | income, expense |
발급 용도 (income 소득공제용 — 개인 연말정산 / expense 지출증빙용 — 사업자 매입세액공제) |
| identifier_type | body | string | 예 | phone, card, business |
발급 수단 (phone 휴대폰번호 / card 현금영수증카드번호 / business 사업자등록번호 — 사업자등록번호는 지출증빙 전용) |
| identifier | body | string | 예 | max 30 | 식별번호 (하이픈·공백 제거 후 검증 — 휴대폰 10 |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/orders/1/cash-receipt HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"receipt_type": "income",
"identifier_type": "phone",
"identifier": "example-key"
}
응답 필드 (data 내부)
data 는 발급 이력 1건(CashReceiptResource)입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| id | integer | 발급 이력 ID |
| provider | string | 발급을 수행한 프로바이더 식별자 (예: sirsoft-pay_tosspayments) |
| transaction_type | string | 거래 유형 — issue(발급) / cancel(취소). 발급 응답은 항상 issue |
| receipt_type | string | 발급 용도 — income(소득공제용) / expense(지출증빙용) |
| receipt_type_label | string | 발급 용도의 다국어 표시명 (예: 소득공제용) |
| amount | integer | 발급 금액 (주문 통화 기준 반올림, 과세분 포함 총액) |
| amount_formatted | string | 발급 금액의 통화 표기 문자열 (예: 12,000원) |
| tax_free_amount | integer | 발급 금액 중 면세 금액 |
| tax_free_amount_formatted | string | 면세 금액의 통화 표기 문자열 |
| identifier_masked | string | 마스킹된 식별번호 (원본은 어떤 응답에도 노출되지 않음) |
| receipt_url | string|null | 프로바이더가 발급한 영수증 조회 링크 |
| issue_number | string|null | 프로바이더가 부여한 승인번호 |
| issue_status | string | 발급 상태 — IN_PROGRESS / COMPLETED / FAILED. 성공 응답은 항상 COMPLETED |
| error_code | string|null | 실패 사유 코드 (성공 시 null) |
| error_message | string|null | 실패 사유 상세 (성공 시 null) |
| issued_at | string|null | 발급 일시 (ISO8601, 머신 판독용) |
| issued_at_formatted | string|null | 발급 일시 (사용자 타임존 기준 표시용) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "현금영수증이 발급되었습니다.",
"data": {
"id": 12,
"provider": "sirsoft-pay_tosspayments",
"transaction_type": "issue",
"receipt_type": "income",
"receipt_type_label": "소득공제용",
"amount": 12000,
"amount_formatted": "12,000원",
"tax_free_amount": 0,
"tax_free_amount_formatted": "0원",
"identifier_masked": "010****5678",
"receipt_url": "https://dashboard.tosspayments.com/receipt/cash/...",
"issue_number": "CR20260710000012",
"issue_status": "COMPLETED",
"error_code": null,
"error_message": null,
"issued_at": "2026-07-10T14:32:11+09:00",
"issued_at_formatted": "2026-07-10 14:32"
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)에 현금영수증을 발급합니다. 주문 당시 구매자가 신청하지 않은 건의 사후 발급과, 발급 실패 후 식별번호를 다시 입력해 발급하는 경우에 사용합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\CashReceiptController@issue가 CashReceiptService::issue()로 발급 프로바이더에 위임합니다.
발급 가능 조건은 무통장입금(dbank) + 입금완료(PAID) + 미발급 + 현금성 금액 > 0 + 프로바이더 설정됨 이며, 하나라도 어긋나면 errors.error_code 로 사유를 구분해 반환합니다 — 이미 발급된 주문은 409(ALREADY_ISSUED), 그 외는 422(NOT_CASH_PAYMENT / PAYMENT_NOT_PAID / NO_ISSUABLE_AMOUNT / PROVIDER_NOT_CONFIGURED). 프로바이더가 발급을 거부하면 422(PROVIDER_ERROR)와 함께 errors.error_message 에 상세 사유가 담깁니다.
receipt_type(발급 용도)과 identifier_type(발급 수단)은 독립 필드입니다. 지출증빙용도 휴대폰번호로 발급할 수 있으며, 사업자등록번호는 체크섬을 검증합니다. 소득공제 + 사업자등록번호 조합과, 지출증빙 + 국세청 자진발급 지정번호(0100001234) 조합은 거부됩니다.
응답의 data 는 발급 이력 1건이며 receipt_url(영수증 조회 링크)·identifier_masked(뒤 4자리 외 마스킹)·issue_number 를 포함합니다. 식별번호 원본은 응답·로그 어디에도 노출되지 않으며, 재발급용으로만 암호화 보관하다 구매확정 시 폐기합니다.
발급 불가 응답의 errors.error_code 는 두 계열로 나뉩니다. 프론트는 이 값으로 안내 문구와 버튼 노출을 분기합니다.
① 사전 가드(resolveIssueBlocker) — 프로바이더 호출 전에 판정하며 코드 6종이 고정입니다.
| error_code | 상태코드 | 의미 |
|---|---|---|
ALREADY_ISSUED |
409 | 이미 활성 현금영수증이 발급된 주문 |
PROVIDER_NOT_CONFIGURED |
422 | 현금영수증 발급 프로바이더가 설정되지 않음 |
PAYMENT_NOT_FOUND |
422 | 주문에 결제 정보가 없음 |
NOT_CASH_PAYMENT |
422 | 무통장입금(dbank) 주문이 아님 |
PAYMENT_NOT_PAID |
422 | 입금이 확인되지 않음 |
NO_ISSUABLE_AMOUNT |
422 | 발급 가능한 현금성 금액이 0 (전액 마일리지 결제·전액 환불 등) |
② 프로바이더 실패 — 422 이며 error_code 는 프로바이더가 반환한 값을 그대로 통과시킵니다(고정 목록 없음). 어떤 리스너도 발급 요청을 처리하지 않은 경우에만 코어가 NO_PROVIDER_HANDLED 를 채웁니다. 상세 사유는 errors.error_message 에 담기므로, 프론트는 알 수 없는 코드를 만나면 error_message 를 그대로 노출하는 것을 기본 동작으로 삼습니다.
{
"success": false,
"message": "이미 현금영수증이 발급된 주문입니다.",
"errors": {
"error_code": "ALREADY_ISSUED"
}
}
POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/cash-receipt/reissue
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.cash-receipt.reissue - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\CashReceiptController@reissue - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 대상 order의 식별자 |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/orders/1/cash-receipt/reissue HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
data 는 재발급된 이력 1건(CashReceiptResource, 필드 구성은 발급 API 와 동일)이거나, 잔여 발급액이 0 이어서 재발급할 것이 없으면 null 입니다. 두 경우 모두 200 이므로 success 만으로 판정하지 말고 data 의 존재 여부까지 확인해야 합니다.
응답 예시
재발급 성공 (잔여 금액 존재):
HTTP/1.1 200
{
"success": true,
"message": "현금영수증이 재발급되었습니다.",
"data": {
"id": 14,
"provider": "sirsoft-pay_tosspayments",
"transaction_type": "issue",
"receipt_type": "income",
"receipt_type_label": "소득공제용",
"amount": 8000,
"amount_formatted": "8,000원",
"tax_free_amount": 0,
"tax_free_amount_formatted": "0원",
"identifier_masked": "010****5678",
"receipt_url": "https://dashboard.tosspayments.com/receipt/cash/...",
"issue_number": "CR20260710000014",
"issue_status": "COMPLETED",
"error_code": null,
"error_message": null,
"issued_at": "2026-07-10T15:02:44+09:00",
"issued_at_formatted": "2026-07-10 15:02"
}
}
전액 환불되어 재발급 대상 금액이 0 인 경우 (정상 결과):
{
"success": true,
"message": "현금영수증이 재발급되었습니다.",
"data": null
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 "취소 성공 + 재발급 실패" 중간 상태를 복구합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\CashReceiptController@reissue가 CashReceiptService::recoverFailedIssue()를 호출합니다.
부분환불이 일어나면 기존 영수증을 전액취소하고 잔여 금액으로 재발급하는데(부분취소 API 미사용), 취소는 성공했는데 재발급만 실패하면 활성 영수증이 없는 상태로 남습니다. 이때 원장에는 취소(COMPLETED)와 발급(FAILED) 2행이 남으며, 관리자 주문 상세가 경고 배지를 띄웁니다. 이 엔드포인트가 그 상태를 되돌립니다 — 마지막 발급 이력의 발급 용도와 저장된 식별번호 암호문을 재사용하므로 요청 본문이 필요 없습니다.
활성 영수증이 이미 있으면 금액 동기화로 위임하고, 잔여 발급액이 0(전액 환불)이면 활성 영수증 없음이 정상 결과이므로 data: null 과 함께 200 을 반환합니다. 구매확정 후에는 식별번호 암호문이 폐기되므로 복구할 수 없고 422(REISSUE_FAILED)를 반환합니다 — 이 경우 관리자가 발급 API(POST .../cash-receipt)로 식별번호를 다시 입력해야 합니다.
PATCH /api/modules/sirsoft-ecommerce/admin/orders/{order}/confirm-deposit
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.confirm-deposit - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@confirmDeposit - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| amount | body | number | 예 | min 0 | 확인된 입금액 (결제예정금액과 정확히 일치해야 함, 불일치 시 422) |
| depositor_name | body | string | 아니오 | max 100 | depositor 이름 (식별자) |
| mark_order_complete | body | boolean | 아니오 | — | 입금확인과 동시에 주문완료 처리 여부 (미지정 시 기본 false — 결제완료 전이만) |
요청 예시
PATCH /api/modules/sirsoft-ecommerce/admin/orders/1316/confirm-deposit HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"amount": 1,
"depositor_name": "예시 이름",
"mark_order_complete": true
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 무통장(dbank) 미결제 주문(order)의 입금을 확인해 결제완료로 전이합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@confirmDeposit가 OrderProcessingService::confirmManualDeposit()으로 입금자명·입금액을 기록하고 결제완료 처리합니다. 입금액(amount)이 결제예정금액과 정확히 일치하지 않으면 422(deposit_amount_mismatch)를 반환하며, mark_order_complete로 결제완료와 동시에 주문완료 처리 여부를 지정할 수 있습니다.
POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/estimate-refund
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.estimate-refund - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@estimateRefund - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| items | body | array | 예 | min 1 | 처리 대상 항목 배열 |
| refund_priority | body | string | 아니오 | pg_first, points_first |
환불 배분 우선순위 (pg_first PG 우선 / points_first 포인트 우선, 기본 pg_first) |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/orders/1316/estimate-refund HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"items": [
"예시값"
],
"refund_priority": "pg_first"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)의 선택 옵션(items) 취소 시 예상 환불 금액을 실제 취소 없이 미리 계산합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@estimateRefund가 OrderCancellationService::previewRefund()로 환불 예상값을 반환합니다. refund_priority에 따라 PG 우선/포인트 우선 환불 배분 결과가 달라집니다. 취소 화면에서 "환불 예정 금액"을 관리자에게 미리 보여주는 용도입니다.
GET /api/modules/sirsoft-ecommerce/admin/orders/{order}/logs
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.logs - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@logs - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
| sort_order | query | string | 아니오 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
요청 예시
GET /api/modules/sirsoft-ecommerce/admin/orders/1316/logs?per_page=1&sort_order=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
목록 응답: data.data[] 배열 항목의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 27789 |
기본 키 (내부 식별자) |
| log_type | string | admin |
|
| log_type_label | string | 관리자 |
log_type 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| loggable_type | string | Modules\Sirsoft\Ecommerce\Models\Orde… |
|
| loggable_type_display | string | OrderOption |
|
| loggable_id | integer | 1264 |
loggable 식별자 (연관 리소스 참조) |
| action | string | order_option.partial_cancel |
|
| action_label | string | 부분 취소 |
action 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| localized_description | string | 주문 옵션 부분 취소 (옵션 ID: 1264) |
description 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
| description_key | string | sirsoft-ecommerce::activity_log.descr… |
|
| properties | object | {"order_id":1316,"product_name":{"ko":"신제품 출시 예정 #21","en… |
|
| changes | null | null |
|
| bulk_changes | null | null |
|
| has_changes | boolean | false |
changes 여부 |
| actor_name | string | 시스템 |
행위를 수행한 주체(사용자/시스템)의 이름 |
| user | object | {"name":"시스템"} |
대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생) |
| ip_address | string | 10.10.10.1 |
요청/행위가 발생한 IP 주소 |
| created_at | string | 2026-07-29 19:56:44 |
생성 일시 |
| is_owner | boolean | false |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "주문 처리 이력을 조회했습니다.",
"data": {
"data": [
{
"id": 27789,
"log_type": "admin",
"log_type_label": "관리자",
"loggable_type": "Modules\\Sirsoft\\Ecommerce\\Models\\OrderOption",
"loggable_type_display": "OrderOption",
"loggable_id": 1264,
"action": "order_option.partial_cancel",
"action_label": "부분 취소",
"localized_description": "주문 옵션 부분 취소 (옵션 ID: 1264)",
"description_key": "sirsoft-ecommerce::activity_log.description.order_option_partial_cancel",
"properties": {
"order_id": 1316,
"product_name": {
"ko": "신제품 출시 예정 #21",
"en": "Coming Soon Product #21"
},
"quantity": 3
},
"changes": null,
"bulk_changes": null,
"has_changes": false,
"actor_name": "시스템",
"user": {
"name": "시스템"
},
"ip_address": "10.10.10.1",
"created_at": "2026-07-29 19:56:44",
"is_owner": false,
"abilities": {
"can_read": true,
"can_delete": true
}
},
{
"id": 27766,
"log_type": "admin",
"log_type_label": "관리자",
"loggable_type": "Modules\\Sirsoft\\Ecommerce\\Models\\OrderOption",
"loggable_type_display": "OrderOption",
"loggable_id": 1263,
"action": "order_option.confirm",
"action_label": "구매 확정",
"localized_description": "구매확인 (옵션 ID: 1263)",
"description_key": "sirsoft-ecommerce::activity_log.description.order_option_confirm",
"properties": {
"order_id": 1316
},
"changes": null,
"bulk_changes": null,
"has_changes": false,
"actor_name": "시스템",
"user": {
"name": "시스템"
},
"ip_address": "10.0.0.5",
"created_at": "2026-07-29 09:06:44",
"is_owner": false,
"abilities": {
"can_read": true,
"can_delete": true
}
},
"... (총 25건 중 2건 표시)"
],
"links": {
"first": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=1",
"last": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=6",
"prev": null,
"next": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 6,
"links": [
{
"url": null,
"label": "pagination.previous",
"page": null,
"active": false
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=1",
"label": "1",
"page": 1,
"active": true
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=2",
"label": "2",
"page": 2,
"active": false
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=3",
"label": "3",
"page": 3,
"active": false
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=4",
"label": "4",
"page": 4,
"active": false
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=5",
"label": "5",
"page": 5,
"active": false
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=6",
"label": "6",
"page": 6,
"active": false
},
{
"url": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs?page=2",
"label": "pagination.next",
"page": 2,
"active": false
}
],
"path": "https://api.example.com/api/modules/sirsoft-ecommerce/admin/orders/1316/logs",
"per_page": 25,
"to": 25,
"total": 126
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.read)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)의 활동 로그(주문·주문옵션·배송지 변경 이력 합산)를 페이지네이션 조회합니다. auth:sanctum + sirsoft-ecommerce.orders.read 권한이 필요하며, Admin\OrderController@logs가 OrderService::getActivityLogs()로 조회해 ActivityLogResource로 반환합니다. sort_order로 시간 정렬 방향을 지정할 수 있습니다. 관리자 주문 상세의 "처리 이력" 탭에서 누가 언제 무엇을 변경했는지 추적하는 용도입니다.
PATCH /api/modules/sirsoft-ecommerce/admin/orders/{order}/options/bulk-status
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.options.bulk-status - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@bulkChangeOptionStatus - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| items | body | array | 예 | min 1 | 처리 대상 항목 배열 |
| status | body | string | 예 | — | 일괄 전환할 옵션 상태 (OrderStatusEnum 값, 옵션별 전이 규칙 검증) |
| carrier_id | body | integer | 아니오 | — | carrier 식별자 |
| tracking_number | body | string | 아니오 | max 50 | 송장(운송장)번호 (배송 관련 상태로 전환 시 carrier_id 와 함께 필수) |
요청 예시
PATCH /api/modules/sirsoft-ecommerce/admin/orders/1316/options/bulk-status HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"items": [
"예시값"
],
"status": "예시값",
"carrier_id": 1,
"tracking_number": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)의 여러 주문 옵션 상태를 수량 분할까지 지원해 일괄 변경합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@bulkChangeOptionStatus가 status를 OrderStatusEnum으로 변환한 뒤 OrderOptionService::bulkChangeStatusWithQuantity()로 처리합니다. 배송중으로 전환 시 carrier_id·tracking_number(택배사·송장번호)를 함께 넘길 수 있습니다. 한 옵션의 일부 수량만 상태 전환(부분 배송 등)하는 시나리오를 지원합니다. items[].option_id는 경로의 {order}에 속한 옵션이어야 합니다. 다른 주문의 옵션 ID를 포함하면 422(items.N.option_id)로 거절되며, 요청 전체가 반영되지 않습니다. 검증을 거치지 않는 내부·훅 호출 경로에서 같은 불일치가 감지되면 400으로 응답합니다.
POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/reset-guest-lookup-password
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.reset-guest-lookup-password - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@resetGuestLookupPassword - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| guest_lookup_password | body | string | 예 | min 8, max 255 | 재설정할 비회원 주문 조회 비밀번호 (8자 이상, 해시로 저장 · 회원가입 정책과 동일) |
| guest_lookup_password_confirmation | body | string | 예 | — | 조회 비밀번호 확인 (guest_lookup_password 와 일치해야 함) |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/orders/1316/reset-guest-lookup-password HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"guest_lookup_password": "Password123!",
"guest_lookup_password_confirmation": "Password123!"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 비회원 주문(order)의 조회 비밀번호를 재설정합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, 비회원 주문(user_id IS NULL)만 허용하고 회원 주문에는 422를 반환합니다. Admin\OrderController@resetGuestLookupPassword가 OrderService::resetGuestLookupPassword()로 새 비밀번호를 해시로 저장하며, 평문은 응답/로그에 노출하지 않습니다. 비회원이 조회 비밀번호를 분실했을 때 관리자가 대신 재설정해 주는 용도입니다.
POST /api/modules/sirsoft-ecommerce/admin/orders/{order}/send-email
- 라우트명:
api.modules.sirsoft-ecommerce.admin.orders.send-email - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\OrderController@sendEmail - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.orders.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| order | path | string | 예 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
| body | 예 | max 255 | 이메일 주소 | ||
| message | body | string | 예 | max 5000 | 관리자가 작성한 안내 메일 본문 |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/orders/1316/send-email HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"email": "user@example.com",
"message": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.orders.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 특정 주문(order)에 대해 주문 관련 안내 이메일을 지정 주소(email)로 발송합니다. auth:sanctum + sirsoft-ecommerce.orders.update 권한이 필요하며, Admin\OrderController@sendEmail이 OrderService::sendEmail()로 관리자가 작성한 메시지(message)를 전송합니다. 주문 관련 개별 안내가 필요할 때 관리자가 상세 화면에서 수동으로 메일을 보내는 용도입니다.
POST /api/modules/sirsoft-ecommerce/orders/{orderNumber}/cancel-payment
- 라우트명:
api.modules.sirsoft-ecommerce.orders.cancel-payment - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Public\OrderController@cancelPayment - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| orderNumber | path | string | 예 | — | 대상 order number의 식별자 |
| cancel_code | body | string | 아니오 | max 100 | PG사 취소 코드 (예: USER_CANCEL, order_payments 취소 이력에 기록) |
| cancel_message | body | string | 아니오 | max 500 | PG사 취소 메시지 (order_payments 취소 이력에 기록) |
요청 예시
POST /api/modules/sirsoft-ecommerce/orders/{orderNumber}/cancel-payment HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json
{
"cancel_code": "예시값",
"cancel_message": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원/비회원이 PG 결제창을 닫았을 때 결제 취소 이력만 기록합니다. optional.sanctum으로 회원/비회원 모두 접근하며, Public\OrderController@cancelPayment가 OrderProcessingService::recordPaymentCancellation()으로 주문 상태는 변경하지 않고 order_payments에 취소창 닫힘 이력(cancel_code·cancel_message)만 남깁니다. 결제 SDK가 사용자 취소 콜백을 받았을 때 프론트가 호출해 결제 시도 이력을 추적하는 용도입니다.
GET /api/modules/sirsoft-ecommerce/user/orders
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.index - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@index - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
| per_page | query | integer | 아니오 | min 1, max 50 | 페이지당 항목 수 |
| status | query | string | 아니오 | — | 상태 필터 (해당 상태의 항목만 조회) |
| with_items | query | boolean | 아니오 | 기본 false |
주문 아이템 전량을 포함할지. 기본값에서는 대표 아이템 1건과 전체 개수(item_count)만 내려갑니다. 주문마다 상품을 전부 나열하는 화면만 켜세요 |
목록은 경량 표현입니다.
기본 응답의 items[] 에는 대표 아이템 1건만 담기고, 전체 개수는 item_count 로 제공됩니다. 아이템이 없는 주문은 빈 배열입니다. 주문마다 상품을 전부 나열해야 하는 화면은 with_items=1 로 전량을 요청하세요 — 그렇지 않은 호출자까지 주문 수 × 아이템 수를 받지 않게 하려는 기본값입니다.
부분취소 뱃지(is_partially_cancelled)는 아이템 전량 없이도 정확합니다. 서버가 집계로 판정하므로 두 경로의 값이 같습니다.
요청 예시
GET /api/modules/sirsoft-ecommerce/user/orders?page=1&per_page=1&status=%EC%98%88%EC%8B%9C%EA%B0%92&with_items=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
목록 응답: data.data[] 배열 항목의 필드 + data.pagination.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 1345 |
기본 키 (내부 식별자) |
| order_number | string | 20260730-1436245243 |
주문번호 (사용자 노출용 고유 식별 코드) |
| status | string | preparing |
주문상태 값 (OrderStatusEnum value — 마이페이지용 status 별칭) |
| status_label | string | 상품준비중 |
상태의 사람이 읽는 라벨 (상태 Enum label() 산물) |
| status_variant | string | info |
상태 표시 색상/스타일 변형 키 (상태 Enum variant() 산물 — UI 배지용) |
| is_partially_cancelled | boolean | false |
partially cancelled 여부 |
| recipient_country_code | string | KR |
배송국가 코드 (ISO 3166-1 alpha-2, shippingAddress 로드 시) |
| recipient_country_name | object | {"ko":"한국","en":"South Korea"} |
배송국가 현지화명 (로케일별 국가명 맵) |
| ordered_at | string | 2026-07-29T14:36:24+00:00 |
ordered 일시 |
| ordered_at_formatted | string | 2026-07-29 23:36:24 |
ordered_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_amount | integer | 30000 |
최종 주문금액 (상품합계 − 할인 + 배송비) |
| total_amount_formatted | string | ¥30,000 |
total_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| mc_total_amount | object | {"KRW":{"amount":30000,"formatted":"30,000원"},"USD":{"amo… |
최종 주문금액 다중 통화 (주문 시점 스냅샷, 통화별 amount·formatted) |
| total_shipping_amount | integer | 0 |
총 배송비 |
| total_shipping_amount_formatted | string | ¥0 |
total_shipping_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| mc_total_shipping_amount | object | {"KRW":{"amount":0,"formatted":"0원"},"USD":{"amount":0,"f… |
총 배송비 다중 통화 (주문 시점 스냅샷, 통화별 amount·formatted) |
| total_points_used_amount | integer | 0 |
총 포인트(마일리지) 사용액 |
| total_points_used_amount_formatted | string | ¥0 |
total_points_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_earned_points_amount | integer | 300 |
총 적립 예정 포인트 |
| total_earned_points_amount_formatted | string | ¥300 |
total_earned_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| items | array | [{"product_name":"USB 충전 케이블 #7","product_option_name":"2… |
주문 품목 목록 (상품명·옵션명·썸네일·수량·단가/소계·추가옵션 요약) |
| item_count | integer | 1 |
item 개수 (집계) |
| abilities | object | {"can_view":true,"can_cancel":false} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "주문 정보를 조회했습니다.",
"data": {
"data": [
{
"id": 1345,
"order_number": "20260730-1436245243",
"status": "preparing",
"status_label": "상품준비중",
"status_variant": "info",
"...": "(18개 키 생략, 총 23개)"
},
{
"id": 1344,
"order_number": "20260730-1436244391",
"status": "preparing",
"status_label": "상품준비중",
"status_variant": "info",
"...": "(18개 키 생략, 총 23개)"
},
"... (총 25건 중 2건 표시)"
],
"statistics": {
"pending_payment": 0,
"payment_complete": 20,
"preparing": 10,
"shipping": 0,
"delivered": 0,
"...": "(1개 키 생략, 총 6개)"
},
"abilities": {
"can_create": true
},
"pagination": {
"current_page": 1,
"last_page": 2,
"per_page": 25,
"total": 30
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 회원이 마이페이지 주문내역에서 본인 주문 목록을 상태별 통계와 함께 페이지네이션 조회합니다. auth:sanctum 인증이 필요하며, User\OrderController@index가 user_id를 본인으로 고정한 뒤 OrderService::getList()와 getUserStatistics()를 호출해 UserOrderCollection으로 반환합니다. status로 특정 주문상태만 필터링할 수 있습니다. 관리자 목록과 달리 항상 본인 주문으로만 한정됩니다.
POST /api/modules/sirsoft-ecommerce/user/orders
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.store - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Public\OrderController@store - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:sirsoft-ecommerce.user-orders.create
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| payment_method | body | string | 예 | — | 결제수단. 코어 8종(card/vbank/dbank/bank/phone/point/deposit/free) 과 PG 플러그인이 등록한 확장 결제수단 ID(예: nhnkcp_naverpay, kginicis_lpay)를 모두 허용한다. 확장 결제수단도 1급 시민으로 그대로 저장된다. 카탈로그에 없는 값은 422 |
| expected_total_amount | body | number | 예 | min 0 | 프론트가 계산한 예상 결제금액 (서버 재계산값과 대조해 금액 위변조 검증) |
| shipping_memo | body | string | 아니오 | max 500 | 배송 요청사항 메모 |
| depositor_name | body | string | 아니오 | max 50 | depositor 이름 (식별자) |
| save_shipping_address | body | boolean | 아니오 | — | 회원 주소록에 이번 배송지 저장 여부 (회원 주문 한정) |
| cash_receipt_requested | body | boolean | 아니오 | — | 현금영수증 신청 여부 (true 면 아래 3개 필드가 필수) |
| cash_receipt_type | body | string | 아니오 | — | 발급 용도 (income 소득공제 / expense 지출증빙) |
| cash_receipt_identifier_type | body | string | 아니오 | — | 발급 수단 (phone 휴대폰번호 / card 현금영수증카드 / business 사업자등록번호 — business 는 지출증빙 전용) |
| cash_receipt_identifier | body | string | 아니오 | max 30 | 발급 식별번호 (하이픈 없는 숫자. 사업자등록번호는 체크섬 검증. 마스킹 저장 + 원본은 암호화 보관) |
| refund_bank.bank_code | body | string | 아니오 | max 10 | 환불 계좌 은행코드 (세 필드는 전부 입력하거나 전부 비워야 함) |
| refund_bank.account_number | body | string | 아니오 | max 50 | 환불 계좌번호 |
| refund_bank.holder | body | string | 아니오 | max 50 | 환불 계좌 예금주 |
| guest_lookup_password | body | string | 예 | min 8, max 255 | 비회원 주문 조회 비밀번호 (비회원만 필수, 8자 이상 · 해시로 저장) |
| guest_lookup_password_confirmation | body | string | 예 | — | 조회 비밀번호 확인 (guest_lookup_password 와 일치해야 함) |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
sirsoft-ecommerce.order.create_validation_rules).
요청 예시
POST /api/modules/sirsoft-ecommerce/user/orders HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json
{
"payment_method": "예시값",
"expected_total_amount": 1,
"shipping_memo": "예시값",
"depositor_name": "예시 이름",
"save_shipping_address": true,
"cash_receipt_requested": true,
"cash_receipt_type": "예시값",
"cash_receipt_identifier_type": "example-key",
"cash_receipt_identifier": "example-key",
"guest_lookup_password": "Password123!",
"guest_lookup_password_confirmation": "Password123!"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.user-orders.create)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지). payment_method 가 결제수단 카탈로그에 없는 값이면 여기서 차단된다 |
설명 주문서 작성을 마치고 실제 주문을 생성(결제하기)하는 회원/비회원 공용 엔드포인트입니다. PG 플러그인의 fetch 인터셉터가 이 한 경로만 매칭하므로 회원/비회원이 동일 URL로 진입하고, Public\OrderController@store가 Auth::id()로 분기합니다(회원은 OrderResource, 비회원은 민감 필드를 가린 GuestOrderResource). optional.sanctum + sirsoft-ecommerce.user-orders.create 권한이 필요하며, expected_total_amount로 금액 위변조를 검증하고 비회원은 guest_lookup_password로 이후 조회 비밀번호를 설정합니다. 회원이 save_shipping_address를 켜면 배송지가 자동 저장(PG 결제는 결제완료 시점) 됩니다.
주문 확정 시점에는 재고·구매대상제한·배송국가·쿠폰 유효성과 함께 마일리지 사용 정책도 현재 설정 기준으로 재검증합니다. 임시 주문을 만든 뒤 관리자가 한도를 강화했거나 임시 주문이 조작된 경우 422(errors.code = mileage_usage_not_allowed)로 차단되며 주문은 생성되지 않습니다. 반대로 정상 생성된 주문에는 그 시점의 사용 정책이 mileage_policy_snapshot 으로 고정되어, 이후 설정이 바뀌어도 해당 주문의 판정 근거를 재현할 수 있습니다(통화·프로모션·배송정책 스냅샷과 동일 취지).
GET /api/modules/sirsoft-ecommerce/user/orders/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.show-by-id - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@show - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
GET /api/modules/sirsoft-ecommerce/user/orders/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 4 |
기본 키 (내부 식별자) |
| order_number | string | APIDOC-20260708-000001 |
주문번호 |
| base_currency | string | KRW |
금액 표기 기준 통화 (모든 *_formatted 필드의 통화, 주문 시점 base_currency 고정) |
| payment_currency | string | KRW |
결제 통화 (유저가 선택·결제한 통화, base_currency 와 다르면 병기 표시) |
| is_cross_currency | boolean | false |
cross currency 여부 |
| order_status | string | pending_payment |
주문상태 (OrderStatusEnum) |
| order_status_label | string | 결제대기 |
order_status 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| order_status_variant | string | warning |
order_status 값의 표시 변형 키 (UI 배지 색상/스타일) |
| is_partially_cancelled | boolean | false |
partially cancelled 여부 |
| order_device | string | pc |
주문 디바이스 (pc/mobile/app) |
| order_device_label | string | PC |
order_device 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_first_order | boolean | false |
first order 여부 |
| subtotal_amount | integer | 324327 |
상품 합계 (할인 전, 상품가×수량 합계) |
| subtotal_amount_formatted | string | 324,327원 |
subtotal_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_discount_amount | integer | 0 |
총 할인금액 (모든 할인 합계) |
| total_discount_amount_formatted | string | 0원 |
total_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_shipping_amount | integer | 3000 |
총 배송비 |
| total_shipping_amount_formatted | string | 3,000원 |
total_shipping_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_amount | integer | 327327 |
최종 주문금액 (subtotal - discount + shipping) |
| total_amount_formatted | string | 327,327원 |
total_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_paid_amount | integer | 0 |
총 실제 결제금액 (PG 결제액) |
| total_paid_amount_formatted | string | 0원 |
total_paid_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_due_amount | integer | 327327 |
총 결제예정금액 (무통장 등) |
| total_due_amount_formatted | string | 327,327원 |
total_due_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| depositor_name | null | null |
무통장 입금자명 (입금확인 모달 기본값, payment 관계 로드 시에만 노출) |
| total_cancelled_amount | integer | 0 |
총 취소금액 |
| total_cancelled_amount_formatted | string | 0원 |
total_cancelled_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_refunded_amount | integer | 0 |
총 환불금액 |
| total_refunded_amount_formatted | string | 0원 |
total_refunded_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_refunded_points_amount | integer | 0 |
총 환불 포인트 |
| total_refunded_points_amount_formatted | string | 0원 |
total_refunded_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_product_coupon_discount_amount | integer | 0 |
상품 쿠폰 할인 합계 |
| total_product_coupon_discount_amount_formatted | string | 0원 |
total_product_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_order_coupon_discount_amount | integer | 0 |
주문 쿠폰 할인 합계 |
| total_order_coupon_discount_amount_formatted | string | 0원 |
total_order_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_coupon_discount_amount | integer | 0 |
총 쿠폰 할인금액 |
| total_coupon_discount_amount_formatted | string | 0원 |
total_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_code_discount_amount | integer | 0 |
총 할인코드 할인금액 |
| total_code_discount_amount_formatted | string | 0원 |
total_code_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_points_used_amount | integer | 0 |
총 포인트 사용액 |
| total_points_used_amount_formatted | string | 0원 |
total_points_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_deposit_used_amount | integer | 0 |
총 예치금 사용액 |
| total_deposit_used_amount_formatted | string | 0원 |
total_deposit_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_earned_points_amount | integer | 3273 |
총 적립 예정 포인트 |
| total_earned_points_amount_formatted | string | 3,273원 |
total_earned_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| mc_subtotal_amount | array | [] |
상품합계 다중 통화 |
| mc_total_discount_amount | array | [] |
총 할인 다중 통화 |
| mc_total_shipping_amount | array | [] |
총 배송비 다중 통화 |
| mc_total_amount | array | [] |
최종금액 다중 통화 (payment_amount) |
| mc_total_product_coupon_discount_amount | array | [] |
상품 쿠폰 할인 다중 통화 |
| mc_total_order_coupon_discount_amount | array | [] |
주문 쿠폰 할인 다중 통화 |
| mc_total_coupon_discount_amount | array | [] |
쿠폰 할인 합계 다중 통화 |
| mc_total_code_discount_amount | array | [] |
할인코드 할인 다중 통화 |
| mc_total_points_used_amount | array | [] |
포인트 사용 다중 통화 |
| mc_total_deposit_used_amount | array | [] |
예치금 사용 다중 통화 |
| item_count | integer | 4 |
item 개수 (집계) |
| total_quantity | integer | 0 |
주문 옵션 수량 합계 (options 로드 시) |
| total_list_price | integer | 0 |
정가 합계 (옵션 스냅샷 정가 × 수량 합계) |
| total_list_price_formatted | string | 0원 |
total_list_price 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| ordered_at | string | 2026-07-08T01:44:49+00:00 |
ordered 일시 |
| ordered_at_formatted | string | 2026-07-08 10:44:49 |
ordered_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| paid_at | null | null |
paid 일시 |
| paid_at_formatted | null | null |
paid_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| confirmed_at | null | null |
confirmed 일시 |
| confirmed_at_formatted | null | null |
confirmed_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| cancelled_at | null | null |
cancelled 일시 |
| cancelled_at_formatted | null | null |
cancelled_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| delivered_at | null | null |
delivered 일시 |
| total_tax_amount | integer | 29757 |
총 과세금액 |
| total_tax_amount_formatted | string | 29,757원 |
total_tax_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_vat_amount | integer | 0 |
총 부가세금액 |
| total_vat_amount_formatted | string | 0원 |
total_vat_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_taxable_supply_amount | integer | 29757 |
과세 공급가액 (총 과세금액 − 부가세, 영수증 과세금액 표시 SSoT) |
| total_taxable_supply_amount_formatted | string | 29,757원 |
total_taxable_supply_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_tax_free_amount | integer | 0 |
총 면세금액 |
| total_tax_free_amount_formatted | string | 0원 |
total_tax_free_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| user | object | {"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"AP… |
대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생) |
| user_id | string | a234c2b1-cde8-437f-b28b-23323be2b98d |
user 식별자 (연관 리소스 참조) |
| user_login_id | null | null |
회원 로그인 아이디 (login_id, 비회원 주문이면 null) |
| orderer_name | null | null |
주문자 이름 (배송지에서 플래튼) |
| orderer_phone | null | null |
주문자 휴대전화 (배송지에서 플래튼) |
| orderer_tel | null | null |
주문자 일반전화 (배송지에서 플래튼, 미입력 시 null) |
| orderer_email | null | null |
주문자 이메일 (배송지에서 플래튼, 비회원 알림 수신 통로) |
| recipient_name | null | null |
수령인 이름 (배송지에서 플래튼) |
| recipient_phone | null | null |
수령인 휴대전화 (배송지에서 플래튼) |
| recipient_tel | null | null |
수령인 일반전화 (배송지에서 플래튼, 미입력 시 null) |
| recipient_zipcode | null | null |
수령인 우편번호 (배송지에서 플래튼) |
| recipient_address | null | null |
수령인 기본 주소 (배송지에서 플래튼) |
| recipient_detail_address | null | null |
수령인 상세 주소 (배송지에서 플래튼, 미입력 시 null) |
| delivery_memo | null | null |
배송 메모 (배송지에서 플래튼, 미입력 시 null) |
| delivery_memo_label | null | null |
delivery_memo 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| options | array | [] |
주문 옵션(품목) 목록 (OrderOptionResource — 상품·옵션·수량·옵션상태·금액) |
| shipping_address | null | null |
배송지 상세 (OrderAddressResource — 주문자/수령인/국내·해외 주소) |
| billing_address | null | null |
청구지 상세 (OrderAddressResource, 미분리 시 null) |
| payment | null | null |
대표 결제 정보 (OrderPaymentResource — 결제수단·결제상태·금액) |
| payments | array | [] |
결제 이력 목록 (OrderPaymentResource 배열 — 다회 결제/부분결제 포함) |
| shippings | array | [] |
배송 이력 목록 (OrderShippingResource 배열 — 배송유형·택배사·송장번호) |
| cancels | array | [] |
취소 이력 목록 (OrderCancelResource 배열 — 취소 사유·상세·취소일시, 최근순) |
| promotions_applied_snapshot | null | null |
적용된 프로모션 스냅샷 (재계산용) |
| shipping_policy_applied_snapshot | object | {"items": [], "address": {}} |
적용된 배송정책 스냅샷 (재계산용). items 는 옵션별 적용 정책 목록(각 항목: product_option_id, policy), address 는 주문 시점 배송지 메타(country_code, zipcode). 항목이 없어도 items 는 빈 배열이다 |
| admin_memo | null | null |
관리자 메모 (내부 관리용) |
| customer_memo | null | null |
고객 메모 (주문 시 고객이 남긴 메모) |
| created_at | string | 2026-07-08T01:44:49+00:00 |
생성 일시 |
| updated_at | string | 2026-07-08T01:44:49+00:00 |
최종 수정 일시 |
| is_owner | boolean | true |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_update":true,"can_cancel":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 마이페이지 주문 상세에서 주문 ID(id)로 본인 주문의 전체 상세를 조회합니다. auth:sanctum 인증이 필요하며, User\OrderController@show가 OrderService::getDetail()로 로드한 뒤 소유자 검증(user_id === Auth::id())을 거쳐 OrderResource로 반환합니다. 본인 주문이 아니거나 존재하지 않으면 정보 노출 방지를 위해 404를 반환합니다. 주문번호로 조회하는 showByOrderNumber와 달리 내부 주문 ID를 사용합니다.
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/cancel
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.cancel - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@cancel - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.user-orders.cancel
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| reason | body | string | 예 | — | 취소 사유 코드 (ClaimReason 의 refund·활성·사용자 선택 가능 코드) |
| reason_detail | body | string | 아니오 | max 500 | 취소 사유 상세 (회원 입력 자유 텍스트) |
| items | body | array | 아니오 | min 1 | 처리 대상 항목 배열 |
| refund_priority | body | string | 아니오 | pg_first, points_first |
환불 배분 우선순위 (pg_first PG 우선 / points_first 포인트 우선, 기본 pg_first) |
요청 예시
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/cancel HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"reason": "예시값",
"reason_detail": "예시값",
"items": [
"예시값"
],
"refund_priority": "pg_first"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.user-orders.cancel)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 마이페이지에서 본인 주문(id)을 취소합니다. auth:sanctum + sirsoft-ecommerce.user-orders.cancel 권한이 필요하며, User\OrderController@cancel이 items 유무에 따라 OrderCancellationService의 cancelOrderOptions()(부분) 또는 cancelOrder()(전체)를 호출합니다. 취소자(cancelledBy)로 회원 본인 ID가 기록되고, refund_priority로 PG/포인트 환불 우선순위를 지정합니다. 취소 가능 상태의 주문만 취소되며, 취소 후 갱신된 주문을 OrderResource로 반환합니다.
GET /api/modules/sirsoft-ecommerce/user/orders/{id}/cash-receipt
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.cash-receipt.show - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\CashReceiptController@show - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
GET /api/modules/sirsoft-ecommerce/user/orders/{id}/cash-receipt HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
| 필드 | 타입 | 설명 |
|---|---|---|
| issuable | boolean | 지금 발급이 가능한지 여부 (무통장 + 입금완료 + 미발급 + 현금성 금액 > 0 + 프로바이더 설정됨) |
| cash_receipt | object|null | 현재 활성 영수증 1건 (CashReceiptResource). 발급 전이거나 전액 취소된 경우 null |
cash_receipt 의 하위 필드 구성은 발급 API(POST admin/orders/{order}/cash-receipt)의 응답 필드 표와 동일합니다.
응답 예시
발급 전 (발급 가능):
HTTP/1.1 200
{
"success": true,
"message": "현금영수증 정보를 조회했습니다.",
"data": {
"issuable": true,
"cash_receipt": null
}
}
발급 완료:
{
"success": true,
"message": "현금영수증 정보를 조회했습니다.",
"data": {
"issuable": false,
"cash_receipt": {
"id": 12,
"provider": "sirsoft-pay_tosspayments",
"transaction_type": "issue",
"receipt_type": "income",
"receipt_type_label": "소득공제용",
"amount": 12000,
"amount_formatted": "12,000원",
"tax_free_amount": 0,
"tax_free_amount_formatted": "0원",
"identifier_masked": "010****5678",
"receipt_url": "https://dashboard.tosspayments.com/receipt/cash/...",
"issue_number": "CR20260710000012",
"issue_status": "COMPLETED",
"error_code": null,
"error_message": null,
"issued_at": "2026-07-10T14:32:11+09:00",
"issued_at_formatted": "2026-07-10 14:32"
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 마이페이지 주문상세에서 본인 주문(id)의 현금영수증 발급 상태를 조회합니다. auth:sanctum 인증이 필요하며, User\CashReceiptController@show가 클라이언트가 넘긴 사용자 식별자를 신뢰하지 않고 Auth::id() 로만 소유권을 판정합니다 — 타인 주문이면 404 를 반환합니다(존재 여부를 노출하지 않기 위해 403 이 아닌 404).
응답의 data.issuable 은 지금 발급이 가능한지 여부(무통장 + 입금완료 + 미발급 + 현금성 금액 > 0 + 프로바이더 설정됨)이고, data.cash_receipt 는 현재 활성 영수증 또는 발급 전이면 null 입니다. 주문상세 화면이 이 두 값으로 [현금영수증 발급] 버튼과 [영수증 보기] 링크 중 무엇을 보일지 결정합니다.
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/cash-receipt
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.cash-receipt.issue - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\CashReceiptController@issue - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| receipt_type | body | string | 예 | income, expense |
발급 용도 (income 소득공제용 — 개인 연말정산 / expense 지출증빙용 — 사업자 매입세액공제) |
| identifier_type | body | string | 예 | phone, card, business |
발급 수단 (phone 휴대폰번호 / card 현금영수증카드번호 / business 사업자등록번호 — 사업자등록번호는 지출증빙 전용) |
| identifier | body | string | 예 | max 30 | 식별번호 (하이픈·공백 제거 후 검증 — 휴대폰 10 |
요청 예시
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/cash-receipt HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"receipt_type": "income",
"identifier_type": "phone",
"identifier": "example-key"
}
응답 필드 (data 내부)
data 는 발급 이력 1건(CashReceiptResource)이며, 필드 구성은 관리자 발급 API(POST admin/orders/{order}/cash-receipt)의 응답 필드 표와 동일합니다.
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "현금영수증이 발급되었습니다.",
"data": {
"id": 12,
"provider": "sirsoft-pay_tosspayments",
"transaction_type": "issue",
"receipt_type": "income",
"receipt_type_label": "소득공제용",
"amount": 12000,
"amount_formatted": "12,000원",
"tax_free_amount": 0,
"tax_free_amount_formatted": "0원",
"identifier_masked": "010****5678",
"receipt_url": "https://dashboard.tosspayments.com/receipt/cash/...",
"issue_number": "CR20260710000012",
"issue_status": "COMPLETED",
"error_code": null,
"error_message": null,
"issued_at": "2026-07-10T14:32:11+09:00",
"issued_at_formatted": "2026-07-10 14:32"
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 주문 당시 신청하지 않은 현금영수증을 마이페이지 주문상세에서 직접 사후 발급합니다. auth:sanctum 인증이 필요하며, User\CashReceiptController@issue가 Auth::id() 로 소유권을 확인한 뒤(타인 주문이면 404) 관리자 발급과 동일한 검증·가드·프로바이더 위임을 거칩니다.
요청 본문(receipt_type / identifier_type / identifier)과 오류 코드 체계는 관리자 발급 API 와 같습니다 — 이미 발급된 주문은 409(ALREADY_ISSUED), 그 외 발급 불가 사유는 422 에 errors.error_code 로 구분해 담깁니다.
발급 취소는 제공하지 않습니다 — 국세청 신고 정정을 동반하므로 관리자 전용이며, 유저용 DELETE 라우트 자체를 노출하지 않습니다(403 이 아니라 404/405).
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/estimate-refund
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.estimate-refund - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@estimateRefund - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.user-orders.cancel
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| items | body | array | 예 | min 1 | 처리 대상 항목 배열 |
| refund_priority | body | string | 아니오 | pg_first, points_first |
환불 배분 우선순위 (pg_first PG 우선 / points_first 포인트 우선, 기본 pg_first) |
요청 예시
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/estimate-refund HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"items": [
"예시값"
],
"refund_priority": "pg_first"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.user-orders.cancel)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 마이페이지에서 본인 주문(id)의 선택 옵션(items) 취소 시 예상 환불 금액을 실제 취소 없이 미리 계산합니다. auth:sanctum + sirsoft-ecommerce.user-orders.cancel 권한이 필요하며, User\OrderController@estimateRefund가 OrderCancellationService::previewRefund()로 환불 예상값을 반환합니다. refund_priority에 따라 PG 우선/포인트 우선 환불 배분 결과가 달라집니다. 취소 확정 전 "환불 예정 금액"을 회원에게 안내하는 용도입니다.
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/options/{optionId}/confirm
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.confirm-option - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@confirmOption - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.user-orders.confirm
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| optionId | path | string | 예 | — | 대상 option의 식별자 |
요청 예시
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/options/{optionId}/confirm HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.user-orders.confirm)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 마이페이지에서 본인 주문(id)의 개별 옵션(optionId)을 구매확정합니다. auth:sanctum + sirsoft-ecommerce.user-orders.confirm 권한이 필요하며, User\OrderController@confirmOption이 OrderService::confirmOption()을 호출합니다. 구매확정 시 적립 포인트 확정 등 후속 처리가 이어지며, 확정 불가 상태(배송 미완료 등)면 422를 반환합니다. 배송 완료된 상품을 회원이 직접 "구매확정" 할 때 사용합니다.
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/reorder
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.reorder - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@reorder - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
POST /api/modules/sirsoft-ecommerce/user/orders/{id}/reorder HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 과거 주문(id)의 옵션들을 현재 장바구니에 다시 담는 재주문 기능입니다. auth:sanctum 인증이 필요하며, User\OrderController@reorder가 CartService::reorderFromOrder()로 처리해 담긴 수량(added_count), 담지 못한 항목(skipped[]), 현재 장바구니 총 개수(cart_count)를 반환합니다. 취소된 주문도 재주문 대상이 되며, 품절·단종·상품별 구매수량 한도 초과 등으로 추가 불가한 항목은 건너뛰어 skipped 배열로 안내합니다. 한 항목이 담기지 못해도 나머지 항목은 그대로 담기며, 응답은 200 입니다(항목 하나 때문에 재주문 전체를 실패시키지 않습니다). 마이페이지 주문내역의 "재주문" 버튼에 사용합니다.
PUT /api/modules/sirsoft-ecommerce/user/orders/{id}/shipping-address
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.update-shipping-address - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\User\OrderController@updateShippingAddress - 인증/권한:
auth:sanctum
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| address_id | body | integer | 아니오 | — | address 식별자 |
| recipient_name | body | string | 아니오 | max 50 | 수령인 이름 |
| recipient_phone | body | string | 아니오 | max 20 | 수령인 연락처 |
| country_code | body | string | 아니오 | — | 국가 코드 (ISO 3166-1 alpha-2) |
| zipcode | body | string | 아니오 | max 10 | 우편번호 |
| address | body | string | 아니오 | max 255 | 기본 주소 |
| address_detail | body | string | 아니오 | max 255 | 상세 주소 |
| address_line_1 | body | string | 아니오 | max 255 | 주소 1행 (기본 주소) |
| address_line_2 | body | string | 아니오 | max 255 | 주소 2행 (상세 주소) |
| intl_city | body | string | 아니오 | max 100 | 도시 (국제 주소) |
| intl_state | body | string | 아니오 | max 100 | 주/도 (국제 주소) |
| intl_postal_code | body | string | 아니오 | max 20 | 우편번호 (국제 주소) |
| delivery_memo | body | string | 아니오 | max 255 | 배송 메모 (배송 시 요청사항) |
이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (
sirsoft-ecommerce.order.shipping_address_validation_rules).
요청 예시
PUT /api/modules/sirsoft-ecommerce/user/orders/{id}/shipping-address HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"address_id": 1,
"recipient_name": "예시 이름",
"recipient_phone": "010-1234-5678",
"country_code": "KR",
"zipcode": "06234",
"address": "서울특별시 강남구 테헤란로 1",
"address_detail": "서울특별시 강남구 테헤란로 1",
"address_line_1": "서울특별시 강남구 테헤란로 1",
"address_line_2": "서울특별시 강남구 테헤란로 1",
"intl_city": "예시값",
"intl_state": "예시값",
"intl_postal_code": "06234",
"delivery_memo": "예시값"
}
응답 필드 (data 내부)
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 회원이 배송 전 상태의 본인 주문(id) 배송지를 변경합니다. auth:sanctum 인증이 필요하며, User\OrderController@updateShippingAddress가 소유자 검증 후 OrderService::updateShippingAddress()로 처리합니다. 저장된 회원 주소(address_id)를 선택하거나 수취인·연락처·주소 필드를 직접 입력할 수 있고, 국내(zipcode/address)와 해외(address_line_1·intl_city 등) 주소를 모두 지원합니다. 이미 배송이 시작된 주문 등 변경 불가 상태면 422를 반환합니다.
GET /api/modules/sirsoft-ecommerce/user/orders/{orderNumber}
- 라우트명:
api.modules.sirsoft-ecommerce.user.orders.show - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Public\OrderController@showByOrderNumber - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| orderNumber | path | string | 예 | — | 대상 order number의 식별자 |
요청 예시
GET /api/modules/sirsoft-ecommerce/user/orders/{orderNumber} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 4 |
기본 키 (내부 식별자) |
| order_number | string | APIDOC-20260708-000001 |
주문번호 |
| base_currency | string | KRW |
금액 표기 기준 통화 (모든 *_formatted 필드의 통화, 주문 시점 base_currency 고정) |
| payment_currency | string | KRW |
결제 통화 (유저가 선택·결제한 통화, base_currency 와 다르면 병기 표시) |
| is_cross_currency | boolean | false |
cross currency 여부 |
| order_status | string | pending_payment |
주문상태 (OrderStatusEnum) |
| order_status_label | string | 결제대기 |
order_status 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| order_status_variant | string | warning |
order_status 값의 표시 변형 키 (UI 배지 색상/스타일) |
| is_partially_cancelled | boolean | false |
partially cancelled 여부 |
| order_device | string | pc |
주문 디바이스 (pc/mobile/app) |
| order_device_label | string | PC |
order_device 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_first_order | boolean | false |
first order 여부 |
| subtotal_amount | integer | 324327 |
상품 합계 (할인 전, 상품가×수량 합계) |
| subtotal_amount_formatted | string | 324,327원 |
subtotal_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_discount_amount | integer | 0 |
총 할인금액 (모든 할인 합계) |
| total_discount_amount_formatted | string | 0원 |
total_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_shipping_amount | integer | 3000 |
총 배송비 |
| total_shipping_amount_formatted | string | 3,000원 |
total_shipping_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_amount | integer | 327327 |
최종 주문금액 (subtotal - discount + shipping) |
| total_amount_formatted | string | 327,327원 |
total_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_paid_amount | integer | 0 |
총 실제 결제금액 (PG 결제액) |
| total_paid_amount_formatted | string | 0원 |
total_paid_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_due_amount | integer | 327327 |
총 결제예정금액 (무통장 등) |
| total_due_amount_formatted | string | 327,327원 |
total_due_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| depositor_name | null | null |
무통장 입금자명 (입금확인 모달 기본값, payment 관계 로드 시에만 노출) |
| total_cancelled_amount | integer | 0 |
총 취소금액 |
| total_cancelled_amount_formatted | string | 0원 |
total_cancelled_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_refunded_amount | integer | 0 |
총 환불금액 |
| total_refunded_amount_formatted | string | 0원 |
total_refunded_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_refunded_points_amount | integer | 0 |
총 환불 포인트 |
| total_refunded_points_amount_formatted | string | 0원 |
total_refunded_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_product_coupon_discount_amount | integer | 0 |
상품 쿠폰 할인 합계 |
| total_product_coupon_discount_amount_formatted | string | 0원 |
total_product_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_order_coupon_discount_amount | integer | 0 |
주문 쿠폰 할인 합계 |
| total_order_coupon_discount_amount_formatted | string | 0원 |
total_order_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_coupon_discount_amount | integer | 0 |
총 쿠폰 할인금액 |
| total_coupon_discount_amount_formatted | string | 0원 |
total_coupon_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_code_discount_amount | integer | 0 |
총 할인코드 할인금액 |
| total_code_discount_amount_formatted | string | 0원 |
total_code_discount_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_points_used_amount | integer | 0 |
총 포인트 사용액 |
| total_points_used_amount_formatted | string | 0원 |
total_points_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_deposit_used_amount | integer | 0 |
총 예치금 사용액 |
| total_deposit_used_amount_formatted | string | 0원 |
total_deposit_used_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_earned_points_amount | integer | 3273 |
총 적립 예정 포인트 |
| total_earned_points_amount_formatted | string | 3,273원 |
total_earned_points_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| mc_subtotal_amount | array | [] |
상품합계 다중 통화 |
| mc_total_discount_amount | array | [] |
총 할인 다중 통화 |
| mc_total_shipping_amount | array | [] |
총 배송비 다중 통화 |
| mc_total_amount | array | [] |
최종금액 다중 통화 (payment_amount) |
| mc_total_product_coupon_discount_amount | array | [] |
상품 쿠폰 할인 다중 통화 |
| mc_total_order_coupon_discount_amount | array | [] |
주문 쿠폰 할인 다중 통화 |
| mc_total_coupon_discount_amount | array | [] |
쿠폰 할인 합계 다중 통화 |
| mc_total_code_discount_amount | array | [] |
할인코드 할인 다중 통화 |
| mc_total_points_used_amount | array | [] |
포인트 사용 다중 통화 |
| mc_total_deposit_used_amount | array | [] |
예치금 사용 다중 통화 |
| item_count | integer | 4 |
item 개수 (집계) |
| total_quantity | integer | 0 |
주문 옵션 수량 합계 (options 로드 시) |
| total_list_price | integer | 0 |
정가 합계 (옵션 스냅샷 정가 × 수량 합계) |
| total_list_price_formatted | string | 0원 |
total_list_price 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| ordered_at | string | 2026-07-08T01:44:49+00:00 |
ordered 일시 |
| ordered_at_formatted | string | 2026-07-08 10:44:49 |
ordered_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| paid_at | null | null |
paid 일시 |
| paid_at_formatted | null | null |
paid_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| confirmed_at | null | null |
confirmed 일시 |
| confirmed_at_formatted | null | null |
confirmed_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| cancelled_at | null | null |
cancelled 일시 |
| cancelled_at_formatted | null | null |
cancelled_at 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| delivered_at | null | null |
delivered 일시 |
| total_tax_amount | integer | 29757 |
총 과세금액 |
| total_tax_amount_formatted | string | 29,757원 |
total_tax_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_vat_amount | integer | 0 |
총 부가세금액 |
| total_vat_amount_formatted | string | 0원 |
total_vat_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_taxable_supply_amount | integer | 29757 |
과세 공급가액 (총 과세금액 − 부가세, 영수증 과세금액 표시 SSoT) |
| total_taxable_supply_amount_formatted | string | 29,757원 |
total_taxable_supply_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| total_tax_free_amount | integer | 0 |
총 면세금액 |
| total_tax_free_amount_formatted | string | 0원 |
total_tax_free_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷) |
| user | object | {"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"AP… |
대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생) |
| user_id | string | a234c2b1-cde8-437f-b28b-23323be2b98d |
user 식별자 (연관 리소스 참조) |
| user_login_id | null | null |
회원 로그인 아이디 (login_id, 비회원 주문이면 null) |
| orderer_name | null | null |
주문자 이름 (배송지에서 플래튼) |
| orderer_phone | null | null |
주문자 휴대전화 (배송지에서 플래튼) |
| orderer_tel | null | null |
주문자 일반전화 (배송지에서 플래튼, 미입력 시 null) |
| orderer_email | null | null |
주문자 이메일 (배송지에서 플래튼, 비회원 알림 수신 통로) |
| recipient_name | null | null |
수령인 이름 (배송지에서 플래튼) |
| recipient_phone | null | null |
수령인 휴대전화 (배송지에서 플래튼) |
| recipient_tel | null | null |
수령인 일반전화 (배송지에서 플래튼, 미입력 시 null) |
| recipient_zipcode | null | null |
수령인 우편번호 (배송지에서 플래튼) |
| recipient_address | null | null |
수령인 기본 주소 (배송지에서 플래튼) |
| recipient_detail_address | null | null |
수령인 상세 주소 (배송지에서 플래튼, 미입력 시 null) |
| delivery_memo | null | null |
배송 메모 (배송지에서 플래튼, 미입력 시 null) |
| delivery_memo_label | null | null |
delivery_memo 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| options | array | [] |
주문 옵션(품목) 목록 (OrderOptionResource — 상품·옵션·수량·옵션상태·금액) |
| shipping_address | null | null |
배송지 상세 (OrderAddressResource — 주문자/수령인/국내·해외 주소) |
| billing_address | null | null |
청구지 상세 (OrderAddressResource, 미분리 시 null) |
| payment | null | null |
대표 결제 정보 (OrderPaymentResource — 결제수단·결제상태·금액) |
| payments | array | [] |
결제 이력 목록 (OrderPaymentResource 배열 — 다회 결제/부분결제 포함) |
| shippings | array | [] |
배송 이력 목록 (OrderShippingResource 배열 — 배송유형·택배사·송장번호) |
| cancels | array | [] |
취소 이력 목록 (OrderCancelResource 배열 — 취소 사유·상세·취소일시, 최근순) |
| promotions_applied_snapshot | null | null |
적용된 프로모션 스냅샷 (재계산용) |
| shipping_policy_applied_snapshot | object | {"items": [], "address": {}} |
적용된 배송정책 스냅샷 (재계산용). items 는 옵션별 적용 정책 목록(각 항목: product_option_id, policy), address 는 주문 시점 배송지 메타(country_code, zipcode). 항목이 없어도 items 는 빈 배열이다 |
| admin_memo | null | null |
관리자 메모 (내부 관리용) |
| customer_memo | null | null |
고객 메모 (주문 시 고객이 남긴 메모) |
| created_at | string | 2026-07-08T01:44:49+00:00 |
생성 일시 |
| updated_at | string | 2026-07-08T01:44:49+00:00 |
최종 수정 일시 |
| is_owner | boolean | true |
현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | {"can_read":true,"can_update":true,"can_cancel":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 주문번호(orderNumber)로 주문 상세를 조회하는 회원/비회원 공용 엔드포인트입니다. optional.sanctum으로 로그인 여부에 따라 분기하는데, 로그인 상태면 본인 회원 주문만 OrderResource로 반환하고 아니면 404(마이페이지 주문 목록으로 안내), 비로그인이면 X-Guest-Order-Token으로 비회원 주문을 매칭해 GuestOrderResource로 반환하고 실패 시 404(비회원 조회 폼으로 안내)합니다. 회원이 비회원 토큰을 들고 와도 회원 분기가 우선하며, 실패 사유는 모두 동일한 404로 처리해 정보 노출을 차단합니다. 결제 완료 후 주문번호 기반 주문 완료/상세 페이지에서 사용합니다.