API docs by Redocly

Smart Supply Pro – Backend API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/Keglev/inventory-service License: MIT

Enterprise REST API for Smart Supply Pro inventory and supplier management system.

Features

  • OAuth2 authentication with Google
  • Inventory item management with audit trail
  • Supplier relationship management
  • Stock movement tracking and analytics
  • Real-time dashboard KPIs

Authentication

All endpoints (except health checks) require OAuth2 authentication via Google. The API uses JWT tokens managed through secure HTTP-only cookies.

Auth

Authentication and user profile operations

Get authenticated user profile

Returns the current authenticated user's profile information including email, full name, role, and profile picture URL from OAuth2 provider.

User data is loaded from the database based on OAuth2 email claim.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
Example
{}

Get user authorities

Returns the list of granted authorities (roles and permissions) for the authenticated user. Used for frontend authorization checks.

Authorities are returned as sorted strings (e.g., ROLE_USER, ROLE_ADMIN).

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
[
  • "ROLE_USER",
  • "ROLE_ADMIN"
]

API logout endpoint

Programmatic logout endpoint for API clients (SPAs, mobile apps).

What it does:

  • Invalidates the Spring Security session
  • Expires JSESSIONID and SESSION cookies
  • Returns 204 No Content

Cookie settings:

  • HttpOnly: true (prevents JavaScript access)
  • Secure: true (HTTPS only)
  • SameSite: None (cross-origin support)
  • MaxAge: 0 (immediate expiration)

Note: Browser clients should prefer the standard POST /logout endpoint.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
{
  • "message": "No authentication provided",
  • "status": 401,
  • "timestamp": "2025-11-18T10:30:00Z",
  • "path": "/api/me"
}

Inventory

Inventory item CRUD operations

Get all inventory items

Retrieves all inventory items in the system (non-paginated). Includes supplier names and calculated total values.

Security: Requires authentication OR demo mode enabled. If APP_DEMO_READONLY=true, unauthenticated access is allowed.

Note: For large datasets, consider using the search endpoint with pagination.

Authorizations:
oauth2None

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new inventory item

Creates a new inventory item. Requires ADMIN role.

Authorization:

  • Requires ROLE_ADMIN
  • Blocked in demo mode (APP_DEMO_READONLY=true) - returns 403 Forbidden

Validation:

  • ID must be absent (system-generated)
  • Name, quantity, price, and supplierId are required
  • Price must be positive
  • Quantity must be zero or positive

Response:

  • 201 Created with Location header pointing to new resource
  • Body contains the created item with system-generated ID and timestamps
Authorizations:
oauth2
Request Body schema: application/json
required
name
required
string non-empty

Display name of the inventory item

quantity
required
integer <int32> >= 0

Initial stock quantity

price
required
number <double> >= 0.01

Price per unit

supplierId
required
string

Associated supplier identifier

minimumQuantity
integer <int32> >= 0

Minimum stock threshold for low-stock alerts

Responses

Request samples

Content type
application/json
{
  • "name": "Premium Widget",
  • "quantity": 100,
  • "price": 29.99,
  • "supplierId": "supplier-123",
  • "minimumQuantity": 50
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Premium Widget",
  • "quantity": 150,
  • "price": 29.99,
  • "totalValue": 4498.5,
  • "supplierId": "supplier-123",
  • "supplierName": "Acme Corp",
  • "minimumQuantity": 50,
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Get inventory item by ID

Retrieves a single inventory item by its unique identifier. Includes supplier name and calculated total value.

Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Unique inventory item identifier

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Premium Widget",
  • "quantity": 150,
  • "price": 29.99,
  • "totalValue": 4498.5,
  • "supplierId": "supplier-123",
  • "supplierName": "Acme Corp",
  • "minimumQuantity": 50,
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Update inventory item

Updates an existing inventory item completely (full replacement).

Authorization:

  • Requires ROLE_ADMIN
  • Blocked in demo mode (APP_DEMO_READONLY=true) - returns 403 Forbidden

ID Handling:

  • Path parameter takes precedence
  • Request body ID is ignored to prevent conflicts

Validation:

  • All required fields must be provided
  • Price must be positive
  • Quantity must be zero or positive
Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Inventory item identifier

Request Body schema: application/json
required
name
required
string non-empty

Display name of the inventory item

quantity
required
integer <int32> >= 0

Current stock quantity

price
required
number <double> >= 0.01

Price per unit

supplierId
required
string

Associated supplier identifier

minimumQuantity
integer <int32> >= 0

Minimum stock threshold

Responses

Request samples

Content type
application/json
{
  • "name": "Premium Widget (Updated)",
  • "quantity": 120,
  • "price": 34.99,
  • "supplierId": "supplier-123",
  • "minimumQuantity": 60
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Premium Widget",
  • "quantity": 150,
  • "price": 29.99,
  • "totalValue": 4498.5,
  • "supplierId": "supplier-123",
  • "supplierName": "Acme Corp",
  • "minimumQuantity": 50,
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Delete inventory item

Deletes an inventory item permanently. Requires ADMIN role.

Authorization:

  • Requires ROLE_ADMIN
  • Blocked in demo mode (APP_DEMO_READONLY=true) - returns 403 Forbidden

Business Rules:

  • Item must have quantity = 0 (all stock must be removed before deletion)
  • Reason parameter is required for compliance tracking
  • Deletion is logged in stock history with specified reason

Validation Flow:

  1. Verify item exists (404 if not found)
  2. Enforce quantity = 0 business rule (409 if quantity > 0)
  3. Validate deletion reason is one of allowed values
  4. Log deletion in audit trail
  5. Remove item from system

Error Response Examples:

  • 404: Item not found
  • 409: Item has quantity > 0 (message: "You still have merchandise in stock. You need to first remove items from stock by changing quantity.")
  • 400: Invalid deletion reason
Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Inventory item identifier

query Parameters
reason
required
string
Enum: "SCRAPPED" "DESTROYED" "DAMAGED" "EXPIRED" "LOST" "RETURNED_TO_SUPPLIER"
Example: reason=SCRAPPED

Business reason for deletion (audit trail). Must be one of deletion-valid reasons.

Responses

Response samples

Content type
application/json
{
  • "error": "Invalid reason for deletion",
  • "status": 400,
  • "timestamp": "2025-11-20T20:00:00Z"
}

Get total item count

Returns the total number of inventory items in the system.

Security: Requires authentication OR demo mode enabled. If APP_DEMO_READONLY=true, unauthenticated access is allowed.

Authorizations:
oauth2None

Responses

Response samples

Content type
application/json
142

Search inventory items by name

Searches for inventory items by name with pagination and sorting support. Name search is case-insensitive and matches substrings.

Security: Requires authentication OR demo mode enabled. If APP_DEMO_READONLY=true, unauthenticated access is allowed.

Authorizations:
oauth2None
query Parameters
name
required
string
Example: name=widget

Case-insensitive name substring to search for

page
integer <int32> >= 0
Default: 0

Page number (0-indexed)

size
integer <int32> [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page

sort
string
Example: sort=price,desc

Sort criteria in format: property,direction. Multiple sort criteria can be specified.

Examples:

  • name,asc - Sort by name ascending
  • price,desc - Sort by price descending
  • createdAt,desc - Sort by creation date descending

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Adjust inventory quantity

Adjusts the quantity of an inventory item by a delta amount.

Authorization:

  • Requires ROLE_USER or ROLE_ADMIN
  • Blocked in demo mode (APP_DEMO_READONLY=true) - returns 403 Forbidden

Delta Logic:

  • Positive delta: Add stock (e.g., +50 to increase by 50 units)
  • Negative delta: Remove stock (e.g., -25 to decrease by 25 units)

Audit Trail:

  • All quantity changes are logged in stock history
  • Reason parameter is required for compliance tracking
Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Inventory item identifier

query Parameters
delta
required
integer <int32>
Example: delta=-25

Quantity change (positive to add, negative to remove)

reason
required
string
Enum: "SALE" "RETURN" "DAMAGED" "EXPIRED" "RESTOCK" "MANUAL_ADJUSTMENT" "INVENTORY_COUNT" "INITIAL_STOCK"
Example: reason=SALE

Business reason for quantity adjustment

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Premium Widget",
  • "quantity": 150,
  • "price": 29.99,
  • "totalValue": 4498.5,
  • "supplierId": "supplier-123",
  • "supplierName": "Acme Corp",
  • "minimumQuantity": 50,
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Update item unit price

Updates the unit price of an inventory item. Total value is automatically recalculated (quantity × new price).

Authorization:

  • Requires ROLE_USER or ROLE_ADMIN
  • Blocked in demo mode (APP_DEMO_READONLY=true) - returns 403 Forbidden
Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Inventory item identifier

query Parameters
price
required
number <double> >= 0.01
Example: price=34.99

New unit price (must be positive)

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Premium Widget",
  • "quantity": 150,
  • "price": 29.99,
  • "totalValue": 4498.5,
  • "supplierId": "supplier-123",
  • "supplierName": "Acme Corp",
  • "minimumQuantity": 50,
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Suppliers

Supplier management

Get all suppliers

Retrieves a list of all suppliers in the system. Supports demo readonly access.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new supplier

Creates a new supplier. Requires ADMIN role.

Validation:

  • ID must be absent (system-generated)
  • Name and createdBy are required
  • Email (if provided) must be valid format

Response:

  • 201 Created with Location header pointing to new resource
  • Body contains the created supplier with system-generated ID and timestamp
Authorizations:
oauth2
Request Body schema: application/json
required
name
required
string non-empty

Supplier display name

contactName
string or null

Optional contact person name

phone
string or null

Optional phone number

email
string or null <email>

Optional email address

createdBy
required
string

User creating this supplier (for audit trail)

Responses

Request samples

Content type
application/json
{
  • "name": "New Supplier Corp",
  • "contactName": "Alice Johnson",
  • "phone": "+1-555-0200",
  • "email": "contact@newsupplier.com",
  • "createdBy": "admin@example.com"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Acme Corp",
  • "contactName": "John Smith",
  • "phone": "+1-555-0100",
  • "email": "contact@acmecorp.com",
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Get supplier by ID

Retrieves a single supplier by its unique identifier.

Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Unique supplier identifier

Responses

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Acme Corp",
  • "contactName": "John Smith",
  • "phone": "+1-555-0100",
  • "email": "contact@acmecorp.com",
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Update supplier

Updates an existing supplier completely (full replacement). Requires ADMIN role.

ID Handling:

  • Path parameter takes precedence
  • Request body ID must match path ID (if provided)

Validation:

  • All required fields must be provided
  • Email (if provided) must be valid format
Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Supplier identifier

Request Body schema: application/json
required
name
required
string non-empty

Supplier display name

contactName
string or null

Optional contact person name

phone
string or null

Optional phone number

email
string or null <email>

Optional email address

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Supplier Corp",
  • "contactName": "Bob Wilson",
  • "phone": "+1-555-0201",
  • "email": "newemail@supplier.com"
}

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Acme Corp",
  • "contactName": "John Smith",
  • "phone": "+1-555-0100",
  • "email": "contact@acmecorp.com",
  • "createdBy": "admin@example.com",
  • "createdAt": "2025-11-01T10:00:00Z"
}

Delete supplier

Deletes a supplier permanently. Requires ADMIN role.

Referential Integrity:

  • System enforces referential integrity checks
  • May fail if supplier has active inventory items
Authorizations:
oauth2
path Parameters
id
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Supplier identifier

Responses

Response samples

Content type
application/json
{
  • "message": "No authentication provided",
  • "status": 401,
  • "timestamp": "2025-11-18T10:30:00Z",
  • "path": "/api/me"
}

Get total supplier count

Returns the total number of suppliers in the system.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
45

Search suppliers by name

Searches for suppliers by partial or full name match. Case-insensitive substring search.

Authorizations:
oauth2
query Parameters
name
required
string
Example: name=Acme

Case-insensitive supplier name substring

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Stock History

Stock movement tracking and history

Get all stock history entries

Retrieves all stock history entries without pagination. Use for comprehensive audit trail export or analysis.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get stock history for item

Retrieves all stock movement history for a specific inventory item. Shows the complete change timeline for an item with reasons and actors.

Authorizations:
oauth2
path Parameters
itemId
required
string
Example: 550e8400-e29b-41d4-a716-446655440000

Inventory item identifier

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get stock history by change reason

Filters stock history entries by the reason for change. Useful for tracking all sales, returns, damages, etc.

Authorizations:
oauth2
path Parameters
reason
required
string
Enum: "SALE" "RETURN" "DAMAGED" "EXPIRED" "RESTOCK" "MANUAL_ADJUSTMENT" "INVENTORY_COUNT" "INITIAL_STOCK"
Example: SALE

Stock change reason

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Search stock history with advanced filters

Advanced paginated search with multiple filter criteria and date range bounds.

Filters (all optional):

  • Date range: startDate to endDate (inclusive, ISO-8601 format)
  • Item name: Partial name matching for inventory items
  • Supplier ID: Filter by supplier identifier

Validation:

  • endDate must be >= startDate if both provided
  • Page size is capped at 200 to prevent memory issues

Default sorting: timestamp DESC (newest first)

Authorizations:
oauth2
query Parameters
startDate
string <date-time>
Example: startDate=2025-11-01T00:00:00Z

Inclusive start timestamp (ISO-8601)

endDate
string <date-time>
Example: endDate=2025-11-30T23:59:59Z

Inclusive end timestamp (ISO-8601)

itemName
string
Example: itemName=Widget

Partial inventory item name to filter by

supplierId
string
Example: supplierId=supplier-123

Supplier identifier to filter by

page
integer <int32> >= 0
Default: 0

Page number (0-indexed)

size
integer <int32> [ 1 .. 200 ]
Default: 50
Example: size=50

Number of items per page (max 200, default 50)

sort
string
Example: sort=timestamp,desc

Sort criteria in format: property,direction. Default: timestamp,desc

Examples:

  • timestamp,desc - Newest changes first
  • itemId,asc - Grouped by item
  • change,desc - Largest changes first

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "page": {
    }
}

Analytics

Dashboard KPIs and analytics

Get stock value over time

Gets time series of total stock value between dates. Shows inventory value trends with optional supplier filtering.

Authorizations:
oauth2
query Parameters
start
required
string <date>
Example: start=2025-11-01

Inclusive start date (ISO yyyy-MM-dd)

end
required
string <date>
Example: end=2025-11-30

Inclusive end date (ISO yyyy-MM-dd)

supplierId
string
Example: supplierId=supplier-123

Optional supplier filter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get stock per supplier

Gets current total stock quantity per supplier for charts and distribution analysis.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get low stock count

Gets the count of items below their minimum stock threshold. Useful for quick dashboard indicators.

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
12

Get item update frequency

Gets item update frequency for a specific supplier. Shows which items are updated most frequently, indicating high activity.

Authorizations:
oauth2
query Parameters
supplierId
required
string
Example: supplierId=supplier-123

Supplier identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get low stock items

Gets items below minimum stock threshold for a supplier. Lists items requiring reorder with current and recommended levels.

Authorizations:
oauth2
query Parameters
supplierId
required
string
Example: supplierId=supplier-123

Supplier identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get monthly stock movement

Gets monthly stock movement (inbound/outbound) within a date range. Shows inventory flow trends with optional supplier filtering.

Authorizations:
oauth2
query Parameters
start
required
string <date>
Example: start=2025-09-01

Inclusive start date (ISO yyyy-MM-dd)

end
required
string <date>
Example: end=2025-11-30

Inclusive end date (ISO yyyy-MM-dd)

supplierId
string
Example: supplierId=supplier-123

Optional supplier filter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get filtered stock updates (query params)

Gets filtered stock updates via query parameters. Defaults to last 30 days if dates not specified.

Filters (all optional):

  • Date range: startDate to endDate (ISO-8601 datetime)
  • Item name: Partial name matching
  • Supplier: By supplierId
  • User: By createdBy (who made the change)
  • Quantity: Min and max change values
Authorizations:
oauth2
query Parameters
startDate
string <date-time>
Example: startDate=2025-10-20T00:00:00Z

Start timestamp (ISO-8601, defaults to 30 days ago)

endDate
string <date-time>
Example: endDate=2025-11-20T23:59:59Z

End timestamp (ISO-8601, defaults to now)

itemName
string
Example: itemName=Widget

Partial item name filter

supplierId
string
Example: supplierId=supplier-123

Supplier identifier filter

createdBy
string
Example: createdBy=user@example.com

User who made the change

minChange
integer <int32>
Example: minChange=-100

Minimum quantity change (inclusive)

maxChange
integer <int32>
Example: maxChange=100

Maximum quantity change (inclusive)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get filtered stock updates (JSON body)

Gets filtered stock updates via JSON request body. Allows complex filtering criteria in structured format.

Authorizations:
oauth2
Request Body schema: application/json
required
startDate
string or null <date-time>

Start timestamp (defaults to 30 days ago)

endDate
string or null <date-time>

End timestamp (defaults to now)

itemName
string or null

Partial item name filter

supplierId
string or null

Supplier identifier filter

createdBy
string or null

User who made the change

minChange
integer or null <int32>

Minimum quantity change

maxChange
integer or null <int32>

Maximum quantity change

Responses

Request samples

Content type
application/json
{
  • "startDate": "2025-10-20T00:00:00Z",
  • "endDate": "2025-11-20T23:59:59Z",
  • "itemName": "Widget",
  • "supplierId": "supplier-123",
  • "createdBy": "user@example.com",
  • "minChange": -100,
  • "maxChange": 100
}

Response samples

Content type
application/json
[
  • {
    }
]

Get dashboard summary

Gets comprehensive dashboard summary with multiple analytics aggregated. Includes supplier distribution, low stock items, trends, and activity.

Defaults: If dates not provided, uses last 30 days.

Authorizations:
oauth2
query Parameters
supplierId
string
Example: supplierId=supplier-123

Optional supplier filter

startDate
string <date-time>
Example: startDate=2025-10-20T00:00:00Z

Start timestamp (defaults to 30 days ago)

endDate
string <date-time>
Example: endDate=2025-11-20T23:59:59Z

End timestamp (defaults to now)

Responses

Response samples

Content type
application/json
{
  • "stockPerSupplier": [
    ],
  • "lowStockItems": [
    ],
  • "monthlyStockMovement": [
    ],
  • "topUpdatedItems": [
    ]
}

Get price trend for item

Gets historical price changes for a specific inventory item. Shows price evolution over a date range with optional supplier filtering.

Authorizations:
oauth2
query Parameters
itemId
required
string
Example: itemId=550e8400-e29b-41d4-a716-446655440000

Inventory item identifier

supplierId
string
Example: supplierId=supplier-123

Optional supplier filter

start
required
string <date>
Example: start=2025-09-01

Inclusive start date (ISO yyyy-MM-dd)

end
required
string <date>
Example: end=2025-11-30

Inclusive end date (ISO yyyy-MM-dd)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get financial summary

Gets financial summary with Weighted Average Cost (WAC) calculations. Shows inventory costs, valuations, and financial metrics.

Authorizations:
oauth2
query Parameters
from
required
string <date>
Example: from=2025-09-01

Start date (ISO yyyy-MM-dd)

to
required
string <date>
Example: to=2025-11-30

End date (ISO yyyy-MM-dd)

supplierId
string
Example: supplierId=supplier-123

Optional supplier filter

Responses

Response samples

Content type
application/json
{
  • "totalInventoryValue": 157500,
  • "totalQuantity": 5243,
  • "weightedAverageCost": 30.04,
  • "totalCost": 157500,
  • "period": {
    }
}

System

Health checks and system information

Basic Application Health Check

Performs a lightweight health check to verify the application is running.

This endpoint provides a quick way to monitor application availability without checking external dependencies like databases. Useful for load balancers, orchestration platforms, and basic uptime monitoring.

Security: This endpoint is publicly accessible (no authentication required). Used by Fly.io HTTP health checks and container orchestration systems.

Responses

Deep Database Health Check

Performs a comprehensive health check including database connectivity verification.

Uses Oracle-specific SYS_CONTEXT query to:

  • Verify database is reachable and responsive
  • Confirm Oracle functionality is available
  • Return client IP address as seen by the database
  • Detect temporary database pausing (common in Oracle Free Tier)

Useful for monitoring critical dependencies and detecting infrastructure issues. Returns 503 Service Unavailable if database is unreachable or misconfigured.

Security: This endpoint is publicly accessible (no authentication required). Used by monitoring systems to verify database health.

Responses

Response samples

Content type
application/json
{
  • "status": "UP",
  • "oracleSeesIp": "192.168.1.100"
}