inventory-barcode-system/docs/API.md

# Inventory Barcode System API Documentation

## Overview

The Inventory Barcode System provides a RESTful API for managing products, inventory levels, and generating barcodes/QR codes. This documentation covers all available endpoints, request/response formats, and usage examples.

## Base URL

```
http://localhost:3000/api
```

## Authentication

Currently, the API does not require authentication. In production environments, consider implementing proper authentication and authorization mechanisms.

## Error Handling

All API endpoints return consistent error responses:

```json
{
  "error": true,
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": {}
}
```

Common HTTP status codes:
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `404` - Not Found
- `409` - Conflict
- `500` - Internal Server Error

## Products API

### Get All Products

Retrieve a list of all products in the system.

**Endpoint:** `GET /api/products`

**Query Parameters:**
- `page` (optional): Page number for pagination (default: 1)
- `limit` (optional): Number of items per page (default: 50)
- `search` (optional): Search term for product code or description
- `category` (optional): Filter by product category

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "product_code": "ABC123",
      "description": "Sample Product",
      "category": "Electronics",
      "unit_of_measure": "pcs",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "pages": 2
  }
}
```

### Get Product by ID

Retrieve a specific product by its ID.

**Endpoint:** `GET /api/products/:id`

**Response:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "product_code": "ABC123",
    "description": "Sample Product",
    "category": "Electronics",
    "unit_of_measure": "pcs",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```

### Create Product

Create a new product in the system.

**Endpoint:** `POST /api/products`

**Request Body:**
```json
{
  "product_code": "ABC123",
  "description": "Sample Product",
  "category": "Electronics",
  "unit_of_measure": "pcs"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "product_code": "ABC123",
    "description": "Sample Product",
    "category": "Electronics",
    "unit_of_measure": "pcs",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```

### Update Product

Update an existing product.

**Endpoint:** `PUT /api/products/:id`

**Request Body:**
```json
{
  "description": "Updated Product Description",
  "category": "Updated Category",
  "unit_of_measure": "kg"
}
```

### Delete Product

Delete a product from the system.

**Endpoint:** `DELETE /api/products/:id`

**Response:**
```json
{
  "success": true,
  "message": "Product deleted successfully"
}
```

### Import Products from Excel

Import products from an Excel file.

**Endpoint:** `POST /api/products/import`

**Request:** Multipart form data with Excel file

**Response:**
```json
{
  "success": true,
  "data": {
    "imported": 50,
    "skipped": 5,
    "errors": [
      {
        "row": 10,
        "error": "Invalid product code format"
      }
    ]
  }
}
```

## Inventory API

### Get Inventory Levels

Retrieve inventory levels for all products or specific products.

**Endpoint:** `GET /api/inventory`

**Query Parameters:**
- `product_id` (optional): Filter by specific product ID
- `low_stock` (optional): Show only products with low stock levels

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "product_id": 1,
      "product_code": "ABC123",
      "description": "Sample Product",
      "current_level": 100,
      "minimum_level": 10,
      "maximum_level": 500,
      "last_updated": "2024-01-01T00:00:00.000Z",
      "updated_by": "system"
    }
  ]
}
```

### Update Inventory Level

Update the inventory level for a specific product.

**Endpoint:** `PUT /api/inventory/:productId`

**Request Body:**
```json
{
  "new_level": 150,
  "change_reason": "Stock replenishment",
  "updated_by": "user123"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "product_id": 1,
    "old_level": 100,
    "new_level": 150,
    "change_reason": "Stock replenishment",
    "updated_by": "user123",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```

### Get Inventory History

Retrieve the history of inventory changes for a product.

**Endpoint:** `GET /api/inventory/:productId/history`

**Query Parameters:**
- `limit` (optional): Number of history records to return (default: 50)
- `from_date` (optional): Start date for history filter (ISO format)
- `to_date` (optional): End date for history filter (ISO format)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "product_id": 1,
      "old_level": 90,
      "new_level": 100,
      "change_reason": "Stock adjustment",
      "updated_by": "user123",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### Export Inventory to Excel

Export current inventory levels to an Excel file.

**Endpoint:** `GET /api/inventory/export`

**Query Parameters:**
- `format` (optional): Export format ('xlsx' or 'csv', default: 'xlsx')
- `include_history` (optional): Include inventory history (true/false, default: false)

**Response:** Excel file download

## Codes API

### Generate Barcode

Generate a barcode for a specific product.

**Endpoint:** `POST /api/codes/barcode`

**Request Body:**
```json
{
  "product_code": "ABC123",
  "format": "CODE128",
  "width": 2,
  "height": 100,
  "displayValue": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "product_code": "ABC123",
    "format": "CODE128",
    "barcode_svg": "<svg>...</svg>",
    "barcode_base64": "data:image/png;base64,..."
  }
}
```

### Generate QR Code

Generate a QR code for a specific product.

**Endpoint:** `POST /api/codes/qrcode`

**Request Body:**
```json
{
  "product_code": "ABC123",
  "size": 200,
  "error_correction": "M",
  "include_product_info": true
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "product_code": "ABC123",
    "qr_code_svg": "<svg>...</svg>",
    "qr_code_base64": "data:image/png;base64,...",
    "embedded_data": {
      "product_code": "ABC123",
      "description": "Sample Product",
      "timestamp": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

### Generate Printable Layout

Generate a printable PDF layout with barcodes/QR codes.

**Endpoint:** `POST /api/codes/printable`

**Request Body:**
```json
{
  "products": ["ABC123", "DEF456", "GHI789"],
  "code_type": "barcode",
  "layout": {
    "page_size": "A4",
    "labels_per_row": 3,
    "labels_per_column": 8,
    "include_description": true,
    "font_size": 10
  }
}
```

**Response:** PDF file download

### Decode Scanned Code

Decode a scanned barcode or QR code and retrieve product information.

**Endpoint:** `POST /api/codes/decode`

**Request Body:**
```json
{
  "code_data": "ABC123",
  "code_type": "barcode"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "product": {
      "id": 1,
      "product_code": "ABC123",
      "description": "Sample Product",
      "category": "Electronics"
    },
    "inventory": {
      "current_level": 100,
      "minimum_level": 10,
      "last_updated": "2024-01-01T00:00:00.000Z"
    }
  }
}
```

## Health Check

### System Health

Check the health status of the application.

**Endpoint:** `GET /health`

**Response:**
```json
{
  "status": "OK",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 3600,
  "memory": {
    "rss": 50331648,
    "heapTotal": 20971520,
    "heapUsed": 15728640,
    "external": 1048576
  },
  "version": "v18.17.0"
}
```

## Rate Limiting

API endpoints are rate-limited to prevent abuse:
- Default: 100 requests per 15 minutes per IP address
- File upload endpoints: 10 requests per 15 minutes per IP address

## File Upload Limits

- Maximum file size: 10MB
- Supported formats: .xlsx, .xls
- Maximum concurrent uploads: 3

## Examples

### Complete Import Workflow

1. **Upload Excel file:**
```bash
curl -X POST \
  http://localhost:3000/api/products/import \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@inventory.xlsx'
```

2. **Generate barcodes for imported products:**
```bash
curl -X POST \
  http://localhost:3000/api/codes/printable \
  -H 'Content-Type: application/json' \
  -d '{
    "products": ["ABC123", "DEF456"],
    "code_type": "barcode",
    "layout": {
      "page_size": "A4",
      "labels_per_row": 3,
      "include_description": true
    }
  }'
```

3. **Update inventory after scanning:**
```bash
curl -X PUT \
  http://localhost:3000/api/inventory/1 \
  -H 'Content-Type: application/json' \
  -d '{
    "new_level": 85,
    "change_reason": "Scanned update",
    "updated_by": "scanner_user"
  }'
```

4. **Export updated inventory:**
```bash
curl -X GET \
  'http://localhost:3000/api/inventory/export?format=xlsx' \
  --output updated_inventory.xlsx
```

## Error Codes

| Code | Description |
|------|-------------|
| `VALIDATION_ERROR` | Request validation failed |
| `PRODUCT_NOT_FOUND` | Product does not exist |
| `DUPLICATE_PRODUCT_CODE` | Product code already exists |
| `INVALID_FILE_FORMAT` | Unsupported file format |
| `FILE_TOO_LARGE` | File exceeds size limit |
| `DATABASE_ERROR` | Database operation failed |
| `GENERATION_ERROR` | Code generation failed |
| `EXPORT_ERROR` | Export operation failed |

## Support

For technical support or questions about the API, please refer to the system documentation or contact the development team.