gper/Gnuboard7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
403154167a25e8b14e3fb7e565d9488eef336303
Gnuboard7/modules/_bundled/sirsoft-ecommerce/docs/api/coupons.md
T
HeuJung 403154167a fix(core): api:docgen 재생성이 문서를 손실·열화시키는 결함 수정 
재생성이 사람이 채운 서술과 이전 실측 결과를 지우고, 코드가 바뀌지 않은
문서까지 매 실행마다 흔들던 결함 5건을 고쳤다.

- 중첩 객체 파라미터가 문서에서 통째로 누락되던 문제: 배열 요소(items.*.id)를
 상위로 대표시키려던 스킵 조건이 점(.) 포함 여부만 봐서, 와일드카드가 없는
 중첩 객체 필드(refund_bank.*, general.*, content.* 등 17개 엔드포인트 수백 개)
 까지 함께 버렸다. 와일드카드가 있을 때만 스킵하도록 좁혔다.
- 사람이 보강한 에러 응답 표가 자동 추론 초안에 덮여 사라지던 문제:
 상태코드 키 단위로 병합한다.
- 실측 실패가 이전에 관측해 둔 응답 예시를 지우던 문제: 실측 성패는 호출 시점
 데이터 유무에 좌우되므로(DELETE /checkout 은 대상이 없으면 404), 실패는
 "새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다.
- 실측 예시값·응답 예시 JSON 이 DB 상태를 그대로 반영해 비멱등하던 문제:
 값이 아니라 스펙(필드 집합·타입)이 바뀐 경우에만 갱신한다. nullable 이
 null 로 관측된 것은 타입 변경이 아니므로 기존 값을 유지한다.
- 요청 예시 path 파라미터가 실측 성패에 따라 흔들리던 문제: placeholder 로 고정.

결과: 문서 63개 전수 대조에서 손실 0(서술·표 셀·응답 예시), 전 scope 연속
재생성 시 diff 0(멱등).
2026-08-06 13:54:35 +09:00

24 KiB
Raw Blame History

Coupons API 레퍼런스

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

TL;DR (5초 요약)

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

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

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

요청 파라미터

이름 위치 타입 필수 허용값 용도
status query string 아니오 available, used, expired 상태 필터 (해당 상태의 항목만 조회)
per_page query integer 아니오 min 1, max 50 페이지당 항목 수

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

요청 예시

GET /api/modules/sirsoft-ecommerce/user/coupons?status=available&per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드 타입 실측 예시값 용도/설명
coupons object {"data":[{"id":2512,"coupon_id":107,"user_id":"a26219fc-9… 회원이 발급받은 쿠폰(발급 내역) 페이지네이션 객체 (data[] 발급 건 + pagination — CouponIssueCollection 직렬화, 쿠폰 정의가 아닌 회원별 발급 건)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "쿠폰 목록을 조회했습니다.",
    "data": {
        "coupons": {
            "data": [
                {
                    "id": 2512,
                    "coupon_id": 107,
                    "user_id": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
                    "coupon_code": "DL-ORG8PPAH",
                    "status": "used",
                    "...": "(12개 키 생략, 총 17개)"
                },
                {
                    "id": 2513,
                    "coupon_id": 61,
                    "user_id": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
                    "coupon_code": "DR-WC3RLEDB",
                    "status": "used",
                    "...": "(12개 키 생략, 총 17개)"
                },
                {
                    "id": 2514,
                    "coupon_id": 62,
                    "user_id": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
                    "coupon_code": "DR-VHQFNYRR",
                    "status": "used",
                    "...": "(12개 키 생략, 총 17개)"
                },
                {
                    "id": 2515,
                    "coupon_id": 63,
                    "user_id": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
                    "coupon_code": "DR-4QRXNXAI",
                    "status": "used",
                    "...": "(12개 키 생략, 총 17개)"
                },
                {
                    "id": 2516,
                    "coupon_id": 64,
                    "user_id": "a26219fc-94a0-4f63-9404-04c2a6ac99e4",
                    "coupon_code": "DR-IT4CCTSM",
                    "status": "used",
                    "...": "(12개 키 생략, 총 17개)"
                },
                "... (총 25건 중 5건 표시)"
            ],
            "pagination": {
                "current_page": 1,
                "last_page": 2,
                "per_page": 25,
                "total": 41,
                "from": 1,
                "...": "(2개 키 생략, 총 7개)"
            }
        }
    }
}

에러 응답

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

설명 로그인한 회원이 마이페이지 쿠폰함에서 자신이 발급받은 쿠폰(발급 내역)을 페이지네이션으로 조회합니다. auth:sanctum 인증이 필요하며, status 필터(available·used·expired)로 사용 가능/사용 완료/만료 쿠폰을 구분합니다. UserCouponService::getUserCoupons()가 조회하고 CouponIssueCollection으로 직렬화되므로, 여기의 항목은 쿠폰 정의(마스터)가 아니라 회원별 발급 건입니다.

GET /api/modules/sirsoft-ecommerce/user/coupons/available

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

요청 파라미터

이름 위치 타입 필수 허용값 용도
product_ids query array 아니오 — product 식별자 배열

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

요청 예시

GET /api/modules/sirsoft-ecommerce/user/coupons/available?product_ids=%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 객체의 필드.

필드 타입 실측 예시값 용도/설명
coupons array [{"id":2534,"coupon_id":85,"user_id":1209,"coupon_code":"… 현재 장바구니 상품에 적용 가능한 보유 쿠폰(발급 건) 배열 (상품/카테고리 범위·최소 주문금액·유효기간을 만족해 주문에 곧바로 선택 가능한 후보만)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "사용 가능한 쿠폰 목록을 조회했습니다.",
    "data": {
        "coupons": [
            {
                "id": 2534,
                "coupon_id": 85,
                "user_id": 1209,
                "coupon_code": "DR-PDZ7HT4G",
                "status": "available",
                "...": "(8개 키 생략, 총 13개)"
            },
            {
                "id": 2542,
                "coupon_id": 94,
                "user_id": 1209,
                "coupon_code": "DR-ROQPOOED",
                "status": "available",
                "...": "(8개 키 생략, 총 13개)"
            },
            {
                "id": 2552,
                "coupon_id": 106,
                "user_id": 1209,
                "coupon_code": "DR-XBLQUABC",
                "status": "available",
                "...": "(8개 키 생략, 총 13개)"
            },
            {
                "id": 2529,
                "coupon_id": 79,
                "user_id": 1209,
                "coupon_code": "DR-90IO2SWI",
                "status": "available",
                "...": "(8개 키 생략, 총 13개)"
            },
            {
                "id": 2532,
                "coupon_id": 83,
                "user_id": 1209,
                "coupon_code": "DR-FEKYVAFT",
                "status": "available",
                "...": "(8개 키 생략, 총 13개)"
            },
            "... (총 27건 중 5건 표시)"
        ]
    }
}

에러 응답

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

설명 체크아웃 화면에서 회원이 현재 장바구니 상품에 실제로 적용할 수 있는 보유 쿠폰만 추려서 반환합니다. auth:sanctum 인증이 필요하고 product_ids 로 대상 상품을 전달하면, UserCouponService::getAvailableCoupons()가 보유 쿠폰 중 상품/카테고리 적용 범위·최소 주문금액·유효기간 등을 만족하는 것만 필터링해 내려줍니다. 쿠폰함 목록(index)과 달리 주문에 곧바로 선택 가능한 후보만 반환하는 점이 다릅니다.

GET /api/modules/sirsoft-ecommerce/user/coupons/downloadable

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

요청 파라미터

이름 위치 타입 필수 허용값 용도
per_page query integer 아니오 min 1, max 50 페이지당 항목 수

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

요청 예시

GET /api/modules/sirsoft-ecommerce/user/coupons/downloadable?per_page=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

목록 응답: data.data[] 배열 항목의 필드.

필드 타입 실측 예시값 용도/설명
id integer 107 기본 키 (내부 식별자)
name object {"ko":"카테고리 배송비 3,000원 할인","en":"Category Shipping 3,000 … 대상의 이름/명칭 (다국어 필드는 로케일별 값 객체)
description object {"ko":"특정 카테고리 배송비 할인","en":"Shipping discount on categor… 설명 (다국어 필드는 로케일별 값 객체)
target_type string shipping_fee 할인 적용 대상 (product_amount=상품금액, order_amount=주문금액, shipping_fee=배송비)
discount_type string fixed 혜택 유형 (fixed=정액 할인, rate=정률(%) 할인)
discount_value string 3000.00 혜택값 (정액이면 할인 금액, 정률이면 할인율 %)
discount_max_amount string 3000.00 정률 할인 시 최대 할인 금액 상한 (없으면 null)
min_order_amount string 20000.00 쿠폰 적용 최소 주문금액 (미만 주문에는 사용 불가)
issue_method string download 발급 방법 (direct=직접발급, download=다운로드, auto=자동발급)
issue_condition string manual 발급 조건 (manual=수동, signup=회원가입, first_purchase=첫구매, birthday=생일)
issue_status string issuing 발급 상태 (issuing=발급중, stopped=발급중단)
total_quantity integer 300 총 발급 수량 상한 (null=무제한)
issued_count integer 1 issued 개수 (집계)
per_user_limit integer 1 회원 1인당 발급 제한 수량
valid_type string period 유효기간 유형 (period=기간지정, days_from_issue=발급일로부터 N일)
valid_days integer 14 발급일로부터 유효한 일수 (valid_type=days_from_issue 인 경우)
valid_from string 2026-07-23T14:36:17.000000Z 유효기간 시작일 (쿠폰 사용 가능 시작 시각)
valid_to string 2026-09-21T14:36:17.000000Z 유효기간 종료일 (쿠폰 사용 가능 종료 시각)
issue_from string 2026-07-23T14:36:17.000000Z 발급기간 시작일 (다운로드 가능 시작 시각)
issue_to string 2026-08-29T14:36:17.000000Z 발급기간 종료일 (다운로드 가능 종료 시각)
is_combinable boolean true combinable 여부
target_scope string categories 적용 범위 (all=전체 상품, products=특정 상품, categories=특정 카테고리)
created_by null null 쿠폰 등록자(관리자) 식별자 (users 참조, 삭제 시 null)
created_at string 2026-07-30T14:36:17.000000Z 생성 일시
updated_at string 2026-07-31T12:51:54.000000Z 최종 수정 일시
deleted_at null null 소프트 삭제 일시 (미삭제 시 null)
is_downloaded boolean true downloaded 여부
user_issued_count integer 1 user issued 개수 (집계)
coupon_id integer 107 coupon 식별자 (연관 리소스 참조)
localized_name string 카테고리 배송비 3,000원 할인 name 의 현재 로케일 해석 값 (다국어 필드를 표시용 문자열로 해석)
target_type_short_label string 배송비 target_type_short 값의 사람이 읽는 라벨 (현지화/Enum 파생)
valid_period_formatted string 2026-07-23 ~ 2026-09-21 valid_period 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷)
min_order_amount_formatted string ¥20,000 min_order_amount 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷)
remaining_quantity integer 299 잔여 발급 가능 수량 (total_quantity − issued_count, 무제한이면 null)
benefit_formatted string ¥3,000 할인 benefit 값의 표시용 포맷 문자열 (통화/용량/일시 등 로케일·단위 포맷)
included_products array [] 적용 대상 포함 상품 목록 (target_scope=products 시 이 상품에만 적용)
excluded_products array [] 적용 제외 상품 목록 (해당 상품은 쿠폰 적용에서 제외)
included_categories array [{"id":32,"name":{"ko":"바지","en":"Pants"},"description":{… 적용 대상 포함 카테고리 목록 (target_scope=categories 시 이 카테고리에만 적용)
excluded_categories array [] 적용 제외 카테고리 목록 (해당 카테고리는 쿠폰 적용에서 제외)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "다운로드 가능한 쿠폰 목록을 불러왔습니다.",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 107,
                "name": {
                    "ko": "카테고리 배송비 3,000원 할인",
                    "en": "Category Shipping 3,000 KRW Off"
                },
                "description": {
                    "ko": "특정 카테고리 배송비 할인",
                    "en": "Shipping discount on categories"
                },
                "target_type": "shipping_fee",
                "discount_type": "fixed",
                "discount_value": "3000.00",
                "discount_max_amount": null,
                "min_order_amount": "20000.00",
                "issue_method": "download",
                "issue_condition": "manual",
                "issue_status": "issuing",
                "total_quantity": 300,
                "issued_count": 1,
                "per_user_limit": 1,
                "valid_type": "period",
                "valid_days": null,
                "valid_from": "2026-07-23T14:36:17.000000Z",
                "valid_to": "2026-09-21T14:36:17.000000Z",
                "issue_from": "2026-07-23T14:36:17.000000Z",
                "issue_to": "2026-08-29T14:36:17.000000Z",
                "is_combinable": true,
                "target_scope": "categories",
                "created_by": null,
                "created_at": "2026-07-30T14:36:17.000000Z",
                "updated_at": "2026-07-31T12:51:54.000000Z",
                "deleted_at": null,
                "is_downloaded": true,
                "user_issued_count": 1,
                "coupon_id": 107,
                "localized_name": "카테고리 배송비 3,000원 할인",
                "target_type_short_label": "배송비",
                "valid_period_formatted": "2026-07-23 ~ 2026-09-21",
                "min_order_amount_formatted": "¥20,000",
                "remaining_quantity": 299,
                "benefit_formatted": "¥3,000 할인",
                "included_products": [],
                "excluded_products": [],
                "included_categories": [
                    {
                        "id": 32,
                        "name": {
                            "ko": "바지",
                            "en": "Pants"
                        },
                        "description": {
                            "ko": "다양한 스타일의 바지",
                            "en": "Various styles of pants"
                        },
                        "parent_id": 30,
                        "path": "29/30/32",
                        "depth": 2,
                        "sort_order": 1,
                        "is_active": true,
                        "slug": "men-pants",
                        "meta_title": null,
                        "meta_description": null,
                        "created_at": "2026-07-30T14:35:47.000000Z",
                        "updated_at": "2026-07-30T14:35:47.000000Z",
                        "pivot": {
                            "coupon_id": 107,
                            "category_id": 32
                        }
                    },
                    {
                        "id": 42,
                        "name": {
                            "ko": "노트북",
                            "en": "Laptops"
                        },
                        "description": {
                            "ko": "노트북 컴퓨터",
                            "en": "Laptop computers"
                        },
                        "parent_id": 38,
                        "path": "38/42",
                        "depth": 1,
                        "sort_order": 1,
                        "is_active": true,
                        "slug": "laptops",
                        "meta_title": null,
                        "meta_description": null,
                        "created_at": "2026-07-30T14:35:47.000000Z",
                        "updated_at": "2026-07-30T14:35:47.000000Z",
                        "pivot": {
                            "coupon_id": 107,
                            "category_id": 42
                        }
                    }
                ],
                "excluded_categories": []
            },
            {
                "id": 103,
                "name": {
                    "ko": "배송비 50% 할인",
                    "en": "Shipping 50% Off"
                },
                "description": {
                    "ko": "배송비 반값 할인",
                    "en": "50% off shipping fee"
                },
                "target_type": "shipping_fee",
                "discount_type": "rate",
                "discount_value": "50.00",
                "discount_max_amount": "3000.00",
                "min_order_amount": "20000.00",
                "issue_method": "download",
                "issue_condition": "manual",
                "issue_status": "issuing",
                "total_quantity": 1000,
                "issued_count": 62,
                "per_user_limit": 1,
                "valid_type": "days_from_issue",
                "valid_days": 14,
                "valid_from": null,
                "valid_to": null,
                "issue_from": "2026-07-25T14:36:17.000000Z",
                "issue_to": "2026-09-28T14:36:17.000000Z",
                "is_combinable": true,
                "target_scope": "all",
                "created_by": null,
                "created_at": "2026-07-30T14:36:17.000000Z",
                "updated_at": "2026-07-31T12:52:41.000000Z",
                "deleted_at": null,
                "is_downloaded": true,
                "user_issued_count": 1,
                "coupon_id": 103,
                "localized_name": "배송비 50% 할인",
                "target_type_short_label": "배송비",
                "valid_period_formatted": "발급일로부터 14일",
                "min_order_amount_formatted": "¥20,000",
                "remaining_quantity": 938,
                "benefit_formatted": "50.00% 할인 (최대 ¥3,000)",
                "included_products": [],
                "excluded_products": [],
                "included_categories": [],
                "excluded_categories": []
            },
            "... (총 11건 중 2건 표시)"
        ],
        "first_page_url": "https://api.example.com/api/modules/sirsoft-ecommerce/user/coupons/downloadable?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "https://api.example.com/api/modules/sirsoft-ecommerce/user/coupons/downloadable?page=1",
        "links": [
            {
                "url": null,
                "label": "pagination.previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://api.example.com/api/modules/sirsoft-ecommerce/user/coupons/downloadable?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "pagination.next",
                "page": null,
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "https://api.example.com/api/modules/sirsoft-ecommerce/user/coupons/downloadable",
        "per_page": 25,
        "prev_page_url": null,
        "to": 11,
        "total": 11
    }
}

에러 응답

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

설명 로그인한 회원이 지금 다운로드해 발급받을 수 있는 쿠폰(다운로드형) 목록을 페이지네이션으로 조회합니다. auth:sanctum 인증이 필요하며, UserCouponService::getDownloadableCoupons()가 발급기간·수량·회원당 한도를 만족하는 다운로드형 쿠폰을 반환하고 각 항목에 is_downloaded·user_issued_count로 이미 받았는지 여부를 표시합니다. 여기 항목은 아직 발급 전이므로 쿠폰 정의(마스터) 기준이며, 실제 발급은 download 엔드포인트로 수행합니다.

POST /api/modules/sirsoft-ecommerce/user/coupons/{couponId}/download

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

요청 파라미터

이름 위치 타입 필수 허용값 용도
couponId path string 예 — 대상 coupon의 식별자
coupon_id body integer 예 — coupon 식별자

요청 예시

POST /api/modules/sirsoft-ecommerce/user/coupons/{couponId}/download HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "coupon_id": 1
}

응답 필드 (data 내부)

응답 예시

에러 응답

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

설명 로그인한 회원이 다운로드형 쿠폰 1건을 실제로 발급받습니다. auth:sanctum 인증이 필요하고 대상 쿠폰은 couponId(경로)로 지정하며, UserCouponService::downloadCoupon()이 발급기간·수량·회원당 한도·중복 발급 여부를 검증한 뒤 발급 내역을 생성해 201로 반환합니다. 한도 초과·발급기간 종료 등 발급 불가 사유는 서비스 예외의 메시지와 코드가 그대로 오류 응답에 전달됩니다.

Reference in New Issue View Git Blame Copy Permalink