# GACHA API
The api provides functionalities that allow user to purchase and ship gachapons online via a website.
## Endpoints
Below are a list of endpoints that are made available for developers. All required data are to be sent over as json objects unless otherwise stated. Relevant results from query are returned as a json object with a key of "data" (see example below).
```json
{
"success": true,
"data": "some result",
}
```
### $\color{Orange}{\textsf{Authentication}}$
**GET** `/api/auth/check-auth`
Checks if the user is logged in
**POST** `/api/auth/refresh`
Request for access token refresh
**POST** `/api/auth/signup`
Create a new user and send out a verification email
```json
"email": "example@email.com",
"name": "John Smith",
"password": "123456",
"country": 1 // id can be retrieved from /api/country
```
**POST** `/api/auth/verify-email`
Verify and initialise the user
```json
"token" : "5bd136b5-5f29-4a91-ac58-79c2c0700b60"
```
**POST** `/api/auth/resend-verify`
Send out an email with a new link for verification
```json
"id": 15 // user id
```
**POST** `/api/auth/login`
Log in user
```json
"email": "example@email.com",
"password": "123456"
```
**POST** `/api/auth/logout`
Log off user
**POST** `/api/auth/logout-all`
Log out all devices for a user
**POST** `/api/auth/forgot-password`
Send out an email with link to reset password
```json
"email": "example@email.com"
```
**POST** `/api/auth/reset-password/:token`
Update password from reset link
```json
"password": "abc123"
```
**POST** `/api/auth/create-admin`
Create an admin user
```json
"email": "example@email.com",
"name": "Jane Doe",
"password": "123456",
"pin": "secretpin",
"country": 1 // id can be retrieved from /api/country
```
**GET** `/api/auth/all` `Admin Only`
Retrieve all verified users
**PATCH** `/api/auth/activate/:id` `Admin Only`
Activate a user
**PATCH** `/api/auth/deactivate/:id` `Admin Only`
Deactivate a user
**POST** `/api/auth/send-email` `Admin Only`
Send an email to the user
```json
"email": "example@email.com",
"subject": "Subject",
"message": "The content of the email",
```
### $\color{Orange}{\textsf{User Management}}$
**PATCH** `/api/user/update-profile`
Update user profile details
```json
"name" : "John Smith"
```
**PATCH** `/api/user/update-password`
Verify old password and update to new password
```json
"oldPassword": "123456",
"newPassword": "abc123"
```
**GET** `/api/user/addresses/:type`
Retrieve all addresses belonging to user
**GET** `/api/user/address/:id`
Retrieve the address belonging to user
**POST** `/api/user/address`
Create a new address
```json
"type": 0, // 0 - billing, 1 - shipping
"name": "John Smith",
"line1": "123 Toa Payoh Ave 6",
"line2": "#02-1234",
"city": "",
"state": "",
"postal": 123456,
"country": 0
```
**POST** `/api/user/address/default/:id`
Set address as the default address
**PATCH** `/api/user/address`
Update the address details
```json
"id": 1,
"type": 0, // 0 - billing, 1 - shipping
"name": "John Smith",
"line1": "456 Toa Payoh Ave 1",
"line2": "#11-1234",
"city": "",
"state": "",
"postal": 123456,
"country": 1
```
**DELETE** `/api/user/address/:id`
Delete the address
**GET** `/api/user/info/:id` `Admin Only`
Retrieve basic information of user
**GET** `/api/user/play-history/:id` `Admin Only`
Retrieve play history of user
**GET** `/api/user/basic-stats` `Admin Only`
Retrieve basic monthly play stats
**GET** `/api/user/top-players` `Admin Only`
Retrieve users with highest play count
### $\color{Orange}{\textsf{Transactions}}$
TBD
### $\color{Orange}{\textsf{Token Wallet}}$
**GET** `/api/wallet`
Retrieve tokens amount in wallet
**GET** `/api/wallet/topup-history`
Retrieve user top up history
**PATCH** `/api/wallet/add`
Add tokens to wallet
```json
"amount": 3
```
**PATCH** `/api/wallet/use`
Use tokens in wallet
```json
"amount": 3
```
**POST** `/api/wallet/topup-option` `Admin Only`
Add a top-up sku for user to purchase
```json
"name": "3 tokens",
"description": "Add 3 tokens to your wallet",
"cost":300,
"coins":3,
"country": 1 // id can be retrieved from /api/country
```
**PATCH** `/api/wallet/topup-option` `Admin Only`
Update a top-up sku
```json
"id":: 1
"name": "3 tokens",
"description": "Add 3 tokens to your wallet",
"cost":299,
"coins":3,
"country": 1 // id can be retrieved from /api/country
```
**DELETE** `/api/wallet/topup-option/:id` `Admin Only`
Delete a top-up sku
**PATCH** `/api/wallet/topup-option/activate/:id` `Admin Only`
Activate a top-up sku
**PATCH** `/api/wallet/topup-option/deactivate/:id` `Admin Only`
Deactivate a top-up sku
**GET** `/api/wallet/topup-option-admin` `Admin Only`
Retrieve all top up SKUs
**GET** `/api/wallet/topup-option-admin/:id` `Admin Only`
Retrieve one top up SKU with id
**GET** `/api/wallet/topup-history-admin/:id` `Admin Only`
Retrieve top up history of user
**GET** `/api/wallet/monthly-sales` `Admin Only`
Retrieve top up monthly sales
### $\color{Orange}{\textsf{Series}}$
**GET** `/api/series/all`
Retrieve all available active series
**GET** `/api/series/one/:id`
Retrieve a particular series
**GET** `/api/series/categories`
Retrieve categories for all collection
**GET** `/api/series/featured-categories`
Retrieve categories for featured collection
**GET** `/api/series/all/admin` `Admin Only`
Retrieve all available series
**POST** `/api/series/eligible:id`
Check if player has enough tokens to play
**POST** `/api/series/play:id`
Roll a capsule
**POST** `/api/series` `Admin Only`
Create a new series
```json
// multipart/form-data
"name": "Series Name",
"desc": "Short Description",
"cost": 3,
"category": 1,
"image": "IMG_1234.jpg", // FILE, NOT STRING
"type": 0, // 0 - gachapon, 1 - kuji
"tag": "anime,naruto"
```
**PATCH** `/api/series` `Admin Only`
Update series details
```json
// multipart/form-data
"id": 1,
"name": "Series Name",
"desc": "Short Description",
"cost": 3,
"category": 1,
"image": "IMG_1234.jpg", // FILE, NOT STRING
"type": 0, // 0 - gachapon, 1 - kuji
"tag": "anime,bleach"
```
**PATCH** `/api/series/activate/:id` `Admin Only`
Activate a series
**PATCH** `/api/series/deactivate/:id` `Admin Only`
Deactivate a series
**DELETE** `/api/series` `Admin Only`
Delete a series
**GET** `/api/series/category/all`
Retrieve all available categories
**GET** `/api/series/category/one/:id`
Retrieve a particular category
**POST** `/api/series/category` `Admin Only`
Create a category for series
```json
"name" : "Anime"
```
**PATCH** `/api/series/category` `Admin Only`
Update a category for series
```json
"id" : 4,
"name" : "TV"
```
**DELETE** `/api/series/category/:id` `Admin Only`
Delete a category for series
**GET** `/api/series/brand/all`
Retrieve all available brands
**GET** `/api/series/brand/one/:id`
Retrieve a particular brand
**POST** `/api/series/brand` `Admin Only`
Create a brand for series
```json
"name" : "Bandai"
```
**PATCH** `/api/series/brand` `Admin Only`
Update a brand for series
```json
"id" : 4,
"name" : "Takara Tomy"
```
**DELETE** `/api/series/brand/:id` `Admin Only`
Delete a brand for series
**POST** `/api/series/event` `Admin Only`
Create a event for series
```json
"name" : "Clearance"
```
**GET** `/api/series/event/all`
Retrieve all available events
**GET** `/api/series/event/one/:id`
Retrieve a particular event
**PATCH** `/api/series/event` `Admin Only`
Update a event for series
```json
"id" : 1,
"name" : "Offer"
```
**DELETE** `/api/series/event/:id` `Admin Only`
Delete a event for series
**GET** `/api/series/one-simple/admin/:id` `Admin Only`
Retrieve basic information of series
**GET** `/api/series/top-played` `Admin Only`
Retrieve the most played series for the month
**GET** `/api/series/featured` `Admin Only`
Retrieve featured series
**GET** `/api/series/running-low` `Admin Only`
Retrieve series with stock under set threshold
### $\color{Orange}{\textsf{Prizes}}$
**POST** `/api/prizes` `Admin Only`
Create a new prize and add it to a series
```json
// multipart/form-data
"id": 1, // series id
"name": "Prize Name",
"stock": 10,
"image": "IMG_1234.jpg" // FILE, NOT STRING
```
**PATCH** `/api/prizes` `Admin Only`
Update prize details
```json
// multipart/form-data
"id": 1, // prize id
"name": "Prize Name",
"stock": 10,
"image": "IMG_1234.jpg" // FILE, NOT STRING
```
**PATCH** `/api/prizes/won`
Reduce count of prize by 1.
```json
"id" : 7 // prize id
```
**PATCH** `/api/prizes/restock` `Admin Only`
Add count of prize by a specified amount.
```json
"id": 4, // prize id
"amount": 5
```
**DELETE** `/api/prizes/:id` `Admin Only`
Delete a prize
### $\color{Orange}{\textsf{Locker}}$
**GET** `/api/locker/all/:status`
Retrieve locker of user
````json
// status
// 0 - await shipping
// 1 - ordered
// 2 - expired
// 3 - discarded
````
**GET** `/api/locker/has-space`
Check if locker is full
**PATCH** `/api/locker`
Add prize to a locker
```json
"id": 4 // prize id
```
**POST** `/api/locker/order`
Shift prizes in locker to shipping order.
```json
"lockersId": [2,3,8,9], // array of locker id
"addressId": 7
```
**POST** `/api/locker/forfeit`
Discard prize in locker.
```json
"id": 13, // locker id
"prizeId": 4
```
**GET** `/api/locker/forfeited` `Admin Only`
Retrieve forfeited prizes
**PATCH** `/api/locker/forfeited` `Admin Only`
Update forfeited prize status and set memo
```json
"id": 1,
"status": 2
"memo": "This is a memo"
```
### $\color{Orange}{\textsf{Shipping}}$
**GET** `/api/shipping`
Get all basic shipping orders of user
**GET** `/api/shipping/one/:orderId`
Get shipping details for one order
**PATCH** `/api/shipping`
Update address for order
```json
"orderId": "26-1770194264233",
"addressId": 6
```
**GET** `/api/shipping-history-admin/:id` `Admin Only`
Retrieve shipping history of user
**GET** `/api/shipping/all` `Admin Only`
Retrieve all shipping details
**GET** `/api/shipping/all/:status` `Admin Only`
Retrieve all shipping details of a particular status
**PATCH** `/api/shipping/status` `Admin Only`
Update shipping status
```json
"orderId": "26-1770194264233",
"status": 1 // 0 - pending, 1 - processing, 2 - shipped
```
**PATCH** `/api/shipping/tracking` `Admin Only`
Update tracking number and memo
```json
"orderId": "26-1770194264233",
"tracking": "abcdefgh",
"memo": "Thank you"
```
**GET** `/api/shipping/shipping-option`
Retrieve available shipping options
**GET** `/api/shipping/shipping-option-admin` `Admin Only`
Retrieve available shipping options for admin
**GET** `/api/shipping/shipping-option-admin/:id` `Admin Only`
Retrieve one shipping options for admin
**POST** `/api/shipping/shipping-option` `Admin Only`
Add a shipping sku for user to purchase
```json
"name": "Standard Shipping",
"description": "Standard International Shipping",
"cost":499,
"trackingLink": "https://www.speedpost.com.sg",
"country": 1 // id can be retrieved from /api/country
```
**PATCH** `/api/shipping/shipping-option` `Admin Only`
Update a shipping sku
```json
"id": 1,
"name": "Standard Shipping",
"description": "Standard International Shipping",
"cost":399,
"trackingLink": "https://www.speedpost.com.sg",
"country": 1 // id can be retrieved from /api/country
```
**DELETE** `/api/shipping/shipping-option/:id` `Admin Only`
Delete a shipping sku
**PATCH** `/api/shipping/shipping-option/activate/:id` `Admin Only`
Activate a shipping sku
**PATCH** `/api/shipping/shipping-option/deactivate/:id` `Admin Only`
Deactivate a shipping sku
**GET** `/api/shipping/monthly-sales` `Admin Only`
Retrieve shipping order monthly sales
### $\color{Orange}{\textsf{Country}}$
**GET** `/api/country`
Retrieve all activated countries
**GET** `/api/country/all` `Admin Only`
Retrieve all available countries
**GET** `/api/country/one/:id` `Admin Only`
Retrieve one country
**POST** `/api/country` `Admin Only`
Add a country
```json
"longName": "Singapore",
"shortName": "SG",
"currency": "SGD"
```
**PATCH** `/api/country` `Admin Only`
Update a country
```json
"id": 1,
"longName": "Singapore",
"shortName": "SG",
"currency": "SGD"
```
**DELETE** `/api/country/:id` `Admin Only`
Delete a country
**PATCH** `/api/country/activate/:id` `Admin Only`
Activate a country
**PATCH** `/api/country/deactivate/:id` `Admin Only`
Deactivate a country
### $\color{Orange}{\textsf{News}}$
**GET** `/api/news`
Retrieve news
**PATCH** `/api/news` `Admin Only`
Update news for news ticker
```json
"content": "News content",
```
## Error Codes
The table below shows the different error codes that can be returned by the api. It can be retrieved by reading the **errcode** key from the return object, e.g.
```json
{
"success": false,
"errcode": 1001,
}
```
| Code | Description |
|:----:|:------------|
|1000| Server error
|1001| Database connection error
|1002| Uncaught error
|1003| Missing/invalid required data
|1004| Reject existing user (Sign Up)
|1005| Reject deactivated user
|1006| Non-existent/invalid user
|1007| Invalid credentials provided
|1008| Invalid token provided
|1009| Token expired
|1010| Email already verified (Verify Email)
|1011| Non-existent/invalid address
|1012| User account setup error, contact system admin
|1013| Non-existent/invalid wallet
|1014| Insufficient tokens
|1015| Invalid admin creation pin
|1016| Forbidden access
|1017| Reject deletion, in use
|1018| Reject deactivated series
|1019| Locker is full
|1020| Machine has ran out of capsule
|1021| Invalid order
|1022| Email not verified
|1023| Invalid brand
|1024| Invalid category
|1025| Invalid prize
|1026| Invalid SKU
|1027| Invalid country
|1028| Reject deactivated country
|1029| Invalid Series
|1030| Invalid Event
|1031| Series contains prizes, reject deletion