📚 Planu Backend API 문서

Planu 백엔드 API의 전체 엔드포인트 명세서입니다.

📑 목차

인증 API
사용자 프로필 API
팔로우 API
카테고리 API
Todo API
Someday API
스티커 API
상점 API
구매 API
쿠폰 API

🔐 인증 API

공개 API (인증 불필요)

1. 이메일 중복 확인

POST /auth/checkDuplicateEmail
Content-Type: application/json

{
  "email": "user@example.com"
}

응답: "true" (사용 가능) 또는 "false" (중복)

2. 이메일 존재 확인

POST /auth/checkExistEmail
Content-Type: application/json

{
  "email": "user@example.com"
}

응답: User 객체 또는 404

3. 인증 코드 발송

POST /auth/sendVerificationCode?email=user@example.com

응답: 인증 코드 발송 완료 메시지

4. 인증 코드 확인

POST /auth/checkVerificationCode?email=user@example.com&code=123456

응답: 인증 완료 메시지

5. 회원가입

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "name": "홍길동"
}

응답: 회원가입 완료 메시지

6. 로그인

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

응답:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

7. 구글 로그인

POST /auth/login/google
Content-Type: application/json

{
  "idToken": "google_id_token"
}

응답: Access Token + Refresh Token

8. 카카오 로그인

POST /auth/login/kakao
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "홍길동"
}

응답: Access Token + Refresh Token

9. 비밀번호 재설정

POST /auth/updatePassword
Content-Type: application/json

{
  "email": "user@example.com",
  "newPassword": "newPassword123"
}

응답: 비밀번호 변경 완료 메시지

인증 필요 API

모든 인증 필요 API는 헤더에 다음을 포함해야 합니다:

Authorization: Bearer {accessToken}

1. 비밀번호 변경

POST /auth/changePassword
Authorization: Bearer {token}
Content-Type: application/json

{
  "currentPassword": "oldPassword",
  "newPassword": "newPassword123"
}

2. 로그아웃

POST /auth/logout
Authorization: Bearer {token}
Refresh-Token: {refreshToken}

3. 회원 탈퇴

POST /auth/unregister
Authorization: Bearer {token}

4. 토큰 갱신

POST /auth/refresh-token
Authorization: Bearer {refreshToken}

응답: 새로운 Access Token

5. 토큰 검증

GET /auth/validate-token
Authorization: Bearer {token}

응답: 200 (유효) 또는 401 (무효)

👤 사용자 프로필 API

1. 내 프로필 조회

GET /auth/profile
Authorization: Bearer {token}

응답:

{
  "userReferenceId": "uuid",
  "email": "user@example.com",
  "name": "홍길동",
  "profileImageUrl": "https://...",
  "introduction": "안녕하세요",
  "isPrivate": false
}

2. 프로필 수정

POST /auth/updateProfile
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "홍길동",
  "introduction": "안녕하세요",
  "isPrivate": false
}

3. 프로필 이미지 업로드

POST /auth/updateProfileImage
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [이미지 파일]

4. 프로필 이미지 삭제

POST /auth/deleteProfileImage
Authorization: Bearer {token}

5. 사용자 검색

POST /auth/findUser
Authorization: Bearer {token}
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "홍길동"
}

응답: 사용자 프로필 목록

👥 팔로우 API

1. 팔로우

POST /auth/follow
Authorization: Bearer {token}
Content-Type: application/json

{
  "followedEmail": "target@example.com"
}

2. 언팔로우

POST /auth/unfollow
Authorization: Bearer {token}
Content-Type: application/json

{
  "followedEmail": "target@example.com"
}

3. 내 팔로잉 목록 조회

GET /auth/following
Authorization: Bearer {token}

응답: 팔로잉 사용자 목록

4. 내 팔로워 목록 조회

GET /auth/followers
Authorization: Bearer {token}

응답: 팔로워 사용자 목록

5. 특정 사용자의 팔로잉 목록

GET /auth/followings/{email}
Authorization: Bearer {token}

6. 특정 사용자의 팔로워 목록

GET /auth/followers/{email}
Authorization: Bearer {token}

📁 카테고리 API

1. 카테고리 생성

POST /category/
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "업무",
  "color": "#FF5733"
}

응답:

{
  "categoryId": 1,
  "title": "업무",
  "color": "#FF5733"
}

2. 내 카테고리 목록 조회

GET /category/
Authorization: Bearer {token}

3. 특정 사용자 카테고리 조회

GET /category/{email}
Authorization: Bearer {token}

4. 카테고리 수정

PUT /category/{categoryId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "개인",
  "color": "#3498DB"
}

5. 카테고리 삭제

DELETE /category/?categoryIds=1,2,3
Authorization: Bearer {token}

Query Parameter: 삭제할 카테고리 ID 목록

✅ Todo API

1. Todo 생성

POST /todo/
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "회의 준비하기",
  "date": "2024-10-21",
  "categoryId": 1,
  "isCompleted": false
}

2. 여러 Todo 한번에 생성

POST /todo/todos
Authorization: Bearer {token}
Content-Type: application/json

{
  "todos": [
    {
      "title": "회의 준비",
      "date": "2024-10-21",
      "categoryId": 1
    },
    {
      "title": "보고서 작성",
      "date": "2024-10-21",
      "categoryId": 1
    }
  ]
}

3. 내 Todo 목록 조회

GET /todo/
Authorization: Bearer {token}

응답: Todo 목록

4. 특정 사용자 Todo 조회

GET /todo/{email}
Authorization: Bearer {token}

5. Todo 수정

PUT /todo/{todoId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "회의 준비 완료",
  "date": "2024-10-21",
  "categoryId": 1,
  "isCompleted": true
}

6. Todo 삭제

DELETE /todo/{todoId}
Authorization: Bearer {token}

7. 여러 Todo 삭제

DELETE /todo/todos?todoIds=1,2,3
Authorization: Bearer {token}

📅 Someday API

1. Someday 생성

POST /todo_someday/
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "언젠가 해야 할 일",
  "categoryId": 1
}

2. Someday 목록 조회

GET /todo_someday/
Authorization: Bearer {token}

3. Someday 수정

PUT /todo_someday/{todoSomedayId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "수정된 제목",
  "categoryId": 2
}

4. Someday 삭제

DELETE /todo_someday/{todoSomedayId}
Authorization: Bearer {token}

🎨 스티커 API

1. 스티커 생성

POST /sticker/
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "하트 스티커",
  "imageUrl": "https://..."
}

2. 내 스티커 목록 조회

GET /sticker/
Authorization: Bearer {token}

응답:

[
  {
    "stickerId": 1,
    "name": "하트 스티커",
    "imageUrl": "https://..."
  }
]

3. 스티커 삭제

DELETE /sticker/{stickerId}
Authorization: Bearer {token}

🏪 상점 API

스티커 상점

1. 스티커 상점 목록

GET /shop_sticker/
Authorization: Bearer {token}

응답:

[
  {
    "shopStickerId": 1,
    "name": "프리미엄 스티커",
    "price": 1000,
    "imageUrl": "https://...",
    "description": "프리미엄 스티커입니다"
  }
]

2. 인기 스티커 목록 (판매량 순)

GET /shop_sticker/sales
Authorization: Bearer {token}

컬러 상점

1. 컬러 상점 목록

GET /shop_color/
Authorization: Bearer {token}

응답:

[
  {
    "shopColorId": 1,
    "name": "민트 컬러",
    "price": 500,
    "colorCode": "#98D8C8"
  }
]

2. 인기 컬러 목록 (판매량 순)

GET /shop_color/sales
Authorization: Bearer {token}

💳 구매 API

스티커 구매

1. 스티커 구매

POST /purchase_sticker/
Authorization: Bearer {token}
Content-Type: application/json

{
  "shopStickerId": 1
}

응답:

{
  "purchaseStickerId": 1,
  "shopStickerId": 1,
  "purchaseDate": "2024-10-21T10:30:00"
}

2. 내 구매 스티커 목록

GET /purchase_sticker/
Authorization: Bearer {token}

컬러 구매

1. 컬러 구매

POST /purchase_color/
Authorization: Bearer {token}
Content-Type: application/json

{
  "shopColorId": 1
}

2. 내 구매 컬러 목록

GET /purchase_color/
Authorization: Bearer {token}

🎟️ 쿠폰 API

1. 쿠폰 목록 조회

GET /coupon/
Authorization: Bearer {token}

응답:

[
  {
    "couponId": 1,
    "name": "신규 회원 쿠폰",
    "discountAmount": 1000,
    "expiryDate": "2024-12-31"
  }
]

2. 쿠폰 사용

POST /coupon/
Authorization: Bearer {token}
Content-Type: application/json

{
  "couponId": 1
}

응답:

{
  "usageId": 1,
  "couponId": 1,
  "usedAt": "2024-10-21T10:30:00"
}

3. 쿠폰 사용 내역 조회

GET /coupon_usage/
Authorization: Bearer {token}

📝 공통 응답 형식

성공 응답

{
  "data": { },
  "message": "성공 메시지"
}

에러 응답

{
  "status": 400,
  "code": "ERROR_CODE",
  "message": "에러 메시지"
}

🔑 인증 헤더

모든 인증이 필요한 API는 다음 헤더를 포함해야 합니다:

Authorization: Bearer {accessToken}

Refresh Token이 필요한 경우:

Refresh-Token: {refreshToken}

📌 참고사항

Swagger UI: http://localhost:8080/swagger-ui.html 에서 실시간 API 테스트 가능
날짜 형식: YYYY-MM-DD
시간 형식: ISO 8601 (YYYY-MM-DDTHH:mm:ss)
토큰 만료: Access Token - 1시간, Refresh Token - 7일
파일 업로드: multipart/form-data 형식 사용
최대 파일 크기: 10MB

🐛 에러 코드

코드	설명
400	잘못된 요청
401	인증 실패
403	권한 없음
404	리소스 없음
409	충돌 (중복 등)
500	서버 에러

더 자세한 내용은 Swagger 문서를 참고하세요.

FilesExpand file tree

API_DOCUMENTATION.md

Latest commit

History