JSON 컨벤션

회원가입을 제외한 모든 API는 인가처리 필요
Request Header에 Authorization : Bearer {jwt_token}으로 요청해야 함
JSON에서 사용할 필드명이 DB에 존재하는 필드값일 경우, DB 속성명에서 참고해서 카멜표기법

공통사항

모든 엔드포인트에 Base URI /api/v1 적용

에러 발생 시 다음과 같은 Response Body를 반환
{
    "errorMessage": "Expired JWT token, 만료된 JWT token 입니다.",
    "statusCode": 401
}

사용자(/users)

”username”:”username”, 
“password”:”password”

} | | response header에서 JWT 토큰 반환 Authorization : Bearer {jwt_token}

status : 200 OK | | 회원가입 | POST | /users/signup | CUSTOMER OWNER | { "username": "username", "password": "password", "email": "[email protected]", "phoneNumber": "01012345678", "role": “CUSTOMER", "imgUrl": “imgUrl” } | { "username": "username" } | username은 최소 4자 이상, 10자 이하이며 알파벳 소문자(a~z), 숫자(0~9) password는 최소 8자 이상, 15자 이하이며 알파벳 대소문자(a~z, A~Z), 숫자(0~9), 특수문자 phoneNumber는 11자리의 숫자 role은 CUSTOMER, OWNER만 가능

status : 201 CREATED | | 회원가입(관리자) | POST | /users/signup/master | MASTER | { "username": "username", "password": "password", "email": "[email protected]", "phoneNumber": "01012345678", "role": “CUSTOMER", "imgUrl": “imgUrl” } | { "username": "username" } | role은 CUSTOMER, OWNER, MANAGER, MASTER 모두 지정 가능 그 외 제약조건은 일반 회원가입과 같음

status : 200 OK | | 회원수정 | PUT | /users/ | ALL | { "password": "password", "email": "[email protected]", "phoneNumber": "01012345678", “publicProfile” : true "imgUrl": “imgUrl” } | { "username": "username" } | publicProfile은 프로필 공개 여부를 설정, true 또는 false username은 수정 불가능 그 외 제약조건은 회원가입과 같음

status : 200 OK | | 회원수정(관리자) | PUT | /users/{username} | MANAGER MASTER | { "password": "password", "email": "[email protected]", "phoneNumber": "01012345678", “publicProfile” : true "imgUrl": “imgUrl” } | { "username": "username" } | 제약조건은 일반 회원수정과 같음 PathVariable {username}을 통해 수정할 사용자 지정

status : 200 OK | | 회원탈퇴 | DELETE | /users/ | CUSTOMER OWNER | | { "username": "username" } | soft delete로 처리

status : 200 OK | | 회원탈퇴(관리자) | DELETE | /users/{username} | MANAGER MASTER | | { "username": "username" } | soft delete로 처리 PathVariable {username}을 통해 수정할 사용자 지정

status : 200 OK | | 회원 정보 조회 | GET | /users/ | ALL | | { "password": "password", "email": "[email protected]", "phoneNumber": "01012345678", "role": “CUSTOMER", “publicProfile” : true "imgUrl": “imgUrl” } | 쿼리 ?username={username}을 통해 조회할 사용자 지정 CUSTOMER, OWNER는 탈퇴한 사용자나 프로필이 비공개인 사용자 정보는 볼 수 없음

status : 200 OK | | 회원 검색 | GET | /users/search | ALL | | "content": [        {            "username": "test",         "email": "[email protected]",           
"phoneNumber": "01012345678",            "publicProfile": true,            "role": "CUSTOMER",         "imgUrl": null     },        {      "username": "testmanage",         "email":"[email protected]",            "phoneNumber": "01112345678",            "publicProfile": true,         "role": "MANAGER",         "imgUrl": null        }, …   ], … | 쿼리 ?keyword={keyword}을 통해 검색어 지정, keyword를 username에 포함하는 사용자를 검색 CUSTOMER, OWNER는 탈퇴한 사용자나 프로필이 비공개인 사용자 정보가 포함되지 않음

페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

Response Body에는 페이징 관련 정보들이 함께 포함됨

| | 배송지 정보 등록 | POST | /users/address/ | ALL | { ”zipNum”: ”zipNum”, ”city”: ”city”, ”district”: ”district”, ”streetName”: ”streetName”, ”streetNum”: ”streetNum”, ”detailAddr”: ”detailAddr” “requestDetails: “requestDetails” } | { “addressId”: “UUID” } | status : 201 CREATED | | 배송지 정보 수정 | PUT | /users/address/{addressId} | ALL | { ”zipNum”: ”zipNum”, ”city”: ”city”, ”district”: ”district”, ”streetName”: ”streetName”, ”streetNum”: ”streetNum”, ”detailAddr”: ”detailAddr” “requestDetails: “requestDetails” } | { “addressId”: “UUID” } | PathVariable {addressId}을 통해 수정할 배송지 지정

status : 200 OK | | 배송지 정보 목록 조회 | GET | /users/address/ | ALL | | "content": [ { ”zipNum”: ”zipNum”, ”city”: ”city”, ”district”: ”district”, ”streetName”: ”streetName”, ”streetNum”: ”streetNum”, ”detailAddr”: ”detailAddr” “requestDetails: “requestDetails” }, { ”zipNum”: ”zipNum”, ”city”: ”city”, ”district”: ”district”, ”streetName”: ”streetName”, ”streetNum”: ”streetNum”, ”detailAddr”: ”detailAddr” “requestDetails: “requestDetails” }, …. ], … | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

Response Body에는 페이징 관련 정보들이 함께 포함됨

status : 200 OK | | 현재(기본) 배송지 조회 | GET | /users/address/current | ALL | | { ”zipNum”: ”zipNum”, ”city”: ”city”, ”district”: ”district”, ”streetName”: ”streetName”, ”streetNum”: ”streetNum”, ”detailAddr”: ”detailAddr” “requestDetails: “requestDetails” } | status : 200 OK | | 현재(기본) 배송지 설정 | PUT | /users/address/{addressId}/current | | | { “addressId”: “UUID” } | PathVariable {addressId}을 통해 수정할 사용자 지정

status : 200 OK | | 배송지 정보 삭제 | DELETE | /users/address/{addressId} | ALL | | { “addressId”: “UUID” } | soft delete로 처리 PathVariable {addressId}을 통해 수정할 사용자 지정

status : 200 OK |

리뷰(/reviews)

{
    “reviewId”: “reviewId”
    “contents”: “내용”
    “rating”: 5
},
{
    “reviewId”: “reviewId”
    “contents”: “내용”
    “rating”: 5
}, …

], … | 쿼리 ?storeId={UUID}를 통해 리뷰를 조회할 점포 지정 삭제된 리뷰는 조회하지 않음

페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

Response Body에는 페이징 관련 정보들이 함께 포함됨

status : 200 OK | | 사용자 리뷰 목록 조회 | GET | /reviews/user | ALL | | “content: [ { “reviewId”: “reviewId” “contents”: “내용” “rating”: 5 }, { “reviewId”: “reviewId” “contents”: “내용” “rating”: 5 }, … ], … | 쿼리 ?username={username}를 통해 리뷰를 조회할 사용자 지정 삭제된 리뷰는 목록에 포함하지 않음

페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

Response Body에는 페이징 관련 정보들이 함께 포함됨

status : 200 OK | | 리뷰 상세 조회 | GET | /reviews/{reviewId} | ALL | | { “reviewId”: “reviewId” “contents”: “내용” “rating”: 5 } | Path Variable {revieId}을 통해 조회할 리뷰를 지정

status : 200 OK | | 리뷰 등록 | POST | /reviews/{orderId} | CUSTOMER MANAGER MASTER | { “contents” : “contents”, “rating : 4” } | { “reviewId”: “reviewId” } | Path Variable {orderId}을 통해 리뷰를 등록할 주문을 지정

status : 201 CREATED | | 리뷰 수정 | PUT | review/{reviewId} | CUSTOMER MANAGER MASTER | { “contents” : “contents”, “rating : 3” } | { “reviewId” : “reviewId” } | Path Variable {revieId}을 통해 수정할 리뷰를 지정

status : 200 OK | | 리뷰 삭제 | DELETE | review/{reviewId} | CUSTOMER MANAGER MASTER | | { "reviewId": "reviewId" } | soft delete로 처리 Path Variable {revieId}을 통해 삭제할 리뷰를 지정

status : 200 OK |

점포(/stores)

• /stores?category=카테고리이름&name=점포이름&address=주소 | | 점포 상세 조회 | GET | /api/v1/stores/{storeId} | GET | | { ”ownerName”:”점주이름”, "storeName" : "가게 이름1", "phoneNumber" : "01000110001", "openTime": "09:00", "closeTime": "18:00", "zipNum" : "16022", "city" : "서울특별시", "district" : "종로구", "streetName" : "효자로", "streetNumber" : "123", "detailAddr" : "국립고궁박물관관", "storeIntro" : "광화문주소", "category":"한식,분식,양식" } | | | 점포 검색 | GET | /api/v1/stores/search | ALL | | { "storeList" : [ { "storeName" : "가게 이름", "phoneNumber" : "000-000-0000", "openTime": "2023-11-06T09:00:00+09:00", "closeTime": "2023-11-06T18:00:00+09:00", "address":{ "zipNum" : "매장주소 우편변호", "city" : "매장주소 시도", "district" : "매장 주소 군/구", "streetName" : "매장 도로명", "streetNum" : "매장 도로번호", "detailAddr" : "매장 상세주소" }, "storeIntro" : "매장 소개글" },..... ] } | | | 점포 삭제 | DELETE | /api/v1/stores/{storeId} | OWNER, MASTER, MANAGER | | { "storeId" : 1 } | | | 가게 등록 허용 | GET | /api/v1/stores/{storeId}/public-switch | MASTER,MANAGER | | | |

음식 (/products)

주문 목록(/orders)

"type": "ONLINE"

} | { "orderId": "order_uuid" } | HTTP status : 201 | | 주문 목록 조회 | GET | /orders?page=1&size=10&sortBy=createdDate&isAsc=true | CUSTOMER, MANAGER, MASTER | | { "content": [ { "orderId": "order_uuid", "storeId": "store_uuid", "username": "user", "status": "CREATE", "type": "ONLINE", "finalPay": 190000, "discountRate": 0, "discountAmount": 0 } ], .. } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

Response Body에는 페이징 관련 정보들이 함께 포함됨

customer 권한은 자신의 주문 목록만 볼 수 있고, admin 권한은 모든 유저의 주문 목록을 볼 수 있음 | | 주문 상세 조회 | GET | /orders/{orderId} | CUSTOMER, MANAGER, MASTER | | { "orderId": “order_uuid", "storeId": "store_id", "username": "user", "status": "CREATE", "type": "ONLINE", "finalPay": 190000, "discountRate": 0, "discountAmount": 0, "products": [ { "productId": "product_uuid1", "name": "product1", "price": 10000, "imgUrl": "image", "productIntro": "intro" }, { "productId": "product_uuid2", "name": "product2", "price": 10000, "imgUrl": "image", "productIntro": "intro" } ] } | 주문 상세 조회는 어떤 품목을 구매했는지 포함해서 response로 리턴

customer 권한은 자신의 주문만 볼 수 있고, admin 권한은 모든 유저의 주문을 볼 수 있음 | | 점포별 주문 목록 조회 | GET | /orders/stores/{storeId}?page=1&size=10&sortBy=finalPay&isAsc=true | OWNER, MANAGER, MASTER | | { "content": [ { "orderId": "order_uuid", "storeId": "store_uuid", "username": "user", "status": "CREATE", "type": "ONLINE", "finalPay": 190000, "discountRate": 0, "discountAmount": 0 } ],… } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

Response Body에는 페이징 관련 정보들이 함께 포함됨

owner 는 자신의 점포 주문 목록만 볼 수 있고, admin 은 모든 점포의 주문 목록을 볼 수 있음 | | 주문 상태 수정 | PUT | /orders | OWNER, MANAGER, MASTER | { "orderId" : "order_uuid", "status" : "ACCEPT" } | { "orderId" : "order_uuid" } | owner 는 자신의 점포에 대한 주문만 상태 수정이 가능 admin 은 모든 점포의 주문에 대해 상태 수정이 가능

status 값으로 [ CREATE , PENDING , ACCEPTED , REJECTED , COMPLETED , CANCEL ] 값이 들어갈 수 있음 각 value의 의미는 생성, 결제 후 대기 중, 주문 수락, 주문 거절, 완료, 취소이다. | | 주문 취소 | DELETE | /orders/{orderId} | CUSTOMER, MANAGER, MASTER | | { “orderId”:”order_uuid” } | customer 은 자신의 주문만 취소 가능 admin 은 모든 유저의 주문 취소 가능 | | 주문 검색 | GET | /orders/search?storeName=흑백&page=0&size=10&sortBy=finalPay&isAsc=true | MASTER, MANAGER | | { "content": [ { "orderId": "order_uuid1", "storeId": "store_uuid1", "username": "user1", "status": "CREATE", "type": "ONLINE", "finalPay": 190000, "discountRate": 0, "discountAmount": 0 }, { "orderId": "order_uuid2", "storeId": "store_uuid2", "username": "user2", "status": "CREATE", "type": "ONLINE", "finalPay": 190000, "discountRate": 0, "discountAmount": 0 } ],… } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

admin 권한만 사용 가능

storeName (가게 이름)을 검색어 기준으로 설정 |

장바구니(/baskets)

"productId": "product_uuid",
"quantity": 2

} | { "basketId": "basket_uuid" } | Http status 201 | | 장바구니 빼기 | DELETE | /baskets/{basketId} | CUSTOMER | | { “bascketId”:”basket_uuid” } | | | 장바구니 조회 | GET | /baskets?page=1&size=10&sortBy=createdDate&isAsc=true | CUSTOMER | | { "content": [ { "basketId": "basket_uuid1", "storeId": "store_uuid1", "storeName": "흑백기사", "productId": "product_uuid1", "productName": "product1", "quantity": 5 } ],… } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false | | 장바구니 수정 | PUT | /baskets | CUSTOMER | { "basketId": "basket_uuid", "quantity": 5 } | { "basketId" : “basket_uuid” } | | | 검색 | GET | /baskets/search?productName=productSearchTest&page=0&size=10&sortBy=quantity&isAsc=true | CUSTOMER | | { "content": [ { "basketId": "basket_uuid1", "username": "user", "storeId": "store_uuid1", "storeName": "흑백기사", "productId": "product_uuid1", "productName": "productName", "quantity": 1 } ],… } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

productName으로 검색 |

결제(/pay)

“orderId” : “order_uuid”

} | { "tid": "tid", "next_redirect_pc_url": "url", "created_at": "2024-11-17T18:26:13" } | orderId를 통해 주문을 조회하고 주문 정보를 카카오페이 서버에 요청으로 포함시켜 전송

next_redirect_pc_url 은 카카오페이의 QR코드 화면의 url | | 결제 승인 | GET | /pays/success?pg_token={pg_token}&tid={tid} | CUSTOMER | | { "aid": "A1234567890", "tid": "T1234567890", "cid": "C1234567890", "partner_order_id": "ORDER1234", "partner_user_id": "USER1234", "payment_method_type": "CARD", "amount": { "total": 50000, "tax_free": 0, "vat": 5000, "point": 0, "discount": 0 }, "item_name": "Laptop", "item_code": "ITEM1234", "quantity": 1, "created_at": "2024-11-18T12:00:00", "approved_at": "2024-11-18T12:05:00", "payload": "Custom payload data" } | QR코드 인증 후 호출하는 URI 결제 승인하는 카카오페이 API

pg_token , tid 를 쿼리 파라미터로 받는다. | | 결제 환불 | POST | /pays/refund | CUSTOMER | { “orderId” : “order_uuid” } | {"message":"주문을 취소했습니다."} | | | 결제 목록 조회 | GET | /pays?page=1&size=10&sortBy=approvedAt&isAsc=true | CUSTOMER, MANAGER, MASTER | | { "content": [ { "payId": “pay_uuid", "itemName": "흑백 기사 배달 주문", "payStatus": "SUCCESS", "payAmount": 190000, "refundAmount": null, "approvedAt": "2024-11-17T18:51:51", "canceledAt": null } ],… } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false | | 결제 상세 조회 | GET | /pays/{payId} | CUSTOMER, MANAGER, MASTER | | { "payId": "pay_uuid1", "order": { "orderId": "order_uuid", "storeId": "store_uuid", "username": "user", "status": "COMPLETED", "type": "ONLINE", "finalPay": 190000, "discountRate": 0, "discountAmount": 0, "products": [ { "productId": "product_uuid1", "name": "product1", "price": 10000, "imgUrl": "image1", "productIntro": "intro" }, { "productId": "product_uuid2", "name": "product2", "price": 10000, "imgUrl": "image2", "productIntro": "intro2" } ] }, "itemName": "흑백 기사 배달 주문", "payStatus": "SUCCESS", "payAmount": 190000, "refundAmount": null, "approvedAt": "2024-11-17T18:51:51", "canceledAt": null } | 결제한 주문의 상세 내역 반환 | | 결제 검색 | POST | /pays/search?storeName=흑백&page=1&size=10&sortBy=createdDate&isAsc=true | MANAGER, MASTER | | { "content": [ { "payId": "pay_uuid", "itemName": "흑백 기사 배달 주문", "payStatus": "SUCCESS", "payAmount": 190000, "refundAmount": null, "approvedAt": "2024-11-17T18:51:51", "canceledAt": null } ],… } | 페이징 및 정렬 옵션으로 쿼리파라미터 page, size, sortBy, isAsc 지정 size는 10, 30, 50 sortBy는 createdAt, lastModifiedAt isAsc는 true, false

가게 이름을 검색하여 결제 검색 |

AI 사용기록(/ai)

“prompt” : “질문” 

} | { “answer” : “답변” } | status: 201 CREATED |