05.ApiDocument.md

E-커머스 서비스 API 명세

📚 문서 목록

• 1️⃣ 요구사항 분석 문서
• 2️⃣ 마일스톤 문서
• 3️⃣ 다이어그램 문서
  • 시퀀스 다이어그램 문서
  • 상태 다이어그램 문서
• 4️⃣ ERD 문서
• 5️⃣ API 명세

---

• E-커머스 서비스 API 명세
  • 잔액 API
    • 잔액 조회
    • 잔액 충전
  • 상품 API
    • 상품 목록 조회
  • 쿠폰 API
    • 보유 쿠폰 목록 조회
    • 쿠폰 발급
  • 주문/결제 API
    • 주문 생성 및 결제 처리
  • 상품 통계 API
    • 상위 상품 조회

잔액 API

잔액 조회

[Description]
사용자 잔액을 조회한다.

[Request]

• URL : /api/v1/users/{id}/balance
• Method : GET
• Path Parameters

Parameter	Description
id	사용자 ID

[Response]

• Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "amount": 1000000
  }
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지
data.balance	Number	잔액

잔액 충전

[Description]
사용자 잔액을 충전한다.

[Request]

• URL : /api/v1/users/{id}/balance/charge
• Method : POST
• Path Parameters

Parameter	Description
id	사용자 ID

• Request Body

{
  "amount": 200000
}

• Request Fields

Path	Type	Required	Description
amount	Number	true	충전 금액

[Response]

• Response

{
  "code": 200,
  "message": "OK"
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지

상품 API

상품 목록 조회

[Description]
상품 목록을 조회한다.

[Request]

• URL : /api/v1/products
• Method : GET

[Response]

• Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "products": [
      {
        "id": 1,
        "name": "상품명",
        "price": 300000,
        "stock": 3
      }
    ]
  }
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지
data.products[].id	Number	상품 ID
data.products[].name	String	상품 이름
data.products[].price	Number	상품 가격
data.products[].stock	Number	상품 재고

쿠폰 API

보유 쿠폰 목록 조회

[Description]
사용 가능한 보유 쿠폰 목록을 조회한다.

[Request]

• URL : /api/v1/users/{id}/coupons
• Method : GET
• Path Parameters

Parameter	Description
id	사용자 ID

[Response]

• Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "coupons": [
      {
        "id": 1,
        "name": "쿠폰명",
        "discountRate": 0.1,
      }
    ]
  }
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지
data.coupons[].id	Number	쿠폰 ID
data.coupons[].name	String	쿠폰 이름
data.coupons[].discountRate	Number	쿠폰 할인율 (예: 0.1은 10%)

쿠폰 발급

[Description]
쿠폰을 발급한다.

[Request]

• URL : /api/v1/users/{id}/coupons/publish
• Method : POST
• Path Parameters

Parameter	Description
id	사용자 ID

• Request Body

{
  "couponId": 1
}

• Request Fields

Path	Type	Required	Description
couponId	Number	true	쿠폰 ID

[Response]

• Response

{
  "code": 200,
  "message": "OK"
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지

주문/결제 API

주문 생성 및 결제 처리

[Description]
주문을 생성하고 결제를 진행한다.

[Request]

• URL : /api/v1/orders

• Method : POST

• Request Body

{
  "userId": 1,
  "couponId": 2,
  "products": [
    {
      "id": 3,
      "quantity": 2
    }
  ]
}

• Request Fields

Path	Type	Required	Description
userId	Number	true	사용자 ID
couponId	Number	false	쿠폰 ID
products[].id	Number	true	상품 ID
products[].quantity	Number	true	상품 수량

[Response]

• Response

{
  "code": 200,
  "message": "OK"
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지

상품 통계 API

상위 상품 조회

[Description]
최근 3일간 상위 상품 Top 5 조회.

[Request]

• URL : /api/v1/products/ranks
• Method : GET

[Response]

• Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "products": [
      {
        "id": 1,
        "name": "상품명",
        "price": 300000,
        "saleCount": 3
      }
    ]
  }
}

• Response Fields

Path	Type	Description
code	Number	응답 코드
message	String	응답 메세지
data.products[].id	Number	상품 ID
data.products[].name	String	상품 이름
data.products[].price	Number	상품 가격
data.products[].saleCount	Number	상품 판매 수