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

Mileage API 레퍼런스

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

---

TL;DR (5초 요약)

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

---

GET /api/modules/sirsoft-ecommerce/user/mileage

• 라우트명: api.modules.sirsoft-ecommerce.user.mileage.balance
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\UserMileageController@balance
• 인증/권한: auth:sanctum

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/modules/sirsoft-ecommerce/user/mileage HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드	타입	실측 예시값	용도/설명
mileage	object	{"enabled":false,"available":102200,"pending":0,"expiring…	마일리지 잔액 요약 객체 (enabled 기능 활성화 여부, available 사용 가능, pending 적립 대기, expiring_soon/expiring_date 소멸 예정, total_earned/total_used 누적 적립·사용, by_currency 통화별 잔액)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "마일리지 잔액을 조회했습니다.",
    "data": {
        "mileage": {
            "enabled": false,
            "available": 102200,
            "pending": 0,
            "expiring_soon": 0,
            "expiring_date": null,
            "total_earned": 110000,
            "total_used": 7800,
            "by_currency": {
                "KRW": {
                    "available": 102200,
                    "pending": 0,
                    "total_earned": 110000,
                    "total_used": 7800,
                    "expiring_soon": 0,
                    "expiring_date": null
                }
            }
        }
    }
}

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우

설명 로그인한 회원이 마이페이지에서 자신의 마일리지 잔액 요약을 조회합니다. auth:sanctum 인증만 필요하며, UserMileageService::getBalance()가 마일리지 기능 활성화 여부, 사용 가능(available)·적립 대기(pending)·소멸 예정 금액을 계산해 mileage 객체로 반환합니다. 마일리지 기능이 꺼져 있으면 enabled: false 와 0값이 내려오므로 화면에서 잔액 위젯 노출 여부를 이 플래그로 판단할 수 있습니다.

GET /api/modules/sirsoft-ecommerce/user/mileage/history

• 라우트명: api.modules.sirsoft-ecommerce.user.mileage.history
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\UserMileageController@history
• 인증/권한: auth:sanctum

요청 파라미터

이름	위치	타입	필수	허용값	용도
category	query	string	아니오	earn, use, expire, adjust	분류 필터 (해당 분류의 항목만 조회)
currency	query	string	아니오	max 10	통화 코드 필터 (해당 통화의 마일리지 거래만 조회)
per_page	query	integer	아니오	min 1, max 100	페이지당 항목 수

요청 예시

GET /api/modules/sirsoft-ecommerce/user/mileage/history?category=earn&currency=%EC%98%88%EC%8B%9C%EA%B0%92&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드	타입	실측 예시값	용도/설명
transactions	object	{"data":[{"number":21,"id":830,"user_id":1209,"currency":…	마일리지 거래 내역 페이지네이션 객체 (data 거래 항목 배열 + 페이지 메타, MileageTransactionCollection 으로 직렬화)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "마일리지 내역을 조회했습니다.",
    "data": {
        "transactions": {
            "data": [
                {
                    "number": 21,
                    "id": 830,
                    "user_id": 1209,
                    "currency": "KRW",
                    "type": "admin_deduct",
                    "...": "(34개 키 생략, 총 39개)"
                },
                {
                    "number": 20,
                    "id": 829,
                    "user_id": 1209,
                    "currency": "KRW",
                    "type": "admin_deduct",
                    "...": "(34개 키 생략, 총 39개)"
                },
                {
                    "number": 19,
                    "id": 828,
                    "user_id": 1209,
                    "currency": "KRW",
                    "type": "admin_deduct",
                    "...": "(34개 키 생략, 총 39개)"
                },
                {
                    "number": 18,
                    "id": 827,
                    "user_id": 1209,
                    "currency": "KRW",
                    "type": "admin_deduct",
                    "...": "(34개 키 생략, 총 39개)"
                },
                {
                    "number": 17,
                    "id": 826,
                    "user_id": 1209,
                    "currency": "KRW",
                    "type": "admin_deduct",
                    "...": "(34개 키 생략, 총 39개)"
                },
                "... (총 21건 중 5건 표시)"
            ],
            "abilities": {
                "can_manage": true
            },
            "currencies": [],
            "pagination": {
                "current_page": 1,
                "last_page": 1,
                "per_page": 25,
                "total": 21,
                "from": 1,
                "...": "(2개 키 생략, 총 7개)"
            }
        }
    }
}

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명 로그인한 회원이 마이페이지에서 자신의 마일리지 적립/사용 내역을 페이지네이션으로 조회합니다. category(earn·use·expire·adjust) 4분류 필터와 currency·per_page(최대 100)를 지원하며, UserMileageService::paginateUserHistory()가 필터를 적용해 조회한 뒤 MileageTransactionCollection으로 직렬화해 transactions 에 담습니다. category 는 원장의 원시 type 이 아니라 사용자 표시용 4분류로 매핑된 값입니다.

GET /api/modules/sirsoft-ecommerce/user/mileage/max-usable

• 라우트명: api.modules.sirsoft-ecommerce.user.mileage.max-usable
• 컨트롤러: Modules\Sirsoft\Ecommerce\Http\Controllers\User\UserMileageController@maxUsable
• 인증/권한: auth:sanctum

요청 파라미터

이름	위치	타입	필수	허용값	용도
order_amount	query	integer	예	min 0	사용 가능 상한 계산 기준 주문금액 (마일리지 사용액은 이 금액을 넘을 수 없음)

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

요청 예시

GET /api/modules/sirsoft-ecommerce/user/mileage/max-usable?order_amount=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드	타입	실측 예시값	용도/설명
max_usable	integer	1000	해당 주문금액(order_amount)에 사용 가능한 최대 마일리지. 보유 잔액·최대 사용 한도(percent/fixed)·주문금액 상한 중 최솟값을 취한 뒤 사용 단위(use_unit)로 내림 보정한 값 (기본 통화 사용 규칙 미설정 시 0)
available	integer	12910	현재 사용 가능한 마일리지 잔액 (getBalance() 의 available 값과 동일)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "사용 가능한 최대 마일리지를 조회했습니다.",
    "data": {
        "max_usable": 1000,
        "available": 12910
    }
}

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우
422	Unprocessable Entity	요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명 체크아웃 화면에서 특정 주문금액(order_amount)에 실제로 사용 가능한 최대 마일리지를 계산해 반환합니다. auth:sanctum 인증이 필요하고 order_amount 는 필수이며, UserMileageService::getMaxUsable()가 보유 잔액·최소 사용 정책·주문금액 상한을 종합해 사용 가능 상한을 산출하고 현재 잔액(available)도 함께 내려줍니다. 확장은 sirsoft-ecommerce.mileage.max_usable_validation_rules 필터로 검증 파라미터를 추가할 수 있습니다.