FS 2 API 명세 - 100-hours-a-week/KTB4-13th-wiki GitHub Wiki
🚧 작성중 · 담당 김세훈 · 수정 2026-09-28 · 원본 [2단계]-API-명세서
요약 도메인 12묶음, 엔드포인트 40개로 구성한 북적북적 풀스택 API 명세다.
모든 API 응답을 다음 세 필드를 가진 ApiResponse로 정의한다.
{ result, data, error }
POST /api/v1/auth/{providerType}/login — 소셜 인증 코드로 로그인 세션 생성
OAuth provider idToken으로 로그인한다. 권한: 공개
POST /api/v1/auth/reissue — 토큰 재발급
Refresh Token으로 Access Token을 재발급한다. 권한: 공개
POST /api/v1/auth/logout — 로그아웃
현재 사용자의 Refresh Token을 폐기하고 로그아웃한다. 권한: 회원
GET /api/v1/users/me — 내 정보 조회
유저의 프로필을 조회한다. 권한: 회원
PATCH /api/v1/users/me — 내 정보 수정
유저의 프로필을 수정한다. 권한: 회원
DELETE /api/v1/users/me — 회원 탈퇴 처리
유저의 프로필을 삭제한다. 권한: 회원
GET /api/v1/onboarding/questions — 질문과 선택지 조회
원본에 정의되지 않음. 권한: 회원
GET /api/v1/users/me/onboarding — 내 온보딩 상태와 답변 조회
원본에 정의되지 않음. 권한: 회원
PUT /api/v1/users/me/onboarding/answers/{questionId} — 질문별 답변 저장 및 수정
원본에 정의되지 않음. 권한: 회원
입력
헤더
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Authorization | string | Y | Bearer {accessToken}. JWT 토큰 |
경로
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| questionId | number | Y | 답변을 등록하거나 수정할 온보딩 질문 식별자 |
본문
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| optionIds | array | Y | 해당 질문에서 선택한 선택지 식별자 목록 |
출력 200 OK
{
"result": "SUCCESS",
"data": {
"questionId": 1,
"optionIds": [1, 2]
},
"error": null
}| 필드 | 타입 | NULL | 설명 |
|---|---|---|---|
| questionId | number | NOT NULL | 저장된 질문 식별자 |
| optionIds | array | NOT NULL | 저장된 선택지 식별자 목록 |
에러
{
"result": "ERROR",
"data": null,
"error": {
"code": "E500",
"message": "알 수 없는 오류가 발생했습니다.",
"data": null
}
}| 코드 | HTTP 코드 | 이름 | 메시지 |
|---|---|---|---|
| E400 | 400 | INVALID_REQUEST | 선택 개수 또는 요청 값이 올바르지 않습니다. |
| E401 | 401 | UNAUTHORIZED | 인증 정보가 유효하지 않습니다. |
| E404 | 404 | NOT_FOUND | 질문 또는 선택지를 찾을 수 없습니다. |
| E409 | 409 | CONFLICT | 해당 질문에 속하지 않는 선택지가 포함되어 있습니다. |
| E500 | 500 | DEFAULT_ERROR | 알 수 없는 오류가 발생했습니다. |
PUT /api/v1/users/me/onboarding/books — 마지막 단계 도서 선택 저장 및 수정
원본에 정의되지 않음. 권한: 회원
GET /api/v1/items — 상품 목록 조회
카테고리에 속한 상품을 cursor 방식으로 조회한다. 권한: 공개
GET /api/v1/items/{itemId} — 상품 상세 조회
원본에 정의되지 않음. 권한: 공개
GET /api/v1/categories — 상품 카테고리 목록 조회
상품 카테고리의 목록을 조회한다. 권한: 공개
GET /api/v1/addresses — 내 배송지 목록 조회
유저의 배송지 목록을 조회한다. 권한: 회원
POST /api/v1/addresses — 배송지 등록
유저의 배송지 목록에 배송지를 등록한다. 권한: 회원
POST /api/v1/addresses/{addressId}/default — 기본 배송지 설정
배송지를 기본 배송지로 설정한다. 권한: 회원
PATCH /api/v1/addresses/{addressId} — 배송지 수정
배송지 수정에서 전달된 필드만 갱신한다. 권한: 회원
DELETE /api/v1/addresses/{addressId} — 배송지 삭제
배송지를 삭제한다. 권한: 회원
GET /api/v1/cart — 내 장바구니 조회
유저의 장바구니에 담긴 상품을 조회한다. 권한: 회원
POST /api/v1/cart/items — 장바구니 상품 추가
유저가 상품을 장바구니에 추가한다. 권한: 회원
PATCH /api/v1/cart/items/{cartItemId} — 장바구니 상품 수량 변경
장바구니 상품의 수량을 변경한다. 권한: 회원
DELETE /api/v1/cart/items/{cartItemId} — 장바구니 상품 삭제
장바구니에서 특정 상품을 삭제한다. 권한: 회원
DELETE /api/v1/cart/items — 장바구니 상품 다건 삭제
장바구니에서 선택한 상품들을 삭제한다. 권한: 회원
POST /api/v1/orders — 주문 생성
상품 옵션과 수량 목록으로 주문을 생성하고 주문 키를 반환한다. 권한: 회원
POST /api/v1/cart-orders — 장바구니 기반 주문 생성
선택한 장바구니 상품들로 주문을 생성한다. 권한: 회원
GET /api/v1/orders/{orderKey}/checkout — 주문의 결제 정보 조회
주문 금액, 주문 상품, 사용 가능한 쿠폰과 포인트를 결제 화면에 필요한 형태로 조회한다. 권한: 회원
GET /api/v1/orders — 내 주문 목록 조회
유저의 주문 이력을 조회한다. 권한: 회원
GET /api/v1/orders/{orderKey} — 내 주문 상세 조회
결제가 완료된 주문의 상세 정보와 주문 상품을 조회한다. 권한: 회원
POST /api/v1/payments — 결제 생성
원본에 정의되지 않음. 권한: 회원
POST /api/v1/payments/{paymentKey}/cancel — 결제 전액 취소
주문 전체를 취소한다. 권한: 회원
POST /api/v1/payments/{paymentKey}/partial-cancel — 결제 부분 취소
주문의 일부 품목을 취소한다. 권한: 회원
POST /api/v1/coupons/{couponId}/issue — 쿠폰 발급
쿠폰을 현재 유저에게 발급한다. 권한: 회원
GET /api/v1/coupons/me — 내 보유 쿠폰 조회
유저가 보유한 사용 가능한 쿠폰 목록을 조회한다. 권한: 회원
GET /api/v1/points — 내 포인트 잔액 조회
유저의 포인트 잔액과 변동 이력을 조회한다. 권한: 회원
GET /api/v1/reviews — 상품 리뷰 목록 조회
대상 상품의 리뷰를 cursor 방식으로 조회한다. 권한: 공개
POST /api/v1/reviews — 리뷰 작성
주문 이력이 있는 상품에 리뷰와 이미지를 등록한다. 권한: 회원
PATCH /api/v1/reviews/{reviewId} — 리뷰 수정
원본에 정의되지 않음. 권한: 회원
DELETE /api/v1/reviews/{reviewId} — 리뷰 삭제
작성한 리뷰를 삭제한다. 권한: 회원
GET /api/v1/notifications — 내 알림 목록
원본에 정의되지 않음. 권한: 회원
PATCH /api/v1/notifications/{notificationId} — 알림 읽음 처리
원본에 정의되지 않음. 권한: 회원
✏️ 이 페이지는 레포 docs/fs/2-api/spec.md에서 수정한다. 위키에서 직접 고치면 다음 반영 때 덮어써진다.