API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:The PayMaster application utilizes a set of internal RESTful API endpoints to support dynamic, client-side functionality without requiring full page reloads. These endpoints, primarily served via AJAX requests, handle tasks such as real-time data validation, financial calculations, and user searches. The primary controller for these operations is ApiController, which centralizes most of the application's AJAX-based logic.
The API is consumed by the main JavaScript file, app.js, which provides a structured ApiService object to interact with the backend. This architecture enhances user experience by providing immediate feedback and interactive components, particularly within data entry forms for customers and contracts.
Architecture Overview
The API endpoints are exposed under the /api path. Client-side JavaScript, primarily located in app.js, initiates fetch requests to these endpoints. The Spring Boot backend routes these requests to the ApiController, which then interacts with various service-layer components (CustomerService, CalculationService) to process the request and returns a JSON response.
This diagram illustrates the general flow for an API request.
Client-Side Integration
Client-side interaction with the API is managed through the ApiService object defined in app.js. This object abstracts the fetch calls into a set of clearly named asynchronous functions.
Sources: src/main/resources/static/js/app.js:223-288
ApiService Object
The ApiService provides methods for GET and POST requests and specific functions for each endpoint.
| Method | Description |
|---|---|
get(url, params) | Performs an asynchronous GET request. |
post(url, data) | Performs an asynchronous POST request. |
checkNationalCode(nationalCode, excludeId) | Checks for the validity and uniqueness of a national code. |
checkMobile(mobile, excludeId) | Checks for the uniqueness of a mobile number. |
calculateInstallments(principal, rate, months) | Calculates contract installment details. |
convertDate(persianDate) | Converts a Persian date string to Gregorian. |
searchCustomers(query) | Searches for customers based on a query string. |
Sources: src/main/resources/static/js/app.js:223-288
API Endpoint Details
All endpoints are located under the /api base path.
Customer Validation
These endpoints are used in the customer creation and editing forms to provide real-time validation.
GET /api/check-national-code
Checks if a given national code is valid and if it already exists in the database. The excludeId parameter is used during an update operation to exclude the current customer from the uniqueness check.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
nationalCode | String | The 10-digit national code to validate. |
excludeId | Long | (Optional) The ID of the customer to exclude from the check. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:29-31
Response Body
The endpoint returns a JSON object indicating validity.
- Success (Valid Code):
{ "valid": true, "message": "کد ملی معتبر است" } - Failure (Invalid or Duplicate):
{ "valid": false, "message": "کد ملی قبلاً ثبت شده است" }
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:36-50
Sequence Diagram
This diagram shows the validation flow when a user enters a national code in the customer form.
GET /api/check-mobile
Checks if a given mobile number already exists in the database. It also performs a basic format validation.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
mobile | String | The mobile number to validate (e.g., 09123456789). |
excludeId | Long | (Optional) The ID of the customer to exclude from the check. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:58-60
Response Body
- Success (Valid Number):
{ "valid": true, "message": "شماره موبایل معتبر است" } - Failure (Invalid or Duplicate):
{ "valid": false, "message": "شماره موبایل قبلاً ثبت شده است" }
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:65-81
Contract Calculation
This endpoint provides real-time calculation for contract previews.
GET /api/calculate-installments
Calculates the simple interest, total amount, and installment amount for a new contract based on the principal, interest rate, and duration.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
principal | Long | The principal amount of the loan. |
rate | Double | The annual interest rate (in percent). |
months | Integer | The number of installments (duration in months). |
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:87-90
Response Body
Returns a JSON object with both raw and formatted calculation results.
{
"principal": 100000000,
"interest": 18000000,
"total": 118000000,
"installmentAmount": 9833333,
"principalFormatted": "100,000,000",
"interestFormatted": "18,000,000",
"totalFormatted": "118,000,000",
"installmentFormatted": "9,833,333"
}
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:95-105, src/main/resources/templates/contracts/form.html:203-214
Related Endpoint: GET /api/calculate
An alternative calculation endpoint exists in HomeController. It performs a similar calculation but returns a CalculationResult record, which is slightly different from the Map returned by /api/calculate-installments. The frontend JavaScript in contracts/form.html and app.js explicitly uses /api/calculate-installments, suggesting it is the primary endpoint for this feature.
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:413-424
Utility Endpoints
GET /api/convert-date
Converts a Persian date string (e.g., "1403/09/20") to its Gregorian equivalent and provides additional formatted date strings.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
persianDate | String | The Persian date in YYYY/MM/DD format. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:111
Response Body
{
"valid": true,
"gregorian": "2024-12-10",
"persian": "1403/09/20",
"persianFull": "..."
}
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:114-123
GET /api/search-customers
Searches for customers by name, national code, or mobile number. It returns a paginated list of simplified customer objects.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
q | String | The search query. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:129
Response Body
Returns a JSON array of customer objects.
[
{
"id": 1,
"fullName": "Ali Mohammadi",
"nationalCode": "0012345678",
"mobile": "09123456789"
}
]
Sources: src/main/java/com/paymaster/backend/presentation/controller/ApiController.java:130-136