generic catch 가 4xx 를 돌려주면 인프라 장애가 입력 오류로 위장돼 장애 인지가 늦어지고, 이미 번역된 예외 메시지를 응답의 메시지 키 자리에 넘기면 키 해석에 실패해 원문이 그대로 화면에 나간다. 두 형태를 코어와 전 번들 확장에서 함께 정리하고, 판정기를 한 확장이 아닌 코어 모집단에 두어 확장 밖 동형 결함도 red 가 되게 했다 — 그 사각에 실제로 15건이 있었다. 주소록에서 해외 배송지를 고르면 국내 6필드만 옮겨 담아 해외 주소가 통째로 사라지던 결함도 함께 고쳤다. 저장은 200 으로 성공 처리돼 주문 상세를 다시 열기 전에는 드러나지 않았다.
50 KiB
Claim Reasons API 레퍼런스
소유: module
sirsoft-ecommerce· 생성:php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Claim Reasons 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.index - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@index - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| type | query | string | 아니오 | — | 유형 필터 (해당 유형의 항목만 조회) |
| fault_type | query | string | 아니오 | customer, seller, carrier |
귀책 구분 필터 (ClaimReasonFaultTypeEnum — 고객/판매자/배송사 귀책). 미전달 시 전체 |
| is_active | query | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
| search | query | string | 아니오 | max 255 | 검색어 (지정한 검색 대상 필드에서 부분 일치) |
요청 예시
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons?type=%EC%98%88%EC%8B%9C%EA%B0%92&fault_type=%EC%98%88%EC%8B%9C%EA%B0%92&is_active=1&search=%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[] 배열 항목의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| number | integer | 7 |
목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
| id | integer | 1 |
기본 키 (내부 식별자) |
| type | string | refund |
클레임 사유 유형 (ClaimReasonTypeEnum — refund(환불/취소)) |
| code | string | order_mistake |
사유 식별 코드 (같은 type 내 고유, 영문 소문자/숫자/_) |
| name | object | {"ko":"주문 실수","en":"Order Mistake"} |
대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| localized_name | string | 주문 실수 |
name 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
| fault_type | string | customer |
귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| fault_type_label | string | 고객 귀책 |
fault_type 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_user_selectable | boolean | true |
user selectable 여부 |
| is_active | boolean | true |
active 여부 |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-30 17:36:00 |
생성 일시 |
| updated_at | string | 2026-07-30 17:36:00 |
최종 수정 일시 |
| creator | array | [] |
생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
| updater | array | [] |
최종 수정자 정보 객체 (id/name — updater 관계 로드 시) |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유 목록을 조회했습니다.",
"data": {
"data": [
{
"number": 7,
"id": 1,
"type": "refund",
"code": "order_mistake",
"name": {
"ko": "주문 실수",
"en": "Order Mistake"
},
"localized_name": "주문 실수",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-30 17:36:00",
"updated_at": "2026-07-30 17:36:00",
"creator": [],
"updater": [],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
{
"number": 6,
"id": 2,
"type": "refund",
"code": "changed_mind",
"name": {
"ko": "단순 변심",
"en": "Changed Mind"
},
"localized_name": "단순 변심",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 1,
"created_at": "2026-07-30 17:36:00",
"updated_at": "2026-07-30 17:36:00",
"creator": [],
"updater": [],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
"... (총 7건 중 2건 표시)"
],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.read)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 관리자가 클레임(반품/교환/환불) 사유 마스터 목록을 조회합니다. permission:sirsoft-ecommerce.settings.read 권한이 필요하며, type(기본 refund)·is_active·fault_type·search 쿼리로 필터링할 수 있습니다. ClaimReasonService::getAllReasons()가 조회하고 ClaimReasonCollection으로 반환하며, 각 항목은 다국어 사유명(name)과 귀책 구분(fault_type: customer·seller·carrier), 사용자 노출 여부(is_user_selectable)를 포함합니다. 환경설정의 클레임 사유 관리 화면에서 사용됩니다.
POST /api/modules/sirsoft-ecommerce/admin/claim-reasons
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.store - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@store - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| type | body | string | 예 | — | 클레임 사유 유형 (ClaimReasonTypeEnum — 현재 refund(환불/취소)) |
| code | body | string | 예 | max 50 | 사유 식별 코드 (영문 소문자/숫자/_, 같은 type 내에서 고유) |
| name | body | array | 예 | — | 대상의 이름/명칭 |
| fault_type | body | string | 예 | — | 귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| is_user_selectable | body | boolean | 아니오 | — | user selectable 여부 |
| is_active | body | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
| sort_order | body | integer | 아니오 | min 0 | 표시 정렬 순서 값 (작을수록 우선) |
요청 예시
POST /api/modules/sirsoft-ecommerce/admin/claim-reasons HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"type": "예시값",
"code": "예시값",
"name": [
"예시 이름"
],
"fault_type": "예시값",
"is_user_selectable": true,
"is_active": true,
"sort_order": 1
}
응답 필드 (data 내부)
단건 응답: data 객체의 필드 (ClaimReasonResource).
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 8 |
생성된 클래임 사유의 기본 키 (내부 식별자) |
| type | string | refund |
클래임 사유 유형 (ClaimReasonTypeEnum — refund(환불/취소)) |
| code | string | apidoc_sample |
사유 식별 코드 (같은 type 내 고유) |
| name | object | {"ko":"API 문서 샘플 사유","en":"API Doc Sample Reason"} |
다국어 사유명 (로케일별 값 객체) |
| localized_name | string | API 문서 샘플 사유 |
name 의 현재 로케일 해석 값 |
| fault_type | string | customer |
귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| fault_type_label | string | 고객 귀책 |
fault_type 값의 사람이 읽는 라벨 (Enum label 파생) |
| is_user_selectable | boolean | true |
회원 취소/반품 신청 화면에서 선택지로 노출할지 여부 |
| is_active | boolean | true |
활성 여부 (false 면 선택지에서 제외) |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-08 10:44:49 |
생성 일시 |
| updated_at | string | 2026-07-08 10:44:49 |
최종 수정 일시 |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (sirsoft-ecommerce.settings.update 권한 기반) |
응답 예시
HTTP/1.1 201
{
"success": true,
"message": "클래임 사유가 등록되었습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유",
"en": "API Doc Sample Reason"
},
"localized_name": "API 문서 샘플 사유",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 10:44:49",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지). 같은 type 내에 동일한 code 가 이미 존재하면 code 필드 검증 실패 |
설명 관리자가 새 클레임 사유를 생성합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하며, 유형(type)·고유 코드(code)·다국어 사유명(name)·귀책 구분(fault_type)을 필수로 받고 사용자 노출 여부·활성 여부·정렬 순서를 선택 입력합니다. ClaimReasonService::createReason()이 저장하고 생성된 사유를 201로 반환합니다. code 는 유형 내에서 고유해야 하며 회원 취소/반품 화면의 사유 선택지로 활용됩니다.
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/active
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.active - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@active - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| type | query | string | 아니오 | — | 유형 필터 (해당 유형의 항목만 조회) |
요청 예시
DELETE /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| reason_id | integer | 8 |
reason 식별자 (연관 리소스 참조) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클래임 사유가 삭제되었습니다.",
"data": {
"reason_id": 8
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 클래임 사유 1건을 삭제합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하며, 대상이 없으면 404 를 반환하고 존재하면 ClaimReasonService::deleteReason()이 삭제합니다. 이미 사용 중인 사유 등 삭제 불가 상황에서는 그 사유에 대응하는 안내 문구를 400 으로 응답합니다 (예외 메시지 원문이 아니라 전용 다국어 키를 사용). 그 밖의 서버 내부 오류는 500 으로 구분됩니다.
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.show - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@show - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 8 |
기본 키 (내부 식별자) |
| type | string | refund |
사유 유형 (refund, exchange, return 등) |
| code | string | apidoc_sample |
고유 코드 (order_mistake 등) |
| name | object | {"ko":"API 문서 샘플 사유","en":"API Doc Sample Reason"} |
대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| localized_name | string | API 문서 샘플 사유 |
name 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
| fault_type | string | customer |
귀책 구분 (customer, seller, carrier) |
| fault_type_label | string | 고객 귀책 |
fault_type 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_user_selectable | boolean | true |
user selectable 여부 |
| is_active | boolean | true |
active 여부 |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-08 10:44:49 |
생성 일시 |
| updated_at | string | 2026-07-08 10:44:49 |
최종 수정 일시 |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클래임 사유 정보를 조회했습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유",
"en": "API Doc Sample Reason"
},
"localized_name": "API 문서 샘플 사유",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 10:44:49",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.read)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 클래임 사유 1건의 상세 정보를 조회합니다. permission:sirsoft-ecommerce.settings.read 권한이 필요하며, ClaimReasonService::getReason()이 대상을 조회해 ClaimReasonResource로 반환합니다. 사유 편집 폼을 열 때 기존 값(다국어 사유명·코드·귀책 구분·활성/노출 설정 등)을 채우는 용도로 사용되며, 해당 사유가 없으면 404 를 반환합니다.
PUT /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.update - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@update - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| type | body | string | 예 | — | 클래임 사유 유형 (ClaimReasonTypeEnum — 현재 refund(환불/취소)) |
| code | body | string | 예 | max 50 | 사유 식별 코드 (영문 소문자/숫자/_, 같은 type 내에서 고유) |
| name | body | array | 예 | — | 대상의 이름/명칭 |
| fault_type | body | string | 예 | — | 귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| is_user_selectable | body | boolean | 아니오 | — | user selectable 여부 |
| is_active | body | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
| sort_order | body | integer | 아니오 | min 0 | 표시 정렬 순서 값 (작을수록 우선) |
요청 예시
PUT /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"type": "예시값",
"code": "예시값",
"name": [
"예시 이름"
],
"fault_type": "예시값",
"is_user_selectable": true,
"is_active": true,
"sort_order": 1
}
응답 필드 (data 내부)
단건 응답: data 객체의 필드 (ClaimReasonResource).
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 8 |
수정된 클래임 사유의 기본 키 (내부 식별자) |
| type | string | refund |
클래임 사유 유형 (ClaimReasonTypeEnum — refund(환불/취소)) |
| code | string | apidoc_sample |
사유 식별 코드 (같은 type 내 고유) |
| name | object | {"ko":"API 문서 샘플 사유(수정)","en":"API Doc Sample Reason (Updated)"} |
다국어 사유명 (로케일별 값 객체) |
| localized_name | string | API 문서 샘플 사유(수정) |
name 의 현재 로케일 해석 값 |
| fault_type | string | seller |
귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| fault_type_label | string | 판매자 귀책 |
fault_type 값의 사람이 읽는 라벨 (Enum label 파생) |
| is_user_selectable | boolean | true |
회원 취소/반품 신청 화면에서 선택지로 노출할지 여부 |
| is_active | boolean | true |
활성 여부 (false 면 선택지에서 제외) |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-08 10:44:49 |
생성 일시 |
| updated_at | string | 2026-07-08 15:00:18 |
최종 수정 일시 |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (sirsoft-ecommerce.settings.update 권한 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클래임 사유가 수정되었습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유(수정)",
"en": "API Doc Sample Reason (Updated)"
},
"localized_name": "API 문서 샘플 사유(수정)",
"fault_type": "seller",
"fault_type_label": "판매자 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 15:00:18",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 400 | Bad Request | 대상 사유가 없거나 갱신에 실패한 경우 (서비스 예외 → exceptions.operation_failed) |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지). 같은 type 내 다른 사유가 동일한 code 를 이미 사용 중이면 code 필드 검증 실패 |
| 500 | Internal Server Error | 서버 내부 오류 — 도메인 규칙 위반이 아닌 예외(인프라 장애·코드 결함)는 4xx 로 뭉개지 않고 500 으로 구분한다 |
설명 관리자가 기존 클래임 사유를 수정합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하고 대상은 경로 id 로 지정하며, 생성과 동일한 필드(유형·코드·다국어 사유명·귀책 구분·노출/활성/정렬)를 받아 ClaimReasonService::updateReason()이 갱신하고 갱신된 사유를 반환합니다. 대상이 없거나 갱신 실패 시 400 오류로 응답합니다.
PATCH /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}/toggle-status
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.toggle-status - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@toggleStatus - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
PATCH /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}/toggle-status HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| id | integer | 8 |
기본 키 (내부 식별자) |
| type | string | refund |
사유 유형 (refund, exchange, return 등) |
| code | string | apidoc_sample |
고유 코드 (order_mistake 등) |
| name | object | {"ko":"API 문서 샘플 사유","en":"API Doc Sample Reason"} |
대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| localized_name | string | API 문서 샘플 사유 |
name 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
| fault_type | string | customer |
귀책 구분 (customer, seller, carrier) |
| fault_type_label | string | 고객 귀책 |
fault_type 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_user_selectable | boolean | true |
user selectable 여부 |
| is_active | boolean | false |
active 여부 |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-08 10:44:49 |
생성 일시 |
| updated_at | string | 2026-07-08 15:00:18 |
최종 수정 일시 |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클래임 사유 상태가 변경되었습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유",
"en": "API Doc Sample Reason"
},
"localized_name": "API 문서 샘플 사유",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": false,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 15:00:18",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
| 500 | Internal Server Error | 서버 내부 오류 — 도메인 규칙 위반이 아닌 예외(인프라 장애·코드 결함)는 4xx 로 뭉개지 않고 500 으로 구분한다 |
설명 관리자가 클래임 사유의 활성 상태를 켜고 끄는 토글을 수행합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하며, ClaimReasonService::toggleStatus()가 대상 사유의 is_active 값을 반전시켜 저장하고 갱신된 사유를 반환합니다. 사유를 삭제하지 않고 일시적으로 회원 선택지에서 감추거나 다시 노출할 때 사용합니다.
GET /api/modules/sirsoft-ecommerce/user/claim-reasons
- 라우트명:
api.modules.sirsoft-ecommerce.user.claim-reasons.index - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@userSelectableReasons - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:sirsoft-ecommerce.user-orders.cancel
요청 파라미터
요청 파라미터 없음.
요청 예시
GET /api/modules/sirsoft-ecommerce/user/claim-reasons HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
목록 응답: data.data[] 배열 항목의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| number | integer | 7 |
목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
| id | integer | 1 |
기본 키 (내부 식별자) |
| type | string | refund |
클레임 사유 유형 (ClaimReasonTypeEnum — refund(환불/취소)) |
| code | string | order_mistake |
사유 식별 코드 (같은 type 내 고유, 영문 소문자/숫자/_) |
| name | object | {"ko":"주문 실수","en":"Order Mistake"} |
대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| localized_name | string | 주문 실수 |
name 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
| fault_type | string | customer |
귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| fault_type_label | string | 고객 귀책 |
fault_type 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_user_selectable | boolean | true |
user selectable 여부 |
| is_active | boolean | true |
active 여부 |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-30 17:36:00 |
생성 일시 |
| updated_at | string | 2026-07-30 17:36:00 |
최종 수정 일시 |
| creator | array | [] |
생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
| updater | array | [] |
최종 수정자 정보 객체 (id/name — updater 관계 로드 시) |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유 목록을 조회했습니다.",
"data": {
"data": [
{
"number": 7,
"id": 1,
"type": "refund",
"code": "order_mistake",
"name": {
"ko": "주문 실수",
"en": "Order Mistake"
},
"localized_name": "주문 실수",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-30 17:36:00",
"updated_at": "2026-07-30 17:36:00",
"creator": [],
"updater": [],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
{
"number": 6,
"id": 2,
"type": "refund",
"code": "changed_mind",
"name": {
"ko": "단순 변심",
"en": "Changed Mind"
},
"localized_name": "단순 변심",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 1,
"created_at": "2026-07-30 17:36:00",
"updated_at": "2026-07-30 17:36:00",
"creator": [],
"updater": [],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
"... (총 7건 중 2건 표시)"
],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.read)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 활성화된 클레임 사유만 추려 Select 옵션용으로 조회합니다. permission:sirsoft-ecommerce.settings.read 권한이 필요하며, type 쿼리(기본 refund)로 유형을 지정하면 ClaimReasonService::getActiveReasons()가 is_active=true 인 사유만 반환합니다. 관리자 화면에서 환불/취소 처리 시 사유 드롭다운을 채우는 용도로, 목록(index)과 달리 필터 없이 활성 사유만 내려주는 점이 다릅니다.
DELETE /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.destroy - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@destroy - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
DELETE /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: 삭제 결과 요약 (data 객체).
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| reason_id | integer | 8 |
삭제된 클레임 사유의 기본 키 |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유가 삭제되었습니다.",
"data": {
"reason_id": 8
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
| 500 | Internal Server Error | 서버 내부 오류 — 도메인 규칙 위반이 아닌 예외(인프라 장애·코드 결함)는 4xx 로 뭉개지 않고 500 으로 구분한다 |
설명 관리자가 클레임 사유 1건을 삭제합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하며, 대상이 없으면 404 를 반환하고 존재하면 ClaimReasonService::deleteReason()이 삭제합니다. 이미 사용 중인 사유 등 삭제 불가 상황에서는 그 사유에 대응하는 안내 문구를 400 으로 응답합니다 (예외 메시지 원문이 아니라 전용 다국어 키를 사용). 그 밖의 서버 내부 오류는 500 으로 구분됩니다.
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.show - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@show - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.read
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
GET /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드 (ClaimReasonResource). 필드 구성은 이 문서의 POST /api/modules/sirsoft-ecommerce/admin/claim-reasons (클레임 사유 생성) 응답 필드 표와 동일합니다.
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유 정보를 조회했습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유",
"en": "API Doc Sample Reason"
},
"localized_name": "API 문서 샘플 사유",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 10:44:49",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.read)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
설명 관리자가 클레임 사유 1건의 상세 정보를 조회합니다. permission:sirsoft-ecommerce.settings.read 권한이 필요하며, ClaimReasonService::getReason()이 대상을 조회해 ClaimReasonResource로 반환합니다. 사유 편집 폼을 열 때 기존 값(다국어 사유명·코드·귀책 구분·활성/노출 설정 등)을 채우는 용도로 사용되며, 해당 사유가 없으면 404 를 반환합니다.
PUT /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.update - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@update - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
| type | body | string | 예 | — | 클레임 사유 유형 (ClaimReasonTypeEnum — 현재 refund(환불/취소)) |
| code | body | string | 예 | max 50 | 사유 식별 코드 (영문 소문자/숫자/_, 같은 type 내에서 고유) |
| name | body | array | 예 | — | 대상의 이름/명칭 |
| fault_type | body | string | 예 | — | 귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| is_user_selectable | body | boolean | 아니오 | — | user selectable 여부 |
| is_active | body | boolean | 아니오 | — | 활성 여부 (true 활성 / false 비활성) |
| sort_order | body | integer | 아니오 | min 0 | 표시 정렬 순서 값 (작을수록 우선) |
요청 예시
PUT /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"type": "예시값",
"code": "예시값",
"name": [
"예시 이름"
],
"fault_type": "예시값",
"is_user_selectable": true,
"is_active": true,
"sort_order": 1
}
응답 필드 (data 내부)
단건 응답: data 객체의 필드 (ClaimReasonResource). 필드 구성은 이 문서의 POST /api/modules/sirsoft-ecommerce/admin/claim-reasons (클레임 사유 생성) 응답 필드 표와 동일합니다.
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유가 수정되었습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유",
"en": "API Doc Sample Reason"
},
"localized_name": "API 문서 샘플 사유",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 10:44:49",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
| 500 | Internal Server Error | 서버 내부 오류 — 도메인 규칙 위반이 아닌 예외(인프라 장애·코드 결함)는 4xx 로 뭉개지 않고 500 으로 구분한다 |
설명 관리자가 기존 클레임 사유를 수정합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하고 대상은 경로 id 로 지정하며, 생성과 동일한 필드(유형·코드·다국어 사유명·귀책 구분·노출/활성/정렬)를 받아 ClaimReasonService::updateReason()이 갱신하고 갱신된 사유를 반환합니다. 대상이 없거나 갱신 실패 시 400 오류로 응답합니다.
PATCH /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}/toggle-status
- 라우트명:
api.modules.sirsoft-ecommerce.admin.claim-reasons.toggle-status - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@toggleStatus - 인증/권한:
auth:sanctum+permission:sirsoft-ecommerce.settings.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| id | path | string | 예 | — | 대상 리소스의 식별자 |
요청 예시
PATCH /api/modules/sirsoft-ecommerce/admin/claim-reasons/{id}/toggle-status HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
응답 필드 (data 내부)
단건 응답: data 객체의 필드 (ClaimReasonResource). 필드 구성은 이 문서의 POST /api/modules/sirsoft-ecommerce/admin/claim-reasons (클레임 사유 생성) 응답 필드 표와 동일합니다. is_active 가 반전된 상태로 반환됩니다.
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유 상태가 변경되었습니다.",
"data": {
"id": 8,
"type": "refund",
"code": "apidoc_sample",
"name": {
"ko": "API 문서 샘플 사유",
"en": "API Doc Sample Reason"
},
"localized_name": "API 문서 샘플 사유",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-08 10:44:49",
"updated_at": "2026-07-08 10:44:49",
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.settings.update)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
| 500 | Internal Server Error | 서버 내부 오류 — 도메인 규칙 위반이 아닌 예외(인프라 장애·코드 결함)는 4xx 로 뭉개지 않고 500 으로 구분한다 |
설명 관리자가 클레임 사유의 활성 상태를 켜고 끄는 토글을 수행합니다. permission:sirsoft-ecommerce.settings.update 권한이 필요하며, ClaimReasonService::toggleStatus()가 대상 사유의 is_active 값을 반전시켜 저장하고 갱신된 사유를 반환합니다. 사유를 삭제하지 않고 일시적으로 회원 선택지에서 감추거나 다시 노출할 때 사용합니다.
GET /api/modules/sirsoft-ecommerce/user/claim-reasons
- 라우트명:
api.modules.sirsoft-ecommerce.user.claim-reasons.index - 컨트롤러:
Modules\Sirsoft\Ecommerce\Http\Controllers\Admin\ClaimReasonController@userSelectableReasons - 인증/권한:
optional.sanctum(선택적 인증: 회원/비회원 모두 접근) +permission:sirsoft-ecommerce.user-orders.cancel
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| type | query | string | 아니오 | — | 유형 필터 (해당 유형의 항목만 조회) |
요청 예시
GET /api/modules/sirsoft-ecommerce/user/claim-reasons?type=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
응답 필드 (data 내부)
목록 응답: data.data[] 배열 항목의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| number | integer | 6 |
목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
| id | integer | 1 |
기본 키 (내부 식별자) |
| type | string | refund |
클레임 사유 유형 (ClaimReasonTypeEnum — refund(환불/취소)) |
| code | string | order_mistake |
사유 식별 코드 (같은 type 내 고유, 영문 소문자/숫자/_) |
| name | object | {"ko":"주문 실수","en":"Order Mistake"} |
대상의 이름/명칭 (다국어 필드는 로케일별 값 객체) |
| localized_name | string | 주문 실수 |
name 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석) |
| fault_type | string | customer |
귀책 구분 (ClaimReasonFaultTypeEnum — customer(고객)/seller(판매자)/carrier(배송사)) |
| fault_type_label | string | 고객 귀책 |
fault_type 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
| is_user_selectable | boolean | true |
user selectable 여부 |
| is_active | boolean | true |
active 여부 |
| sort_order | integer | 0 |
표시 정렬 순서 값 (작을수록 우선) |
| created_at | string | 2026-07-30 17:36:00 |
생성 일시 |
| updated_at | string | 2026-07-30 17:36:00 |
최종 수정 일시 |
| creator | array | [] |
생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
| updater | array | [] |
최종 수정자 정보 객체 (id/name — updater 관계 로드 시) |
| abilities | object | {"can_create":true,"can_update":true,"can_delete":true} |
현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
응답 예시
HTTP/1.1 200
{
"success": true,
"message": "클레임 사유 목록을 조회했습니다.",
"data": {
"data": [
{
"number": 6,
"id": 1,
"type": "refund",
"code": "order_mistake",
"name": {
"ko": "주문 실수",
"en": "Order Mistake"
},
"localized_name": "주문 실수",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 0,
"created_at": "2026-07-30 17:36:00",
"updated_at": "2026-07-30 17:36:00",
"creator": [],
"updater": [],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
{
"number": 5,
"id": 2,
"type": "refund",
"code": "changed_mind",
"name": {
"ko": "단순 변심",
"en": "Changed Mind"
},
"localized_name": "단순 변심",
"fault_type": "customer",
"fault_type_label": "고객 귀책",
"is_user_selectable": true,
"is_active": true,
"sort_order": 1,
"created_at": "2026-07-30 17:36:00",
"updated_at": "2026-07-30 17:36:00",
"creator": [],
"updater": [],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
"... (총 6건 중 2건 표시)"
],
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 403 | Forbidden | 요구 권한(sirsoft-ecommerce.user-orders.cancel)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 회원(및 선택적으로 비회원)이 주문 취소/반품 신청 화면에서 선택할 수 있는 클레임 사유 목록을 조회합니다. optional.sanctum(회원/비회원 모두 접근)과 permission:sirsoft-ecommerce.user-orders.cancel 권한이 적용되며, ClaimReasonService::getUserSelectableReasons()가 활성이면서 is_user_selectable=true 인 사유만 반환합니다. 관리 전용 목록과 달리 사용자에게 공개 가능한 사유만 내려주는 사용자향 엔드포인트입니다.