Scribd
Upload
26 views61 pages

SAM Final API Document

The document outlines an authentication module and management system for a salon application, detailing API endpoints for user login, registration, and profile management for super admins, salon staff, and customers. It also includes staff management, service management, package management, and customer management functionalities, specifying the request and response structures for each operation. Each section is designed for different roles (Admin, Staff, Customer) with clear instructions on how to interact with the API.

Uploaded by

harshalmore115
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
26 views61 pages

SAM Final API Document

The document outlines an authentication module and management system for a salon application, detailing API endpoints for user login, registration, and profile management for super admins, salon staff, and customers. It also includes staff management, service management, package management, and customer management functionalities, specifying the request and response structures for each operation. Each section is designed for different roles (Admin, Staff, Customer) with clear instructions on how to interact with the API.

Uploaded by

harshalmore115
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd

🔐 AUTHENTICATION MODULE (START)

Common Notes (Auth – Mention Once)


● API: /api/auth/login

● Method: POST

● Token: JWT

● Password field maps to password_hash internally

● last_login updated on success

1️⃣SUPER ADMIN LOGIN


Table: super_admin_login

Request
{
"body":{
"email":"admin@[Link]",
"password":"string"
}
}

Success Response
{
"status":"success",
"data":{
"super_admin_id":1,
"name":"string",
"email":"string",
"phone":"string",
"status":1,
"last_login":"YYYY-MM-DD HH:mm:ss",
"token":"jwt"
}
}
✅ Uses only: super_admin_id,name,email,phone,status,last_login

2️⃣SALON ADMIN / STAFF LOGIN


Table: users

Request
{
"body":{
"email":"user@[Link]",
"password":"string"
}
}

Success Response
{
"status":"success",
"data":{
"user_id":10,
"salon_id":3,
"username":"string",
"role":"ADMIN|STAFF",
"email":"string",
"status":"ACTIVE",
"last_login":"YYYY-MM-DD HH:mm:ss",
"token":"jwt"
}
}

✅ Uses only: user_id,salon_id,username,role,email,status,last_login

3️⃣CUSTOMER LOGIN
Table: customer_authentication
(Related table: customers)

Request
{
"body":{
"email":"customer@[Link]",
"password":"string"
}
}

Success Response
{
"status":"success",
"data":{
"customer_id":25,
"salon_id":3,
"email":"string",
"status":"ACTIVE",
"last_login":"YYYY-MM-DD HH:mm:ss",
"token":"jwt"
}
}

✅ Uses only: customer_id,salon_id,email,status,last_login

4️⃣REGISTER — CUSTOMER
POST /api/auth/register

Request
{
"body":{
"name":"string",
"phone":"string",
"email":"string",
"gender":"Male|Female|Other",
"dob":"YYYY-MM-DD",
"anniversary_date":"YYYY-MM-DD",
"password":"string"
}
}

Response
{
"status":"success",
"data":{
"customer_id":1,
"salon_id":1,
"email":"string",
"status":"ACTIVE",
"token":"jwt"
}
}

4️⃣AUTH – GET ME
API: /api/auth/me
Method: GET

Header: Authorization: Bearer <token>

Request
{

Response (Role-Based)
{
"status":"success",
"data":{
"id":1,
"role":"SUPER_ADMIN|ADMIN|STAFF|CUSTOMER",
"salon_id":3,
"email":"string",
"status":"ACTIVE"
}
}

✅ Abstracted, role resolved from JWT

6️⃣UPDATE CURRENT USER (ME)


PUT /api/auth/me

Request
{
"body":{
"name":"string",
"phone":"string",
"email":"string"
}
}

Response
{
"status":"success"
}

5️⃣AUTH – LOGOUT
API: /api/auth/logout
Method: POST

Header: Authorization: Bearer <token>

Request
{}

Response
{
"status":"success",
"message":"Logged out"
}

6️⃣AUTH – REFRESH TOKEN


API: /api/auth/refresh
Method: POST

Header: Authorization: Bearer <token>

Request
{

Response
{
"status":"success",
"data":{
"token":"jwt"
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

👥 STAFF MANAGEMENT
Tables used: users ,staff_info ,staff_documents ,incentives ,incentive_payouts
All fields below map directly to UML columns. No extras.

1️⃣Create Staff
POST /api/admin/staff

API Owner: Admin

Who Can Use: Admin

Tables: users, staff_info,

Request
{
"body":{
"username":"string",
"email":"string",
"password":"string",
"role":"STAFF",
"name":"string",
"phone":"string",
"status":"ACTIVE"
}
}

Response
{
"status":"success",
"data":{
"user_id":1,
"staff_id":1
}
}

➕ ADD STAFF DOCUMENT


Post /api/admin/staff/{staff_id}/documents

Who Owns: Admin


Who Can Use: Admin
Tables Used: staff_documents, staff_info

✅ Request
{
"path":{
"staff_id":12
},
"body":{
"doc_type":"CERTIFICATION|ID|CONTRACT",
"file_path":"uploads/staff/docs/cert_12.pdf"
}
}

✅ Response
{
"status":"success",
"data":{
"doc_id":101,
"staff_id":12,
"doc_type":"CERTIFICATION",
"file_path":"uploads/staff/docs/cert_12.pdf",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}

2️⃣Update Staff Details


PUT /api/admin/staff/{staff_id}
API Owner: Admin

Who Can Use: Admin

Tables: users, staff_info

Request
{
"path":{"staff_id":1},
"body":{
"name":"string",
"phone":"string",
"email":"string"
}
}

Response
{
"status":"success"
}

3️⃣Activate / Deactivate Staff


PATCH /api/admin/staff/{staff_id}/status

API Owner: Admin

Who Can Use: Admin

Tables: users, staff_info

Request
{
"path":{"staff_id":1},
"body":{
"status":"ACTIVE|INACTIVE"
}
}

Response
{
"status":"success"
}
5️⃣Generate Staff Incentive
POST /api/staff/incentives

API Owner: Admin

Who Can Use: Admin

Tables: incentives, staff_info, appointments

Request
{
"body":{
"staff_id":1,
"appointment_id":10,
"incentive_type":"service_commission|admin_bonus",
"remarks":"string",
"incentive_amount":500.00
}
}

Response
{
"status":"success",
"data":{
"incentive_id":1
}
}

6️⃣Incentive Payout
POST /api/staff/incentives/{incentive_id}/payout

API Owner: Admin

Who Can Use: Admin

Tables: incentive_payout, incentives, staff_info

Request
{
"path":{"incentive_id":1},
"body":{
"staff_id":1,
"payout_amount":500.00,
"payout_date":"YYYY-MM-DD",
"payment_mode":"CASH|UPI|BANK"
}
}

Response
{
"status":"success",
"data":{
"payout_id":1
}
}

7️⃣View Staff List


GET /api/admin/staff

API Owner: Admin

Who Can Use: Admin,Customer

Tables: users, staff_info

Request
{
"query":{
"status":"ACTIVE|INACTIVE",
"page":1,
"limit":20
}
}

Response
{
"status":"success",
"data":{
"items":[
{
"staff_id":1,
"user_id":1,
"name":"string",
"phone":"string",
"email":"string",
"status":"ACTIVE"
}
],
"pagination":{"page":1,"limit":20,"total":0}
}
}

8️⃣View Staff Details


GET /api/admin/staff/{staff_id}

API Owner: Admin

Who Can Use: Admin ,Staff

Tables: users, staff_info

Request
{
"path":{"staff_id":1}
}

Response
{
"status":"success",
"data":{
"staff_id":1,
"user_id":1,
"name":"string",
"phone":"string",
"email":"string",
"status":"ACTIVE",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
🛎 SERVICE MANAGEMENT
Table: services
All fields used below exist in UML. No extras.

1️⃣Create Service
POST /api/admin/services

API Owner: Admin

Who Can Use: Admin

Tables: Services

Request
{
"body":{
"service_name":"string",
"price":500.00,
"duration":60,
"image_url":"string",
"status":"ACTIVE"
}
}

Response
{
"status":"success",
"data":{
"service_id":1
}
}

2️⃣Update Service Details


PUT /api/admin/services/{service_id}

API Owner: Admin

Who Can Use: Admin

Tables: Services
Request
{
"path":{"service_id":1},
"body":{
"service_name":"string",
"price":600.00,
"duration":75,
"image_url":"string"
}
}

Response
{
"status":"success"
}

3️⃣Activate / Deactivate Service


PATCH /api/admin/services/{service_id}/status

API Owner: Admin

Who Can Use: Admin

Tables: Services

Request
{
"path":{"service_id":1},
"body":{
"status":"ACTIVE|INACTIVE"
}
}

Response
{
"status":"success"
}

5️⃣List Services (Salon)


GET /api/services

API Owner: Admin

Who Can Use: Admin,staff, customer

Tables: Services

Request
{
"query":{
"status":"ACTIVE|INACTIVE",
"page":1,
"limit":20
}
}

Response
{
"status":"success",
"data":{
"items":[
{
"service_id":1,
"service_name":"string",
"price":500.00,
"duration":60,
"status":"ACTIVE"
}
],
"pagination":{"page":1,"limit":20,"total":0}
}
}

6️⃣View Service Details


GET /api/services/{service_id}

API Owner: Admin

Who Can Use: Admin,staff , customer

Tables: Services

Request
{
"path":{"service_id":1}
}

Response
{
"status":"success",
"data":{
"service_id":1,
"service_name":"string",
"price":500.00,
"duration":60,
"image_url":"string",
"status":"ACTIVE",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

📦 PACKAGES MANAGEMENT
Tables: packages, package_services, services

1️⃣Create Package (WITH service


mapping)
POST /api/admin/packages

API Owner: Admin

Who Can Use: Admin

Tables: Packages,Services

Request
{

"body":{

"package_name":"string",

"total_price":1500.00,

"validity_days":30,

"image_url":"string",

"status":"ACTIVE",

"service_ids":[1,2,3]

Backend Logic (important)


● Insert into packages

● Get package_id

● Insert multiple rows into package_services:

○ (package_id, service_id)

Response
{

"status":"success",

"data":{

"package_id":1

2️⃣Update Package Details (AND


services)
PUT /admin/packages/{package_id}

API Owner: Admin

Who Can Use: Admin

Tables: Packages,Services

Request
{

"path":{"package_id":1},

"body":{

"package_name":"string",

"total_price":1600.00,

"validity_days":45,

"image_url":"string",

"service_ids":[2,4]

Backend Logic
● Update packages

● Delete existing mappings:

○ DELETE FROM package_services WHERE package_id = ?

● Insert new composite mappings:

○ (package_id, service_id)

Response
{

"status":"success"

}
3️⃣Activate / Deactivate Package
PATCH /api/admin/packages/{package_id}/status

API Owner: Admin

Who Can Use: Admin

Tables: Packages

Request
{

"path":{"package_id":1},

"body":{

"status":"ACTIVE|INACTIVE"

Response
{

"status":"success"

4️⃣List Packages (Salon)


GET /api/packages

API Owner: Admin

Who Can Use: Admin, Staff, customer

Tables: Packages

Request
{

"query":{

"status":"ACTIVE|INACTIVE",

"page":1,

"limit":20

Response
{

"status":"success",

"data":{

"items":[

"package_id":1,

"package_name":"string",

"total_price":1500.00,

"validity_days":30,

"status":"ACTIVE"

],

"pagination":{"page":1,"limit":20,"total":0}

5️⃣View Package Details (DERIVED via


composite key)
GET /api/packages/{package_id}

API Owner: Admin

Who Can Use: Admin, staff, customer

Tables: Packages,services

Request
{

"path":{"package_id":1}

Response
{

"status":"success",

"data":{

"package_id":1,

"package_name":"string",

"total_price":1500.00,

"validity_days":30,

"image_url":"string",

"status":"ACTIVE",

"services":[

"service_id":1,

"service_name":"string",

"price":500.00,

"duration":60

}
}

Derivation Logic
packages

→ package_services (package_id, service_id)

→ services

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

👤 CUSTOMER MANAGEMENT
Tables: customers ,appointments ,appointment_services
,appointment_packages ,appointment_feedback

1️⃣Create Customer ( Manual)


POST /api/customers

API Owner: Admin

Who Can Use: Admin,staff

Tables: Customers

Request
{
"body":{
"name":"string",
"phone":"string",
"email":"string",
"gender":"Male|Female|Other",
"dob":"YYYY-MM-DD",
"anniversary_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":{
"customer_id":1
}
}

2️⃣Update Customer Details


PUT /customers/{customer_id}

API Owner: Admin

Who Can Use: Admin,staff

Tables: Customers

Request
{
"path":{"customer_id":1},
"body":{
"name":"string",
"phone":"string",
"email":"string",
"gender":"Male|Female|Other",
"dob":"YYYY-MM-DD",
"anniversary_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success"
}
3️⃣Soft Delete Customer
PATCH /customers/{customer_id}

API Owner: Admin

Who Can Use: Admin,staff

Tables: Customers

Request
{
"path":{"customer_id":1},
"body":{
"status":"INACTIVE"
}
}

Response
{
"status":"success"
}

4️⃣List Customers (Salon)


GET /api/customers

API Owner: Admin

Who Can Use: Admin,staff

Tables: Customers

Request
{
"query":{
"page":1,
"limit":20
}
}

Response
{
"status":"success",
"data":{
"items":[
{
"customer_id":1,
"name":"string",
"phone":"string",
"email":"string"
}
],
"pagination":{"page":1,"limit":20,"total":0}
}
}

5️⃣View Customer Profile


GET /api/customers/{customer_id}

API Owner: Admin

Who Can Use: Admin,staff,customer

Tables: Customers

Request
{
"path":{"customer_id":1}
}

Response
{
"status":"success",
"data":{
"customer_id":1,
"name":"string",
"phone":"string",
"email":"string",
"gender":"Male",
"dob":"YYYY-MM-DD",
"anniversary_date":"YYYY-MM-DD",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}
6️⃣Update Own Profile (Customer)
PUT api/customers/me

API Owner: Customer

Who Can Use: Customer

Tables: Customers

Request
{
"body":{
"name":"string",
"phone":"string",
"email":"string",
"dob":"YYYY-MM-DD",
"anniversary_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success"
}

7️⃣View Own Appointment History


GET /api/customers/me/appointments
API Owner: Customer
Who Can Use: Customer
Tables: appointments, appointment_services, appointment_packages

Request
{
"query":{
"page":1,
"limit":20
}
}

Response
{
"status":"success",
"data":{
"items":[
{
"appointment_id":1,
"appointment_date_time":"YYYY-MM-DD HH:mm:ss",
"status":"BOOKED",
"services":[
{
"service_id":1,
"staff_id":2
}
],
"packages":[
{
"package_id":3,
"staff_id":2
}
],
"feedback_given":false
}
]
}
}

8️⃣View Customer Appointment History


GET /api/customers/{customer_id}/appointments
API Owner: Admin
Who Can Use: Admin, Staff
Tables: appointments, appointment_services, appointment_packages

Request
{
"path":{"customer_id":1}
}

Response
{
"status":"success",
"data":[
{
"appointment_id":1,
"appointment_date_time":"YYYY-MM-DD HH:mm:ss",
"status":"COMPLETED",
"services":[
{
"service_id":1,
"staff_id":2
}
],
"packages":[
{
"package_id":3,
"staff_id":2
}
],
"feedback_given":true
}
]
}

9️⃣Create Appointment Feedback


POST /api/appointments/{appointment_id}/feedback
API Owner: Customer
Who Can Use: Customer
Tables: appointment_feedback, appointments

Request
{
"path":{"appointment_id":1},
"body":{
"rating":5,
"comment":"string"
}
}

Response
{
"status":"success",
"data":{
"feedback_id":1
}
}

🔹 Constraint:
● Only allowed if appointment status = COMPLETED

● Only one feedback per appointment

🔟 View Own Feedback History


GET /api/customers/me/feedback
API Owner: Customer
Who Can Use: Customer
Tables: appointment_feedback, appointments

Headers:Authorization: Bearer <JWT_TOKEN>

Request
{}

Response
{
"status":"success",
"data":[
{
"feedback_id":1,
"appointment_id":1,
"rating":5,
"comment":"string",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
]
}

1️⃣1️⃣View Customer Feedback History


GET /api/customers/{customer_id}/feedback
API Owner: Admin
Who Can Use: Admin
Tables: appointment_feedback, appointments

Request
{
"path":{"customer_id":1}
}
Response
{
"status":"success",
"data":[
{
"feedback_id":1,
"appointment_id":1,
"rating":4,
"comment":"string",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
]
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

📅 APPOINTMENT MANAGEMENT
Tables involved:

● appointments

● appointment_services

● appointment_packages

● services

● packages

● staff_info

Key rule (important, mention once in slides):

An appointment can have EITHER services OR packages OR both


Mapping rows are created in respective junction tables.

✅ Combined Create Appointment API


POST /api/appointments
API Domain: Appointment
Who Can Use: Customer, Admin, Staff
Tables: appointments, appointment_services, appointment_packages

Request
(Services OR Packages OR both)

{
"body":{
"customer_id":10,
"appointment_date_time":"YYYY-MM-DD HH:mm:ss",
"services":[
{
"service_id":1,
"staff_id":2
}
],
"packages":[
{
"package_id":1,
"staff_id":3
}
]
}
}

Notes (implicit, not repeated in JSON)

● customer_id

○ required for Admin / Staff

○ ignored or auto-derived for Customer (from token)

Internal Logic (this is the key part)


Role Status Stored in
[Link]

Custom NOT_YET_APPROVED
er

Admin BOOKED

Staff BOOKED

Internal Table Usage


● appointments → 1 row

● appointment_services → 1 row per service

● appointment_packages → 1 row per package

Response
{
"status":"success",
"data":{
"appointment_id":1,
"status":"NOT_YET_APPROVED | BOOKED",
"created_by_role":"CUSTOMER | ADMIN | STAFF"
}
}

3️⃣Update Appointment Date / Time


PUT /api/appointments/{appointment_id}

API Domain: Appointment


Who Can Use: Customer, Admin, Staff
Tables: appointments, appointment_services, appointment_packages

Request
{
"path":{"appointment_id":1},
"body":{
"appointment_date_time":"YYYY-MM-DD HH:mm:ss"
}
}
Response
{
"status":"success"
}

4️⃣Approve Appointment
PATCH /api/appointments/{appointment_id}/approve

API Domain: Appointment


Who Can Use: Admin, Staff
Tables: appointments,

Request
{
"path":{"appointment_id":1}
}

Response
{
"status":"success",
"data":{
"status":"BOOKED"
}
}

5️⃣Cancel Appointment
PATCH /api/appointments/{appointment_id}/cancel

API Domain: Appointment


Who Can Use: Admin, Staff
Tables: appointments,

Request
{
"path":{"appointment_id":1}
}

Response
{
"status":"success",
"data":{
"status":"CANCELLED"
}
}

6️⃣Complete Appointment
PATCH /api/appointments/{appointment_id}/complete

API Domain: Appointment


Who Can Use: Admin, Staff
Tables: appointments,

Request
{
"path":{"appointment_id":1}
}

Response
{
"status":"success",
"data":{
"status":"COMPLETED"
}
}

7️⃣Update Assigned Staff / Service


PUT /api/appointments/{appointment_id}/services/{service_id}

API Domain: Appointment


Who Can Use: Admin, Staff
Tables: appointments,

Request
{
"path":{
"appointment_id":1,
"service_id":2
},
"body":{
"staff_id":5
}
}

Response
{
"status":"success"
}

8️⃣Remove Service from Appointment (Soft)


PATCH /api/appointments/{appointment_id}/services/{service_id}

API Domain: Appointment


Who Can Use: Admin, Staff
Tables: appointments,

Request
{
"path":{
"appointment_id":1,
"service_id":2
}
}

Response
{
"status":"success"
}

9️⃣View Appointment Details


GET /api/appointments/{appointment_id}

API Domain: Appointment


Who Can Use: Admin, Staff, customer
Tables: appointments,appointment_packages, appointment_services
Request
{
"path":{"appointment_id":1}
}

Response
{
"status":"success",
"data":{
"appointment_id":1,
"appointment_date_time":"YYYY-MM-DD HH:mm:ss",
"status":"BOOKED",
"services":[
{
"service_id":1,
"staff_id":2
}
],
"packages":[
{
"package_id":1,
"staff_id":3
}
]
}
}

🔟 List Appointments (Salon)


GET api/appointments

API Domain: Appointment


Who Can Use: Admin, Staff
Tables: appointments,

Request
{
"query":{
"page":1,
"limit":20,
"status":"BOOKED|COMPLETED"
}
}
Response
{
"status":"success",
"data":{
"items":[
{
"appointment_id":1,
"appointment_date_time":"YYYY-MM-DD HH:mm:ss",
"status":"BOOKED"
}
]
}
}

1️⃣1️⃣List Own Appointments


GET /api/customers/me/appointments

API Domain: Appointment


Who Can Use: customer
Tables: appointments,

Headers:Authorization: Bearer <JWT_TOKEN>

Request
{}

Response
{
"status":"success",
"data":[
{
"appointment_id":1,
"appointment_date_time":"YYYY-MM-DD HH:mm:ss",
"status":"COMPLETED"
}
]
}
—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

🧾 CUSTOMER INVOICE MANAGEMENT


Tables:

● invoice_customer

● customer_payments

● appointments

1️⃣Generate Customer Invoice


POST /api/appointments/{appointment_id}/invoice

API Domain: invoice


Who Can Use: admin, staff
Tables: customer_invoice

Request
{
"path":{"appointment_id":1},
"body":{
"tax_amount":100.00,
"discount_amount":50.00
}
}

total_amount is computed internally


invoice_number generated by system

Response
{
"status":"success",
"data":{
"invoice_customer_id":1001,
"invoice_number":"INV-C-001",
"total_amount":1050.00,
"payment_status":"UNPAID"
}
}

2️⃣View Customer Invoice


GET /api/invoices/customer/{invoice_customer_id}

API Domain: invoice


Who Can Use: admin, staff, customer
Tables: customer_invoice

Request
{
"path":{"invoice_customer_id":1001}
}

Response
{
"status":"success",
"data":{
"invoice_customer_id":1001,
"appointment_id":1,
"invoice_number":"INV-C-001",
"tax_amount":100.00,
"discount_amount":50.00,
"total_amount":1050.00,
"payment_status":"UNPAID",
"invoice_date":"YYYY-MM-DD"
}
}

3️⃣Add Customer Payment


POST /api/invoices/customer/{invoice_customer_id}/payments

API Domain: invoice


Who Can Use: admin, staff
Tables: customer_payment

Request
{
"path":{"invoice_customer_id":1001},
"body":{
"payment_mode":"CASH|UPI|CARD",
"transaction_no":"TXN123",
"amount":500.00
}
}

Response
{
"status":"success",
"data":{
"customer_payment_id":1
}
}

4️⃣View Customer Payment History


GET /api/invoices/customer/{invoice_customer_id}/payments

API Domain: invoice


Who Can Use: admin, staff, customer
Tables: customer_payment

Request
{
"path":{"invoice_customer_id":1001}
}

Response
{
"status":"success",
"data":[
{
"customer_payment_id":1,
"payment_mode":"UPI",
"transaction_no":"TXN123",
"amount":500.00,
"created_at":"YYYY-MM-DD HH:mm:ss"
}
]
}
—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

📊 REPORT MANAGEMENT (DYNAMIC /


CALCULATED)
Global Report Rules (mention once in slides):

● No report tables

● All values computed using SUM, COUNT, GROUP BY

● Filters via query params

● Default scope: logged-in salon

1️⃣Sales Report
GET /api/reports/sales

API Domain: Report


Who Can Use: admin
Tables: invoice_customer, customer_payments

Logic:

● Total revenue

● Paid vs unpaid

● Aggregated from invoice_customer,customer_payments

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":{
"total_invoices":120,
"total_billed":150000.00,
"total_received":135000.00,
"pending_amount":15000.00
}
}

2️⃣Appointment Report
GET /api/reports/appointments

API Domain: Report


Who Can Use: admin
Tables:appointments

Logic:

● Count by status

● Uses appointments

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":{
"total":200,
"completed":150,
"cancelled":30,
"upcoming":20
}
}
3️⃣Staff Performance Report
GET /api/reports/staff-performance

API Domain: Report


Who Can Use: admin
Tables: appointment_services,appointments,incentives

Logic:

● Appointments handled

● Incentives earned

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":[
{
"staff_id":1,
"appointments_handled":40,
"total_incentive":8000.00
}
]
}

4️⃣Service-wise Revenue Report


GET /api/reports/services

API Domain: Report


Who Can Use: admin
Tables: appointment_services ,invoice_customer

Logic:
● Revenue per service

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":[
{
"service_id":1,
"total_bookings":60,
"revenue":30000.00
}
]
}

5️⃣Package-wise Revenue Report


GET /api/reports/packages

API Domain: Report


Who Can Use: admin
Tables: appointment_Packages ,invoice_customer

Logic:

● Revenue per package

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}
Response
{
"status":"success",
"data":[
{
"package_id":1,
"total_bookings":25,
"revenue":50000.00
}
]
}

6️⃣Customer Visit Report


GET /api/reports/customers

API Domain: Report


Who Can Use: admin
Tables: appointments

Logic:

● Visit frequency per customer

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":[
{
"customer_id":10,
"visit_count":8
}
]
}
7️⃣Inventory Usage Report
GET /api/reports/inventory

API Domain: Report


Who Can Use: admin
Tables: stock_transaction

Logic:

● Quantity used per product

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":[
{
"product_id":3,
"total_quantity_used":120
}
]
}

8️⃣Incentive Payout Report


GET /api/reports/incentives

API Domain: Report


Who Can Use: admin
Tables: incentives, incentive_payouts

Logic:
● Earned vs paid incentives

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success",
"data":{
"total_incentives":20000.00,
"total_paid":15000.00,
"pending":5000.00
}
}

9️⃣Tax Report
GET /api/reports/tax

API Domain: Report


Who Can Use: admin
Tables: invoice_customer

Logic:

● Tax collected over time

Request
{
"query":{
"from_date":"YYYY-MM-DD",
"to_date":"YYYY-MM-DD"
}
}
Response
{
"status":"success",
"data":{
"total_tax_collected":18000.00
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

🧩 SUBSCRIPTION PLAN MANAGEMENT


(SUPER ADMIN)
Table: subscription_plans
All fields used exist in UML. No assumptions.

1️⃣Create Subscription Plan


POST /api/super-admin/subscription-plans

API Domain: super admin


Who Can Use: super admin
Tables: subscription_plans

Request
{
"body":{
"plan_name":"string",
"price":999.00,
"duration_days":30,
"status":1
}
}

Response
{
"status":"success",
"data":{
"plan_id":1
}
}

2️⃣Update Subscription Plan


PUT /api/super-admin/subscription-plans/{plan_id}

API Domain: super admin


Who Can Use: super admin
Tables: subscription_plans

Request
{
"path":{"plan_id":1},
"body":{
"plan_name":"string",
"price":1099.00,
"duration_days":45
}
}

Response
{
"status":"success"
}

3️⃣Activate / Deactivate Plan


PATCH /api/super-admin/subscription-plans/{plan_id}/status

API Domain: super admin


Who Can Use: super admin
Tables: subscription_plans

Request
{
"path":{"plan_id":1},
"body":{
"status":1
}
}
status: 1 = active, 0 = inactive

Response
{
"status":"success"
}

5️⃣List Subscription Plans


GET /api/subscription-plans

API Domain: super admin


Who Can Use: super admin
Tables: subscription_plans

Request
{
"query":{
"status":1
}
}

Response
{
"status":"success",
"data":[
{
"plan_id":1,
"plan_name":"string",
"price":999.00,
"duration_days":30,
"status":1
}
]
}
6️⃣View Subscription Plan Details
GET /api/subscription-plans/{plan_id}

API Domain: super admin


Who Can Use: super admin
Tables: subscription_plans

Request
{
"path":{"plan_id":1}
}

Response
{
"status":"success",
"data":{
"plan_id":1,
"plan_name":"string",
"price":999.00,
"duration_days":30,
"status":1,
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

🏬 SALON MANAGEMENT (SUPER


ADMIN)
Table: salons
All fields used exist in UML. Compact. No extras.

1️⃣Create Salon
POST /api/super-admin/salons
API Domain: super admin
Who Can Use: super admin
Tables: salon

Request
{
"body":{
"salon_name":"string",
"salon_ownername":"string",
"phone":"string",
"gst_num":"string",
"address":"string",
"city":"string",
"state":"string",
"country":"string",
"salon_logo":"string",
"status":1
}
}

Response
{
"status":"success",
"data":{
"salon_id":1
}
}

2️⃣Create Salon Admin User


POST /api/super-admin/salons/{salon_id}/admin

API Domain: Super Admin


Who Can Use: Super Admin
Tables: users

Precondition: Salon must already exist


salon_id is passed via path and stored as FK in users

Request
{
"path":{
"salon_id":1
},
"body":{
"username":"string",
"email":"string",
"phone":"string"
}
}

Internal Logic
● Validate salon_id exists in salons

● Create record in users

● Set:

○ salon_id → from path

○ role → "ADMIN"

○ status → "ACTIVE"

● Generate password

● Log action in audit_log

Response
{
"status":"success",
"data":{
"user_id":10,
"role":"ADMIN",
"salon_id":1
}
}

2️⃣Update Salon Details


PUT /api/super-admin/salons/{salon_id}

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon
Request
{
"path":{"salon_id":1},
"body":{
"salon_name":"string",
"salon_ownername":"string",
"phone":"string",
"gst_num":"string",
"address":"string",
"city":"string",
"state":"string",
"country":"string",
"salon_logo":"string"
}
}

Response
{
"status":"success"
}

3️⃣Activate / Deactivate Salon


PATCH /api/super-admin/salons/{salon_id}/status

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon

Request
{
"path":{"salon_id":1},
"body":{
"status":1
}
}

1 = ACTIVE, 0 = INACTIVE

Response
{
"status":"success"
}
5️⃣List Salons
GET /api/super-admin/salons

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon

Request
{
"query":{
"status":1,
"page":1,
"limit":20
}
}

Response
{
"status":"success",
"data":{
"items":[
{
"salon_id":1,
"salon_name":"string",
"city":"string",
"status":1
}
],
"pagination":{"page":1,"limit":20,"total":0}
}
}

6️⃣View Salon Details


GET /api/super-admin/salons/{salon_id}

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon
Request
{
"path":{"salon_id":1}
}

Response
{
"status":"success",
"data":{
"salon_id":1,
"salon_name":"string",
"salon_ownername":"string",
"email":"string",
"phone":"string",
"gst_num":"string",
"address":"string",
"city":"string",
"state":"string",
"country":"string",
"status":1,
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

🔗 SUBSCRIPTION MANAGEMENT
(ASSIGN PLAN TO SALON)
Table: salon_subscriptions
Logic: one salon ↔ multiple subscriptions over time, only one ACTIVE at a time.

1️⃣Assign Subscription to Salon


POST /api/super-admin/salons/{salon_id}/subscriptions

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon_subcriptions
Request
{
"path":{"salon_id":1},
"body":{
"plan_id":2,
"start_date":"YYYY-MM-DD",
"end_date":"YYYY-MM-DD",
"status":"ACTIVE"
}
}

Response
{
"status":"success",
"data":{
"subscription_id":10
}
}

2️⃣Update Subscription Dates


PUT /api/super-admin/subscriptions/{subscription_id}

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon_subcriptions

Request
{
"path":{"subscription_id":10},
"body":{
"start_date":"YYYY-MM-DD",
"end_date":"YYYY-MM-DD"
}
}

Response
{
"status":"success"
}
3️⃣View Salon Subscription History
GET /api/super-admin/salons/{salon_id}/subscriptions

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon_subcriptions

Request
{
"path":{"salon_id":1}
}

Response
{
"status":"success",
"data":[
{
"subscription_id":10,
"plan_id":2,
"start_date":"YYYY-MM-DD",
"end_date":"YYYY-MM-DD",
"status":"ACTIVE"
},
{
"subscription_id":5,
"plan_id":1,
"start_date":"YYYY-MM-DD",
"end_date":"YYYY-MM-DD",
"status":"EXPIRED"
}
]
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

🧾 SALON INVOICE MANAGEMENT


(SUPER ADMIN)
NOTES: Salon_invoice is created as unpaid then bill is created calculated and sees of its
partial or fully paid
1️⃣Generate Salon Invoice
POST /api/super-admin/invoices/salon

API Domain: Super Admin


Who Can Use: Super Admin
Tables: salon_subcriptions

Logic
● Picks ACTIVE salon_subscriptions

● Calculates base amount from subscription_plans.price

● Tax calculated internally

● invoice_number auto-generated

Request
{
"body":{
"salon_id":1,
"subscription_id":10
}
}

Response
{
"status":"success",
"data":{
"invoice_salon_id":2001,
"invoice_number":"INV-S-001",
"amount":4500.00,
"tax_amount":500.00,
"total_amount":5000.00,
"payment_status":"UNPAID",
"due_date":"YYYY-MM-DD"
}
}

2️⃣View Salon Invoice


GET /api/api/super-admin/invoices/salon/{invoice_salon_id}

API Domain: Super Admin


Who Can Use: Super Admin
Tables: invoice_salon

Request
{
"path":{"invoice_salon_id":2001}
}

Response
{
"status":"success",
"data":{
"invoice_salon_id":2001,
"salon_id":1,
"subscription_id":10,
"invoice_number":"INV-S-001",
"amount":4500.00,
"tax_amount":500.00,
"total_amount":5000.00,
"payment_status":"UNPAID",
"created_at":"YYYY-MM-DD HH:mm:ss"
}
}

3️⃣Record Salon Invoice Payment


POST /api/super-admin/invoices/salon/{invoice_salon_id}/payments

API Domain: Super Admin


Who Can Use: Super Admin
Tables: payment_salon

Request
{
"path":{"invoice_salon_id":2001},
"body":{
"payment_mode":"BANK|UPI",
"transaction_no":"TXN789",
"amount":2500.00
}
}
Logic
● Supports PARTIAL / FULL payments

● Updates payment_status accordingly

Response
{
"status":"success",
"data":{
"payment_salon_id":1,
"payment_status":"PARTIAL"
}
}

4️⃣List Salon Invoices


GET /api/super-admin/invoices/salon

API Domain: Super Admin


Who Can Use: Super Admin
Tables: invoice_salon

Request
{
"query":{
"salon_id":1,
"payment_status":"PAID|UNPAID|PARTIAL",
"page":1,
"limit":20
}
}

Response
{
"status":"success",
"data":{
"items":[
{
"invoice_salon_id":2001,
"invoice_number":"INV-S-001",
"total_amount":5000.00,
"payment_status":"PARTIAL",
"due_date":"YYYY-MM-DD"
}
],
"pagination":{"page":1,"limit":20,"total":0}
}
}

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

—------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------

You might also like