# Give++ API 文件
## URL Path Documentation
### Root Path: `/api/v1`
所有 api 區分成五個類別：
* /v1/users
* /v1/products
* /v1/orders
* /v1/carts
* /v1/manages
### [使用者 User](#User)
| 說明 | Method | Path |
| -------------------- | ------ | ------------------ |
| 註冊使用者 | POST | /users/register |
| 登入使用者 | POST | /users/login |
| 登出使用者 | GET | /users/logout |
| 取得自己的使用者資料 | GET | /users/me |
| 修改自己的使用者資料 | PATCH | /users/me |
| 修改自己的密碼 | PATCH | /users/password |
| 修改自己的公告 | PATCH | /users/announcment |
| 取得單一使用者資料 | GET | /users/:id |
| 修改單一使用者資料 | PATCH | /users/:id |
| 取得所有使用者資料 | GET | /users |
| 申請成為賣家 | POST | /users/apply |
| 使用者向平台寄送站內信 | POST | /users/mail |
### [產品分類 Product Category](#Category)
| 說明 | Method | Path |
| ------------ | ------ | ---------------------- |
| 取得所有分類 | GET | /products/categories |
### [產品 Product](#Product)
| 說明 | Method | Path | Params |
| -------------------- | ------ | ---------------------------- | ----------------------------------------------------------------------- |
| 取得所有商品 | GET | /products | all（全部）<br>passed（通過）<br>failed（未通過）<br>checking（審核中） |
| 取得該分類商品 | GET | /products/categories/:id | all（全部）<br>passed（通過）<br>failed（未通過）<br>checking（審核中） |
| 取得該賣家商品 | GET | /products/vendor/:id | all（全部）<br>passed（通過）<br>failed（未通過）<br>checking（審核中） |
| 取得搜尋商品結果 | GET | /products/search/`<keyword>` | |
| 取得單ㄧ商品詳細資料 | GET | /products/:id | |
| 新增商品 | POST | /products/new | |
| 編輯商品 | PATCH | /products/:id | |
| 刪除商品 | DELETE | /products/:id | |
| 取得待審核商品 | GET | /products/unaudited | |
### [購物車 Cart](#Cart)
| 說明 | Method | Path |
| -------------------- | ------ | -------------------- |
| 取得購物車商品 | GET | /carts/ |
| 新增商品至購物車 | POST | /carts/cart_item/new |
| 編輯購物車商品 | PATCH | /carts/cart-item/:id |
| 刪除購物車商品 | DELETE | /carts/cart-item/:id |
| 刪除購物車同賣家商品 | DELETE | /carts/seller/:id |
### [訂單 Order](#Order)
| 說明 | Method | Path |
| -------------------- | ------ | -------------------------- |
| 取得全部訂單列表 | GET | /orders |
| 取得自己買的訂單列表 | GET | /orders/buy |
| 取得自己賣的訂單列表 | GET | /orders/sell |
| 取得單一訂單明細 | GET | /orders/:id |
| 成立訂單 | POST | /orders/new |
| 訂單完成 | PATCH | /orders/:id/complete |
| 訂單付款 | PATCH | /orders/:id/pay |
| 訂單出貨 | PATCH | /orders/:id/send |
| 訂單取消 | PATCH | /orders/:id/cancel |
| 刪除訂單 | DELETE | /orders/:id |
### [條款 Rule](#Rule)
| 說明 | Method | Path |
| ---------------- | ------ | ------------------ |
| 取得所有條款資料 | GET | /manages/rules |
| 取得單一條款資料 | GET | /manages/rules/:id |
| 新增條款 | POST | /manages/rules/new |
| 編輯條款 | PATCH | /manages/rules/:id |
| 刪除條款 | DELETE | /manages/rules/:id |
### [常見問題 FAQ](#FAQ)
| 說明 | Method | Path |
| ---------------- | ------ | ----------------- |
| 取得所有常見問題 | GET | /manages/faqs |
| 取得單一常見問題 | GET | /manages/faqs/:id |
| 新增常見問題 | POST | /manages/faqs/new |
| 編輯常見問題 | PATCH | /manages/faqs/:id |
| 刪除常見問題 | DELETE | /manages/faqs/:id |
### [常見問題分類 FAQ Category](#FAQ-Category)
| 說明 | Method | Path |
| ---------------- | ------ | --------------------------- |
| 取得所有問題分類 | GET | /manages/faq-categories/new |
| 新增問題分類 | POST | /manages/faq-categories/new |
| 編輯問題分類 | PATCH | /manages/faq-categories/:id |
| 刪除問題分類 | DELETE | /manages/faq-categories/:id |
### [管理相關 manage](#manage)
| 說明 | Method | Path |
| ------------ | ------ | ------------------------- |
| 編輯商品審核狀態 | POST | /manages/audit |
| 取得所有用戶寄來的站內信 | GET | /manages/mails |
| 取得單一用戶寄來的站內信 | GET | /manages/mail/:id |
### P2 [使用者的平台窗口留言板 Board](#Board)
*底下僅供參考
| 說明 | Method | Path |
| ------------------------ | ------ | --------------------------- |
| 取得使用者留言板所有留言 | GET | /users/:id/board |
| 新增留言板留言 | POST | /users/:id/board/comment |
| 編輯留言板留言 | PATCH | /users/:id/board/comment/:id |
| 刪除留言板留言 | DELETE | /users/:id/board/comment/:id |
## API Details & Examples
### User
#### 註冊使用者
Request Example
```json
{
"username": "Nicolas",
"password": "1234",
"email": "123@gmail.com"
}
```
Response Example
```json
{
"ok": 1,
}
```
#### 登入使用者
Request Example
```json
{
"username": "Nicolas",
"password": "1234",
}
```
Response Example
```json
{
"ok": 1,
}
```
#### 登出使用者
Response Example
```json
{
"ok": 1,
}
```
#### 取得自己的使用者資料
Response Example
```json
{
"ok": 1,
"data": {
"userId": 1,
"username": "Nicolas Wood",
"nickname": "Nick",
"email": "test2@gmail.com",
"address": "Mars",
"role": "user",
"isVendor": "yes",
"announcment": "welcome to my store",
"account": "32189423"
"avatarUrl": "https://i.imgur.com/32145",
"bannerUrl": "https://i.imgur.com/34214",
"account": "28321235406",
"birthday": "2002/02/29"
"idCardNo": "A128376979",
"status": "normal"
}
}
```
#### 修改自己的使用者資料
Request Example
```json
{
"nickname": "123",
"email": "123@gmail.com",
"address": "456",
"account": "1234-5678-9123",
"socialmedia_id": "3213123",
"birthday": "2020-12-13",
"id_card_no": "A123456789",
"avatar_url": "https//",
"banner_url": "https//"
}
```
Response Example
```json
{
"ok": 1,
"data": "success"
}
```
#### 修改自己的密碼
Request Example
```json=
{
"oldPassword": "123",
"newPassword": "test",
"confirmPassword": "test"
}
```
Response Example
```json
{
"ok": 1,
"data": "success"
}
```
#### 修改自己的賣家公告
```json=
{
"announcement": "公告123"
}
```
Response Example
```json
{
"ok": 1,
"data": "success"
}
```
#### 取得使用者資料
Response Example
```json
{
"ok": 1,
"data": {
"userId": 1,
"username": "Nicolas Wood",
"nickname": "Nick",
"email": "test2@gmail.com",
"address": "Mars",
"role": "user",
"isVendor": "yes",
"announcment": "welcome to my store",
"account": "32189423"
"avatarUrl": "https://i.imgur.com/32145",
"bannerUrl": "https://i.imgur.com/34214",
"account": "28321235406",
"birthday": "2002/02/29"
"idCardNo": "A128376979",
"status": "normal"
}
}
```
#### 修改使用者資料
Request Example
```json
{
"nickname": "testupdate",
"email": "test@mail.com",
"address": "road",
"account": "1234-5678-9123",
"socialmedia_id": "3213123",
"birthday": "2020-01-09",
"id_card_no": "A123456789",
"avatar_url": "https//",
"banner_url": "https//"
}
```
Response Example
```json
{
"ok": 1,
"data": "success"
}
```
#### 取得所有使用者資料
Response Example
```json
{
"ok": 1,
"data": [
{
"userId": 1,
"username": "Nicolas Wood",
"nickname": "Nick",
"email": "test2@gmail.com",
"address": "Mars",
"role": "user",
"isVendor": "yes",
"announcment": "welcome to my store",
"account": "32189423"
"avatarUrl": "https://i.imgur.com/32145",
"bannerUrl": "https://i.imgur.com/34214",
"account": "28321235406",
"birthday": "2002/02/29"
"idCardNo": "A128376979",
"status": "normal"
},
{
"userId": 2,
"username": "Nicolas Wood",
"nickname": "Nick",
"email": "test2@gmail.com",
"address": "Mars",
"role": "user",
"isVendor": "yes",
"announcment": "welcome to my store",
"account": "32189423"
"avatarUrl": "https://i.imgur.com/32145",
"bannerUrl": "https://i.imgur.com/34214",
"account": "28321235406",
"birthday": "2002/02/29"
"idCardNo": "A128376979",
"status": "normal"
},
]
}
```
#### 使用者向平台寄送站內信
Request Example
```json
{
"name": "Tom",
"email": "123@gmail.com",
"phone": "0912345678",
"content": "留言"
}
```
Response Example
```json
{
"ok": 1,
"data": "success"
}
```
### Category
#### 取得所有分類
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1,
"name": "棒棒糖",
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
},
{
"id": 2,
"name": "棉花糖",
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
},
{
"id": 3,
"name": "麥芽糖",
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
}
]
}
```
### Product
#### 取得所有商品
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 2,
"name": "棒棒糖-已審核通過",
"picture_url": "https://i.imgur.com/05CXT8U.jpg",
"info": "棒棒棒",
"price": 20000,
"quantity": 1,
"delivery": 1,
"delivery_location": "台北",
"delivery_time": "2020-12-01T02:24:30.000Z",
"payment_method": 0,
"remark": null,
"status": 1,
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z",
"ProductCategoryId": 1,
"UserId": 1,
"Product_category": {
"id": 1,
"name": "棒棒糖",
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
},
"User": {
"id": 1,
"username": "John",
"password": "Doe",
"nickname": "Johnny",
"email": null,
"address": null,
"is_admin": false,
"is_vendor": false,
"announcement": null,
"account": null,
"socialmedia_id": null,
"birthday": null,
"id_card_no": null,
"avatar_url": null,
"banner_url": null,
"status": 0,
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
}
},
{
"id": 5,
"name": "棉花糖-已審核通過",
"picture_url": "https://i.imgur.com/05CXT8U.jpg",
"info": "棉棉棉",
"price": 10000,
"quantity": 1,
"delivery": 1,
"delivery_location": "台北",
"delivery_time": "2020-12-01T02:24:30.000Z",
"payment_method": 0,
"remark": null,
"status": 1,
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z",
"ProductCategoryId": 2,
"UserId": 1,
"Product_category": {
"id": 2,
"name": "棉花糖",
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
},
"User": {
"id": 1,
"username": "John",
"password": "Doe",
"nickname": "Johnny",
"email": null,
"address": null,
"is_admin": false,
"is_vendor": false,
"announcement": null,
"account": null,
"socialmedia_id": null,
"birthday": null,
"id_card_no": null,
"avatar_url": null,
"banner_url": null,
"status": 0,
"deletedAt": null,
"createdAt": "2020-12-01T02:24:30.000Z",
"updatedAt": "2020-12-01T02:24:30.000Z"
}
},
```
#### 取得該分類商品
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1
"name": "一件長袖上衣"
"categoryId": 4
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": 0
"status": 0
"UserId": 4
},
{
"id": 1
"name": "一件長袖上衣"
"categoryId": 4
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": 0
"status": 0
"UserId": 4
},
]
}
```
#### 取得賣家商品
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1
"name": "一件長袖上衣"
"category": "生活"
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": "面交"
"status": "checked"
"UserId": 4
},
{
"id": 1
"name": "一件長袖上衣"
"category": "生活"
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": "面交"
"status": "checked"
"UserId": 4
},
]
}
```
#### 搜尋已通過商品
Request Example
```json
{
"keyword": "短",
}
```
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1
"name": "一件長袖上衣"
"category": "生活"
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": "面交"
"status": "checked"
"UserId": 4
},
{
"id": 1
"name": "一件長袖上衣"
"category": "生活"
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": "面交"
"status": "checked"
"UserId": 4
},
]
}
```
#### 取得單ㄧ商品詳細資料
Response Example
```json
{
"ok": 1,
"data": {
"id": 1
"name": "一件長袖上衣"
"category": "生活"
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": "面交"
"status": "checked"
"UserId": 4
}
}
```
#### 新增商品
FORM Example
```json
{
"name": "一件長袖上衣"
"category": "生活"
"pictureUrl": "https://i.imgur.com"
"info": "讚讚"
"price": 4
"quantity": 1
"delivery": "面交"
"UserId": 4
}
```
Response Example
```json
{
"ok": 1,
"productId": "2",
}
```
#### 編輯商品
Request Example
```json
{
"id": 1,
"name": "一件長袖上衣",
"category": "生活",
"pictureUrl": "https://i.imgur.com",
"info": "讚讚",
"price": 4,
"quantity": 1,
"delivery": "面交",
"status": "checked",
"UserId": 4
}
```
Response Example
```json
{
"ok": 1,
"data": {
"productId": 1,
"status": "success"
}
}
```
#### 刪除商品
Response Example
```json
{
"ok": 1,
"productId": 1,
}
```
### Cart
#### 取得購物車商品
Response Example
```json
{
"ok": 1,
"data": {
"seller2": [
{
"cartItemId": 3,
"sellerId": 2,
"productName": "測試商品3",
"productId": 3,
"pictureUrl": "https://i.imgur.com/05CXT8U.jpg",
"price": 5000,
"quantity": 1
}
],
"seller3": [
{
"cartItemId": 1,
"sellerId": 3,
"productName": "測試商品1",
"productId": 1,
"pictureUrl": "https://i.imgur.com/05CXT8U.jpg",
"price": 20000,
"quantity": 1
},
{
"cartItemId": 2,
"sellerId": 3,
"productName": "測試商品2",
"productId": 2,
"pictureUrl": "https://i.imgur.com/05CXT8U.jpg",
"price": 10000,
"quantity": 1
}
]
}
}
```
#### 新增購物車商品
Request Body
```jsx
productId
quantity
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 編輯購物車商品
Request Body
```jsx
quantity
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 刪除購物車商品
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 刪除購物車同賣家商品
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
### Order
#### 取得全部訂單列表
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1,
"orderNumber": "AC131247",
"shipping": "面交",
"content": "淡水河旁面交",
"createdAt": "2020-11-15-14:30",
"status": {
"isPaid": "false",
"isSent": "false",
"isCompleted": "false",
"isRefunded": "false",
}
},
{
"id": 2,
"orderNumber": "AC1312534",
"content": "101旁面交",
"createdAt": "2020-11-15-14:30",
"status": {
"isPaid": "false",
"isSent": "false",
"isCompleted": "false",
"isRefunded": "false",
}
},
]
}
```
#### 取得自己買的訂單列表
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1,
"orderNumber": "AC131247",
"shipping": "面交",
"content": "淡水河旁面交",
"createdAt": "2020-11-15-14:30",
"status": {
"isPaid": "false",
"isSeent": "false",
"isCompleted": "false",
"isRefunded": "false",
}
},
{
"id": 2,
"orderNumber": "AC1312534",
"content": "101旁面交",
"createdAt": "2020-11-15-14:30",
"status": {
"isPaid": "false",
"isSent": "false",
"isCompleted": "false",
"isRefunded": "false",
}
},
]
}
```
#### 取得自己賣的訂單列表
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1,
"orderNumber": "AC131247",
"shipping": "面交",
"content": "淡水河旁面交",
"createdAt": "2020-11-15-14:30",
"status": {
"isPaid": "false",
"isSent": "false",
"isCompleted": "false",
"isRefunded": "false",
}
},
{
"id": 2,
"orderNumber": "AC1312534",
"content": "101旁面交",
"createdAt": "2020-11-15-14:30",
"status": {
"isPaid": "false",
"isSent": "false",
"isCompleted": "false",
"isRefunded": "false",
}
},
]
}
```
#### 取得單一訂單明細
Response Example
```json
{
"ok": 1,
"data": {
"id": 2,
"orderNumber": "AC1312534",
"totalQuantity": 1,
"totalAmount": 600,
"shipping": "面交",
"content": "101旁面交",
"createdAt": "2020-11-15-14:30"
"seller": {
"id": 3,
"name": "Nicolas",
"email": "lidemy@lidemy.com",
"phone": "0928476617",
"address": "台北101",
}
"client": {
"id": 4,
"name": "Ruofan",
"email": "lidemy@lidemy.com",
"phone": "0928476617",
"address": "台北101",
}
"status": {
"isPaid": "false",
"isSent": "false",
"isCompleted": "false",
"isRefunded": "false"
}
}
}
```
#### 成立訂單
- 新增一張訂單 orders
- 有訂單之後，把購物車商品新增成這張訂單的訂單商品 order_items
- 同時要把要下單的購物車商品從購物車裡刪掉 cart_items
Request Example
```json
[
{
"product_quantity":10,
"ProductId":3,
"UserId":3
},
{
"product_quantity":1,
"ProductId":4,
"UserId":3
},
{
"product_quantity":2,
"ProductId":5,
"UserId":3
}
]
```
Response Example
```json
{
"ok": 1,
"orderNumber": "202011201234",
}
```
#### 訂單完成
買家點選「完成付款」，要驗證使用者是否和該訂單的 client_id 一樣
Response Example
```json
{
"ok": 1,
"data": {
"isCompleted": "1",
"updatedAt": "2020-11-15-14:30"
}
}
```
#### 訂單付款
買家點選「訂單付款」，要驗證使用者是否和該訂單的 client_id 一樣
Response Example
```json
{
"ok": 1,
"data": {
"isPaid": "1",
"updatedAt": "2020-11-15-14:30"
}
}
```
#### 訂單出貨
賣家點選「訂單付款」，要驗證使用者是否和該訂單的 seller_id 一樣
Response Example
```json
{
"ok": 1,
"data": {
"isSent": "1",
"updatedAt": "2020-11-15-14:30"
}
}
```
#### 訂單取消
賣家點選「訂單取消」，要驗證使用者是否和該訂單的 seller_id 或 client_id 一樣
Response Example
```json
{
"ok": 1,
"data": {
"isCanceled": "1",
"updatedAt": "2020-11-15-14:30"
}
}
```
#### 刪除訂單
Response Example
```json
{
"ok": 1,
"updatedAt": "2020-11-15-14:30"
}
```
### Rule
#### 取得所有條款資料
Response Example
```json
{
"ok": 1,
"data": [
{
"id": 1,
"rule": "隱私權條款",
"content": "測試測試測試測試"
},
{
"id": 2,
"rule": "免責聲明",
"content": "測試測試測試測試"
},
]
}
```
#### 取得單一條款資料
Response Example
```json
{
"ok": 1,
"data": {
"id": 1,
"rule": "隱私權條款",
"content": "測試測試測試測試"
}
}
```
#### 新增條款
Request Body
```jsx
rule
content
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 編輯條款
Request Body
```jsx
rule
content
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 刪除條款
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
### FAQ
#### 取得所有常見問題
Response Example
```json
{
"ok": 1,
"data": {
"faqId": 1,
"question": "可以亂賣東西嗎？",
"faqCategory": "常見問題",
"answer": "不行哦，不要欺負我 QQ"
}
}
```
#### 新增常見問題
Request Body
```jsx
question
answer
faqCategoryId
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 編輯常見問題
Request Body
```jsx
question
answer
faqCategoryId
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 刪除常見問題
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
### FAQ-Category
#### 新增問題分類
Request Body
```jsx
name
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 編輯問題分類
Request Body
```jsx
name
```
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
#### 刪除問題分類
Response Example
```json
{
"ok": 1,
"message": "success"
}
```
### Board
#### 取得所有留言板
Response Example
```json
{
"ok": 1,
"data": [
{
"boardId": "1",
"isArchived": false,
"updatedAt": "2020-11-10-12:20",
"comments": [
{
"id": 1,
"cotent": "哈囉"
},
{
"id": 2,
"cotent": "早安安"
}
]
},
{
"boardId": "2",
"isArchived": true,
"updatedAt": "2020-11-10-12:20",
"comments": [
{
"id": 1,
"cotent": "哈囉"
},
{
"id": 2,
"cotent": "早安安"
}
]
}
]
}
```
#### 取得留言板所有訊息（打開使用者的留言板）
Response Example
```json
{
"ok": 1,
"data": {
"userId": "1",
"comments": [
{
"id": 1,
"cotent": "哈囉"
},
{
"id": 2,
"cotent": "早安安"
}
]
}
}
```
#### 新增留言板留言
Request Example
```json
{
"userId": "1",
"commentContent": "測試測試"
}
```
Response Example
```json
{
"ok": 1,
"userId": "1",
}
```
#### 編輯留言板留言
Request Example
```json
{
"userId": "1",
"commentId": "4",
"commentContent": "編輯測試測試"
}
```
Response Example
```json
{
"ok": 1,
"userId": "1",
}
```
#### 刪除留言板留言
Response Example
```json
{
"ok": 1,
"userId": "1",
}
```
Sign in with Wallet
Connect another wallet