Skip to main content

​
Overview

jshERP provides a comprehensive RESTful API built on Spring Boot that allows you to interact with all core ERP functionalities including inventory management, sales, purchasing, financial operations, and more. The API follows REST principles and returns JSON responses for all endpoints.

​
Base URL

The API base URL is configured in application.properties: 
server.port=9999
server.servlet.context-path=/jshERP-boot
Default Base URL: 
http://localhost:9999/jshERP-boot
All API endpoints are prefixed with this base URL.
In production environments, replace localhost with your actual domain name and ensure proper SSL/TLS configuration.

​
API Structure

The API is organized into logical resource groups:

​
Core Resources

  • /user - User management and authentication
  • /material - Product/material management
  • /depotHead - Warehouse document management (orders, receipts)
  • /depot - Warehouse/depot operations
  • /supplier - Supplier management
  • /role - Role and permissions management
  • /organization - Organization structure management

​
Inventory Management

  • /depotItem - Warehouse item details
  • /materialCategory - Product categories
  • /serialNumber - Serial number tracking
  • /unit - Unit of measure management

​
Financial Operations

  • /accountHead - Financial transaction headers
  • /accountItem - Financial transaction line items
  • /account - Account management

​
System Configuration

  • /systemConfig - System configuration settings
  • /function - Function/menu management
  • /log - System logging
  • /tenant - Multi-tenant management

​
Request & Response Format

​
Request Format

All requests should include: 
curl -X POST "http://localhost:9999/jshERP-boot/material/add" \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: your-token-here" \
  -d '{
    "name": "Product Name",
    "categoryId": 1,
    "standard": "Standard Spec"
  }'

​
Standard Response Format

{
  "code": 200,
  "data": {
    "rows": [...],
    "total": 100
  }
}

​
Response Codes

CodeDescription
200Success - Request completed successfully
500Error - Request failed, check error message
501Special condition (e.g., WeChat not bound)
jshERP uses a simplified response code structure. Most responses use code 200 for success and 500 for errors, with detailed messages in the data field.

​
Common Patterns

​
Pagination

List endpoints support pagination through query parameters: 
GET /material/list?pageNum=1&pageSize=20
Parameters:
  • pageNum - Page number (starting from 1)
  • pageSize - Number of records per page
Response includes: 
{
  "code": 200,
  "data": {
    "rows": [...],
    "total": 150
  }
}

​
Search Filtering

Many endpoints accept a search parameter with JSON-encoded search criteria: 
GET /material/list?search={"materialParam":"laptop","enabled":"true"}

​
Batch Operations

Batch operations use comma-separated IDs: 
DELETE /material/deleteBatch?ids=1,2,3,4,5

​
Data Operations

​
CRUD Operations

Standard endpoints follow consistent patterns:
OperationMethodEndpoint PatternExample
Get by IDGET/{resource}/info?id={id}/material/info?id=1
ListGET/{resource}/list/material/list
CreatePOST/{resource}/add/material/add
UpdatePUT/{resource}/update/material/update
DeleteDELETE/{resource}/delete?id={id}/material/delete?id=1
Batch DeleteDELETE/{resource}/deleteBatch?ids={ids}/material/deleteBatch?ids=1,2,3

​
Existence Checks

Many resources provide existence check endpoints: 
GET /material/checkIsExist?id=0&name=Product&model=X100&...
Returns: 
{
  "code": 200,
  "data": {
    "status": true
  }
}

​
Session Management

All API requests (except login, registration, and documentation endpoints) require authentication via the X-Access-Token header.
jshERP uses Redis-backed session management:
  • Session data is stored in Redis with configurable timeout
  • Default session timeout: 10 hours (36000 seconds)
  • Token is passed via X-Access-Token header
  • Session automatically expires after the configured timeout

​
Multi-Tenant Support

jshERP includes built-in multi-tenant capabilities:
  • Each user belongs to a tenant
  • Tenant configuration includes user limits and trial periods
  • Data isolation is enforced at the application level
  • Tenant information is stored in user sessions
When working with the API, all operations are automatically scoped to the authenticated user’s tenant.

​
Swagger Documentation

jshERP includes Swagger UI for interactive API exploration: 
http://localhost:9999/jshERP-boot/doc.html
Swagger provides:
  • Complete endpoint documentation
  • Request/response schemas
  • Interactive API testing
  • API version information
Swagger UI is accessible without authentication for ease of development.

​
Error Handling

​
Common Error Scenarios

Session Expired: 
{
  "code": 500,
  "data": "loginOut"
}
Business Logic Error: 
{
  "code": 500,
  "data": "操作失败"
}
Validation Error: Check the specific error message in the data field for details.

​
Error Codes in Business Operations

Some operations return specific status codes in the response data: 
{
  "code": 200,
  "data": {
    "status": 2
  }
}
Where status might indicate:
  • 0 - Operation failed
  • 1 - Operation succeeded
  • 2 - Specific condition (e.g., wrong password)
  • 3 - Exception occurred

​
Rate Limiting

Session timeout is configured to 10 hours. Each authenticated request automatically extends the session timeout.

​
Best Practices

  1. Always include the X-Access-Token header for authenticated requests
  2. Handle session expiration gracefully and redirect to login
  3. Use batch operations when performing multiple similar operations
  4. Implement proper error handling for all API calls
  5. Encode search parameters properly when using JSON in query strings
  6. Check existence before creating resources to avoid duplicates
  7. Validate input data on the client side before sending requests

​
Next Steps

Authentication

Learn how to authenticate and manage user sessions

Swagger API Docs

Explore the interactive API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us