REST API

All ICOSYS backend services expose REST APIs that follow a consistent CRUD pattern. The React frontend consumes these APIs via Axios with automatic service routing.

---

Base URLs

Service	Port	Base URL	Database
Icglb (Core)	8010	/icglb/services	icglb2
BPM	8020	/icbpm/services	icbpm
DMS	8030	/icdms/services	icdms

In development, the Vite proxy forwards all /ic*/services/* requests to the corresponding backend port — the browser always sees http://localhost:5174.

---

Standard CRUD Endpoints

Every entity exposes six endpoints. Replace {entity} with the resource path (e.g., branch, business-partner, dms-file).

Method	Path	Description
GET	/api/{entity}/{id}	Get single record by ID
POST	/api/{entity}	Create new record
PUT	/api/{entity}/{id}	Update existing record
DELETE	/api/{entity}/{id}	Delete record
POST	/api/{entity}/list	Paginated list with filters
GET	/api/{entity}/stats	Entity statistics

---

Pagination

Request — PageRequest<F>

All list endpoints accept a POST body with this structure:

POST /api/{entity}/list

{
  "page": 0,
  "size": 20,
  "searchTerm": "jane",
  "sorts": [
    { "field": "lastName", "direction": "ASC" },
    { "field": "id", "direction": "DESC" }
  ],
  "filter": {
    "crProcessId": 123,
    "department": "Engineering"
  }
}

Field	Type	Required	Description
page	int	Yes	Zero-based page index
size	int	Yes	Items per page (default 20)
searchTerm	string	No	Free-text search across main fields
sorts	Sort[]	No	Multi-field sorting
filter	F	Yes	Entity-specific filter DTO

Tenant Isolation

filter.crProcessId is required in every list request. The backend will throw an NPE if it is missing. The React frontend injects it automatically.

Sort Object

{ "field": "accountName", "direction": "ASC" }

Field	Type	Values
field	string	Entity field name (Java property, not DB column)
direction	string	ASC or DESC

Response — PageResponse<T>

Response 200 OK

{
  "content": [
    { "id": 1, "firstName": "Jane", "lastName": "Doe", ... },
    { "id": 2, "firstName": "John", "lastName": "Smith", ... }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 150,
  "totalPages": 8,
  "first": true,
  "last": false,
  "empty": false
}

Field	Type	Description
content	T[]	Page items (ListDto format)
page	int	Current page index
size	int	Requested page size
totalElements	long	Total matching records
totalPages	int	Total pages
first	boolean	Is first page
last	boolean	Is last page
empty	boolean	No results

---

Entity Statistics

GET /api/{entity}/stats

Returns aggregate counts for the entity.

Response 200 OK

{
  "totalCount": 150,
  "activeCount": 130,
  "passiveCount": 20
}

Field	Type	Description
totalCount	long	All records
activeCount	long	Records with status = true
passiveCount	long	Records with status = false

---

CRUD Operations

Create

POST /api/{entity}

curl -X POST http://localhost:8010/icglb/services/api/branch \
  -H "Content-Type: application/json" \
  -d '{
    "crProcessId": 123,
    "branchName": "Istanbul HQ",
    "branchCode": "IST-001",
    "status": true
  }'

Response 200 OK

{
  "id": 456,
  "version": 0,
  "crProcessId": 123,
  "branchName": "Istanbul HQ",
  "branchCode": "IST-001",
  "status": true
}

• crProcessId is required — sets the tenant
• version is initialized to 0
• id is auto-generated

Read

GET /api/{entity}/{id}

curl http://localhost:8010/icglb/services/api/branch/456

Response 200 OK

{
  "id": 456,
  "version": 3,
  "crProcessId": 123,
  "branchName": "Istanbul HQ",
  "branchCode": "IST-001",
  "status": true
}

Returns 404 if not found — see Error Codes.

Update

PUT /api/{entity}/{id}

curl -X PUT http://localhost:8010/icglb/services/api/branch/456 \
  -H "Content-Type: application/json" \
  -d '{
    "version": 3,
    "branchName": "Istanbul Headquarters",
    "branchCode": "IST-001",
    "status": true
  }'

Response 200 OK

{
  "id": 456,
  "version": 4,
  "crProcessId": 123,
  "branchName": "Istanbul Headquarters",
  "branchCode": "IST-001",
  "status": true
}

Optimistic Locking

The version field must match the current database version. If another user modified the record, the backend returns 409 Conflict with error code IC-SYS-4002.

Delete

DELETE /api/{entity}/{id}

curl -X DELETE http://localhost:8010/icglb/services/api/branch/456

Returns 204 No Content on success, or 409 Conflict with IC-SYS-4003 if the record has foreign key references.

---

Common Request Headers

Every API request should include:

Header	Value	Required	Description
Content-Type	application/json	Yes	All endpoints except file upload
Cookie	ICOSYS_SESSION=<jwt>	Yes	Browser SPA authentication
Authorization	Bearer <jwt>	Alt	Postman / service-to-service auth
X-API-Key	<api-key>	Some	Required for session/log endpoints
X-Project-Code	ICOSYS	No	Project identifier
Accept-Language	en or tr	No	Error message language

---

Service Endpoints

Icglb-Services (Port 8010)

Core platform — authentication, users, accounts, security, lookups.

Authentication

See Authentication for full details.

Method	Path	Auth	Description
POST	/api/auth/login	API Key	Authenticate and get JWT
GET	/api/auth/me	JWT	Validate session, get user info
POST	/api/auth/switch-account	JWT	Switch active account
POST	/api/auth/logout	JWT	End session, clear cookie
POST	/api/auth/change-password	JWT	Change password, invalidate tokens

Account Management

Method	Path	Description
GET	/api/account/{accountNo}	Get account by account number
POST	/api/account/list	List accounts (paginated)
POST	/api/account	Create account
PUT	/api/account/{accountNo}	Update account
DELETE	/api/account/{accountNo}	Delete account
GET	/api/account/stats	Account statistics

User Management

Method	Path	Description
GET	/api/user-info/{id}	Get user
POST	/api/user-info/list	List users
POST	/api/user-info	Create user
PUT	/api/user-info/{id}	Update user
DELETE	/api/user-info/{id}	Delete user
GET	/api/user-info/stats	User statistics

User Process (User–Account Link)

Method	Path	Description
GET	/api/user-process/{id}	Get link
POST	/api/user-process/list	List links
POST	/api/user-process	Create link
PUT	/api/user-process/{id}	Update link
DELETE	/api/user-process/{id}	Delete link
GET	/api/user-process/stats	Link statistics

Security — Groups

Method	Path	Description
GET	/api/group/{id}	Get group
POST	/api/group/list	List groups
POST	/api/group	Create group
PUT	/api/group/{id}	Update group
DELETE	/api/group/{id}	Delete group
GET	/api/group/stats	Group statistics

Security — Group Members

Method	Path	Description
GET	/api/group-member/{id}	Get member
POST	/api/group-member/list	List members
POST	/api/group-member	Add member
PUT	/api/group-member/{id}	Update member
DELETE	/api/group-member/{id}	Remove member

Security — Group Roles

Method	Path	Description
GET	/api/group-role/{id}	Get role assignment
POST	/api/group-role/list	List role assignments
POST	/api/group-role	Assign role
PUT	/api/group-role/{id}	Update assignment
DELETE	/api/group-role/{id}	Remove assignment

Security — Role Types

Method	Path	Description
GET	/api/role-type/{id}	Get role type
POST	/api/role-type/list	List role types
POST	/api/role-type	Create role type
PUT	/api/role-type/{id}	Update role type
DELETE	/api/role-type/{id}	Delete role type

Licensing

Method	Path	Description
GET	/api/license/{id}	Get license
POST	/api/license/list	List licenses
POST	/api/license	Create license
PUT	/api/license/{id}	Update license
DELETE	/api/license/{id}	Delete license
GET	/api/license/stats	License statistics
GET	/api/license-history/{id}	Get history entry
POST	/api/license-history/list	List history

Lookups — Countries

Method	Path	Description
GET	/api/country/{id}	Get country
POST	/api/country/list	List countries
POST	/api/country	Create country
PUT	/api/country/{id}	Update country
DELETE	/api/country/{id}	Delete country

Lookups — Cities

Method	Path	Description
GET	/api/city/{id}	Get city
POST	/api/city/list	List cities
POST	/api/city	Create city
PUT	/api/city/{id}	Update city
DELETE	/api/city/{id}	Delete city

Lookups — Currencies

Method	Path	Description
GET	/api/currency/{id}	Get currency
POST	/api/currency/list	List currencies
POST	/api/currency	Create currency
PUT	/api/currency/{id}	Update currency
DELETE	/api/currency/{id}	Delete currency

Corporation Contacts

Method	Path	Description
GET	/api/corporation-contact/{id}	Get contact
POST	/api/corporation-contact/list	List contacts
POST	/api/corporation-contact	Create contact
PUT	/api/corporation-contact/{id}	Update contact
DELETE	/api/corporation-contact/{id}	Delete contact
GET	/api/corporation-contact/stats	Contact statistics

Session Management (API Key)

Method	Path	Description
GET	/api/session/{sessionId}	Get session
POST	/api/session	Create session
PUT	/api/session/{sessionId}	Update session
GET	/api/session/active	Get active sessions
POST	/api/session/active/list	List active sessions
GET	/api/session/history/list	Session history
GET	/api/session/stats	Session statistics

Exception Logs (API Key)

Method	Path	Description
GET	/api/logs/exceptions/{refId}	Get exception by ref ID
POST	/api/logs/exceptions/list	List exceptions

---

BPM Services (Port 8020)

Business Partner Management — partners, branches, contacts, contracts, accruals.

Business Partners

Method	Path	Description
GET	/api/business-partner/{id}	Get partner
POST	/api/business-partner/list	List partners
POST	/api/business-partner	Create partner
PUT	/api/business-partner/{id}	Update partner
DELETE	/api/business-partner/{id}	Delete partner
GET	/api/business-partner/stats	Partner statistics

Branches

Method	Path	Description
GET	/api/branch/{id}	Get branch
POST	/api/branch/list	List branches
POST	/api/branch	Create branch
PUT	/api/branch/{id}	Update branch
DELETE	/api/branch/{id}	Delete branch
GET	/api/branch/stats	Branch statistics
GET	/api/branch/by-partner/{id}	Branches by partner ID

Contacts

Method	Path	Description
GET	/api/contact/{id}	Get contact
POST	/api/contact/list	List contacts
POST	/api/contact	Create contact
PUT	/api/contact/{id}	Update contact
DELETE	/api/contact/{id}	Delete contact
GET	/api/contact/stats	Contact statistics

Products

Method	Path	Description
GET	/api/product/{id}	Get product
POST	/api/product/list	List products
POST	/api/product	Create product
PUT	/api/product/{id}	Update product
DELETE	/api/product/{id}	Delete product
GET	/api/product/stats	Product statistics

Contracts

Method	Path	Description
GET	/api/contract/{id}	Get contract
POST	/api/contract/list	List contracts
POST	/api/contract	Create contract
PUT	/api/contract/{id}	Update contract
DELETE	/api/contract/{id}	Delete contract
GET	/api/contract/stats	Contract statistics

Contract Items

Method	Path	Description
GET	/api/contract-item/{id}	Get item
POST	/api/contract-item/list	List items
POST	/api/contract-item	Create item
PUT	/api/contract-item/{id}	Update item
DELETE	/api/contract-item/{id}	Delete item

Accruals

Method	Path	Description
GET	/api/accrual/{id}	Get accrual
POST	/api/accrual/list	List accruals
POST	/api/accrual	Create accrual
PUT	/api/accrual/{id}	Update accrual
DELETE	/api/accrual/{id}	Delete accrual
GET	/api/accrual/stats	Accrual statistics
POST	/api/accrual/{id}/approve	Approve accrual
POST	/api/accrual/{id}/invoice	Mark as invoiced
POST	/api/accrual/{id}/cancel	Cancel accrual

---

DMS Services (Port 8030)

Document Management — file upload/download, categories, sharing, retention.

File Upload

POST /api/dms-file/upload (multipart/form-data)

curl -X POST http://localhost:8030/icdms/services/api/dms-file/upload \
  -F "file=@document.pdf" \
  -F "crProcessId=123" \
  -F "entityType=CONTRACT" \
  -F "entityId=456" \
  -F "categoryId=10" \
  -F "description=Q4 Report" \
  -F "tags=finance,quarterly"

Field	Type	Required	Description
file	MultipartFile	Yes	The file to upload
crProcessId	Long	Yes	Tenant ID
entityType	String	No	Linked entity type (e.g., CONTRACT)
entityId	Long	No	Linked entity ID
integrationKey	String	No	External system reference
categoryId	Long	No	Category ID
description	String	No	File description
tags	String	No	Comma-separated tags

Response 200 OK

{
  "fileId": 789,
  "originalFileName": "document.pdf",
  "storedFileName": "abc123.pdf",
  "fileSize": 102400,
  "mimeType": "application/pdf",
  "uploadDate": "2026-02-15T10:00:00Z"
}

File Download (Signed URL)

GET /api/dms-file/download/{id}

curl "http://localhost:8030/icdms/services/api/dms-file/download/789?token=xyz&expires=1708102400&inline=false"

Param	Required	Description
token	Yes	HMAC signature
expires	Yes	Unix timestamp expiration
inline	No	true for browser preview, false for download

Response headers:

Content-Disposition: attachment; filename="document.pdf"
Content-Type: application/pdf
X-Content-Type-Options: nosniff
Cache-Control: no-store
Accept-Ranges: bytes

Supports Range header for video streaming (returns 206 Partial Content).

File CRUD

Method	Path	Description
GET	/api/dms-file/{id}	Get file metadata with download URL
PUT	/api/dms-file/{id}	Update metadata
DELETE	/api/dms-file/{id}	Soft delete file
POST	/api/dms-file/list	List files (paginated)
GET	/api/dms-file/{id}/download-url	Generate signed download URL

File Queries

Method	Path	Description
GET	/api/dms-file/by-entity?entityType={t}&entityId={id}	Files by linked entity
GET	/api/dms-file/search?crProcessId={id}&searchTerm={term}	Search files
PUT	/api/dms-file/{id}/category?categoryId={id}	Move to category

Categories

Method	Path	Description
GET	/api/dms-category/{id}	Get category
POST	/api/dms-category/list	List categories
POST	/api/dms-category	Create category
PUT	/api/dms-category/{id}	Update category
DELETE	/api/dms-category/{id}	Delete category
GET	/api/dms-category/stats	Category statistics

Share Links

Method	Path	Description
GET	/api/dms-share-link/{id}	Get share link
POST	/api/dms-share-link/list	List share links
POST	/api/dms-share-link	Create share link
PUT	/api/dms-share-link/{id}	Update share link
DELETE	/api/dms-share-link/{id}	Delete share link
GET	/api/dms-share-link/stats	Share link statistics
GET	/api/dms-share-link/public/{token}	Access shared file (public)
POST	/api/dms-share-link/public/{token}/validate-password	Validate share password (public)

Retention Policies

Method	Path	Description
GET	/api/dms-retention-policy/{id}	Get policy
POST	/api/dms-retention-policy/list	List policies
POST	/api/dms-retention-policy	Create policy
PUT	/api/dms-retention-policy/{id}	Update policy
DELETE	/api/dms-retention-policy/{id}	Delete policy
GET	/api/dms-retention-policy/stats	Policy statistics

Audit Logs

Method	Path	Description
GET	/api/dms-audit-log/{id}	Get audit entry
POST	/api/dms-audit-log/list	List audit entries

Account Config

Method	Path	Description
GET	/api/dms-account-config/{id}	Get config
POST	/api/dms-account-config/list	List configs
POST	/api/dms-account-config	Create config
PUT	/api/dms-account-config/{id}	Update config
DELETE	/api/dms-account-config/{id}	Delete config
GET	/api/dms-account-config/stats	Config statistics

---

Frontend Service Routing

The React frontend resolves handler base paths to the correct microservice and API path automatically:

service-registry.ts (simplified)

{
  "business-partners": { service: "icbpm", apiPath: "/api/business-partner" },
  "branches":          { service: "icbpm", apiPath: "/api/branch" },
  "account":           { service: "icglb", apiPath: "/api/account" },
  "dms-files":         { service: "icdms", apiPath: "/api/dms-file" },
}

A single createRealCrudService(basePath) call provides all CRUD methods that automatically target the correct service.

---

Health Checks

All services expose Spring Boot Actuator endpoints:

curl http://localhost:8010/icglb/services/actuator/health

Response 200 OK

{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP" }
  }
}

---

What's Next?

• Authentication — JWT flow, API keys, security filters
• Error Codes — IC-* error registry and error handling