API Documentation

1-n Relationships and Include Orders

To display orders related to a transaction, use the parameter includeOrders=true in

the URL or request.

Filter
For filtering, use parameters in the URL or request. For example:

 To filter transactions with total_money greater than 100,000, add ?

totalMoney[gt]=100000 to the URL or request.

 All the field in every table can be filtered with the format like example above. But it

has to make sense, it will not work if you pass like ?address[gt]=”KTX khu A”

Operator Map
Use the following operators corresponding to filter:

 'eq' (equal) corresponds to =

 'lt' (less than) corresponds to <

 'gt' (greater than) corresponds to >

 'lte' (less than or equal) corresponds to <=

 'gte' (greater than or equal) corresponds to >=

Search
Applicable only for GET requests to /products. Pass it in the URL like api/products?

search=Plant to search for products with the name "Plant".

Combine Filter and Search
To combine filter and search, pass parameters in the URL. For example: /products?

search=Plant&categoryId[eq]=1 to search for products with the name "Plant" and

belonging to category with id = 1.

Sort Ascending/Descending
Applicable only for GET requests to /products. Pass it in the URL like:

 /products?orderBy=price to sort by price in ascending order.

 /products?orderBy=price-desc to sort by price in descending order.

 Replace price with other fields like view, sold, discount, createdAt.

Categories

 Get All Categories

Route: /api/categories

Method: GET

Data Send: includeProducts (true/false), filter

Response: includeProducts=false: Show data category, includeProducts=true: Show

data category with products

Token: none.

 Get Category by ID

Route: /api/categories/{id}

Method: GET

Data Send: includeProducts (true/false), id

Response: Show category with the given ID

Token: none.

 Create New Category

Route: /api/categories

Method: POST

Data Send:

Response: Create new category (Admin only)

Token: admin.

 Update Category

Route: /api/categories/{id}

Method: PATCH

Data Send: id

Response: Update category with the given ID (Admin only)

Token: admin.

 Delete Category

Route: /api/categories

Method: DELETE

Data Send: id

Response: Delete category with the given ID (Admin only).

{
"message": "Success"
}
Token: admin.

Products

 Get All Products

Route: /api/products

Method: GET

Data Send: filter, search, orderBy

Response: Show data product.

{
"id": 1,
"name": "Cây Ngọc Bích",
"price": 170000,
"imgPath": "https://cayxinh.vn/wp-content/uploads/2018/01/cay-ngoc-bich-1208192-
400x400.jpg",
"content": "",
"quantity": 10,
"sold": 0,
"view": 0,
"slug": "cay-ngoc-bich",
"discount": 0,
"categoryId": 2,
"createdAt": "2023-10-28 16:32:15",
"updatedAt": "2023-11-11 13:41:50"
},
Token: none.

 Get Product by ID

Route: /api/products/{id}

Method: GET

Data Send: id
 Response: Show product with the given ID.

Token: none.

 Create New Product

Route: /api/products

Method: POST

Data Send:

Response: Create new product (Admin only). New product.

Token: admin.

 Update Product

Route: /api/products/{id}

Method: PATCH

Data Send: id

'name'=>['sometimes', 'required'],
'price'=>['sometimes', 'required'],
'imgPath'=>['sometimes', 'required'],
'contents'=>['sometimes', 'required'],
'quantity'=>['sometimes', 'required'],
'sold'=>['sometimes', 'required'],
'view'=>['sometimes', 'required'],
'categoryId'=>['sometimes', 'required']
 Response: Update product with the given ID (Admin only)

{
"message": "Success"
}
Token: admin.

 Delete Product

Route: /api/products/{id}

Method: DELETE

Data Send: id

Response: Delete product with the given ID (Admin only)

{
"message": "Success"
}
Token: admin

Users

 Configure Settings for sending email (email is for testing, not

real email).

We use https://mailtrap.io/ for sending email. You need to login before testing.

After login, follow these steps for setting:

 Click on the Start Testing in Email Testing.

 Choose Laravel 9+ in Intergrations.

 Copy the document and paste into .env.

Copy and paste into:

An email sending will have two important key: token and email. You can use them for next

actions like updating new password and verification email.

1. Verification email for login.

Go to: \backend\app\Http\Controllers\User\UserAuth.php

Update the redirect in the completeRegister function to the URL you want to appear when

a user clicks the link in the email.

2. Verification email for reset password.

Go to: \backend\resources\views\forget-password.blade.php

Update the href in the a tags to the URL which you want to appear if a user click it.
And do not delete token and email if you want to send them in the next actions.

 Sending email for new password.

 Route: /forget-password

 Method: POST

 Data Send: email

 {
 "email": "[email protected]"
 }

 Response:

 {
 "message": "Success"
 }
or fail with error 404 if email is not in database.
{
"message": "Not found"
}

For testing, you go to inboxes in https://mailtrap.io/ with account logged in. You will see a

testing mail to your email testing.

 Updating new Password.

 Route: /reset-password

 Method: POST

 Data Send: new password (input from the front-end), email and token already

available in the URL.

 {
 "email": "[email protected]",
 "password":"user",
 "token":"15b7HtzAk9e36irqxvYUj2Z4SeKrWzvwQoAaBrL7Ogo7Htb5CrUDBF16Pv6JY6p3"
 }

 Response:

 {
 "message": "Change password success"
 }
Or fail with the message:
{
"message": "Invalid"
}

 Register

Route: /register

Method: POST

Data Send:

$request->validate([
'email' => 'required|unique:users,email',
'password' => ['required'],
]);

{
"email": "[email protected]",
"password":"user"
}

Response:

{
"message": "Please verify email"
}
For testing, you should check the email like the instruction in Sending email for new

password section above.

Remember, a user must verify email before login or else it will fail.

After

Token: none.
  Login

Route: /login

Method: POST

Data Send:

$credentials = $request->validate([
'email' => ['required', 'email'],
'password' => ['required'],
]);

Response: Login user

{
"token": "66|8EGKp3ERu9GvsU39VjccKQK6ufYdypNFhHoL4Nsu2867bfe3",
"userId": 31,
"message": "Login Success"
}
Or fail with the message if wrong email or password:

{
"message": "Not found"
}

Or fail with the message if user not verify email:

{
"message": "Please verify email"
}

Token: none

 Logout

Route: /logout

Method: GET
 Response: Logout user

{
"message": "Logout Success"
}
Token: user

 Get User by ID

Route: /api/user/{id}

Method: GET

Data Send: id

Response: Show user's information with the given ID

{
"data": {
"userId": 31,
"email": "[email protected]",
"name": null,
"address": null,
"phone": null,
"createdAt": "2023-11-12 14:53:38",
"updatedAt": "2023-11-12 14:53:38"
}
}
Token: user

 Update User

Route: /api/user/{id}

Method: PATCH

Data Send: id

'email' => 'sometimes|required|unique:users,email',

'password'=>'sometimes|required',
'address'=>'sometimes|required',
'phone'=>['sometimes','required'],
'name'=>'sometimes|required'
 Response: Update user's information with the given ID (User only)

{
"message": {
"name": "Tùng",
"address": "KTX A",
"phone": "0335664121",
"Address": "KTX A",
"Phone": "0335664121",
"Name": "Tùng"
}
}

Cart

 Get User Cart

 Route: /api/cart

 Method: GET

 Data Send: filter. If you want to show all the Cart of a user who has User_ID = 31. You

should send: /api/cart?userId[eq]=31.

 Response: All the carts after filtering.

{
"data": [
{
"id": 4,
"productId": 1,
"productName": "Cây trồng",
"productPrice": 1200000,
"quantity": 120,
"userId": 31,
"status": 0,
"createdAt": "2023-11-18T07:05:20.000000Z",
"updatedAt": "2023-11-18T07:05:20.000000Z"
},
{
"id": 5,
"productId": 4,
"productName": "Cây Vui",
"productPrice": 1200000,
"quantity": 120,
"userId": 31,
 "status": 0,
"createdAt": "2023-11-18T07:17:14.000000Z",
"updatedAt": "2023-11-18T07:17:14.000000Z"
}
]
}

 Create a new Cart

 Route: /api/cart

 Method: POST

 Data Send:

 {
 "productId": 5,
 "productName": "CÂy",
 "productPrice": 10000,
 "quantity": 12000,
 "userId": 45,
 "status": 0,
 "imgPath": "example.com"
 }

 Response: new Cart.

 {
 "data": {
 "id": 2,
 "productId": 5,
 "productName": "CÂy",
 "productPrice": 10000,
 "quantity": 12000,
 "userId": 45,
 "status": 0,
 "imgPath": "example.com",
 "createdAt": "2023-12-04T13:00:13.000000Z",
 "updatedAt": "2023-12-04T13:00:13.000000Z"
 }
 }
  Update the Carts

 Route: /api/cart

 Method: PATCH

 Data Send: An array of object of Carts which requiring cartId in every object.

 cartId => ['required'],

 productId => ['sometimes', 'required'],
 productName => ['sometimes', 'required'],
 productPrice => ['sometimes', 'required'],
 quantity => ['sometimes', 'required'],
 userId => ['sometimes', 'required'],
 status => ['sometimes', 'required']
 imgPath => ['sometimes', 'required']


Ex: update carts have cartId = 4 and 5. You should send json like below which will update

status of cartId = 4 to 1, productId of cartId = 5 to 3 and status to 1.

[
{
"cartId": 4,
"status": 1
},
{
"cartId": 5,
"productId": 3,
"status": 1
}
]

 Response:

 {
 "message": "Success"
 }
  Delete a Cart by ID

 Route: /api/cart/destroy/{id}

 Method: DELETE

 Data Send: id

 Response: Delete a cart has the given id.

 Delete Carts

 Route: /api/cart/bulkdestroy

 Method: DELETE

 Data Send: filter.

Ex: If you want to delete Carts which have userId = 31 and status = 1. You should pass URL

like this:

/api/cart/bulkdestroy?userId[eq]=31&status[eq]=1

 Response: Delete carts after filtered.

 {
 "message": "Success"
 }

Transactions

 Get Transaction by ID

Route: /api/transactions/{id}

Method: GET
 Data Send: id, includeOrder (true/false)

Response: Show transaction with the given ID and the user buy it.

{
"data": [
{
"id": 1,
"phone": "empty",
"address": "empty",
"status": 0,
"totalMoney": 100000,
"paymentMethod": null,
"note": "",
"createdAt": "2023-11-12 22:00:29",
"updatedAt": "2023-11-12 22:00:29",
"purchaser": {
"userId": 31,
"email": "[email protected]",
"name": "Tùng",
"address": "KTX A",
"phone": "0335664121",
"createdAt": "2023-11-12 21:59:14",
"updatedAt": "2023-11-12 14:59:14"
}
}
]
}
Token: user.

 Create Transaction

Route: /api/transactions

Method: POST

Data Send:

'userId'=>['required'],
'name'=>['sometimes', 'required'],
'phone'=>['sometimes', 'required'],
'address'=>['sometimes', 'required'],
'status'=>['sometimes', 'required'],
'totalMoney'=>['sometimes', 'required'],
'paymentMethod'=>['sometimes', 'required'],
'note'=>['sometimes', 'required']

Response: Create a new transaction (User only). If user already has transaction
 which is empty (Status = 0), it will be invalid

{
"message": "Invalid"
}
else it will create a new empty transaction.

{
"transactionId": 11,
"message": "Create new Transaction Successfully"
}
Token: user

Update Transaction

Route: /api/transactions/{id}

Method: PATCH

Status = 0 : don’t purchase

Status = 1: purchased

Status = 2 : received

Status = 3 : canceled

Data Send: id,

'userId'=>['sometimes', 'required'],
'name'=>['sometimes', 'required'],
'Phone'=>['sometimes', 'required'],
'address'=>['sometimes', 'required'],
'status'=>['sometimes', 'required'],
'totalMoney'=>['sometimes', 'required'],
'paymentMethod'=>['sometimes', 'required'],
'note'=>['sometimes', 'required']

Response: Update transaction with the given ID (User only)

{
"message": "Success"
}
Token: user
  Delete Transaction

Route: /api/transactions/{id}

Method: DELETE

Data Send: id

Response: Delete transaction with the given ID (User only)

{
"message": "Success"
}

 Get User Transactions

Route: /api/user/{userId}/transactions

Method: GET

Data Send: userId, filter, includeOrder (true/false)

Response: Show all transactions of a user has the given ID

{
"data": [
{
"id": 1,
"phone": "empty",
"address": "empty",
"status": 5,
"totalMoney": 100000,
"paymentMethod": null,
"note": "",
"createdAt": "2023-11-12 22:00:29",
"updatedAt": "2023-11-12 22:00:29",
"purchaser": {
"userId": 31,
"email": "[email protected]",
"name": "Tùng",
"address": "KTX A",
"phone": "0335664121",
"createdAt": "2023-11-12 21:59:14",
"updatedAt": "2023-11-12 14:59:14"
 }
}
]
}
Token: user

Orders

 Get All Orders

Route: /api/orders

Method: GET

Data Send: filter

Response: Show all orders

{
"data": [
{
"id": 1,
"productId": 2,
"productName": "LALALA",
"productPrice": 10000,
"quantity": 12000,
"createdAt": "2023-11-12 22:13:37",
"updatedAt": "2023-11-12 22:13:37"
}
]
}

 Get Order by ID

Route: /api/orders/{id}

Method: GET

Data Send: id

Response: Show order with the given ID

 Create Orders in Bulk

Route:
 Method: POST

Data Send: An array of orders

'*.productId'=>['required'],
'*.productName'=>['required'],
'*.productPrice'=>['required'],
'*.quantity'=>['required'],
'*.transactionId'=>['required'],

[
{
"productId": 3,
"productName": "LALALA",
"productPrice": 10000,
"quantity": 12000,
"transactionId": 1
},
{
"productId": 4,
"productName": "LA",
"productPrice": 10000,
"quantity": 120,
"transactionId": 1
}
]
Response: Store an array of orders into the database (User only)

{
"message": "Success"
}
Token: user

 Update Order

Route: /api/order/{id}

Method: PATCH

Data Send: id

'productId'=>['sometimes','required'],
'productName'=>['sometimes','required'],
'productPrice'=>['sometimes','required'],
'quantity'=>['sometimes','required'],
'transactionId'=>['sometimes','required'],
 Response: Update an order with the given ID (User only)

{
"message": "Success"
}

 Delete Order

Route: /api/order/{id}

Method: DELETE

Data Send: id

Response: Delete an order with the given ID (User only)

{
"message": "Success"
}

Payment

 Setting for payment

Go to: \backend\app\Http\Controllers\Api\PaymentController.php

Change the URL in the redirect to the URL you want to appear after user finishes their

payment.

Change the status you want to update for the transaction after the user finishes their

payment.
  COD

 Route: /api/payment_cod

 Method: POST

 Data Send: transactionId

 {
 "transactionId": 1
 }

 Response: the page in the redirect section. For instance, it is the example.com like the

instruction above and update the transaction’s status.

  MOMO (Only test, not real).

 Route: /api/payment_momo

 Method: POST

 Data Send: transactionId

 {
 "transactionId": 1
 }

 Response: a json data

 {
 "partnerCode": "MOMOBKUN20180529",
 "orderId": "1701077895",
 "requestId": "1701077895",
 "amount": 12000,
 "responseTime": 1701078154021,
 "message": "Thành công.",
 "resultCode": 0,
 "payURL": "https://test-payment.momo.vn/v2/gateway/pay?
t=TU9NT0JLVU4yMDE4MDUyOXwxNzAxMDc3ODk1&s=6805a0f151ec9252919ba2a3eabf3b4bbfbcf7f69efccf
090c9edddac7b4d17e",
 "signature": "31962682a4fbad5fff07276639f9856a80ba94a3837479458c4c29fe5d7e12ac"
 }

Next, you must redirect the page to the website that has the payURL in the JSON

 "payURL": "https://test-payment.momo.vn/v2/gateway/pay?
t=TU9NT0JLVU4yMDE4MDUyOXwxNzAxMDc3ODk1&s=6805a0f151ec9252919ba2a3eabf3b4bbfbcf7f69efccf
090c9edddac7b4d17e",
It will appear the momo website for payment. You need to fill in the blank using bank

account below:

Tên: NGUYEN VAN A

Số thẻ: 9704 0000 0000 0018

Ngày phát hành: 03/07

OTP: OTP
 The final response is the website in the redirect section above. For instance, it is the

example.com

Admin

 Admin Login

Route: /admin/login

Method: POST

Response: Admin login

 Admin Logout

Route: /admin/logout

Method: GET

Response: Admin logout

 Token: admin

 Get All Transactions (Admin)

Route: /api/transactions

Method: GET

Data Send: filter, includeOrder (true/false)

Response: Show all transactions in the database (Admin only)

Token: admin

 Get Transactions in Period (Admin)

Route: /api/transactions/period

Method: POST

Data Send: period

{
"period": 5
}

Response: Show transactions in a period of days (Admin only)

{
"data": [
{
"id": 1,
"phone": "empty",
"address": "empty",
"status": 5,
"totalMoney": 100000,
"paymentMethod": null,
"note": "",
"createdAt": "2023-11-12 22:00:29",
"updatedAt": "2023-11-12 22:00:29",
"purchaser": {
"userId": 31,
"email": "[email protected]",
"name": "Tùng",
 "address": "KTX A",
"phone": "0335664121",
"createdAt": "2023-11-12 21:59:14",
"updatedAt": "2023-11-12 14:59:14"
}
}
]
}

 Get Products Statistics (Admin)

Route: /api/statistics/products

Method: GET

Data Send: period (sometimes, required)

{
"period": 5
}

Response: Show products statistics in a period of days (Admin only)

"productId": 1,
"name": "Cây Ngọc Bích",
"totalSold": 0,
"avgSoldPerDay": 0,
"totalRevenue": 0
Token: admin

 Get Product Statistics by ID (Admin)

Route: /api/statistics/products/{id}

Method: GET

Data Send: id, period (sometimes, required)

Response: Show a product's statistics with the given ID (Admin only)

Token: admin
  Get All Users (Admin)

Route: /api/admin/allUsers

Method: GET

Data Send: filter

Response: Show all users after filtered (Admin only)

{
"data": [
{
"userId": 31,
"email": "[email protected]",
"name": "Tùng",
"address": "KTX A",
"phone": "0335664121",
"createdAt": "2023-11-12 21:59:14",
"updatedAt": "2023-11-12 14:59:14"
}
]
}
Token: admin

 Create User (Admin)

Route: /api/createUser

Method: POST

Data Send:

'email' => 'required|unique:users,email',

'password' => ['required'],

Response: Admin can create a user (Admin only)

{
"message": "Create Success"
}
  Delete User (Admin)

Route: /api/users/{id}

Method: DELETE

Data Send: id

Response: Admin can delete a user with the given ID (Admin only)

{
"message": "Delete Success"
}

 Get Online Users (Admin)

Route: /api/userOnline

Method: GET

Response: Admin can see the users who are online (Admin only)

Note
Fields in red are required in the request.

Fields with "sometimes" are optional in the request.

Fields with "required" must be included in the request.

Upon login, the server will respond with a token and user ID. The frontend uses it for

necessary functionalities.

When creating a product, category, transaction, or order, the server responds with

necessary information like ID for further functionalities.

Admin accounts:

 Email: [email protected]
  Email: [email protected]

 Email: [email protected]

 Email: [email protected]

 Email: [email protected]

 Password: admin

Missing functional api:

 Login session.

 Real-time chat room.