Inventory Module - API Documentation

Overview

This section contains complete REST API documentation for the Inventory Module. All endpoints use JSON for request/response payloads and follow RESTful conventions. The API is built on ASP.NET Core Web API with Swagger/OpenAPI documentation available at /swagger.

Base URL: /api (configured in appsettings.json) Authentication: Required (Bearer token) Content-Type: application/json API Version: 1.0

Quick Reference

Core Endpoints

Feature	Endpoint	Description
Transactions	`GET /api/transactions`	Query transaction history
Movements	`POST /api/inventory/movements`	Create stock movement
Adjustments	`POST /api/inventory/adjustments`	Create stock adjustment
Assembly	`POST /api/assembly/create`	Execute assembly operation
Inventory	`GET /api/inventory`	Query current stock levels
Items	`GET /api/items`	Item master data
Locations	`GET /api/locations`	Location hierarchy
BOM	`GET /api/bom`	Bill of materials

API Structure

The API documentation is organized into focused sections for easy navigation:

📦 Items API

Path: ./items/

Complete item master data management including stockable behavior, categories, and units.

Documentation:

Items API Documentation - Full CRUD operations, filtering, search
Items Overview - Quick reference and integration guides

Key Operations:

Create stockable and non-stockable items
Update stockable behavior
Archive and restore items
Advanced search and filtering

📍 Locations API

Path: ./locations/

Hierarchical warehouse location management with unlimited depth support.

Documentation:

Locations API Documentation - Location hierarchy operations
Locations Overview - Tree queries and UI integration

Key Operations:

Create location hierarchies
Query location tree with depth control
Manage operational status
Move locations within hierarchy

🔧 Bill of Materials (BOM) API

Path: ./bom/

Manufacturing recipes and component explosion for assembly operations.

Documentation:

BOM API Documentation - BOM lifecycle management
BOM Overview - Component synchronization patterns

Key Operations:

Create and update BOMs
Synchronize component lines
Explode components for production
Archive and restore BOMs

📋 Transactions API

Path: ./transactions/

All five transaction types: Purchase, Sales, Movement, Adjustment, and Assembly.

Documentation:

Transactions API Documentation - Complete transaction processing
Transactions Overview - Type-specific workflows

Key Operations:

Create purchase transactions
Process sales transactions
Execute stock movements
Record inventory adjustments
Perform assembly operations

🔗 Shared Patterns

Path: ./shared/

Common patterns, conventions, and best practices used across all APIs.

Documentation:

Shared API Patterns - Comprehensive pattern documentation

Includes:

Soft delete strategy (archive/unarchive)
Pagination pattern
Filtering conventions
Error response format (RFC 7807)
Date/time and GUID formats
HTTP methods and semantics
Validation patterns
Security guidelines

Common Patterns

📖 For comprehensive pattern documentation, see Shared API Patterns

Request/Response Format

Standard Success Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2024-10-23T10:30:00Z",
  "data": { ... }
}

Error Response:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more validation errors occurred",
  "errors": {
    "field_name": ["Error message"]
  }
}

Pagination

Query Parameters:

?pageNumber=1&pageSize=20

Paginated Response:

{
  "items": [ ... ],
  "page_number": 1,
  "page_size": 20,
  "total_count": 150,
  "total_pages": 8,
  "has_previous": false,
  "has_next": true
}

Filtering

Common Filter Parameters:

search - Text search across relevant fields
startDate / endDate - Date range filtering
locationId - Filter by location
itemId - Filter by item
type - Filter by transaction type
isActive - Include/exclude archived records

Example:

GET /api/transactions?type=Movement&startDate=2024-01-01&locationId=abc123

Sorting

Query Parameter:

?sortBy=createdDate&sortDirection=desc

Common Sort Fields:

createdDate - Creation timestamp
quantity - Quantity values
name - Alphabetical sorting

Authentication & Authorization

Authentication

Method: Bearer Token (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authorization Matrix

Operation	Required Role	Notes
Query Inventory	`Inventory.Read`	View stock levels
Create Movement	`Inventory.Movement`	Transfer stock
Create Adjustment	`Inventory.Adjustment`	Correct quantities
Execute Assembly	`Inventory.Assembly`	Manufacturing
Query Transactions	`Inventory.Read`	View history
Manage Items	`Inventory.Admin`	Master data

Error Handling

HTTP Status Codes

Status	Meaning	When Used
200 OK	Success	Successful GET, PATCH operations
201 Created	Resource created	Successful POST operations
400 Bad Request	Validation error	Invalid input data
401 Unauthorized	Not authenticated	Missing/invalid token
403 Forbidden	Not authorized	Insufficient permissions
404 Not Found	Resource not found	Invalid ID
409 Conflict	Business rule violation	Domain exception
500 Internal Server Error	Server error	Unexpected errors

Error Response Structure

Validation Error (400):

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more validation errors occurred",
  "errors": {
    "SourceLocationId": ["Source location is required"],
    "LineItems[0].Quantity": ["Quantity must be positive"]
  }
}

Business Rule Violation (409):

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8",
  "title": "Business rule violation",
  "status": 409,
  "detail": "Source and destination locations cannot be the same",
  "error_code": "SAME_LOCATION_MOVEMENT"
}

Rate Limiting

Limits:

1000 requests per hour per user
100 requests per minute per user
Bulk operations count as single request

Headers:

X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 987
X-Rate-Limit-Reset: 1635523200

Versioning

Current Version: 1.0

Version Strategy: URL-based versioning (future)

/api/v1/inventory/movements
/api/v2/inventory/movements

Deprecation Policy:

6 months notice for breaking changes
Backward compatibility maintained within major version

API Testing

Swagger UI

URL: https://your-domain/swagger Features:

Interactive API documentation
Try-it-out functionality
Request/response examples
Schema definitions

Postman Collection

Available at: /docs/postman/inventory-api.json Includes:

All endpoints with examples
Environment variables
Pre-request scripts for authentication

Performance Considerations

Best Practices

Use Pagination: Always paginate large result sets
Filter Aggressively: Apply filters to reduce data transfer
Selective Fields: Request only needed fields (future feature)
Batch Operations: Use bulk endpoints when possible
Cache: Leverage ETags for caching (future feature)

Timeouts

Standard Operations: 30 seconds
Bulk Operations: 120 seconds
Report Generation: 300 seconds

Integration Examples

C# Client Example

using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient
{
    BaseAddress = new Uri("https://api.your-domain.com")
};

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", token);

// Create movement
var movementRequest = new CreateBulkMovementCommand
{
    SourceLocationId = sourceId,
    DestinationLocationId = destId,
    LineItems = new[]
    {
        new LineItemDto { ItemId = itemId, Quantity = 50, UnitOfMeasureId = unitId }
    },
    Reason = "Stock transfer"
};

var response = await client.PostAsJsonAsync(
    "/api/inventory/movements",
    movementRequest);

response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<MovementDto>();

JavaScript/TypeScript Example

const apiClient = {
  baseUrl: 'https://api.your-domain.com',
  token: 'your-jwt-token',

  async createMovement(request: CreateMovementRequest) {
    const response = await fetch(`${this.baseUrl}/api/inventory/movements`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify(request)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.detail);
    }

    return await response.json();
  }
};

// Usage
const movement = await apiClient.createMovement({
  sourceLocationId: 'abc-123',
  destinationLocationId: 'def-456',
  lineItems: [
    { itemId: 'item-1', quantity: 50, unitOfMeasureId: 'unit-1' }
  ],
  reason: 'Stock transfer'
});

Monitoring & Logging

Request Tracing

Every request includes correlation ID:

X-Correlation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Logging Levels

Info: Successful operations
Warning: Business rule violations
Error: System errors
Debug: Detailed execution flow (dev only)

Domain Documentation

Domain Overview - Business logic and aggregates
Transaction Aggregate - Transaction domain model

Conceptual Documentation

Transaction Types - Workflow explanations
Inventory Tracking - How inventory updates work
Finance Integration - Cross-module integration

User Guides

User Guides - Step-by-step operational guides

Last Updated: 2025-10-23 | Version: 1.0 | API Status: Active Development

Next Updates:

Phase 2: Assembly API completion
Phase 3: Advanced filtering and search
Future: GraphQL endpoint consideration

Overview​

Quick Reference​

Core Endpoints​

API Structure​

📦 Items API​

📍 Locations API​

🔧 Bill of Materials (BOM) API​

📋 Transactions API​

🔗 Shared Patterns​

Common Patterns​

Request/Response Format​

Pagination​

Filtering​

Sorting​

Authentication & Authorization​

Authentication​

Authorization Matrix​

Error Handling​

HTTP Status Codes​

Error Response Structure​

Rate Limiting​

Versioning​

API Testing​

Swagger UI​

Postman Collection​

Performance Considerations​

Best Practices​

Timeouts​

Integration Examples​

C# Client Example​

JavaScript/TypeScript Example​

Monitoring & Logging​

Request Tracing​

Logging Levels​

Related Documentation​

Domain Documentation​

Conceptual Documentation​

User Guides​

Overview

Quick Reference

Core Endpoints

API Structure

📦 Items API

📍 Locations API

🔧 Bill of Materials (BOM) API

📋 Transactions API

🔗 Shared Patterns

Common Patterns

Request/Response Format

Pagination

Filtering

Sorting

Authentication & Authorization

Authentication

Authorization Matrix

Error Handling

HTTP Status Codes

Error Response Structure

Rate Limiting

Versioning

API Testing

Swagger UI

Postman Collection

Performance Considerations

Best Practices

Timeouts

Integration Examples

C# Client Example

JavaScript/TypeScript Example

Monitoring & Logging

Request Tracing

Logging Levels

Related Documentation

Domain Documentation

Conceptual Documentation

User Guides