Skip to content

Instantly share code, notes, and snippets.

@quanKM

quanKM/e-mb.yaml

Created July 10, 2025 17:37
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save quanKM/514f09d437c9899c9aa84e9e9a1fec19 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save quanKM/514f09d437c9899c9aa84e9e9a1fec19 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
e-mb.yaml
openapi: 3.0.0
info:
title: Login API
version: 1.0.0
description: API for user login
paths:
/v1/login:
post:
summary: User login
description: Xác thực người dùng và trả về một JWT token
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerNumber
- password
properties:
customerNumber:
type: string
format: string
example: KH123456
description: Mã Khách Hàng
password:
type: string
format: password
example: strongpassword123
responses:
'200':
description: Successful login
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: JWT token
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
'400':
description: Invalid customer number or password
'401':
description: Unauthorized
'500':
description: Internal server error
tags:
- Auth
/v1/forgot-password:
post:
summary: Forgot password
description: Gửi một đường link reset password tới địa chỉ email khác hàng
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerNumber
properties:
customerNumber:
type: string
format: string
example: KH123456
description: Mã Khách Hàng
responses:
'200':
description: Password reset email sent successfully
'400':
description: Invalid customer number
'404':
description: User not found
'500':
description: Internal server error
tags:
- Auth
/v1/profile:
get:
summary: Lấy thông tin hồ sơ
description: Trả về Mã Khách Hàng, Cơ sở và Vùng của người dùng.
security:
- bearerAuth: []
responses:
'200':
description: Trả về thông tin hồ sơ người dùng
content:
application/json:
schema:
type: object
properties:
customerNumber:
type: string
example: KH123456
description: Mã Khách Hàng
tenant:
type: string
example: Cơ sở Hà Nội
description: Cơ sở hiện tại
region:
type: string
example: Miền Bắc
description: Vùng địa lý
'404':
description: User not found
'500':
description: Internal server error
tags:
- Profile
/v1/debts:
get:
summary: Lấy thông tin công nợ
description: Trả về danh sách công nợ của khách hàng gồm loại hình, kỳ hóa đơn, số tiền, hạn thanh toán,...
security:
- bearerAuth: []
responses:
'200':
description: Danh sách công nợ
content:
application/json:
schema:
type: array
items:
type: object
properties:
serviceType:
type: string
enum: [Electricity, Water]
example: Electricity
description: Loại hình dịch vụ
billingPeriod:
type: string
example: "2025-06"
description: Kỳ hóa đơn
amount:
type: number
format: float
example: 150000.0
description: Số tiền
invoiceNumber:
type: string
example: "HD123456"
description: Số hóa đơn
dueDate:
type: string
format: date
example: "2025-07-01"
description: Hạn thanh toán
overdueDays:
type: integer
example: 5
description: Số ngày quá hạn
estimatedLateFeeInterest:
type: number
format: float
example: 12000.0
description: Lãi suất chậm trả tạm tính
'401':
description: Unauthorized
'500':
description: Lỗi hệ thống
tags:
- Debt
/debt/electricity:
get:
summary: Dư nợ và sản lượng dư nợ dịch vụ Điện
description: Trả về dư nợ cộng dồn và sản lượng chưa thanh toán cho dịch vụ điện.
security:
- bearerAuth: []
responses:
'200':
description: Thông tin công nợ điện
content:
application/json:
schema:
type: object
properties:
totalDebt:
type: number
format: float
example: 1250000.0
description: Dư nợ cộng dồn (VND)
unpaidConsumption:
type: number
format: float
example: 350.5
description: Sản lượng điện chưa thanh toán (kWh)
unit:
type: string
example: kWh
'401':
description: Unauthorized
'500':
description: Lỗi hệ thống
tags:
- Debt
/debt/water:
get:
summary: Dư nợ và sản lượng dư nợ dịch vụ Nước
description: Trả về dư nợ cộng dồn và sản lượng chưa thanh toán cho dịch vụ nước.
security:
- bearerAuth: []
responses:
'200':
description: Thông tin công nợ nước
content:
application/json:
schema:
type: object
properties:
totalDebt:
type: number
format: float
example: 840000.0
description: Dư nợ cộng dồn (VND)
unpaidConsumption:
type: number
format: float
example: 28.3
description: Sản lượng nước chưa thanh toán (m³)
unit:
type: string
example: m3
'401':
description: Unauthorized
'500':
description: Lỗi hệ thống
tags:
- Debt
/usage/electricity:
get:
summary: Sản lượng và tổng giá trị dịch vụ điện
description: Trả về sản lượng điện theo ngày và tổng giá trị dựa trên đơn giá.
security:
- bearerAuth: []
parameters:
- in: query
name: date
required: false
schema:
type: string
format: date
description: Ngày muốn tra cứu (YYYY-MM-DD), mặc định là hôm nay
responses:
'200':
description: Dữ liệu sản lượng điện
content:
application/json:
schema:
type: object
properties:
date:
type: string
format: date
example: "2025-07-10"
unit:
type: string
example: kWh
consumption:
type: number
format: float
example: 12.3
description: Sản lượng sử dụng (kWh)
unitPrice:
type: number
format: float
example: 2500.0
description: Đơn giá mỗi kWh (VND)
totalAmount:
type: number
format: float
example: 30750.0
description: Tổng giá trị = consumption × unitPrice
'401':
description: Unauthorized
'500':
description: Lỗi hệ thống
tags:
- Usage
/usage/water:
get:
summary: Sản lượng và tổng giá trị dịch vụ nước
description: Trả về sản lượng nước theo ngày và tổng giá trị dựa trên đơn giá.
security:
- bearerAuth: []
parameters:
- in: query
name: date
required: false
schema:
type: string
format: date
description: Ngày muốn tra cứu (YYYY-MM-DD), mặc định là hôm nay
responses:
'200':
description: Dữ liệu sản lượng nước
content:
application/json:
schema:
type: object
properties:
date:
type: string
format: date
example: "2025-07-10"
unit:
type: string
example: m3
consumption:
type: number
format: float
example: 4.7
description: Sản lượng sử dụng (m³)
unitPrice:
type: number
format: float
example: 12000.0
description: Đơn giá mỗi m³ (VND)
totalAmount:
type: number
format: float
example: 56400.0
description: Tổng giá trị = consumption × unitPrice
'401':
description: Unauthorized
'500':
description: Lỗi hệ thống
tags:
- Usage
components:
securitySchemes:
bearerAuth: # arbitrary name for the security scheme
type: http
scheme: bearer
bearerFormat: JWT # optional, arbitrary value for documentation purposes
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment